Skip to main content
A task is a manual action item — either generated when a sequence reaches a step that needs a human (call, email reply, lead review) or created directly as a standalone to-do. Tasks are assigned to a workspace user until completed, skipped, or reassigned.
Read endpoints require tasks:read. Creating to-dos, executing actionable tasks, skipping, reopening, reassigning, and completing require tasks:write.

​
Task types

​
Task statuses

​
List and filter tasks

GET /v1/tasks supports filters including contact_id, sequence_id, sequence_template_ids (repeat for multiple), types, status, priorities, assignee_user_id, and due-date bounds. GET /v1/tasks/{task_id} returns one task. GET /v1/tasks/{task_id}/messages returns the email thread for reply tasks.

​
Standalone to-dos

POST /v1/tasks creates a TODO task. Required fields: title and due_date (ISO date). Optional: notes, contact_id, assignee_user_id (defaults to the API key owner). PATCH /v1/tasks/{task_id} updates a standalone to-do (title, notes, due_date, assignee_user_id).

​
Execute actionable tasks

POST /v1/tasks/{task_id}/execute runs the task in Topo — send a reply, approve a lead, log a call, etc. The body is a discriminated payload keyed by task type:

​
Complete, skip, reopen, reassign

  • POST /v1/tasks/{task_id}/complete — optional body with completion_source (TASK_EXECUTION, EXTERNAL_REPLY, SEQUENCE_TRANSITION, EXTERNAL_CRM, PLAYBOOK_RESOLUTION; default TASK_EXECUTION) and disposition for CALL tasks (ANSWERED, VOICEMAIL_LEFT, NO_ANSWER)
  • POST /v1/tasks/{task_id}/skip
  • POST /v1/tasks/{task_id}/reopen
  • PATCH /v1/tasks/{task_id}/assignee with { "assignee_user_id": "<uuid>" }
Mark tasks complete from your CRM with completion_source: EXTERNAL_CRM so Topo records the outcome without re-executing the step in-app.