v1Resources/Approvals/postCreate a task
Create a task
Creates a task in Tasks & Approvals. A task is a piece of work your team tracks for a client, or for the agency itself when you leave out clientId. You can set one owner, an approver and up to 25 subtasks in the same call; subtasks you add here copy the task's owner, approver, priority and dates unless you set their own. To create a subtask of an existing open task, pass parentTaskId instead. When the owner is a client user and you leave out clientId, the task is created for that client user's client. Retries are safe: sending the same idempotencyKey with the same body returns the first result with replayed set to true, and reusing a key with a different body returns 409. If Tasks & Approvals isn't turned on for your workspace, this returns 404.
post
approvals:write/api/v1/work-management/tasksRequest body
idempotencyKeystringrequired
A unique string you choose, 8 to 200 characters. Reuse it only to retry the same request.
clientIdstringoptional
The client the task is for. Leave it out or send null for agency work. With a key that can reach all clients, this accepts the client's id, public id or slug. With a key limited to specific clients, pass the client's id; any other value, or a client outside the key's access, returns 403. A subtask always shares its parent's client, and naming a different one returns 400.
titlestringrequired
The task's title, up to 500 characters.
descriptionstringoptional
What needs to be done, up to 20,000 characters.
locationIdstringoptional
A location of the task's client that the task is about. A location of another client returns 400.
projectIdstringoptional
A project of the same client to group the task under.
parentTaskIdstringoptional
Create this as a subtask of an existing task. The parent must be open and can't itself be a subtask. The new subtask takes the parent's owner, approver, project, location, priority, due date and start date unless you send your own. Can't be combined with subtasks.
metaobjectoptional
Priority and due date. Send both fields together. Defaults to medium priority and no due date.
prioritystring (urgent | high | medium | low)required
How urgent the task is.
dueDatestringrequired
Due date as YYYY-MM-DD in your workspace's time zone, or null.
detailsobjectoptional
Labels, start date and time estimate.
labelsarray of stringoptional
Up to 10 labels, 40 characters each. Duplicates that differ only in case are merged.
startDatestringoptional
Start date as YYYY-MM-DD, or null. It can't be later than the due date.
estimatedMinutesintegeroptional
Estimated effort in minutes, or null.
subtasksarray of objectoptional
Up to 25 subtasks to create with the task. Each one copies the task's owner, approver, priority, due date and start date unless you set its own.
titlestringrequired
The subtask's title, up to 200 characters.
descriptionstringoptional
What the subtask covers, up to 20,000 characters.
ownerIdstringoptional
The subtask's owner. Leave it out to copy the task's owner, or send null for no owner.
ownerTypestring (user | client_user)optional
Whether the owner is an agency teammate (user) or a client user (client_user). Defaults to user.
approverIdstringoptional
The subtask's approver. Leave it out to copy the task's approver, or send null for none.
dueDatestringoptional
The subtask's due date as YYYY-MM-DD, or null.
startDatestringoptional
The subtask's start date as YYYY-MM-DD, or null.
prioritystring (urgent | high | medium | low)optional
The subtask's priority.
ownerIdstringoptional
The id of the person who owns the task, from GET /api/v1/work-management/owners. Send null for no owner. On a subtask, leaving it out copies the parent's owner.
ownerTypestring (user | client_user)optional
Whether the owner is an agency teammate (user) or a client user (client_user). Defaults to user.
approverIdstringoptional
The id of an agency teammate who approves the task's work when someone requests approval. Send null for none.
Response
okbooleanoptional
Always true on a successful response.
dataobjectoptional
keystringoptional
The task's key, in the form task:<id>.
rowVersionintegeroptional
The task's version number. It goes up each time the task is edited.
replayedbooleanoptional
true when this response repeats an earlier request with the same idempotencyKey, so nothing new was saved.
Errors
400Tasks & Approvals errors come back as ok: false with an error object holding code, message, retryable and details. Errors from the API key check itself (a missing or invalid key, a missing scope, the rate limit) use the standard error shape, where error is a string.
401Missing, invalid, expired, or revoked API key.
403Tasks & Approvals errors come back as ok: false with an error object holding code, message, retryable and details. Errors from the API key check itself (a missing or invalid key, a missing scope, the rate limit) use the standard error shape, where error is a string.
404Tasks & Approvals errors come back as ok: false with an error object holding code, message, retryable and details. Errors from the API key check itself (a missing or invalid key, a missing scope, the rate limit) use the standard error shape, where error is a string.
409Tasks & Approvals errors come back as ok: false with an error object holding code, message, retryable and details. Errors from the API key check itself (a missing or invalid key, a missing scope, the rate limit) use the standard error shape, where error is a string.
429Too many requests. Retry after the number of seconds in the Retry-After header.
500The request couldn't be completed because of a problem on our side.
post/api/v1/work-management/tasks
Your API key
Request body*
{}