Tasks API
Create, list, reschedule, and complete CRM to-do tasks through the Goliath developer API
About
A task is one actionable line item — a follow-up call, a document to chase, a step in an onboarding SOP. It has a title, an optional description, a due date, and assignees, and it gets checked off when the work is done.
Two things a task is not:
- A calendar event. Something with a start time and attendees is an appointment — see the Appointments API.
- A background job. The async jobs that ops like
addContactTagsreturn abulkTaskIdfor live under the Bulk Tasks API, and are unrelated to the CRM tasks on this page.
Tasks anchor either to a contact (the usual case — follow-ups on a person) or directly to a deal (pipeline work that belongs to the deal itself, with no contact involved). Which one it is determines how you complete it, so the distinction matters — see the callout below.
To create tasks from a saved checklist, use applyTaskTemplate or
applyTaskSet in the Workflows API.
These apply reusable templates to a contact; applyTaskSet can report a
partial result, so inspect its failedStep before reporting completion.
All operations go through the developer API gateway — one endpoint, called by
operationId. If you haven’t set up a key yet, start with the
Developer API Overview.
Operations
Reading tasks (READ scope)
| operationId | What it does |
|---|---|
listMyTasks |
The working queue — open and completed tasks, filterable by taskStatus (OVERDUE | TODAY | FUTURE), completed, a dueBefore/dueAfter window, participants, and searchTerm. Pass timezone so day boundaries land correctly. Returns tasks, the unpaged total, and canFetchNext. limit defaults to 25, capped at 50; page forward with cursor. |
listContactTasks |
Every task on one contact by contactId — title, description, dueDate, completedAt, and assigned participants. Use it to review outstanding work before a call, or to find the taskId + contactId pair the write operations need. |
When users.getUserTasks.canFetchNext is true, call listMyTasks again with
the same filters and cursor set to the last task’s id. Repeat until false.
Pagination is forward-only; start again without a cursor to revisit earlier
rows. OVERDUE means before today in the supplied timezone. To find tasks
past due at this instant, use completed: false and dueBefore instead.
Writing tasks (WRITE scope)
| operationId | What it does |
|---|---|
createTaskOnContact |
Create a task on a contact. Requires contactId, title, dueDate, and timezone; optional description, taskType (free-text label like Call), participants, and dealIds to also link it to deals. A dealIds deal that already holds an open task can refuse the create and name that task; resend with alongsideOpenTasks: true to add another anyway. |
createTaskOnDeal |
Create a task attached directly to a deal, with no contact. Requires dealId, title, dueDate, and timezone; optional description, taskType, and participants. For pipeline work that belongs to the deal rather than to a person. Takes alongsideOpenTasks like createTaskOnContact. |
updateTask |
Edit a task by taskId + its linked contactId. Patch semantics — only the fields you pass change. This is how you reschedule (“push that follow-up to Friday”): update in place rather than deleting and recreating. Passing participants replaces the whole assignee list. |
completeTask |
Tick off a task that has a contact, by taskId + contactId. Also writes the completion onto that contact’s timeline. Pass isCompleted: false to reopen one completed by mistake. |
completeTaskById |
Tick off a task that has no contact, by taskId alone. Refuses a task that does have a contact rather than quietly skipping the timeline entry. |
deleteTask |
Permanently delete one task by taskId + contactId. No undo. Many at once is deleteTasks. |
deleteTasks |
deleteTask for many: items: [{ id, contactId }] (up to 200), each task on its own contact. Returns deletedCount. No undo. |
bulkCreateTasksOnContacts |
The Contacts bulk bar’s Add task: one task (same fields as createTaskOnContact) on each of contactIds, as a background task (bulkTaskId, getBulkTask). assignToPointPerson gives each contact’s task to that contact’s point person instead of participants, skipping contacts with none. |
rescheduleTasks |
Move many tasks to one dueDate + timezone in a single call — either taskIds (up to 200) or dueBefore + expectedCount (the key owner’s own open tasks due before then, moved only if exactly expectedCount match). Each is saved as updateTask saves it. Moving by ids does not check ownership, so read participants first. |
updateTaskOnDeal |
updateTask for a task with no contact, by taskId + its dealId. Same fields and rules; no timeline keeps old values, so note them first if you may need to undo. |
deleteTaskOnDeal |
deleteTask for a task with no contact, by taskId + its dealId. |
Clearing stale workflow tasks (WRITE scope)
| operationId | What it does |
|---|---|
clearStaleWorkflowTasks |
Clear the key owner’s stale workflow tasks: open to-dos a workflow made, assigned to them alone, due more than 7 days before today in timezone (an IANA zone). At most 2,000 per call; they are removed (never completed) after a 10-second hold. Returns bulkTaskId (null when nothing qualified), taskCount and hasMore. |
cancelTaskClear |
Undo a clear inside its 10-second hold, by bulkTaskId: CANCELLED means nothing changed; ALREADY_STARTED means use restoreClearedTasks. |
restoreClearedTasks |
Bring back the tasks a clear removed, for 30 days after it, by the clear’s bulkTaskId. |
No read counts the stale tasks beforehand — report taskCount from the
clear’s result.
Example
List everything overdue, then complete one of them:
curl -X POST https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer gsk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "operationId": "listMyTasks", "variables": { "taskStatus": "OVERDUE", "timezone": "PST" } }'curl -X POST https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer gsk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "operationId": "completeTask", "variables": { "taskId": "YOUR_TASK_ID", "contactId": "YOUR_CONTACT_ID", "isCompleted": true } }'Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.