> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/task.md).

# The task object

The task object in the Shortcut API - every field, an example, and the endpoints that return it.

A to-do for the office, often about a customer, lead, or estimate.

## Fields

| Field           | Type                  | Description                                   |
| --------------- | --------------------- | --------------------------------------------- |
| `id`            | id                    | The task's id.                                |
| `object`        | `"task"`              | Always `task`.                                |
| `name`          | string                | What to do.                                   |
| `description`   | string or null        | More detail, when there is any.               |
| `status`        | `pending`, `complete` | Whether the task is done.                     |
| `deadline`      | timestamp or null     | When it is due, ISO 8601 in UTC.              |
| `completedAt`   | timestamp or null     | When it was completed.                        |
| `assignee`      | object or null        | Who it is assigned to; null when unassigned.  |
| `assignee.id`   | id                    | The staff member's id (`GET /v1/users/{id}`). |
| `assignee.name` | string or null        | Their name.                                   |
| `customerId`    | id or null            | The customer it is for.                       |
| `leadId`        | id or null            | The lead it is for.                           |
| `estimateId`    | id or null            | The estimate it is for.                       |
| `createdAt`     | timestamp             | When it was created, ISO 8601 in UTC.         |
| `updatedAt`     | timestamp             | When it last changed, ISO 8601 in UTC.        |

## Example

```json
{
  "id": "edd27dac-ea1c-48f3-8666-f43ae2b12f81",
  "object": "task",
  "name": "Weekly mowing",
  "description": null,
  "status": "pending",
  "deadline": "2026-10-16T17:04:12.381Z",
  "completedAt": null,
  "assignee": {
    "id": "a1dce0f3-9e27-4c3a-8a71-578196bb92c8",
    "name": "Weekly mowing"
  },
  "customerId": "5c425948-588c-448f-84d6-cfd651210b1d",
  "leadId": "9bfa4982-9844-44c9-848e-c01090d8fb57",
  "estimateId": "e18b885a-ddd5-43a1-8a1f-fee8d66a3a2f",
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z"
}
```

## Endpoints

| Endpoint                       | What it does            |
| ------------------------------ | ----------------------- |
| `GET /v1/customers/{id}/tasks` | List a customer's tasks |
| `GET /v1/tasks`                | List tasks              |
| `POST /v1/tasks`               | Create a task           |
| `GET /v1/tasks/{id}`           | Get a task              |
| `PATCH /v1/tasks/{id}`         | Update a task           |
