> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/tasks.md).

# Tasks

Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog.

## List tasks in a workroom.

> Tasks assigned to staff, with their status, due date, assignee and linked contact. Filterable by \`status\`, \`responsible\_id\`, \`task\_type\_id\`, \`due\_at\` ranges, \`contact\_id\` and \`is\_overdue\` (the dashboard's Overdue filter). Covers one-off tasks; recurring task definitions are \`listRecurringTasks\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Task":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskId"},"object":{"type":"string","enum":["task"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed"]},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","nullable":true},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"responsible_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true,"description":"Due date + time with the account's UTC offset. Stored the dashboard way: the date in `due_on` and the wall-clock time in `due_on_time`. A date-only task (no time) renders as local midnight with `due_time: null`."},"due_time":{"type":"string","nullable":true,"description":"Due time of day, \"HH:MM\" in the account timezone; null for a date-only task (overdue from the next day)."},"recurring_task_id":{"$ref":"#/components/schemas/RecurringTaskId","nullable":true,"description":"Set when this task is an occurrence of a recurring task."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Legacy storage: `attachments[0].path`."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TaskNote"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"completed_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"email_overdue":{"type":"boolean"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. True when the dashboard shows this task as Overdue: status is not `Completed` and the due moment has passed in the WORKROOM's timezone (the workroom's own timezone, falling back to the account's). A timed task is overdue once its `due_time` passes; a date-only task from the day after its due date. Computed at read time, never stored."}}},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"TaskNote":{"type":"object","properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/tasks":{"get":{"tags":["Tasks"],"operationId":"listTasks","summary":"List tasks in a workroom.","description":"Tasks assigned to staff, with their status, due date, assignee and linked contact. Filterable by `status`, `responsible_id`, `task_type_id`, `due_at` ranges, `contact_id` and `is_overdue` (the dashboard's Overdue filter). Covers one-off tasks; recurring task definitions are `listRecurringTasks`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"status":{"type":"string","enum":["Open","Completed"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"responsible_id":{"$ref":"#/components/schemas/StaffId"},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId"},"is_overdue":{"type":"boolean","description":"The dashboard's \"Overdue\" task filter. `true`: `Open` tasks whose due DATE is before today (UTC calendar day, time of day ignored). `false`: every other task. Because the filter is date-only, a task due at an earlier time today has `is_overdue: true` in the response but is not matched by `filter[is_overdue]=true` — the same as in the dashboard. Combines with the other filters."},"due_at":{"type":"object","properties":{"gte":{"type":"string","format":"date-time"},"lte":{"type":"string","format":"date-time"},"gt":{"type":"string","format":"date-time"},"lt":{"type":"string","format":"date-time"}}}}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}}]}}}}}}}}}
```

## POST /tasks

> Requires the task name, who it is for and when it is due. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"TaskCreate":{"type":"object","required":["title","due_at","task_type_id"],"anyOf":[{"required":["contact_id"]},{"required":["responsible_id"]}],"properties":{"title":{"type":"string","description":"What needs doing, as it appears in the task list. Take the user's wording rather than paraphrasing."},"description":{"type":"string","description":"Optional detail shown when the task is opened."},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","description":"REQUIRED. Call / Email / Follow-up etc. — the dashboard's own task form treats this as mandatory too. Call `listTaskTypes` for this workroom's options — the set is configurable per workroom, so do not guess an id."},"contact_id":{"$ref":"#/components/schemas/ContactId","description":"The contact this task is about. Required unless `responsible_id` is given."},"contact_name":{"type":"string","description":"Display name cached alongside `contact_id` for the list view. Resolved server-side when omitted."},"responsible_id":{"$ref":"#/components/schemas/StaffId","description":"The staff member who has to do it. Required unless `contact_id` is given. Call `listStaff` for valid ids. Unassigned tasks appear on nobody's list."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"REQUIRED. When it is due, RFC 3339, or `YYYY-MM-DD` for an all-day task. A timestamp without an offset is read in the account timezone. A task with no due date never surfaces in any due-date view, so there is no sensible default — ask the user."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard."}}},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Task":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskId"},"object":{"type":"string","enum":["task"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed"]},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","nullable":true},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"responsible_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true,"description":"Due date + time with the account's UTC offset. Stored the dashboard way: the date in `due_on` and the wall-clock time in `due_on_time`. A date-only task (no time) renders as local midnight with `due_time: null`."},"due_time":{"type":"string","nullable":true,"description":"Due time of day, \"HH:MM\" in the account timezone; null for a date-only task (overdue from the next day)."},"recurring_task_id":{"$ref":"#/components/schemas/RecurringTaskId","nullable":true,"description":"Set when this task is an occurrence of a recurring task."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Legacy storage: `attachments[0].path`."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TaskNote"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"completed_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"email_overdue":{"type":"boolean"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. True when the dashboard shows this task as Overdue: status is not `Completed` and the due moment has passed in the WORKROOM's timezone (the workroom's own timezone, falling back to the account's). A timed task is overdue once its `due_time` passes; a date-only task from the day after its due date. Computed at read time, never stored."}}},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"TaskNote":{"type":"object","properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}}}},"paths":{"/tasks":{"post":{"tags":["Tasks"],"operationId":"createTask","description":"Requires the task name, who it is for and when it is due. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}}}}
```

## Retrieve one task.

> Full task record including status, due date, type, assignees, the linked contact and its notes.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"Task":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskId"},"object":{"type":"string","enum":["task"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed"]},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","nullable":true},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"responsible_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true,"description":"Due date + time with the account's UTC offset. Stored the dashboard way: the date in `due_on` and the wall-clock time in `due_on_time`. A date-only task (no time) renders as local midnight with `due_time: null`."},"due_time":{"type":"string","nullable":true,"description":"Due time of day, \"HH:MM\" in the account timezone; null for a date-only task (overdue from the next day)."},"recurring_task_id":{"$ref":"#/components/schemas/RecurringTaskId","nullable":true,"description":"Set when this task is an occurrence of a recurring task."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Legacy storage: `attachments[0].path`."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TaskNote"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"completed_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"email_overdue":{"type":"boolean"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. True when the dashboard shows this task as Overdue: status is not `Completed` and the due moment has passed in the WORKROOM's timezone (the workroom's own timezone, falling back to the account's). A timed task is overdue once its `due_time` passes; a date-only task from the day after its due date. Computed at read time, never stored."}}},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"TaskNote":{"type":"object","properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/tasks/{id}":{"get":{"tags":["Tasks"],"operationId":"retrieveTask","summary":"Retrieve one task.","description":"Full task record including status, due date, type, assignees, the linked contact and its notes.\n","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}}}}
```

## Update a task's fields.

> Patch any subset of title, due date, type, assignees, priority or linked contact. Omitted fields are left unchanged. Marking a task done is \`completeTask\`, not a status patch — completion is what fires the \`after\_completing\` sales-automation trigger.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"TaskUpdate":{"type":"object","description":"Partial update. Same fields as TaskCreate, plus `status` — set it back to `Open` to reopen a `Completed` task, or to `Completed` to complete it (equivalent to `POST /v3/tasks/{id}/complete` with no `completed_by`). Reopening clears `completed_at` (as the dashboard does) and leaves `completed_by` untouched. `contact_id` cannot be changed after creation.\n","properties":{"title":{"type":"string"},"description":{"type":"string"},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId"},"responsible_id":{"$ref":"#/components/schemas/StaffId"},"due_at":{"type":"string","description":"RFC 3339 or `YYYY-MM-DD` (all-day); offset-less values are read in the account timezone."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Set to `null` to clear the existing attachment; omit to leave it untouched."},"status":{"type":"string","enum":["Open","Completed"],"description":"Set to `Open` to reopen a completed task, or `Completed` to complete it."}}},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Task":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskId"},"object":{"type":"string","enum":["task"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed"]},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","nullable":true},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"responsible_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true,"description":"Due date + time with the account's UTC offset. Stored the dashboard way: the date in `due_on` and the wall-clock time in `due_on_time`. A date-only task (no time) renders as local midnight with `due_time: null`."},"due_time":{"type":"string","nullable":true,"description":"Due time of day, \"HH:MM\" in the account timezone; null for a date-only task (overdue from the next day)."},"recurring_task_id":{"$ref":"#/components/schemas/RecurringTaskId","nullable":true,"description":"Set when this task is an occurrence of a recurring task."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Legacy storage: `attachments[0].path`."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TaskNote"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"completed_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"email_overdue":{"type":"boolean"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. True when the dashboard shows this task as Overdue: status is not `Completed` and the due moment has passed in the WORKROOM's timezone (the workroom's own timezone, falling back to the account's). A timed task is overdue once its `due_time` passes; a date-only task from the day after its due date. Computed at read time, never stored."}}},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"TaskNote":{"type":"object","properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/tasks/{id}":{"patch":{"tags":["Tasks"],"operationId":"updateTask","summary":"Update a task's fields.","description":"Patch any subset of title, due date, type, assignees, priority or linked contact. Omitted fields are left unchanged. Marking a task done is `completeTask`, not a status patch — completion is what fires the `after_completing` sales-automation trigger.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}}}}
```

## DELETE /tasks/{id}

> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}}},"paths":{"/tasks/{id}":{"delete":{"tags":["Tasks"],"operationId":"deleteTask","description":"**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","responses":{"204":{"description":"Deleted."}}}}}}
```

## POST /tasks/{id}/complete

> Mark a task Completed. Sets \`completed\_at\` + optional \`completed\_by\`.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Task":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskId"},"object":{"type":"string","enum":["task"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed"]},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","nullable":true},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"responsible_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true,"description":"Due date + time with the account's UTC offset. Stored the dashboard way: the date in `due_on` and the wall-clock time in `due_on_time`. A date-only task (no time) renders as local midnight with `due_time: null`."},"due_time":{"type":"string","nullable":true,"description":"Due time of day, \"HH:MM\" in the account timezone; null for a date-only task (overdue from the next day)."},"recurring_task_id":{"$ref":"#/components/schemas/RecurringTaskId","nullable":true,"description":"Set when this task is an occurrence of a recurring task."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Legacy storage: `attachments[0].path`."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TaskNote"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"completed_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"email_overdue":{"type":"boolean"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. True when the dashboard shows this task as Overdue: status is not `Completed` and the due moment has passed in the WORKROOM's timezone (the workroom's own timezone, falling back to the account's). A timed task is overdue once its `due_time` passes; a date-only task from the day after its due date. Computed at read time, never stored."}}},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"TaskNote":{"type":"object","properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/tasks/{id}/complete":{"post":{"tags":["Tasks"],"operationId":"completeTask","summary":"Mark a task Completed. Sets `completed_at` + optional `completed_by`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"completed_by":{"$ref":"#/components/schemas/StaffId"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}}}}
```

## Reassign a task to different staff.

> Replaces the task's assignees. Distinct from \`updateTask\` so a reassignment is a single auditable action rather than a field patch.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Task":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskId"},"object":{"type":"string","enum":["task"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed"]},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","nullable":true},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"responsible_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true,"description":"Due date + time with the account's UTC offset. Stored the dashboard way: the date in `due_on` and the wall-clock time in `due_on_time`. A date-only task (no time) renders as local midnight with `due_time: null`."},"due_time":{"type":"string","nullable":true,"description":"Due time of day, \"HH:MM\" in the account timezone; null for a date-only task (overdue from the next day)."},"recurring_task_id":{"$ref":"#/components/schemas/RecurringTaskId","nullable":true,"description":"Set when this task is an occurrence of a recurring task."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Legacy storage: `attachments[0].path`."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TaskNote"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"completed_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"email_overdue":{"type":"boolean"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. True when the dashboard shows this task as Overdue: status is not `Completed` and the due moment has passed in the WORKROOM's timezone (the workroom's own timezone, falling back to the account's). A timed task is overdue once its `due_time` passes; a date-only task from the day after its due date. Computed at read time, never stored."}}},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"TaskNote":{"type":"object","properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/tasks/{id}/reassign":{"post":{"tags":["Tasks"],"operationId":"reassignTask","summary":"Reassign a task to different staff.","description":"Replaces the task's assignees. Distinct from `updateTask` so a reassignment is a single auditable action rather than a field patch.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["responsible_id"],"properties":{"responsible_id":{"$ref":"#/components/schemas/StaffId"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}}}}
```

## Add a note to a task.

> Appends a timestamped note to the task's activity trail, attributed to the authenticated user. Notes are append-only: there is no edit or delete.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Task":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskId"},"object":{"type":"string","enum":["task"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed"]},"task_type_id":{"$ref":"#/components/schemas/TaskTypeId","nullable":true},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"responsible_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true,"description":"Due date + time with the account's UTC offset. Stored the dashboard way: the date in `due_on` and the wall-clock time in `due_on_time`. A date-only task (no time) renders as local midnight with `due_time: null`."},"due_time":{"type":"string","nullable":true,"description":"Due time of day, \"HH:MM\" in the account timezone; null for a date-only task (overdue from the next day)."},"recurring_task_id":{"$ref":"#/components/schemas/RecurringTaskId","nullable":true,"description":"Set when this task is an occurrence of a recurring task."},"attachment_url":{"type":"string","format":"uri","nullable":true,"description":"Only one attachment is supported per task, matching the dashboard. Legacy storage: `attachments[0].path`."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TaskNote"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"completed_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"email_overdue":{"type":"boolean"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. True when the dashboard shows this task as Overdue: status is not `Completed` and the due moment has passed in the WORKROOM's timezone (the workroom's own timezone, falling back to the account's). A timed task is overdue once its `due_time` passes; a date-only task from the day after its due date. Computed at read time, never stored."}}},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"TaskNote":{"type":"object","properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/tasks/{id}/notes":{"post":{"tags":["Tasks"],"operationId":"addTaskNote","summary":"Add a note to a task.","description":"Appends a timestamped note to the task's activity trail, attributed to the authenticated user. Notes are append-only: there is no edit or delete.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId"}}}}}},"responses":{"201":{"description":"Note appended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}}}}
```

## GET /task\_types

> List task types (call, demo, email, etc.).

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"TaskType":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskTypeId"},"object":{"type":"string","enum":["task_type"]},"name":{"type":"string"},"description":{"type":"string","nullable":true}}},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"}}},"paths":{"/task_types":{"get":{"tags":["Tasks"],"operationId":"listTaskTypes","summary":"List task types (call, demo, email, etc.).","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskType"}}}}]}}}}}}}}}
```

## Retrieve one task type.

> A task category as configured for the workroom. Read-only: task types are managed in the dashboard.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"TaskType":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TaskTypeId"},"object":{"type":"string","enum":["task_type"]},"name":{"type":"string"},"description":{"type":"string","nullable":true}}},"TaskTypeId":{"type":"string","pattern":"^tst_[0-9a-f]{24}$"}}},"paths":{"/task_types/{id}":{"get":{"tags":["Tasks"],"operationId":"retrieveTaskType","summary":"Retrieve one task type.","description":"A task category as configured for the workroom. Read-only: task types are managed in the dashboard.\n","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskType"}}}}}}}}}
```

## List recurring task definitions.

> The templates that generate tasks on a schedule, as opposed to the task instances themselves (\`listTasks\`). Read-only: these are authored in the dashboard.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"RecurringTask":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/RecurringTaskId"},"object":{"type":"string","enum":["recurring_task"]},"status":{"type":"string"},"frequency":{"type":"integer"},"frequency_type":{"type":"string","enum":["day","week","month","year"]},"start_date":{"$ref":"#/components/schemas/Timestamp"},"end_date":{"$ref":"#/components/schemas/Timestamp","nullable":true},"end_type":{"type":"string","enum":["occurrence","date"]},"end_value":{"description":"Count when end_type=occurrence; date when end_type=date."},"completed_occurrence":{"type":"integer"},"next_recursion_date":{"type":"string","nullable":true},"parent_task_id":{"$ref":"#/components/schemas/TaskId","nullable":true}}},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"}}},"paths":{"/recurring_tasks":{"get":{"tags":["Tasks"],"operationId":"listRecurringTasks","summary":"List recurring task definitions.","description":"The templates that generate tasks on a schedule, as opposed to the task instances themselves (`listTasks`). Read-only: these are authored in the dashboard.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringTask"}}}}]}}}}}}}}}
```

## Retrieve one recurring task definition.

> Its schedule, assignees and the task template it generates from. Read-only.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Tasks","description":"Assignable tasks — usually calls, follow-ups, or reminders — with a title, due date, responsible staff, and a link to a contact. Includes recurring task templates and a task-type catalog."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"RecurringTask":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/RecurringTaskId"},"object":{"type":"string","enum":["recurring_task"]},"status":{"type":"string"},"frequency":{"type":"integer"},"frequency_type":{"type":"string","enum":["day","week","month","year"]},"start_date":{"$ref":"#/components/schemas/Timestamp"},"end_date":{"$ref":"#/components/schemas/Timestamp","nullable":true},"end_type":{"type":"string","enum":["occurrence","date"]},"end_value":{"description":"Count when end_type=occurrence; date when end_type=date."},"completed_occurrence":{"type":"integer"},"next_recursion_date":{"type":"string","nullable":true},"parent_task_id":{"$ref":"#/components/schemas/TaskId","nullable":true}}},"RecurringTaskId":{"type":"string","pattern":"^rtsk_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"TaskId":{"type":"string","pattern":"^tsk_[0-9a-f]{24}$"}}},"paths":{"/recurring_tasks/{id}":{"get":{"tags":["Tasks"],"operationId":"retrieveRecurringTask","summary":"Retrieve one recurring task definition.","description":"Its schedule, assignees and the task template it generates from. Read-only.\n","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringTask"}}}}}}}}}
```
