Tasks 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 addContactTags return a bulkTaskId for 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.

What listMyTasks returns depends on the key’s roleWithout a participants filter, every role gets the key owner’s own queue. A MEMBER or ISA key stays limited to that queue even when other participants are supplied. A team-admin key can request teammates’ queues by passing their user ids in participants (from listTeammates), but the results still include only tasks on contacts the key owner can access. Neither form includes unassigned tasks or guarantees a complete org backlog.

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.
`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.
`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. One task per call — there is no bulk delete.

A task with no participants is invisibleparticipants (teammate userIds — from getMyProfile for the key owner, or listTeammates for a colleague) is what puts a task in someone’s queue. Create a task without them and it is unassigned: it exists, but it will never appear in anyone’s listMyTasks. This is the most common way a scripted checklist silently goes missing.

Which complete operation to uselistMyTasks tells you: if a task comes back with contact: null, there is no contactId to pass and completeTask cannot touch it — use completeTaskById. If it has a contact, use completeTask, which records the completion on that contact’s timeline as well. completeTaskById refuses a task that has a contact, so an error there means you want the other operation.

Due dates are a local day, not an instanttimezone (PST, MST, CST, EST, …) is the zone the due date’s day is read in, and it decides which TODAY / OVERDUE bucket the task lands in. Send the user’s own zone, and for a day-level request (“follow up Friday”) pick an end-of-business time in that zone rather than a bare midnight.

No bulk create, and no re-anchoringThere is no multi-task call: a checklist is built by calling createTaskOnContact once per step, in order, with staggered due dates. The response echoes the contact’s full task list every time, so the last call confirms the whole set landed.A task also cannot be moved to a different contact. contactId on updateTask identifies the task’s existing contact — any other contact is rejected. Delete-and-recreate is not equivalent: a fresh task loses the original’s completedAt history, created date, and notification links.

Organization guardEvery id you pass is org-guarded before the operation runs: taskId (via its linked contact, or via an in-org participant for a contact-less task), contactId, dealId/dealIds, and participants user ids. The write operations additionally bind the pair — a foreign task id can never be completed or edited under a contact you do own, and vice versa. See Authorization for the model.

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.

Getting Started

TypeScript SDK

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Operations

Reading tasks (`READ` scope)

Writing tasks (`WRITE` scope)

Example

​About

​Operations

​Reading tasks (READ scope)

​Writing tasks (WRITE scope)

​Example

About

Operations

Reading tasks (`READ` scope)

Writing tasks (`WRITE` scope)

Example