Skip to content
SAVE4545% off every plan.See the offer

API ReferenceTasks & Activities API

Tasks & Activities API

The Tasks & Activities API enables you to manage tasks, log activities (calls, emails, meetings, notes), and track work across your CRM. Tasks can…

On this page· 24

Overview#

The Tasks & Activities API enables you to manage the tasks that live in your projects — the ones you see under Projects → Tasks. You can create tasks and subtasks, put several people on a task, set priorities, statuses, and due dates, work with checklists and linked tasks, and mark tasks complete. You can also manage a project's task lists and automation rules and the folders that group projects. Every task belongs to a project, so you need the project's ID before you create one; it appears in the project's URL in the app (/projects/<id>). Activities (calls, emails, meetings, and notes logged on customer records) are covered at the end of this guide. Every request needs an API key in the Authorization header; see API Overview & Authentication.

Tasks#

List Tasks#

GET /api/tasks

Query Parameters#

  • status (string) — The kind of status: todo, in_progress, review, completed, cancelled.
  • status_id (string) — One of a project's own statuses (see Task Statuses below).
  • project_id (string) — Filter by project.
  • list_id (string) — One of a project's task lists, or null for the tasks in no list (the project's General list).
  • parent_task_id (string) — A task's own subtasks, or null for top-level tasks only.
  • assignee_id (string) — The tasks a person is on, as the lead or not.
  • client_visible (boolean) — true for the tasks shared with the project's client, false for internal ones.
  • limit (integer) — Records per page, from 1 to 1,000. Default: 50.
  • offset (integer) — Records to skip. Default: 0.

Tasks are returned newest first.

Example Request#

curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/tasks?status=todo&project_id=0c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response#

{
  "data": [
    {
      "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "title": "Follow up with Acme Corp",
      "description": "Send proposal revision based on feedback",
      "status": "todo",
      "status_id": "4b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "status_name": "Up next",
      "status_color": "#8b5cf6",
      "list_id": null,
      "list_name": "General",
      "priority": "high",
      "due_date": "2026-03-25T17:00:00Z",
      "assigned_to": "b7e3c1d2-5f6a-4b8c-9d0e-1f2a3b4c5d6e",
      "assignee_ids": ["b7e3c1d2-5f6a-4b8c-9d0e-1f2a3b4c5d6e", "c8f4d2e3-6a7b-4c9d-8e0f-2a3b4c5d6e7f"],
      "project_id": "0c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "parent_task_id": null,
      "client_visible": true,
      "dependencies": null,
      "tags": ["proposal"],
      "estimated_hours": 2,
      "actual_hours": null,
      "recurrence": "none",
      "custom_fields": {},
      "completed_at": null,
      "created_by": "b7e3c1d2-5f6a-4b8c-9d0e-1f2a3b4c5d6e",
      "created_at": "2026-03-20T10:00:00Z",
      "updated_at": "2026-03-20T10:00:00Z",
      "project": {
        "id": "0c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
        "name": "Acme Corp rollout"
      },
      "assignee": {
        "id": "b7e3c1d2-5f6a-4b8c-9d0e-1f2a3b4c5d6e",
        "first_name": "Sarah",
        "last_name": "Johnson",
        "username": "sarah"
      }
    }
  ],
  "count": 1,
  "total": 1,
  "pagination": { "count": 1, "total": 1, "offset": 0, "limit": 25, "has_more": false }
}

Each task embeds its project (id, name) and assignee, its lead (id, first_name, last_name, username). assigned_to is the lead and assignee_ids everyone on the task, the lead first. status is the kind of status and status_name what the task's project calls it (null when the project has no statuses of its own). list_name is the name of the task's list, General when it is in none. count is the number of records in this page and total the number that match; request further pages until pagination.has_more is false.

Get a Task#

GET /api/tasks/:id

Returns a single task with the same fields and embedded objects. Returns 404 when no task with that ID exists in your organization.

Create a Task#

POST /api/tasks

Request Body

  • title (string, required) — Task title.
  • project_id (string, required) — ID of the project the task belongs to. A subtask sent with only its parent_task_id goes in its parent's project.
  • description (string) — Detailed description.
  • status (string) — todo, in_progress, review, completed, or cancelled. Default: todo. On a project with statuses of its own, the task lands on the project's first status of that kind.
  • status_id (string) — One of the project's own statuses (GET /api/task-statuses). It sets status to that status's kind.
  • priority (string) — low, medium, high, or urgent. Default: medium.
  • due_date (string) — Due date in ISO 8601 format.
  • assignee_ids (array) — Everyone on the task, at most 50 members of your organization (not portal clients). The first is the lead. assigned_to (string) still works on its own for a single lead. GET /api/users lists the team.
  • list_id (string) — One of the project's task lists (GET /api/task-lists?project_id=<id>). Left out or null, the task is in the project's General list.
  • parent_task_id (string) — ID of a parent task, to create a subtask (see Subtasks, Checklists, and Linked Tasks).
  • client_visible (boolean) — true shares the task with the project's client on their portal; false keeps it internal, and its subtasks are hidden too. Left out, the task follows its parent task, or else the project.
  • estimated_hours, actual_hours (number) — Time estimates and actuals.
  • tags (array) — Array of tag strings.
  • dependencies (array) — IDs of tasks this task waits on.
  • recurrence (string) — none, daily, weekly, or monthly. Default: none.
  • custom_fields (object) — Your own task fields, by field key (GET /api/custom-fields?entity_type=task).

Fields the API does not write are left out of the task and named in the X-Ignored-Fields response header; they are not an error. An ID that is not a UUID, or not a record or member of your organization, is refused with 400. The response is 201 with the created task.

Example#

curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Send contract to TechStart",
    "project_id": "0c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "assignee_ids": ["b7e3c1d2-5f6a-4b8c-9d0e-1f2a3b4c5d6e"],
    "due_date": "2026-03-28T10:00:00Z",
    "priority": "high",
    "tags": ["contract"]
  }'

Update a Task#

PUT /api/tasks/:id
PATCH /api/tasks/:id

Update task properties. Only include fields you want to change. The response is the updated task. assignee_ids, when sent, is the whole set of people on the task ([] for nobody); sending assigned_to hands the lead to that person. PUT replaces the whole custom_fields object, while PATCH merges the keys you send and removes a key you send as null. A task moved to another project takes its subtasks along and leaves its list.

Complete a Task#

Completing a task is an update of its status. Send completed_at in the same request if you want the completion time recorded:

curl -X PATCH "https://app.automatenexuscrm.com/functions/v1/api/tasks/9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "completed_at": "2026-03-27T15:30:00Z"}'

Delete a Task#

DELETE /api/tasks/:id

Permanently deletes the task. The response is {"message": "Task deleted successfully"}, or 404 ("Task not found").

Search, Bulk, and Export#

  • Search: GET /api/search?q=contract&entities=tasks matches task titles and descriptions and returns up to limit tasks (default 10) under results.tasks.
  • Bulk: POST /api/bulk with "entity_type": "tasks", "operation": "create" or "update", and a data array of up to 200 tasks (updates need each task's id) creates or updates them in one request and reports success_count and error_count.
  • Export: POST /api/export with "entity_type": "tasks" and "format": "json" or "csv" returns every task (up to 50,000), optionally filtered, for example "filters": {"status": "completed"}.

Subtasks, Checklists, and Linked Tasks#

Subtasks#

Create a subtask by sending parent_task_id with the task. A subtask stays in its parent's project, can't sit under one of its own subtasks, and goes at most five levels below a top-level task; the database refuses anything else with a 400 that says why. GET /api/tasks?parent_task_id=<id> lists a task's own subtasks.

GET /api/tasks/:id/subtree

Returns the task, every task under it however deep (each with its depth below the task, 1 for its own subtasks, and each parent before its subtasks), and how many of them are done, with cancelled ones left out:

{
  "task": { ... },
  "subtasks": [
    { "id": "...", "title": "Order the worktops", "parent_task_id": "...", "depth": 1, ... },
    { "id": "...", "title": "Confirm the measurements", "parent_task_id": "...", "depth": 2, ... }
  ],
  "rollup": { "done": 1, "total": 2 }
}

Checklists#

  • GET /api/tasks/:id/checklists — The task's checklists in order, each with its items (text, done, done_by, done_at, assignee_id, due_date) and its progress, plus the task's progress over all of them.
  • POST /api/tasks/:id/checklists — Adds a checklist: {"name": "Before handover", "items": ["Photos", {"text": "Client sign-off", "assignee_id": "..."}]}. Send {"template_id": "..."} instead to copy a checklist template, nothing ticked. A checklist holds at most 300 items.
  • PATCH /api/tasks/:id/checklists/:checklist_id renames or moves a checklist (name, position); DELETE removes it with its items.
  • POST /api/tasks/:id/checklists/:checklist_id/items adds an item (text, done, assignee_id, due_date as YYYY-MM-DD, position). PATCH …/items/:item_id ticks, unticks, edits, or moves one (checklist_id moves it to another checklist of the same task), DELETE removes it, and POST …/items/:item_id/convert turns it into a subtask of the task.

An item's assignee_id must be a member of your team, not a portal client. An item ticked through the API is ticked by the person who made the API key.

Linked Tasks#

  • GET /api/tasks/:id/links — The tasks this one is linked to, in any project. kind is relates_to, duplicates, or duplicated_by, read from this task, and each comes with the other task's title, status, and project.
  • POST /api/tasks/:id/links — {"other_task_id": "...", "kind": "relates_to"} links another task of your organization (kind defaults to relates_to). A task can't be linked to itself, and a pair that is already linked answers 409.
  • DELETE /api/tasks/:id/links/:link_id — Removes a link.

What a task waits on stays in its dependencies, not in its links.

Statuses, Task Lists, Folders, and Project Automations#

Task Statuses#

GET /api/task-statuses lists projects' own task statuses in board order; add project_id for one project's. Each has an id, project_id, name, color, category, and position. Send a status's id as a task's status_id; its category (todo, in_progress, review, completed, or cancelled) becomes the task's status. Statuses are read-only through the API.

Task Lists#

  • GET /api/task-lists?project_id=<id> — A project's lists in order (every project's without project_id). A list's id is what a task's list_id takes.
  • POST /api/task-lists — {"project_id": "...", "name": "Design", "color": "#8b5cf6"}, with an optional position; left out, the list goes at the end. A list stays in its project.
  • GET, PATCH (rename, recolor, or reorder), and DELETE /api/task-lists/:id. Deleting a list moves its tasks to General.

Folders#

  • GET /api/folders — The folders that group projects, in order, each with its project_count. Add workspace_id for one workspace's, and include_archived=true to include archived folders.
  • GET /api/folders/:id — One folder with its projects (id, name, status, progress, workspace_id). This is also a way to find a project's ID.
  • POST /api/folders — {"name": "Client work", "color": "#3b82f6"}, with optional parent_id, workspace_id, and description. Left out, workspace_id is your main workspace. Folders go one level deep.
  • PATCH /api/folders/:id — Rename, recolor, move inside another folder (parent_id), or archive (archived_at; null to unarchive).
  • DELETE /api/folders/:id — Its projects are left in no folder, and its subfolders move to the top level.
  • POST /api/folders/:id/projects and DELETE /api/folders/:id/projects — {"project_ids": [...]}, 1 to 500 IDs, put projects in the folder or take them out. A project goes only into a folder of its own workspace.

Project Automations#

A project's own rules ("when … then …"), the same rules as Automations on the project's page:

  • GET /api/project-automations — The rules in the order they run (project_id, enabled, limit, offset), each with last_run_at, last_status, last_error, and run_count. GET /api/project-automations/:id returns one rule.
  • GET /api/project-automations/:id/runs — Its latest runs: the task, success, error, or skipped, and what it did or why not.
  • POST /api/project-automations — project_id, name, trigger, and actions are required; conditions and enabled are optional. trigger.type is task_created, status_changed (with to_status or to_status_id), assignee_added (user_id), priority_changed (to_priority), due_date_changed, all_subtasks_done, overdue, or due_soon. actions holds 1 to 10 of assign, add_assignees, remove_assignees, set_priority, set_status, create_subtasks, move_due_date, notify, and add_comment. conditions narrows a rule by priority, level (top or subtask), or assignee_id. A rule that makes no sense is refused with a 400 that says why.
  • PATCH /api/project-automations/:id changes a rule or switches it off ("enabled": false); a rule stays in its project. DELETE removes the rule and its runs.
{
  "project_id": "0c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "name": "Client review is urgent",
  "trigger": { "type": "status_changed", "to_status": "review" },
  "conditions": { "level": "top" },
  "actions": [
    { "type": "set_priority", "priority": "high" }
  ]
}

Activities#

Activities are the calls, emails, meetings, and notes logged on contacts, companies, customers, and deals; you see them under CRM → Activities and on each record's timeline. The REST API has no activities resource: activities cannot be listed or created through /api.

To attach a written record to a contact, company, deal, or customer through the API, create a note instead:

curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/notes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Discovery call with Jane Smith",
    "body_text": "Discussed requirements for the Q2 rollout. Interested in the enterprise plan.",
    "target_type": "deal",
    "target_id": "6d2f8b4a-1c3e-4f5a-9b7c-8d9e0f1a2b3c"
  }'

target_type may be contact, company, deal, or customer, and target_id must be a record in your organization. Provide at least a title or body_text. GET /api/notes?target_type=deal&target_id=<id> lists the notes on that record, newest first.

Troubleshooting#

  • 400 mentioning project_id: Every task needs a project_id, unless it is a subtask sent with its parent_task_id. Copy it from the project's URL in the app (/projects/<id>).
  • 400 mentioning status or priority: Use one of the values listed above; they are lowercase with underscores (in_progress). For a project's own status, send its status_id from GET /api/task-statuses.
  • Task not appearing for assignee: assignee_ids and assigned_to take user IDs — the IDs GET /api/users returns, and the same value the assignee.id field returns for existing tasks.
  • A field you sent did not change: Read the X-Ignored-Fields response header. It names each field the API left out.
  • Note not linking to a record: target_type and target_id must both be present, and the record must exist in your organization; otherwise the request returns 400 or 404 and no note is created.

Was this page helpful?

Last updated