Tasks

CRM tasks — the Task object, linking a task to an order or contact, due dates and overdue reminders, and every endpoint for listing, creating, updating and deleting tasks.

A task is a to-do for a project member: call a customer back, send a quote, check a delivery. A task has an assignee (user_uuid), an optional due date, and can be linked to an order or a contact. Creating and completing a linked task is recorded in that order's or contact's journal.

A task is either open or done. When an open task passes its due date, the assignee is notified and the project's task_overdue automations run once. If the due date is moved later, the reminder can fire again.

Field types follow the field notation.

Access

Every endpoint on this page requires both the projects and tasks OAuth scopes. The user must be a member of the project, and the owner's subscription must be active. Otherwise the endpoint returns 404 RES_NOT_FOUND. The project owner bypasses permission checks.

Every endpoint that addresses a task, including updating and deleting it, sees only the tasks within the user's widest view permission. A task outside that range behaves as if it does not exist (404 RES_NOT_FOUND).

The assignee (user_uuid) must be a member of the project; otherwise the request fails with 400 RES_NOT_FOUND. On update it is checked only when it changes.

Task Object

Task Structure

Example Task

{
  "uuid": "0199a7c1-4d5e-7f60-8172-839405a1b2c3",
  "title": "Send the revised quote",
  "description": "Customer wants a price with triple glazing.",
  "status": "open",
  "due_date": "2026-10-03T15:00:00.000Z",
  "user_uuid": "0198e7aa-91f0-7c22-a4d1-0f9e8d7c6b5a",
  "user_name": "Anna Petrova",
  "created_by": "0198e7aa-91f0-7c22-a4d1-0f9e8d7c6b5a",
  "entity_type": "order",
  "entity_uuid": "0199a4e2-7b1c-7c3e-9d2a-5f4e8b1c0a11",
  "entity_name": "26274003",
  "completion_note": null,
  "completed_at": null,
  "created_at": "2026-10-01T09:45:00.000Z",
  "updated_at": "2026-10-01T09:45:00.000Z"
}

Linking a task

entity_type and entity_uuid go together. Send both to link a task, send both as null to unlink it, or omit both. The order or contact must exist in this project; otherwise the request fails with 400 TASK_ENTITY_NOT_FOUND.

What a link records in the entity's journal:

The task_created and task_completed payload is {task_uuid, title, due_date}.

List Tasks

GET /api/v1/projects/{project.uuid}/tasks

Returns the tasks visible to the user. Tasks are sorted by due date, soonest first, with undated tasks last; ties go to the newest task.

Requires one of can_view_own_tasks, can_view_role_tasks, can_view_all_tasks.

Query String Params

Task Filter Structure

Each filter is {"field": ..., "value": ...}. Filters with the same field combine with OR; different fields combine with AND. Filters with an empty value are skipped.

Example Request

All open tasks of one order:

[
  {
    "field": "entity_uuid",
    "value": "0199a4e2-7b1c-7c3e-9d2a-5f4e8b1c0a11"
  },
  {
    "field": "status",
    "value": "open"
  }
]

GET /api/v1/projects/0198e7a0-0000-7000-8000-000000000001/tasks?filters=%5B%7B%22field%22%3A%22entity_uuid%22%2C%22value%22%3A%220199a4e2-7b1c-7c3e-9d2a-5f4e8b1c0a11%22%7D%2C%7B%22field%22%3A%22status%22%2C%22value%22%3A%22open%22%7D%5D
Authorization: Bearer <access_token>

Response

200 OK — an array of task objects.

Errors

Get Task

GET /api/v1/projects/{project.uuid}/tasks/{task.uuid}

Returns a single task.

Requires one of can_view_own_tasks, can_view_role_tasks, can_view_all_tasks.

Errors

Create Task

POST /api/v1/projects/{project.uuid}/tasks

Creates an open task. If it is linked, a task_created entry is written to the entity's journal.

Requires can_edit_tasks.

JSON Params

Example Request

{
  "title": "Send the revised quote",
  "due_date": "2026-10-03T15:00:00Z",
  "entity_type": "order",
  "entity_uuid": "0199a4e2-7b1c-7c3e-9d2a-5f4e8b1c0a11"
}

Response

201 Created

{
  "uuid": "0199a7c1-4d5e-7f60-8172-839405a1b2c3"
}

Errors

Modify Task

PATCH /api/v1/projects/{project.uuid}/tasks/{task.uuid}

Updates only the fields you send.

• Setting status to done sets completed_at and, for a linked task, writes task_completed to the journal. Setting it back to open clears completed_at.
• Changing due_date re-arms the overdue and due-soon reminders.
• Setting completion_note to a new non-empty value copies it into the linked entity's journal as a note.

Requires can_edit_tasks.

JSON Params

All fields are optional, but at least one must be present.

Example Request

{
  "status": "done",
  "completion_note": "Quote sent, customer will reply by Monday."
}

Response

204 No Content

Errors

Replace Task

PUT /api/v1/projects/{project.uuid}/tasks/{task.uuid}

Same as Modify Task, but every field in the table must be present. Nullable fields accept null.

Requires can_edit_tasks.

Response

204 No Content

Errors

Same as Modify Task, except REQ_NO_DATA_PROVIDED.

Delete Task

DELETE /api/v1/projects/{project.uuid}/tasks/{task.uuid}

Permanently deletes the task. Journal entries it has already produced stay.

Requires can_edit_tasks.

Response

204 No Content

Errors