EmpiraaEmpiraaDEVELOPERS Use cases Prompts Playground FAQ empiraa.com

Tasks

Read and manage the to-do items on the /tasks list.

View as MarkdownOpen in ClaudeOpen in ChatGPT

The /tasks endpoints manage a to-do list of items with a title, due date, priority and status, linked to a Deal, Contact, Account or prospect contact.

Looking for Actions? Signal's Actions are activities with type_id rat_action. To create an Action that appears in Signal's Actions list, use POST /activities. Items created with /tasks are stored separately: they show on a linked prospect contact's page in Signal, not in the Actions list.

The task object#

Field Type Notes
id string 25-character ID.
title string
description string or null
due_at string or null ISO 8601 timestamp.
priority string or null Defaults to medium.
is_completed boolean
completed_at string or null Set when the item is marked complete.
status_id string or null See Status IDs.
account_id string or null
contact_id string or null
deal_id string or null
prospect_id string or null
owner_id string or null User ID of the person responsible.
created_at string ISO 8601 timestamp.
updated_at string ISO 8601 timestamp.
JSON
{
  "id": "cm3k9x7r20011qz8fb4e2c9d1",
  "title": "Call back about pricing",
  "description": null,
  "due_at": "2026-11-15T17:00:00.000Z",
  "priority": "high",
  "is_completed": false,
  "completed_at": null,
  "status_id": "rts_todo",
  "account_id": null,
  "contact_id": null,
  "deal_id": null,
  "prospect_id": "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63",
  "owner_id": "5b8d1f3a-7e2c-4a9b-b6d4-1c3e5f7a9b20",
  "created_at": "2026-11-12T09:30:00.000Z",
  "updated_at": "2026-11-12T09:30:00.000Z"
}

Status IDs#

status_id Status
rts_todo To Do
rts_in_progress In Progress
rts_blocked Blocked
rts_done Done
rts_cancelled Cancelled

status_id and is_completed are separate fields. Setting one doesn't change the other.

List tasks#

GET /tasks · Scope: tasks:read

Returns items newest first.

Query parameters#

Parameter Type Required Notes
deal_id string No
contact_id string No
account_id string No
prospect_id string No
owner_id string No
is_completed string No true for completed items only. Any other value returns open items only. Leave out for both.
limit integer No 1 to 100. Default 20.
cursor string No meta.cursor from the previous page.

Example#

curl "https://crm.empiraa.app/api/v1/tasks?owner_id=5b8d1f3a-7e2c-4a9b-b6d4-1c3e5f7a9b20&is_completed=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200#

An array of task objects in data; meta has cursor and hasMore.

Create a task#

POST /tasks · Scope: tasks:write

Request body#

Field Type Required Notes
title string Yes
description string or null No
due_at string or null No ISO 8601 timestamp.
priority string or null No Defaults to medium.
status_id string or null No See Status IDs.
account_id string or null No
contact_id string or null No
deal_id string or null No
prospect_id string or null No
owner_id string or null No A user ID from GET /users.

The linked records must be in your workspace and owner_id must be an active member, or the request answers 404 NOT_FOUND. See Linked records.

Example#

curl -X POST https://crm.empiraa.app/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Call back about pricing", "due_at": "2026-11-15T17:00:00Z", "priority": "high", "prospect_id": "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63"}'

Response 201#

The new task object in data.

Errors#

Status Code When
400 INVALID_REQUEST title is missing, due_at isn't a date, or a linked id isn't a string or null.
404 NOT_FOUND A linked Account, Contact, Deal or prospect contact isn't in this workspace (title says which), or owner_id isn't an active member of the workspace.

Webhook events: none. Starts any Autopilot workflows that run when a task is created.

Get a task#

GET /tasks/{id} · Scope: tasks:read

Example#

curl https://crm.empiraa.app/api/v1/tasks/cm3k9x7r20011qz8fb4e2c9d1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200#

The task object in data.

Errors#

Status Code When
404 NOT_FOUND No task with that ID in this workspace.

Update a task#

PATCH /tasks/{id} · Scope: tasks:write

Send only the fields you want to change: any field from create, plus is_completed (boolean). Setting is_completed to true sets completed_at to now; false clears it.

Example#

curl -X PATCH https://crm.empiraa.app/api/v1/tasks/cm3k9x7r20011qz8fb4e2c9d1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_completed": true, "status_id": "rts_done"}'

Response 200#

The updated task object in data.

Errors#

Status Code When
400 INVALID_REQUEST due_at isn't a date, or a linked id isn't a string or null.
404 NOT_FOUND No task with that ID in this workspace, a linked record isn't in it, or owner_id isn't an active member of the workspace.

Webhook events: none. Starts any Autopilot workflows that run when a task is updated or completed.

Delete a task#

DELETE /tasks/{id} · Scope: tasks:write

Deletes the item permanently.

Example#

curl -X DELETE https://crm.empiraa.app/api/v1/tasks/cm3k9x7r20011qz8fb4e2c9d1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 204#

No body.

Errors#

Status Code When
404 NOT_FOUND No task with that ID in this workspace.

Webhook events: none. Starts any Autopilot workflows that run when a task is deleted.