Tasks

What the team owes a person: a call, an email, a meeting or a to-do, with a due date, pointing at the contact, company or deal it is for. A task may point at nothing — a plain to-do is still a task — which is the one way it differs from an activity.

Scopes and the site rule are shared with every CRM resource — see companies.

The task object

{
  "id": "t_5e0d",
  "object": "task",
  "title": "Call back about the proposal",
  "notes": null,
  "kind": "call",
  "typeLabel": "Call",
  "priority": "high",
  "priorityLabel": "High",
  "status": "open",
  "statusLabel": "In Progress",
  "dueAt": "2026-09-10T15:00:00.000Z",
  "remindAt": "2026-09-10T15:00:00.000Z",
  "reminderSentAt": null,
  "completedAt": null,
  "assigneeUid": "u_9f1c",
  "contactId": "k7d2b9f104",
  "companyId": null,
  "dealId": "d_3c9a",
  "siteId": "site_a1b2c3",
  "created": "2026-09-05T18:23:23.941Z",
  "updated": "2026-09-05T18:23:23.941Z"
}

Field	Type	Notes
`id`	string	Opaque task id.
`object`	string	Always `"task"`.
`title`	string	Required. Trimmed, truncated to 200 characters. Writable.
`notes`	string \| null	Free text, 5,000 characters. Writable.
`kind`	string	The task's Type, as its meaning: `call`, `email`, `meeting` or `todo`. `todo` when never set. Writable: send a meaning, or a value of your organization's Type picklist (`"Meeting"`, `"Site visit"`) and the task stores the meaning that value carries.
`typeLabel`	string	Your organization's label for the type — the one the task holds, or the first active value of its meaning when it holds none. Read-only; set through `kind`.
`priority`	string	`low`, `normal` or `high`. `normal` when never set. Writable, as a meaning or a value of the Priority picklist.
`priorityLabel`	string	Your organization's label for the priority. Read-only; set through `priority`.
`status`	string	`open` or `done`. `open` when never set. Writable, as a meaning or a value of the Status picklist (`"In Progress"`, `"Completed"`) — marking a task `done` stamps `completedAt`; marking it `open` again clears it, so a reopened task never reads as completed on the day it was first closed. A value of the same meaning (`"Waiting on someone else"` on an open task) relabels it and changes nothing else.
`statusLabel`	string	Your organization's label for the status — `"Not Started"` and `"Completed"` among the standard values. Read-only; set through `status`.
`dueAt`	string \| null	ISO 8601 instant. Writable.
`remindAt`	string \| null	ISO 8601 instant. When the assignee is reminded — a console notification and an email, sent by an hourly runner, so it arrives within the hour after this time. Writable. Omitted on create, it is the due time (or `null` when there is none). Omitted on update, it follows a moved `dueAt` when it still sat on the old due time, and stays put when it was set to a time of its own; send `null` for no reminder. Marking the task `done` clears a reminder that has not yet been sent.
`reminderSentAt`	string \| null	When the runner handled the reminder. Read-only. Cleared whenever `remindAt` changes, so a moved reminder is sent again.
`completedAt`	string \| null	When the task was marked done. Read-only.
`assigneeUid`	string \| null	Who owes it. Must be a member of your organization. Writable.
`contactId`, `companyId`, `dealId`	string \| null	What the task is for. Each must exist. All optional. Writable.
`siteId`	string \| null	The site the task was created from, or `null` for an organization task — one filed from the organization's console with no site, owed by the organization itself rather than by any of its sites. Read-only. A task created over the API always names a site.
`created` / `updated`	string \| null	ISO 8601.

Endpoints

List tasks

GET /v1/tasks — scope crm:read. Paginated, ordered by task id unless updatedAfter is given.

Param	Notes
`dealId`, `contactId`, `companyId`	Tasks for that record.
`assigneeUid`	Tasks owed by this member.
`status`	`open` or `done`. Anything else is a `400`.
`updatedAfter`	Tasks updated after this instant, oldest first — the sync filter.
`limit`, `cursor`	Standard pagination.

# one person's open work
curl "https://app.aglyn.com/api/v1/tasks?assigneeUid=u_9f1c&status=open" \
  -H "Authorization: Bearer aglyn_sk_…"

One filter narrows the query — in the order listed, so dealId before status — and the rest are checked on the page, which can come back short.

Retrieve a task

GET /v1/tasks/{taskId} — scope crm:read. Returns a task, or 404 not_found ("No such task").

Add a task

POST /v1/tasks — scope crm:write. Accepts an Idempotency-Key, scoped to the organization. title is required. consentSiteId names the site the record came from; leave it out for a record from no site, which belongs to the whole organization. It is required only when your organization keeps each site's records apart.

curl -X POST "https://app.aglyn.com/api/v1/tasks" \
  -H "Authorization: Bearer aglyn_sk_…" \
  -H "Idempotency-Key: 9a41f0c2-…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call back about the proposal","kind":"call","dueAt":"2026-09-10T15:00:00Z","assigneeUid":"u_9f1c","dealId":"d_3c9a","consentSiteId":"site_a1b2c3"}'

Returns 201, or 200 with the original when an Idempotency-Key replays. A task created with status: "done" is completed the instant it is created, and carries no reminder. A task created with a dueAt and no remindAt is reminded at its due time; pass "remindAt": null for a task that should not remind.

Reminders reach only members who can open the CRM, in organizations whose plan includes the daily digest, and not a member who has muted the operational notification category — see Tasks & follow-ups.

Update a task

PATCH /v1/tasks/{taskId} — scope crm:write. No Idempotency-Key. An omitted key is left alone, null clears an optional field, {} is a no-op.

curl -X PATCH "https://app.aglyn.com/api/v1/tasks/t_5e0d" \
  -H "Authorization: Bearer aglyn_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

Delete a task

DELETE /v1/tasks/{taskId} — scope crm:write. Accepts an Idempotency-Key, scoped to the organization.

{ "id": "t_5e0d", "object": "task", "deleted": true }

Errors

Status	`type`	When
`400`	`bad_request`	`code: "validation_failed"` — a missing `title`, a missing `consentSiteId` where the organization keeps its sites apart, a `kind`, `priority` or `status` that is neither a meaning nor an active value of your organization's picklist (the error names the values it allows), a `dueAt` or `remindAt` that is not an ISO 8601 instant, an `assigneeUid` who is not a member, or a `contactId`, `companyId` or `dealId` that does not exist. On the list, a `?status=` outside `open`/`done` or a malformed `?updatedAfter=`. `fields` names each key.
`403`	`insufficient_scope`	Key lacks `crm:read` / `crm:write`.
`404`	`not_found`	`"No such task"`.
`405`	`method_not_allowed`	`Allow`: `GET, POST` on `/v1/tasks`, `GET, PATCH, DELETE` on one task.
`409`	`conflict`	`code: "idempotency_in_progress"`.

See Conventions → Errors for the shared envelope.

Activities — what happened, as opposed to what is owed.

The task object​

Endpoints​

List tasks​

Retrieve a task​

Add a task​

Update a task​

Delete a task​

Errors​

Related​