v1Resources/Approvals/postCreate a task
Create a task
Create a task or subtask using the token creator’s current access, narrowed by token client restrictions. A task in a private project inherits its audience; subtasks inherit their parent’s restrictions. Owners and approvers must already have access. Creating an unassigned or clientless task does not itself make it private. Project sharing is managed by a person in the application, not by this endpoint.
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*
{}