> For the complete documentation index, see [llms.txt](https://getubic.gitbook.io/ubic-partner-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getubic.gitbook.io/ubic-partner-api/tasks.md).
# Tasks
## List tasks in the API key workspace
> Requires \`tasks:read\`. API keys issued before this scope existed must\
> be replaced from the Ubic settings before using task endpoints.\
> Tasks attached to anonymized contacts are excluded. Results use a\
> monotonic change cursor, so a task changed during pagination can be\
> returned again without being skipped. Rate limit: 120 requests per\
> minute, per API key and IP.
```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"tags":[{"name":"Tasks"}],"servers":[{"url":"https://app.getubic.com/api/partner/v1"}],"security":[{"partnerApiKey":[]}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ubic_pk"}},"parameters":{"PerPage":{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned in `pagination.next_cursor`. It keeps the initial `updated_since` filter.","schema":{"type":"string"}}},"schemas":{"TaskPage":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}}},"Task":{"type":"object","required":["id","status","type","type_label","due_at","created_at","updated_at","assignee","lead"],"properties":{"id":{"type":"string","format":"uuid"},"external_reference":{"type":["string","null"]},"status":{"type":"string","enum":["open","done","canceled"]},"type":{"type":"string","description":"Workspace task type identifier."},"type_label":{"type":"string","description":"Current workspace label for the task type."},"note":{"type":["string","null"]},"due_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assignee":{"$ref":"#/components/schemas/Agent"},"lead":{"$ref":"#/components/schemas/TaskLead"}}},"Agent":{"type":"object","required":["id","email"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"email":{"type":["string","null"],"format":"email"}}},"TaskLead":{"type":"object","required":["id","phone"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":["string","null"]},"phone":{"type":"string"},"email":{"type":["string","null"],"format":"email"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"company":{"type":["string","null"]}}},"CursorPagination":{"type":"object","required":["per_page","next_cursor"],"properties":{"per_page":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass this value as `cursor` to retrieve the next page. Null means the end has been reached."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Invalid payload or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this API key and IP.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/tasks":{"get":{"tags":["Tasks"],"operationId":"listPartnerTasks","summary":"List tasks in the API key workspace","description":"Requires `tasks:read`. API keys issued before this scope existed must\nbe replaced from the Ubic settings before using task endpoints.\nTasks attached to anonymized contacts are excluded. Results use a\nmonotonic change cursor, so a task changed during pagination can be\nreturned again without being skipped. Rate limit: 120 requests per\nminute, per API key and IP.\n","parameters":[{"$ref":"#/components/parameters/PerPage"},{"$ref":"#/components/parameters/Cursor"},{"name":"updated_since","in":"query","required":false,"description":"Inclusive ISO-8601 filter on `updated_at`. A timezone is required; deduplicate on task `id`.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Workspace tasks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```
## Create a task for a workspace contact
> Requires \`tasks:write\`. API keys issued before this scope existed must\
> be replaced from the Ubic settings before using task endpoints.\
> The contact and assignee must belong to the API key workspace. When\
> \`assignee\_email\` is omitted, the owner of the contact list is used.\
> The created task always starts with the \`open\` status.\
> \
> Either \`Idempotency-Key\` or \`external\_reference\` is required. Repeating\
> the same reference returns the existing task instead of creating a\
> duplicate. Rate limit: 30 requests per minute, per API key and IP.
```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"tags":[{"name":"Tasks"}],"servers":[{"url":"https://app.getubic.com/api/partner/v1"}],"security":[{"partnerApiKey":[]}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ubic_pk"}},"schemas":{"CreateTaskRequest":{"type":"object","additionalProperties":false,"required":["lead_id","due_at"],"properties":{"lead_id":{"type":"string","format":"uuid","description":"Ubic contact identifier returned by a session contact or call response."},"assignee_email":{"type":"string","format":"email","maxLength":180,"description":"Workspace member assigned to the task. Defaults to the contact list owner."},"due_at":{"type":"string","format":"date-time","description":"ISO-8601 date and time with an explicit timezone. Stored and returned in UTC."},"type":{"type":"string","maxLength":30,"description":"One of the task types configured in the workspace. Defaults to the workspace default."},"note":{"type":"string","maxLength":10000},"external_reference":{"type":"string","maxLength":255,"description":"Stable external task reference, required when the Idempotency-Key header is omitted."}}},"Task":{"type":"object","required":["id","status","type","type_label","due_at","created_at","updated_at","assignee","lead"],"properties":{"id":{"type":"string","format":"uuid"},"external_reference":{"type":["string","null"]},"status":{"type":"string","enum":["open","done","canceled"]},"type":{"type":"string","description":"Workspace task type identifier."},"type_label":{"type":"string","description":"Current workspace label for the task type."},"note":{"type":["string","null"]},"due_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assignee":{"$ref":"#/components/schemas/Agent"},"lead":{"$ref":"#/components/schemas/TaskLead"}}},"Agent":{"type":"object","required":["id","email"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"email":{"type":["string","null"],"format":"email"}}},"TaskLead":{"type":"object","required":["id","phone"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":["string","null"]},"phone":{"type":"string"},"email":{"type":["string","null"],"format":"email"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"company":{"type":["string","null"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"responses":{"BadRequest":{"description":"Invalid JSON request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Requested resource not found in the API key workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Idempotency key and external reference identify different resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Invalid payload or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this API key and IP.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/tasks":{"post":{"tags":["Tasks"],"operationId":"createPartnerTask","summary":"Create a task for a workspace contact","description":"Requires `tasks:write`. API keys issued before this scope existed must\nbe replaced from the Ubic settings before using task endpoints.\nThe contact and assignee must belong to the API key workspace. When\n`assignee_email` is omitted, the owner of the contact list is used.\nThe created task always starts with the `open` status.\n\nEither `Idempotency-Key` or `external_reference` is required. Repeating\nthe same reference returns the existing task instead of creating a\nduplicate. Rate limit: 30 requests per minute, per API key and IP.\n","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique request reference, required when `external_reference` is omitted.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskRequest"}}}},"responses":{"201":{"description":"Task created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```
## Read one task
> Requires \`tasks:read\`. The task must belong to the API key workspace\
> and its contact must not be anonymized. Rate limit: 120 requests per\
> minute, per API key and IP.
```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"tags":[{"name":"Tasks"}],"servers":[{"url":"https://app.getubic.com/api/partner/v1"}],"security":[{"partnerApiKey":[]}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ubic_pk"}},"parameters":{"TaskId":{"name":"id","in":"path","required":true,"description":"Task UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"Task":{"type":"object","required":["id","status","type","type_label","due_at","created_at","updated_at","assignee","lead"],"properties":{"id":{"type":"string","format":"uuid"},"external_reference":{"type":["string","null"]},"status":{"type":"string","enum":["open","done","canceled"]},"type":{"type":"string","description":"Workspace task type identifier."},"type_label":{"type":"string","description":"Current workspace label for the task type."},"note":{"type":["string","null"]},"due_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assignee":{"$ref":"#/components/schemas/Agent"},"lead":{"$ref":"#/components/schemas/TaskLead"}}},"Agent":{"type":"object","required":["id","email"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"email":{"type":["string","null"],"format":"email"}}},"TaskLead":{"type":"object","required":["id","phone"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":["string","null"]},"phone":{"type":"string"},"email":{"type":["string","null"],"format":"email"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"company":{"type":["string","null"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Requested resource not found in the API key workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this API key and IP.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/tasks/{id}":{"get":{"tags":["Tasks"],"operationId":"getPartnerTask","summary":"Read one task","description":"Requires `tasks:read`. The task must belong to the API key workspace\nand its contact must not be anonymized. Rate limit: 120 requests per\nminute, per API key and IP.\n","parameters":[{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"Task details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://getubic.gitbook.io/ubic-partner-api/tasks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.