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/tasksQuery 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
nullfor the tasks in no list (the project's General list). - parent_task_id (string) — A task's own subtasks, or
nullfor top-level tasks only. - assignee_id (string) — The tasks a person is on, as the lead or not.
- client_visible (boolean) —
truefor the tasks shared with the project's client,falsefor 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/:idReturns 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/tasksRequest 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_idgoes in its parent's project. - description (string) — Detailed description.
- status (string) —
todo,in_progress,review,completed, orcancelled. 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 setsstatusto that status's kind. - priority (string) —
low,medium,high, orurgent. 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/userslists the team. - list_id (string) — One of the project's task lists (
GET /api/task-lists?project_id=<id>). Left out ornull, 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) —
trueshares the task with the project's client on their portal;falsekeeps 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, ormonthly. 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/:idUpdate 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/:idPermanently 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=tasksmatches task titles and descriptions and returns up tolimittasks (default 10) underresults.tasks. - Bulk:
POST /api/bulkwith"entity_type": "tasks","operation": "create"or"update", and adataarray of up to 200 tasks (updates need each task'sid) creates or updates them in one request and reportssuccess_countanderror_count. - Export:
POST /api/exportwith"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/subtreeReturns 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 itsprogress, 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_idrenames or moves a checklist (name,position);DELETEremoves it with its items.POST /api/tasks/:id/checklists/:checklist_id/itemsadds an item (text,done,assignee_id,due_dateas YYYY-MM-DD,position).PATCH …/items/:item_idticks, unticks, edits, or moves one (checklist_idmoves it to another checklist of the same task),DELETEremoves it, andPOST …/items/:item_id/convertturns 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.kindisrelates_to,duplicates, orduplicated_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 (kinddefaults torelates_to). A task can't be linked to itself, and a pair that is already linked answers409.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 withoutproject_id). A list'sidis what a task'slist_idtakes.POST /api/task-lists—{"project_id": "...", "name": "Design", "color": "#8b5cf6"}, with an optionalposition; left out, the list goes at the end. A list stays in its project.GET,PATCH(rename, recolor, or reorder), andDELETE /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 itsproject_count. Addworkspace_idfor one workspace's, andinclude_archived=trueto 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 optionalparent_id,workspace_id, anddescription. Left out,workspace_idis your main workspace. Folders go one level deep.PATCH /api/folders/:id— Rename, recolor, move inside another folder (parent_id), or archive (archived_at;nullto unarchive).DELETE /api/folders/:id— Its projects are left in no folder, and its subfolders move to the top level.POST /api/folders/:id/projectsandDELETE /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 withlast_run_at,last_status,last_error, andrun_count.GET /api/project-automations/:idreturns one rule.GET /api/project-automations/:id/runs— Its latest runs: the task,success,error, orskipped, and what it did or why not.POST /api/project-automations—project_id,name,trigger, andactionsare required;conditionsandenabledare optional.trigger.typeistask_created,status_changed(withto_statusorto_status_id),assignee_added(user_id),priority_changed(to_priority),due_date_changed,all_subtasks_done,overdue, ordue_soon.actionsholds 1 to 10 ofassign,add_assignees,remove_assignees,set_priority,set_status,create_subtasks,move_due_date,notify, andadd_comment.conditionsnarrows a rule bypriority,level(toporsubtask), orassignee_id. A rule that makes no sense is refused with a400that says why.PATCH /api/project-automations/:idchanges a rule or switches it off ("enabled": false); a rule stays in its project.DELETEremoves 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 aproject_id, unless it is a subtask sent with itsparent_task_id. Copy it from the project's URL in the app (/projects/<id>). - 400 mentioning
statusorpriority: Use one of the values listed above; they are lowercase with underscores (in_progress). For a project's own status, send itsstatus_idfromGET /api/task-statuses. - Task not appearing for assignee:
assignee_idsandassigned_totake user IDs — the IDsGET /api/usersreturns, and the same value theassignee.idfield returns for existing tasks. - A field you sent did not change: Read the
X-Ignored-Fieldsresponse header. It names each field the API left out. - Note not linking to a record:
target_typeandtarget_idmust both be present, and the record must exist in your organization; otherwise the request returns400or404and no note is created.