Tasks

Tasks represent workflow items that can be assigned to users within a client account. Tasks support hierarchical organization through subtasks and integrate with the chat system for communication.

Endpoints

List Tasks

GET /api/v2/tasks

Retrieves a paginated list of tasks.

Query Parameters

Response

{
  "data": [
    {
      "id": 1,
      "title": "Review Q1 journal entries",
      "description": "Check all journal entries for Q1 2024",
      "status": "PENDING",
      "task_type": "EXECUTION",
      "completed_at": null,
      "completion_summary": null,
      "client_account_id": 7,
      "assigned_to_id": 7,
      "provider_client_account_id": null,
      "parent_task_id": null,
      "relation_type": null,
      "relation_id": null,
      "thread_id": 42,
      "created_at": "2024-03-15T10:00:00Z",
      "updated_at": "2024-03-15T10:00:00Z",
      "created_by_id": 7,
      "updated_by_id": null
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 1
  }
}

Create Task

POST /api/v2/tasks

Creates a new task.

Request Body

Response

Returns the created task with status 201 Created.

Get Task

GET /api/v2/tasks/{id}

Retrieves a specific task by ID.

Response

Returns a single task object.

Update Task

PUT /api/v2/tasks/{id}

Updates an existing task.

Request Body

Same fields as Create Task. All fields are optional for updates — only the fields present in the body are applied.

client_account_id may be sent, but only with the task’s current value: moving a task to another client account is rejected with task.client_account_immutable. provider_client_account_id, assigned_to_id and relation_type/relation_id are re-checked against the task’s client account only when they change, so editing an old task whose assignee has since lost access still works.

Response

Returns the updated task.

Delete Task

DELETE /api/v2/tasks/{id}

Deletes a task and its associated chat channel.

Response

Returns 204 No Content on success.

Attributes

Relationships

Neither is included by default — request them with ?with=subtasks or ?with=parent_task. parent_task is omitted from the response when the task has no parent.

Business Rules

1. Deleting a task also deletes its associated chat channel
2. Tasks can be organized hierarchically using parent_task_id; a parent task must belong to the same client account
3. Each task automatically gets a chat thread for discussion
4. A task’s client_account_id is fixed once the task exists
5. Every id a task carries must stay inside its client account: the provider firm must have access to it (through its own account or an active contract), the assignee must be able to access it, and relation_id must name a row owned by it

Error Responses

Errors use the standard v2 envelope ({"error": {"code", "message", "request_id"}}) — see Error Handling.

Related Resources

• Chat
• Users
• Client Accounts