Upsert a task
Creates or updates a single task in one call. Omit id to create a new task; pass the id of
an existing task to update it. Responds 201 on create and 200 on update, with the full saved
task as the body. The task's creator is always the API key's user; it cannot be set.
On create, name, status, and due_datetime are required. On update every field is optional:
this is a sparse update, so only the fields you send are changed and any field you omit keeps its
stored value. Sending a nullable optional field (description, color, owner_id,
location_id) as null clears it; sending a required field as null is rejected with a 400.
Linking to another entity: set exactly one of order_id, invoice_id, purchase_id,
contact_id, product_id, batch_id, assembly_id, return_id, or company_id. Sending more
than one is a 400. The linked entity must exist in your company and be visible to the
authenticated user; otherwise 400. The link is set-once: once a task is linked, the link cannot be
changed or removed, and sending any relation field for an already-linked task is a 400. The linked
entity is returned as in GET /public/v1/tasks.
Required permission: tasks_permissions_create to create, tasks_permissions_edit to update.
Creating also requires the authenticated user's team restrictions to allow some access to tasks.
Updating requires access to the task under those restrictions; a hidden task returns 403.
BearerAuthorizationBearer <token>API token generated in Distru (Settings → Distru API). Send it on every request as Authorization: Bearer YOUR_API_TOKEN.
application/json- body
id?stringID of the task to update. Omit to create. When present but not matching a task in your company, the request fails.
name?stringThe task's name. Required on create. On update, omit to leave unchanged.
description?stringFree-form description. Optional. On update, send null to clear.
status?stringThe task's status. Required on create.
"ACTIVE""COMPLETED"due_datetime?stringWhen the task is due, as a UTC ISO8601 datetime. Required on create.
color?stringA label color for the task. Must be one of the company's allowed default colors. Optional; send null to clear.
owner_id?stringID of the user the task is assigned to. Optional; send null to unassign. Must be a user you are allowed to assign.
location_id?stringID of the location the task is at. Optional; send null to clear.
custom_data?Custom field values as an object keyed by custom field ID. Replaces the stored custom data when sent; omit to leave unchanged. Use GET /public/v1/custom-fields to find Task field IDs and their value formats.
order_id?stringLink this task to an order. Set-once; at most one relation field.
invoice_id?stringLink this task to an invoice. Set-once; at most one relation field.
purchase_id?stringLink this task to a purchase. Set-once; at most one relation field.
contact_id?stringLink this task to a contact. Set-once; at most one relation field.
product_id?stringLink this task to a product. Set-once; at most one relation field.
batch_id?stringLink this task to a batch. Set-once; at most one relation field.
assembly_id?stringLink this task to an assembly. Set-once; at most one relation field.
return_id?stringLink this task to a return. Set-once; at most one relation field.
company_id?stringLink this task to a company relationship, by its ID. Set-once; at most one relation field.
The updated task
*/*- response
A single task
data?A task
curl -X POST 'https://app.distru.com/public/v1/tasks' \ -H 'Content-Type: application/json' \ -d '{ "contact_id": "00000000-0000-0000-0000-000000000087", "description": "Ring them", "due_datetime": "2025-06-01T12:00:00Z", "name": "Call the buyer", "status": "ACTIVE"}'{ "data": { "assembly": {}, "batch": {}, "color": "string", "company": {}, "contact": {}, "creator": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "custom_data": [ { "id": 0, "name": "string", "value": "string" } ], "description": "string", "due_datetime": "string", "id": "string", "inserted_datetime": "string", "invoice": {}, "location": { "address": "1234 Warehouse Street, Oakland, CA", "id": "02c88a3f-d759-4973-88f9-60049d682524", "license_id": "02c88a3f-d759-4973-88f9-60049d682524", "name": "Warehouse 1" }, "name": "string", "order": {}, "owner": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "product": {}, "purchase": {}, "return": {}, "status": "ACTIVE", "updated_datetime": "string" }}