> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks API — Manage Manual Outreach and Standalone To-Dos

> List, create, execute, complete, skip, reopen, and reassign tasks — including sequence steps and standalone to-do items.

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.

<Note>
  Read endpoints require `tasks:read`. Creating to-dos, executing actionable tasks, skipping, reopening, reassigning, and completing require `tasks:write`.
</Note>

## Task types

| Type                | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `CALL`              | Place a phone call to the contact.                       |
| `EMAIL_REPLY`       | Send or review an email reply in an active thread.       |
| `LINKEDIN_REPLY`    | Reply to a LinkedIn conversation.                        |
| `NEW_LEAD_REVIEW`   | Review and approve or reject a new lead before outreach. |
| `PLAYBOOK_APPROVAL` | Approve or reject a playbook-generated action.           |
| `TODO`              | Standalone to-do not tied to a sequence step.            |

## Task statuses

| Status        | Description                                      |
| ------------- | ------------------------------------------------ |
| `PENDING`     | Open and waiting for action.                     |
| `IN_PROGRESS` | Opened by an assignee and actively being worked. |
| `COMPLETED`   | Carried out and marked done.                     |
| `SKIPPED`     | Deliberately skipped without execution.          |

## 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:

| `payload.type`      | Used for                                       |
| ------------------- | ---------------------------------------------- |
| `email_reply`       | `EMAIL_REPLY` tasks                            |
| `linkedin_reply`    | `LINKEDIN_REPLY` tasks                         |
| `new_lead_review`   | `NEW_LEAD_REVIEW` tasks                        |
| `call`              | `CALL` tasks (optional `phone`, `disposition`) |
| `playbook_approval` | `PLAYBOOK_APPROVAL` tasks                      |

## 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>" }`

<Tip>
  Mark tasks complete from your CRM with `completion_source: EXTERNAL_CRM` so Topo records the outcome without re-executing the step in-app.
</Tip>