Projects – API reference

List projects

GET/api/v1/projects

Newest first. Filter by status and customer.

Permission: projects:read

Query parameters

status"active" | "done" | "archived"
only projects with this status
contactIdstring
only projects of this customer
max. 128 characters
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<Project>required
- idstringrequired
- numberstring | nullrequired
  Project number from the "project" number range
- namestringrequired
- descriptionstring | nullrequired
- contactIdstring | nullrequired
  Customer (contact ID)
- contactNamestring | nullrequired
  Display name of the customer
- status"active" | "done" | "archived"required
- budgetProjectBudget | nullrequired
- hourlyRateCentsinteger | nullrequired
  Hourly rate in cents (net or gross depending on the invoice)
  0–10000000
- billablebooleanrequired
  Default for new time entries
- startDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- endDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- tasksArray<ProjectTask>required
  - idstringrequired
  - namestringrequired
  - hourlyRateCentsinteger | nullrequired
    different hourly rate; null = project rate
    0–10000000
  - billableboolean | nullrequired
    null = as project
  - donebooleanrequired
- archivedAtstring (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/projects' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "number": "string",
      "name": "string",
      "description": "string",
      "contactId": "string",
      "contactName": "string",
      "status": "active",
      "budget": null,
      "hourlyRateCents": 0,
      "billable": false,
      "startDate": "2026-11-01",
      "endDate": "2026-11-01",
      "tasks": [
        {
          "id": null,
          "name": null,
          "hourlyRateCents": null,
          "billable": null,
          "done": null
        }
      ],
      "archivedAt": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Customer (contactId), budget in hours or euros, hourly rate and optional tasks. The project number comes from the project number range (can be turned off with assignNumber: false). Triggers project.created.

Permission: projects: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) · ProjectCreate

namestringrequired
max. 160 characters
descriptionstring | null
max. 2000 characters
contactIdstring | null
max. 128 characters
status"active" | "done" | "archived"
Default: "active"
budgetProjectBudget | null
hourlyRateCentsinteger | null
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billableboolean
Default: true
startDatestring (date) | null
Date (YYYY-MM-DD)
endDatestring (date) | null
Date (YYYY-MM-DD)
tasksArray<object>
- namestringrequired
  max. 120 characters
- hourlyRateCentsinteger | null
  Hourly rate in cents (net or gross depending on the invoice)
  0–10000000
- billableboolean | null
assignNumberboolean
Assign project number from the number range
Default: true

Response 201 · Project

idstringrequired
numberstring | nullrequired
Project number from the "project" number range
namestringrequired
descriptionstring | nullrequired
contactIdstring | nullrequired
Customer (contact ID)
contactNamestring | nullrequired
Display name of the customer
status"active" | "done" | "archived"required
budgetProjectBudget | nullrequired
hourlyRateCentsinteger | nullrequired
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billablebooleanrequired
Default for new time entries
startDatestring (date) | nullrequired
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
tasksArray<ProjectTask>required
- idstringrequired
- namestringrequired
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = project rate
  0–10000000
- billableboolean | nullrequired
  null = as project
- donebooleanrequired
archivedAtstring (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/projects' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "contactId": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": true,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01",
  "tasks": [
    {
      "name": "string",
      "hourlyRateCents": 0,
      "billable": false
    }
  ],
  "assignNumber": true
}'

Response 201

{
  "id": "string",
  "number": "string",
  "name": "string",
  "description": "string",
  "contactId": "string",
  "contactName": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": false,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01",
  "tasks": [
    {
      "id": "string",
      "name": "string",
      "hourlyRateCents": 0,
      "billable": false,
      "done": false
    }
  ],
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve project

GET/api/v1/projects/{id}

Permission: projects:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · Project

idstringrequired
numberstring | nullrequired
Project number from the "project" number range
namestringrequired
descriptionstring | nullrequired
contactIdstring | nullrequired
Customer (contact ID)
contactNamestring | nullrequired
Display name of the customer
status"active" | "done" | "archived"required
budgetProjectBudget | nullrequired
hourlyRateCentsinteger | nullrequired
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billablebooleanrequired
Default for new time entries
startDatestring (date) | nullrequired
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
tasksArray<ProjectTask>required
- idstringrequired
- namestringrequired
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = project rate
  0–10000000
- billableboolean | nullrequired
  null = as project
- donebooleanrequired
archivedAtstring (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/projects/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "number": "string",
  "name": "string",
  "description": "string",
  "contactId": "string",
  "contactName": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": false,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01",
  "tasks": [
    {
      "id": "string",
      "name": "string",
      "hourlyRateCents": 0,
      "billable": false,
      "done": false
    }
  ],
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update project

PATCH/api/v1/projects/{id}

Only the fields you pass are changed. status: "archived" archives the project (event project.archived). A new customer is carried over to time entries that have not yet been invoiced.

Permission: projects:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · ProjectUpdate

namestring
max. 160 characters
descriptionstring | null
max. 2000 characters
contactIdstring | null
max. 128 characters
status"active" | "done" | "archived"
budgetProjectBudget | null
hourlyRateCentsinteger | null
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billableboolean
startDatestring (date) | null
Date (YYYY-MM-DD)
endDatestring (date) | null
Date (YYYY-MM-DD)

Response 200 · Project

idstringrequired
numberstring | nullrequired
Project number from the "project" number range
namestringrequired
descriptionstring | nullrequired
contactIdstring | nullrequired
Customer (contact ID)
contactNamestring | nullrequired
Display name of the customer
status"active" | "done" | "archived"required
budgetProjectBudget | nullrequired
hourlyRateCentsinteger | nullrequired
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billablebooleanrequired
Default for new time entries
startDatestring (date) | nullrequired
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
tasksArray<ProjectTask>required
- idstringrequired
- namestringrequired
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = project rate
  0–10000000
- billableboolean | nullrequired
  null = as project
- donebooleanrequired
archivedAtstring (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 -X PATCH 'https://www.debt-flow.io/api/v1/projects/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "contactId": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": false,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01"
}'

Response 200

{
  "id": "string",
  "number": "string",
  "name": "string",
  "description": "string",
  "contactId": "string",
  "contactName": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": false,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01",
  "tasks": [
    {
      "id": "string",
      "name": "string",
      "hourlyRateCents": 0,
      "billable": false,
      "done": false
    }
  ],
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete project

DELETE/api/v1/projects/{id}

Only projects without time entries (otherwise 409 project_has_entries – archive instead).

Permission: projects: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/projects/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Project report

GET/api/v1/projects/{id}/summary

Recorded, billable, open and invoiced time and amounts over the entire duration, budget usage and breakdown by task. Amounts = exact minutes × hourly rate (without billing increment).

Permission: projects:read, time:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · ProjectSummary

projectIdstringrequired
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
firstDatestring (date) | nullrequired
Date (YYYY-MM-DD)
lastDatestring (date) | nullrequired
Date (YYYY-MM-DD)
budgetProjectBudget | nullrequired
budgetUsedPercentnumber | nullrequired
budget used in per cent (hours: all recorded; amount: billable amount)
budgetRemainingnumber | nullrequired
Remaining in hours or cents
byTaskArray<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, 404, 429, 500

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

Response 200

{
  "projectId": "string",
  "entries": 0,
  "minutes": 0,
  "billableMinutes": 0,
  "nonBillableMinutes": 0,
  "unbilledMinutes": 0,
  "invoicedMinutes": 0,
  "billableAmountCents": 0,
  "unbilledAmountCents": 0,
  "invoicedAmountCents": 0,
  "missingRateMinutes": 0,
  "firstDate": "2026-11-01",
  "lastDate": "2026-11-01",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "budgetUsedPercent": 0,
  "budgetRemaining": 0,
  "byTask": [
    {
      "key": "string",
      "label": "string",
      "entries": 0,
      "minutes": 0,
      "billableMinutes": 0,
      "nonBillableMinutes": 0,
      "unbilledMinutes": 0,
      "invoicedMinutes": 0,
      "billableAmountCents": 0,
      "unbilledAmountCents": 0,
      "invoicedAmountCents": 0,
      "missingRateMinutes": 0
    }
  ]
}

Add task to project

POST/api/v1/projects/{id}/tasks

Tasks are optional. A task's own hourly rate/billable setting overrides the project values. Response: the updated project.

Permission: projects: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) · ProjectTaskCreate

namestringrequired
max. 120 characters
hourlyRateCentsinteger | null
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billableboolean | null

Response 201 · Project

idstringrequired
numberstring | nullrequired
Project number from the "project" number range
namestringrequired
descriptionstring | nullrequired
contactIdstring | nullrequired
Customer (contact ID)
contactNamestring | nullrequired
Display name of the customer
status"active" | "done" | "archived"required
budgetProjectBudget | nullrequired
hourlyRateCentsinteger | nullrequired
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billablebooleanrequired
Default for new time entries
startDatestring (date) | nullrequired
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
tasksArray<ProjectTask>required
- idstringrequired
- namestringrequired
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = project rate
  0–10000000
- billableboolean | nullrequired
  null = as project
- donebooleanrequired
archivedAtstring (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/projects/ID/tasks' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "hourlyRateCents": 0,
  "billable": false
}'

Response 201

{
  "id": "string",
  "number": "string",
  "name": "string",
  "description": "string",
  "contactId": "string",
  "contactName": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": false,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01",
  "tasks": [
    {
      "id": "string",
      "name": "string",
      "hourlyRateCents": 0,
      "billable": false,
      "done": false
    }
  ],
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update task

PATCH/api/v1/projects/{id}/tasks/{taskId}

Name, hourly rate, billable or done. Response: the updated project.

Permission: projects:write

Path parameters

idstringrequired
max. 128 characters
taskIdstringrequired
Task ID
max. 128 characters

Body (JSON) · ProjectTaskUpdate

namestring
max. 120 characters
hourlyRateCentsinteger | null
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billableboolean | null
doneboolean

Response 200 · Project

idstringrequired
numberstring | nullrequired
Project number from the "project" number range
namestringrequired
descriptionstring | nullrequired
contactIdstring | nullrequired
Customer (contact ID)
contactNamestring | nullrequired
Display name of the customer
status"active" | "done" | "archived"required
budgetProjectBudget | nullrequired
hourlyRateCentsinteger | nullrequired
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billablebooleanrequired
Default for new time entries
startDatestring (date) | nullrequired
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
tasksArray<ProjectTask>required
- idstringrequired
- namestringrequired
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = project rate
  0–10000000
- billableboolean | nullrequired
  null = as project
- donebooleanrequired
archivedAtstring (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 -X PATCH 'https://www.debt-flow.io/api/v1/projects/ID/tasks/TASKID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "hourlyRateCents": 0,
  "billable": false,
  "done": false
}'

Response 200

{
  "id": "string",
  "number": "string",
  "name": "string",
  "description": "string",
  "contactId": "string",
  "contactName": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": false,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01",
  "tasks": [
    {
      "id": "string",
      "name": "string",
      "hourlyRateCents": 0,
      "billable": false,
      "done": false
    }
  ],
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete task

DELETE/api/v1/projects/{id}/tasks/{taskId}

Only tasks without time entries (otherwise 409 task_has_entries – mark as done instead). Response: the updated project.

Permission: projects:write

Path parameters

idstringrequired
max. 128 characters
taskIdstringrequired
Task ID
max. 128 characters

Response 200 · Project

idstringrequired
numberstring | nullrequired
Project number from the "project" number range
namestringrequired
descriptionstring | nullrequired
contactIdstring | nullrequired
Customer (contact ID)
contactNamestring | nullrequired
Display name of the customer
status"active" | "done" | "archived"required
budgetProjectBudget | nullrequired
hourlyRateCentsinteger | nullrequired
Hourly rate in cents (net or gross depending on the invoice)
0–10000000
billablebooleanrequired
Default for new time entries
startDatestring (date) | nullrequired
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
tasksArray<ProjectTask>required
- idstringrequired
- namestringrequired
- hourlyRateCentsinteger | nullrequired
  different hourly rate; null = project rate
  0–10000000
- billableboolean | nullrequired
  null = as project
- donebooleanrequired
archivedAtstring (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 DELETE 'https://www.debt-flow.io/api/v1/projects/ID/tasks/TASKID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "number": "string",
  "name": "string",
  "description": "string",
  "contactId": "string",
  "contactName": "string",
  "status": "active",
  "budget": {
    "type": "hours",
    "hours": 0
  },
  "hourlyRateCents": 0,
  "billable": false,
  "startDate": "2026-11-01",
  "endDate": "2026-11-01",
  "tasks": [
    {
      "id": "string",
      "name": "string",
      "hourlyRateCents": 0,
      "billable": false,
      "done": false
    }
  ],
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}