REST API

Connection details

Use the versioned API base for requests, and use the resource value when requesting OAuth API scopes. Send API tokens and OAuth access tokens as bearer tokens.

/api defaults to the current version, which is v1. Use /api/v1 when you want the version to be explicit.

Authentication options

Choose the narrowest credential type that fits the integration.

Examples

Scopes

Request the smallest set of scopes that match the action. Write and send scopes depend on the matching read scope.

Payloads are scope-aware. If a token can read the requested record but not a related record, DoubleTime omits nested details for that related resource. Request the related read scope when your integration needs linked client, project, task, invoice, or tag detail.

Endpoints

This is the public API surface intended for scoped tokens and OAuth clients. Reads need the read scope for the area, and mutations need the matching write scope.

Deposit invoices

Deposits use the existing invoice endpoints. Creating or finalising a deposit invoice requires an active Pro subscription, invoices:read and invoices:write. Reading deposits and applying an existing paid deposit remain available on every plan with the required scopes.

Request an upfront payment

POST /api/v1/invoices with type set to deposit creates a draft deposit invoice. Omit type, or use standard, for an ordinary invoice. The type cannot change after creation. Replace the example client and tax rate IDs with records available to the account; taxRateId can be null for an untaxed deposit. A null invoiceNumber selects the next invoice number.

Finalise the draft through PUT /api/v1/invoices/:invoice with finalize set to true, preserving its current invoice fields and items. Send it through the ordinary invoice send endpoint, which requires invoices:read and invoices:send. Record money actually received through POST /api/v1/invoices/:invoice/payments with paidTotal and, optionally, paidAt; paidTotal includes tax. Payment receipts use the existing send-receipt endpoint.

Find a deposit for a work invoice

GET /api/v1/invoices?filter[type]=deposit lists deposit invoices. Invoice responses include type and a deposit summary with amount, usedAmount, availableAmount and draws. These amounts are before tax and include reservations made by drafts.

Once the later work invoice exists, GET /api/v1/invoices/:invoice/deposit-candidates returns an array of its contact's finalised deposits that have money left or are already used on that invoice. Each includes id, descriptions, taxRateId, availableAmount, taxTotal, availableTaxTotal, isPaidInFull and unavailableReason. There is no pagination.

Only use a candidate whose unavailableReason is null. A deposit must be paid in full and match the invoice's contact and currency. The reasons unpaid and currency explain an unavailable candidate. availableAmount excludes amounts reserved by other invoices, but includes this invoice's existing draw so it can be replaced when editing.

Apply or release a deposit

Read the work invoice first, then PUT /api/v1/invoices/:invoice with its current required fields and the complete desired items array. Preserve existing item IDs and link fields; omitted items are removed. Add a line with depositInvoiceId set to the candidate id, quantity 1, quantityUnit unit, the candidate taxRateId and a negative unitPrice equal to the amount before tax. The following example assumes work item 789 and paid deposit 123, both using tax rate 3. Replace the fields with values from your invoice and candidate response.

A deposit draw cannot exceed availableAmount or make the work invoice subtotal or total negative. Use at most two decimal places for the amount. The server calculates the tax credit from the original deposit, including rounding, and returns the saved totals. Do not record another payment for the applied amount: the negative item reduces the amount due.

One deposit can cover several invoices. Draft items reserve their amounts; removing a deposit item releases its amount. Resend depositInvoiceId when retaining a linked item. Read candidates again if a concurrent update changes the available balance.

Deposit invoice items must share one tax rate and cannot link tracked time, expenses or other deposits. Deposit invoices cannot have adjustments. Once another invoice draws on a deposit, its contact, tax and item amounts are locked. Refunds of unused deposits are not supported.

Implementation notes

Requests and pagination

• JSON endpoints expect Content-Type: application/json unless the endpoint is a file upload or download.
• Task lists support limit, offset, and sort query parameters and return X-Total-Count, X-Offset, and X-Limit.

Scopes and subscriptions

• Read scopes allow viewing records. Write scopes require the matching read scope and can create, update, archive, or delete records.
• Preview, send, receipt, and resend invoice endpoints require invoices:send plus invoices:read.
• Some report endpoints require an active subscription in addition to reports:read.

Invoices and expenses

• For an existing invoice, GET /api/v1/invoices/:invoice/import is the preferred import-candidate query because the invoice supplies the client and existing linked activity exclusions.
• Reading expense records, removing attachment links, and deleting draft expenses remain available on every plan with the required scopes. Existing downloads depend on Google authorisation and file availability, not an active subscription. Creating or updating expense financial records requires an active subscription.
• Listing invoice expense candidates and linking selected expense attachments to an invoice require a subscription and the scopes listed above.
• Adding, removing, or reassigning expense links requires expenses:write and expenses:read alongside invoices:write and invoices:read, plus an active subscription. Invoice updates that preserve existing expense links keep the base invoice access requirements.
• The expenses and profit-loss report endpoints require reports:read and an active subscription. They use finalised documents by expense or invoice date, regardless of payment timing. Profit and loss values exclude tax; mixed currencies are not automatically converted.

Attachments

• Add new Google Drive files through Google Picker in the DoubleTime app for first-time file selection and authorisation. DoubleTime uses drive.file for per-file access; another Drive connector's access does not grant DoubleTime access. Use REST to manage attachments already linked in the app.
• The from-expense endpoint requires expenseId and an explicit, nonempty expenseArtifactIds array. List the expense attachments first and pass only IDs selected by the user; omission never means all attachments.
• Sharing a selected receipt creates an independent invoice attachment, not a file copy. Removing a document attachment link does not delete its Google file or the link on another document.
• Receipt sharing requires an active subscription and creates links atomically. A failed batch creates no links, and repeating a selection returns existing links without duplicates. Confirm the selected receipts and invoice before sharing: invoice recipients can download them. If sharing fails after the invoice was saved, retry against that invoice ID rather than creating another invoice.
• Direct invoice and expense attachment uploads are retired. POST to either document's /artifacts collection returns HTTP 410 with ARTIFACT_UPLOAD_RETIRED; add files through Picker in the app.