Time tracking – API reference

List time entries

GET/api/v1/time-entries

Newest first. Period from/to (calendar days, Europe/Berlin), filter by project or customer and by billing status (running, unbilled, invoiced, non_billable).

Permission: time:read

Query parameters

fromstring (date)
from day (inclusive, Europe/Berlin)
tostring (date)
to day (inclusive)
projectIdstring
max. 128 characters
contactIdstring
not together with projectId
max. 128 characters
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"
limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<TimeEntry>required
- idstringrequired
- projectIdstring | nullrequired
- taskIdstring | nullrequired
- contactIdstring | nullrequired
- descriptionstringrequired
- startstring (date-time)required
  Timestamp (ISO 8601)
- endstring (date-time) | nullrequired
  null while the timer is running
- datestring (date)required
  Calendar day of the start (Europe/Berlin)
- durationMinutesintegerrequired
  Duration in minutes; for a running timer, the time elapsed so far
  0–9007199254740991
- runningbooleanrequired
- billablebooleanrequired
- billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = rate of the task or project
  0–10000000
- invoicedInvoiceIdstring | nullrequired
  Invoice with which the time was invoiced
- invoicedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "projectId": "string",
      "taskId": "string",
      "contactId": "string",
      "description": "string",
      "start": "2026-11-01T09:30:00.000Z",
      "end": "2026-11-01T09:30:00.000Z",
      "date": "2026-11-01",
      "durationMinutes": 0,
      "running": false,
      "billable": false,
      "billingStatus": "running",
      "hourlyRateCents": 0,
      "invoicedInvoiceId": "string",
      "invoicedAt": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Either start + end or date (+ optionally startTime) + durationMinutes. At most 24 hours per entry. Without billable, the default of the task or project applies. Triggers time_entry.created.

Permission: time:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · TimeEntryCreate

projectIdstring | null
max. 128 characters
taskIdstring | null
max. 128 characters
contactIdstring | null
without project: customer directly; with project: the project's customer
max. 128 characters
descriptionstring
max. 1000 characters · Default: ""
startstring (date-time)
Start; alternatively `date` + `durationMinutes`
endstring (date-time)
Timestamp (ISO 8601)
datestring (date)
Day (Europe/Berlin) when only a duration is recorded
startTimestring
Time for `date` (default 09:00)
durationMinutesinteger
1–1440
billableboolean
Default: as project/task, otherwise true
hourlyRateCentsinteger | null
Hourly rate in cents (net or gross depending on the invoice)
0–10000000

Response 201 · TimeEntry

idstringrequired
projectIdstring | nullrequired
taskIdstring | nullrequired
contactIdstring | nullrequired
descriptionstringrequired
startstring (date-time)required
Timestamp (ISO 8601)
endstring (date-time) | nullrequired
null while the timer is running
datestring (date)required
Calendar day of the start (Europe/Berlin)
durationMinutesintegerrequired
Duration in minutes; for a running timer, the time elapsed so far
0–9007199254740991
runningbooleanrequired
billablebooleanrequired
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
hourlyRateCentsinteger | nullrequired
different hourly rate; null = rate of the task or project
0–10000000
invoicedInvoiceIdstring | nullrequired
Invoice with which the time was invoiced
invoicedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "startTime": "string",
  "durationMinutes": 1,
  "billable": false,
  "hourlyRateCents": 0
}'

Response 201

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve time entry

GET/api/v1/time-entries/{id}

Permission: time:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · TimeEntry

idstringrequired
projectIdstring | nullrequired
taskIdstring | nullrequired
contactIdstring | nullrequired
descriptionstringrequired
startstring (date-time)required
Timestamp (ISO 8601)
endstring (date-time) | nullrequired
null while the timer is running
datestring (date)required
Calendar day of the start (Europe/Berlin)
durationMinutesintegerrequired
Duration in minutes; for a running timer, the time elapsed so far
0–9007199254740991
runningbooleanrequired
billablebooleanrequired
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
hourlyRateCentsinteger | nullrequired
different hourly rate; null = rate of the task or project
0–10000000
invoicedInvoiceIdstring | nullrequired
Invoice with which the time was invoiced
invoicedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update time entry

PATCH/api/v1/time-entries/{id}

Only the fields you pass. durationMinutes sets the end relative to the start. Invoiced entries are locked (409 time_entry_invoiced). Triggers time_entry.updated.

Permission: time:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · TimeEntryUpdate

projectIdstring | null
max. 128 characters
taskIdstring | null
max. 128 characters
contactIdstring | null
max. 128 characters
descriptionstring
max. 1000 characters
startstring (date-time)
Timestamp (ISO 8601)
endstring (date-time)
Timestamp (ISO 8601)
durationMinutesinteger
sets end = start + duration
1–1440
billableboolean
hourlyRateCentsinteger | null
Hourly rate in cents (net or gross depending on the invoice)
0–10000000

Response 200 · TimeEntry

idstringrequired
projectIdstring | nullrequired
taskIdstring | nullrequired
contactIdstring | nullrequired
descriptionstringrequired
startstring (date-time)required
Timestamp (ISO 8601)
endstring (date-time) | nullrequired
null while the timer is running
datestring (date)required
Calendar day of the start (Europe/Berlin)
durationMinutesintegerrequired
Duration in minutes; for a running timer, the time elapsed so far
0–9007199254740991
runningbooleanrequired
billablebooleanrequired
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
hourlyRateCentsinteger | nullrequired
different hourly rate; null = rate of the task or project
0–10000000
invoicedInvoiceIdstring | nullrequired
Invoice with which the time was invoiced
invoicedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/time-entries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "durationMinutes": 1,
  "billable": false,
  "hourlyRateCents": 0
}'

Response 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete time entry

DELETE/api/v1/time-entries/{id}

Invoiced entries are locked (409 time_entry_invoiced). Triggers time_entry.deleted.

Permission: time:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/time-entries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Stop running time entry

POST/api/v1/time-entries/{id}/stop

Sets the end (default: now). At least 1 minute, at most 24 hours. 409 timer_not_running if the entry is not running.

Permission: time:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · TimerStop

endstring (date-time)
End time (default: now)

Response 200 · TimeEntry

idstringrequired
projectIdstring | nullrequired
taskIdstring | nullrequired
contactIdstring | nullrequired
descriptionstringrequired
startstring (date-time)required
Timestamp (ISO 8601)
endstring (date-time) | nullrequired
null while the timer is running
datestring (date)required
Calendar day of the start (Europe/Berlin)
durationMinutesintegerrequired
Duration in minutes; for a running timer, the time elapsed so far
0–9007199254740991
runningbooleanrequired
billablebooleanrequired
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
hourlyRateCentsinteger | nullrequired
different hourly rate; null = rate of the task or project
0–10000000
invoicedInvoiceIdstring | nullrequired
Invoice with which the time was invoiced
invoicedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/ID/stop' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "end": "2026-11-01T09:30:00.000Z"
}'

Response 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Create draft invoice from time entries

POST/api/v1/time-entries/invoice

Invoices open, billable time of a project (optionally for a period) or selected entries. Creates a draft invoice (without a number, not finalised) and marks the entries as invoiced – in a single transaction. Line items per project, task or entry; quantity = hours (2 decimal places) according to the billing increment. Errors: 400 without customer/hourly rate, 409 time_entries_not_billable, 422 nothing_to_invoice. Triggers invoice.created and time_entry.updated. Continue with POST /invoices/{id}/finalize.

Permission: time:write, invoices:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · TimeInvoiceRequest

projectIdstring
all open, billable time of the project (optionally with from/to)
max. 128 characters
entryIdsArray<string>
or exactly these time entries
max. 128 characters
fromstring (date)
Date (YYYY-MM-DD)
tostring (date)
Date (YYYY-MM-DD)
contactIdstring
Invoice recipient; default: the project's customer
max. 128 characters
groupBy"project" | "task" | "entry"
Default: "task"
roundingMinutesinteger
Billing increment per time entry in minutes
-9007199254740991–9007199254740991 · Default: 1
roundingMode"up" | "nearest"
Default: "up"
taxRatenumber
Tax rate of the line items (for standard taxation)
0–100 · Default: 19
hourlyRateCentsinteger
Rate for entries without an hourly rate
0–10000000
issueDatestring (date)
Invoice date (default: today)
subjectstring
max. 200 characters
introTextstring
max. 5000 characters
closingTextstring
max. 5000 characters

Response 201 · TimeInvoiceResult

invoiceIdstringrequired
ID of the draft invoice (GET /invoices/{id})
status"draft"required
contactIdstringrequired
entryCountintegerrequired
-9007199254740991–9007199254740991
totalMinutesintegerrequired
-9007199254740991–9007199254740991
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/invoice' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "entryIds": [
    "string"
  ],
  "from": "2026-11-01",
  "to": "2026-11-01",
  "contactId": "string",
  "groupBy": "task",
  "roundingMinutes": 1,
  "roundingMode": "up",
  "taxRate": 19,
  "hourlyRateCents": 0,
  "issueDate": "2026-11-01",
  "subject": "string",
  "introText": "string",
  "closingText": "string"
}'

Response 201

{
  "invoiceId": "string",
  "status": "draft",
  "contactId": "string",
  "entryCount": 0,
  "totalMinutes": 0,
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  }
}

Preview: invoice from time entries

POST/api/v1/time-entries/invoice-preview

Like POST /time-entries/invoice, but creates nothing. Returns line items, totals and notices (warnings).

Permission: time:read

Body (JSON) · TimeInvoiceRequest

projectIdstring
all open, billable time of the project (optionally with from/to)
max. 128 characters
entryIdsArray<string>
or exactly these time entries
max. 128 characters
fromstring (date)
Date (YYYY-MM-DD)
tostring (date)
Date (YYYY-MM-DD)
contactIdstring
Invoice recipient; default: the project's customer
max. 128 characters
groupBy"project" | "task" | "entry"
Default: "task"
roundingMinutesinteger
Billing increment per time entry in minutes
-9007199254740991–9007199254740991 · Default: 1
roundingMode"up" | "nearest"
Default: "up"
taxRatenumber
Tax rate of the line items (for standard taxation)
0–100 · Default: 19
hourlyRateCentsinteger
Rate for entries without an hourly rate
0–10000000
issueDatestring (date)
Invoice date (default: today)
subjectstring
max. 200 characters
introTextstring
max. 5000 characters
closingTextstring
max. 5000 characters

Response 200 · TimeInvoicePreview

contactIdstring | nullrequired
contactNamestring | nullrequired
projectIdstring | nullrequired
entryCountintegerrequired
-9007199254740991–9007199254740991
entryIdsArray<string>required
totalMinutesintegerrequired
Minutes after rounding
-9007199254740991–9007199254740991
servicePeriodobject | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
priceMode"net" | "gross"required
taxTreatmentstringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
missingRateEntryIdsArray<string>required
Entries without an hourly rate – without `hourlyRateCents` no invoice is created
warningsArray<string>required

Possible errors: 400, 401, 403, 404, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/invoice-preview' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "entryIds": [
    "string"
  ],
  "from": "2026-11-01",
  "to": "2026-11-01",
  "contactId": "string",
  "groupBy": "task",
  "roundingMinutes": 1,
  "roundingMode": "up",
  "taxRate": 19,
  "hourlyRateCents": 0,
  "issueDate": "2026-11-01",
  "subject": "string",
  "introText": "string",
  "closingText": "string"
}'

Response 200

{
  "contactId": "string",
  "contactName": "string",
  "projectId": "string",
  "entryCount": 0,
  "entryIds": [
    "string"
  ],
  "totalMinutes": 0,
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "priceMode": "net",
  "taxTreatment": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "missingRateEntryIds": [
    "string"
  ],
  "warnings": [
    "string"
  ]
}

Release invoiced time entries

POST/api/v1/time-entries/release

Releases the time entries of an invoice so they can be invoiced again – only if the draft invoice has been deleted or the invoice has been cancelled (otherwise 409 invoice_active). Triggers time_entry.updated for each entry.

Permission: time:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · TimeEntriesRelease

invoiceIdstringrequired
deleted draft or cancelled invoice
max. 128 characters

Response 200 · TimeEntriesReleaseResult

releasedintegerrequired
-9007199254740991–9007199254740991

Possible errors: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/release' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "invoiceId": "string"
}'

Response 200

{
  "released": 0
}

Time report

GET/api/v1/time-entries/summary

Totals per project, task, customer, day, week or month for a period (default: current month). Amounts = exact minutes × hourly rate (entry → task → project); minutes without a rate are listed in missingRateMinutes.

Permission: time:read

Query parameters

fromstring (date)
Default: first day of the current month
tostring (date)
Default: today
projectIdstring
max. 128 characters
contactIdstring
max. 128 characters
groupBy"project" | "task" | "contact" | "day" | "week" | "month"
Default: "project"

Response 200 · TimeSummary

fromstring (date)required
Date (YYYY-MM-DD)
tostring (date)required
Date (YYYY-MM-DD)
groupBy"project" | "task" | "contact" | "day" | "week" | "month"required
totalsobjectrequired
- entriesintegerrequired
  -9007199254740991–9007199254740991
- minutesintegerrequired
  -9007199254740991–9007199254740991
- billableMinutesintegerrequired
  -9007199254740991–9007199254740991
- nonBillableMinutesintegerrequired
  -9007199254740991–9007199254740991
- unbilledMinutesintegerrequired
  -9007199254740991–9007199254740991
- invoicedMinutesintegerrequired
  -9007199254740991–9007199254740991
- billableAmountCentsintegerrequired
  billable time × hourly rate
  -9007199254740991–9007199254740991
- unbilledAmountCentsintegerrequired
  not yet invoiced
  -9007199254740991–9007199254740991
- invoicedAmountCentsintegerrequired
  -9007199254740991–9007199254740991
- missingRateMinutesintegerrequired
  billable minutes without an hourly rate (not included in the amount)
  -9007199254740991–9007199254740991
rowsArray<TimeSummaryRow>required
- keystringrequired
- labelstringrequired
- entriesintegerrequired
  -9007199254740991–9007199254740991
- minutesintegerrequired
  -9007199254740991–9007199254740991
- billableMinutesintegerrequired
  -9007199254740991–9007199254740991
- nonBillableMinutesintegerrequired
  -9007199254740991–9007199254740991
- unbilledMinutesintegerrequired
  -9007199254740991–9007199254740991
- invoicedMinutesintegerrequired
  -9007199254740991–9007199254740991
- billableAmountCentsintegerrequired
  billable time × hourly rate
  -9007199254740991–9007199254740991
- unbilledAmountCentsintegerrequired
  not yet invoiced
  -9007199254740991–9007199254740991
- invoicedAmountCentsintegerrequired
  -9007199254740991–9007199254740991
- missingRateMinutesintegerrequired
  billable minutes without an hourly rate (not included in the amount)
  -9007199254740991–9007199254740991

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries/summary' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "from": "2026-11-01",
  "to": "2026-11-01",
  "groupBy": "project",
  "totals": {
    "entries": 0,
    "minutes": 0,
    "billableMinutes": 0,
    "nonBillableMinutes": 0,
    "unbilledMinutes": 0,
    "invoicedMinutes": 0,
    "billableAmountCents": 0,
    "unbilledAmountCents": 0,
    "invoicedAmountCents": 0,
    "missingRateMinutes": 0
  },
  "rows": [
    {
      "key": "string",
      "label": "string",
      "entries": 0,
      "minutes": 0,
      "billableMinutes": 0,
      "nonBillableMinutes": 0,
      "unbilledMinutes": 0,
      "invoicedMinutes": 0,
      "billableAmountCents": 0,
      "unbilledAmountCents": 0,
      "invoicedAmountCents": 0,
      "missingRateMinutes": 0
    }
  ]
}

Retrieve running timer

GET/api/v1/time-entries/timer

At most one timer runs per account. entry.durationMinutes = time elapsed so far.

Permission: time:read

Response 200 · Timer

runningbooleanrequired
entryTimeEntry | nullrequired
- idstringrequired
- projectIdstring | nullrequired
- taskIdstring | nullrequired
- contactIdstring | nullrequired
- descriptionstringrequired
- startstring (date-time)required
  Timestamp (ISO 8601)
- endstring (date-time) | nullrequired
  null while the timer is running
- datestring (date)required
  Calendar day of the start (Europe/Berlin)
- durationMinutesintegerrequired
  Duration in minutes; for a running timer, the time elapsed so far
  0–9007199254740991
- runningbooleanrequired
- billablebooleanrequired
- billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = rate of the task or project
  0–10000000
- invoicedInvoiceIdstring | nullrequired
  Invoice with which the time was invoiced
- invoicedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries/timer' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "running": false,
  "entry": {
    "id": "string",
    "projectId": "string",
    "taskId": "string",
    "contactId": "string",
    "description": "string",
    "start": "2026-11-01T09:30:00.000Z",
    "end": "2026-11-01T09:30:00.000Z",
    "date": "2026-11-01",
    "durationMinutes": 0,
    "running": false,
    "billable": false,
    "billingStatus": "running",
    "hourlyRateCents": 0,
    "invoicedInvoiceId": "string",
    "invoicedAt": "2026-11-01T09:30:00.000Z",
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z"
  }
}

Start timer

POST/api/v1/time-entries/timer

Creates a running time entry. A timer that is already running is stopped at the start time. Triggers time_entry.created (and, if applicable, time_entry.updated for the stopped one).

Permission: time:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · TimerStart

projectIdstring | null
max. 128 characters
taskIdstring | null
max. 128 characters
contactIdstring | null
max. 128 characters
descriptionstring
max. 1000 characters · Default: ""
billableboolean
startstring (date-time)
Start time (default: now); at most 24 h in the past

Response 201 · TimeEntry

idstringrequired
projectIdstring | nullrequired
taskIdstring | nullrequired
contactIdstring | nullrequired
descriptionstringrequired
startstring (date-time)required
Timestamp (ISO 8601)
endstring (date-time) | nullrequired
null while the timer is running
datestring (date)required
Calendar day of the start (Europe/Berlin)
durationMinutesintegerrequired
Duration in minutes; for a running timer, the time elapsed so far
0–9007199254740991
runningbooleanrequired
billablebooleanrequired
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
hourlyRateCentsinteger | nullrequired
different hourly rate; null = rate of the task or project
0–10000000
invoicedInvoiceIdstring | nullrequired
Invoice with which the time was invoiced
invoicedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/timer' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "",
  "billable": false,
  "start": "2026-11-01T09:30:00.000Z"
}'

Response 201

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Stop running timer

POST/api/v1/time-entries/timer/stop

Stops the running timer without knowing its ID (e.g. for Zapier/Make). 409 timer_not_running if none is running.

Permission: time:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · TimerStop

endstring (date-time)
End time (default: now)

Response 200 · TimeEntry

idstringrequired
projectIdstring | nullrequired
taskIdstring | nullrequired
contactIdstring | nullrequired
descriptionstringrequired
startstring (date-time)required
Timestamp (ISO 8601)
endstring (date-time) | nullrequired
null while the timer is running
datestring (date)required
Calendar day of the start (Europe/Berlin)
durationMinutesintegerrequired
Duration in minutes; for a running timer, the time elapsed so far
0–9007199254740991
runningbooleanrequired
billablebooleanrequired
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"required
hourlyRateCentsinteger | nullrequired
different hourly rate; null = rate of the task or project
0–10000000
invoicedInvoiceIdstring | nullrequired
Invoice with which the time was invoiced
invoicedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/timer/stop' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "end": "2026-11-01T09:30:00.000Z"
}'

Response 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}