Tasks

Tasks are action items that can be assigned to users and linked to other records. Clarify automatically creates tasks from meeting action items, but you can also create them via the API.

Fields

The description field uses BlockNote JSON — a structured block format, not plain text or markdown. If you pass a string, the UI will render it as a single paragraph block. See Rich text fields below for the full shape.

Tasks also support relationship fields to link them to other records — see relationships.

Create a task

POST /objects/task/records

{
  "data": {
    "type": "task",
    "attributes": {
      "title": "Send proposal to Acme Corp",
      "status": "To Do",
      "priority": "High",
      "due_date": "2024-04-01",
      "assignee_id": "usr_01HX9Z2K3M4N5P6Q7R8S9T0U"
    }
  }
}

Tasks don't have a unique field for upsert matching — every POST creates a new record.

Update a task

PATCH /objects/task/records/{id}

{
  "data": {
    "type": "task",
    "attributes": {
      "status": "Done"
    }
  }
}

Link a task to a record

Set the relationship field when creating or updating:

{
  "data": {
    "type": "task",
    "attributes": {
      "title": "Follow up after discovery call",
      "status": "To Do",
      "priority": "Medium",
      "person_id": "per_01HX9Z2K3M4N5P6Q7R8S9T0U",
      "deal_id": "deal_01HX9Z2K3M4N5P6Q7R8S9T0V"
    }
  }
}

List tasks

GET /objects/task/resources

Returns a paginated list of tasks. Supports the same filtering and sorting as other record types — see search and filter.

Common filters:

# Open tasks assigned to a user
GET /objects/task/resources?filter[status][In]=To Do,In Progress&filter[assignee_id][Equals]=usr_01HX...

# Overdue tasks
GET /objects/task/resources?filter[due_date][LessThan]=2024-04-01&filter[status][In]=To Do,In Progress

Bulk operations

Tasks support the same bulk create, update, and delete endpoints as other record types — see records for details. Use object type task in the path:

• POST /objects/task/records/bulk — bulk create (max 25)
• PATCH /objects/task/records — bulk update
• DELETE /objects/task/records — bulk delete

User IDs

assignee_id returns an opaque identifier — not a name or email. The format depends on the user's auth provider:

• WorkOS: user_01K59WY3MBB1KE6SZSKNEW1RDR
• Google OAuth: google-oauth2|106236165388989412707
• Automated (system actor): system (only on _created_by/_updated_by)

There is no public users endpoint to resolve these IDs. The same applies to _created_by and _updated_by on every record type.

Rich text fields

The description field uses BlockNote JSON — the same format Clarify's UI editor produces. Each top-level entry is a block (paragraph, heading, bullet list item, etc.) with an array of inline text runs.

Minimum-viable example: a single paragraph.

{
  "data": {
    "type": "task",
    "attributes": {
      "title": "Send proposal to Acme Corp",
      "description": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "Follow up after the meeting on " },
            { "type": "text", "text": "Tuesday", "styles": { "bold": true } },
            { "type": "text", "text": " with the proposal." }
          ]
        }
      ]
    }
  }
}

Common block types: paragraph, heading (with props.level: 1–3), bulletListItem, numberedListItem, checkListItem. Inline text runs accept styles: bold, italic, underline, strike, code.

If you only need plain text, the simplest payload is one paragraph with a single text run:

{ "description": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Plain text body." }] }] }

The same description shape is returned on GET requests, so you can round-trip it. If you want to render plain text from a description you fetched, walk the block tree and concatenate the inline text values.