> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/endpoints/tasks.md).

# Tasks

In the API, a task is an `activities` record, so tasks live at `/v2/activities`. They support every request on the [Records](/api/endpoints/records.md) page: list, get, history, create, update, delete and search.

## Creating a task

```bash
curl -X POST "https://api.tiny.plus/v2/activities" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
        "description": "Send the revised fee proposal",
        "related_id": "1343",
        "related_type": "projects",
        "due_date": "2026-10-15",
        "assigned_user": "1231"
      }'
```

```javascript
{
    "id": "161083"
}
```

* `description` is the task itself. The task's `name` is set from its first 200 characters.
* `related_id` is the project, company or contact the task is about, and `related_type` is that record's type, such as `projects`. Deleting that record deletes its tasks.
* `due_date` is a date, `YYYY-MM-DD`. If you leave it out, it's set to a week from today.
* `assigned_user` has no default, so send one. The team member it names joins the task's team.
* A new task's `record_status` is `open`.

To complete a task, set its `record_status` to `completed`.

## Reminders

At 7am on a task's due date, on the account's clock, tiny+ reminds the task's subscribers, if it's still open. They include the team member who created it and the one it's assigned to.

## Finding tasks

The open tasks assigned to one team member, soonest first:

```bash
curl "https://api.tiny.plus/v2/activities?assigned_user=1231&record_status=open&sort=due_date&fields=id,name,due_date,related_id&return_format=array&with_related=0" \
  -H "Authorization: Bearer {{user_access_token}}"
```

```javascript
{
    "total_records": 3,
    "returned_records": 3,
    "records": [
        {
            "id": "161083",
            "name": "Send the revised fee proposal",
            "due_date": "2026-10-15",
            "related_id": "1343",
            "show_obscured": false
        },
        ...
    ]
}
```

{% hint style="info" %}
A task's `record_status` only takes one value per filter. `record_status=open,completed` looks for a status with that exact name, and finds nothing.
{% endhint %}

## Follow-ups on a relationship plan

A [relationship plan](/api/endpoints/relationship-plans.md) books its follow-ups as tasks, so they come back from `/v2/activities` like any other task. Six fields say which plan a task belongs to, and when a task was finished. tiny+ sets them, and they can't be changed through the API.

| Field                              | Meaning                                                                                                               |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `plan_id`                          | The plan the task is a follow-up on. `null` for an ordinary task.                                                     |
| `plan_step_id`, `plan_occurrence`  | The plan's step, and which repeat of it this is.                                                                      |
| `touch_type`                       | How the follow-up is to be done, such as `call`. See [Touch types](/api/endpoints/relationship-plans.md#touch-types). |
| `completed_date`, `completed_user` | When the task was completed, in UTC, and the team member who completed it. Every task has these, not only follow-ups. |

* `GET /v2/activities?plan_id={id}` lists a plan's follow-ups, open and completed.
* A follow-up's `related_id` is the plan's company, and the contacts it is with are linked to it. To find a contact's follow-ups, use [`linked_to`](/api/concepts/listing.md#records-linked-to-another-record).
* Completing a follow-up counts as done on its plan, without notes, and the plan books the next one. Deleting it counts as skipping it. To record what was said, [log it on the plan](/api/endpoints/relationship-plans.md#log-a-follow-up) instead.

## Fields

| Field           | Label in tiny+      | Type        | Notes                                                                              | Editable |
| --------------- | ------------------- | ----------- | ---------------------------------------------------------------------------------- | -------- |
| `description`   | Your task           | Text        | Required. The task itself. The task's `name` is set from its first 200 characters. | Yes      |
| `due_date`      | Due Date            | Date        | `YYYY-MM-DD`. A week from today, unless you send another.                          | Yes      |
| `record_status` | Activity Status     | Option      | `open` or `completed`. `open` unless you send another.                             | Yes      |
| `related_id`    | Related To          | Record id   | The id of the record the task is about. Deleting that record deletes the task.     | Yes      |
| `related_type`  | Related Record Type | Record type | The type of the record the task is about, such as `projects`.                      | Yes      |
| `reminder_sent` | Reminder Sent?      | Yes/no      | `1` once the task's reminder has been sent.                                        | No       |