Tasks — Create, Update & Cancel

Write tasks from your own systems (CRM, call-center, IoT). Three operations cover the full write lifecycle:

POST creates a task or a batch of up to 50.
PUT applies a partial update to an existing task.
DELETE cancels a task.

Every operation accepts either a single object or a batch wrapper { "items": [...] } (1 to 50 items) and returns a per-item result: one item can succeed while another fails, so a batch is never all-or-nothing once it passes shape validation.

Prerequisites

All endpoints require a valid JWT token, API key, and tenant header. See Authentication. The company (ciaid) and acting user are taken from your credentials — never from the request body.

IDs and dates

IDs are opaque strings (BigInt) — never parse them as numbers. Timestamps are sent and returned without timezone (e.g., "2026-04-04T14:32:00"). Do not append Z or apply UTC conversion. All request fields use snake_case.

Three identifiers in every response

Every successful write returns the three identifiers a task carries:

Field	Type	Description
`serid`	string	Internal task identifier (BigInt as string).
`service_number`	string	Service number, assigned by the system on creation.
`assistance_number`	string	Assistance number (links related child tasks to a parent).

The external_id you send is not echoed in the result item — it is your own key. To update or cancel later, you may identify the task by serid, service_number, or external_id (see Identifying a task).

Classification — Motive OR provision+cause+subcause

A task must be classified down two parallel axes. For each axis you choose one of two paths:

Axis	Path A	Path B
Product	`procedence` + `product`	`motive`
Provision	`provision` + `origin_cause` + `origin_subcause`	`motive`

When you send motive, the matching provision, cause, and subcause are filled in automatically from the reason's configuration — you don't need to send them. If you send both motive and an explicit provision/cause/subcause, the motive wins (it overwrites the others).

coverage is always optional.

If neither path is satisfied on an axis, the item fails with MOTIVE_OR_CLASSIFICATION_REQUIRED.

Resolution by name

Catalog and geographic fields accept either an id (opaque string) or a name. The system resolves the name to its id (e.g., a motive name to its motive, a country name to its country). When a name can't be resolved, the item either fails (hard) or proceeds with a warning, depending on the field — see Errors.

Create Task

POST/apidev/v1/tasks

PermissionAPICLI_TASKS_CREATE

Rate Limit20 req/min (sliding window)

CacheNone

Creates a task in initial state SA (or ASI when an assignment block is sent). A batch counts as one request against the rate limit.

Request Body — top-level fields

Field	Type	Required	Max	Description
`contact`	string	Yes	200	Name of the person requesting the task.
`external_id`	string	No	200	Your own identifier for the task.
`service_number`	string	No	40	Service number (numeric string). Omit or `0` to auto-number.
`assistance_number`	string	No	40	Assistance number (numeric string). A value links this task to a parent.
`phone_mobile`	string	No	50	Mobile phone of the contact.
`phone`	string	No	50	Landline phone of the contact.
`priority`	string	No	200	Priority id or value. Resolved against the company's priority table; omitted → default priority.
`detail`	string	No	—	Free-text detail of the request.
`notes`	string	No	—	Internal notes.
`scheduled_at`	string	No	40	Scheduled date/time (ISO without timezone).
`scheduled_until`	string	No	40	Scheduled-until date/time (ISO without timezone).
`automate`	boolean	No	—	Whether the task is automated.
`pending_unconfirmed`	boolean	No	—	Mark as pending / unconfirmed.
`computes`	boolean	No	—	Default `true`. `false` → does not consume coverage quota.
`delay_minutes`	string	No	20	GPS delay tolerance, in whole minutes.
`communication_medium`	string	No	200	Communication template (id or name). Unresolved → warning.
`shift`	string	No	200	Shift (id or name). Unresolved → warning.
`telephonist_email`	string	No	200	Operator email. Defaults to your credentials' user; unresolved → hard fail.
`no_notify_mobile`	boolean	No	—	Suppress the mobile notification (mainly relevant on update).
`assignment_alert`	string	No	2000	Assignment alert text stored on the task.
`vehicle_types`	string[]	No	200 each	Requested mobile types (ids or names). An invalid one fails the item.
`classification`	object	Yes	—	See Classification rule and classification fields.
`origin`	object	Yes	—	Origin address. `country` + `department` + `street` are required. See geo fields.
`destination`	object	Conditional	—	Required or optional depending on the product (e.g., tow / move products require it).
`reserve`	object	No	—	Reserve a resource without assigning. See reserve fields.
`assignment`	object	No	—	Assign the task on creation (state `ASI`; mobile notification only when `notify_mobile` is `true`). See assignment fields.
`account`	object	Yes	—	Requesting account. Auto-created from the origin address if it doesn't exist. See account fields.
`dynamic_fields`	array	Conditional	—	OAV dynamic fields. Required when the product has mandatory OAV fields. See dynamic fields.
`attachments`	array	No	—	Attachments by URL — stored as an external link (the URL is saved as-is to open from web/app; not downloaded). See attachment fields.
`load`	object	No	—	Cargo data (weight, volume, packages, handling requirements). Gated by the product's cargo profile. See load.

`classification` fields

Field	Type	Required	Description
`procedence`	string	Conditional	Origin/source (id or name). Required with `product` unless `motive` is sent.
`product`	string	Conditional	Product (id, line, or name). Requires `procedence`.
`coverage`	string	No	Coverage (id or name).
`motive`	string	Conditional	Reason (id or name). Fills in provision/cause/subcause automatically.
`provision`	string	Conditional	Provision (id or name). Required with the two causes unless `motive` is sent.
`origin_cause`	string	Conditional	Origin cause (id or name).
`origin_subcause`	string	Conditional	Origin subcause (id or name).
`destination_cause`	string	No	Destination cause (id or name).
`destination_subcause`	string	No	Destination subcause (id or name).

`origin` / `destination` fields

origin and destination share the same shape. Geographic and special-place fields accept an id or a name.

Field	Type	Required (origin)	Description
`country`	string	Yes	Country (id or name).
`department`	string	Yes	Department / province (id or name).
`city`	string	No	City (id or name).
`zone`	string	No	Zone (id or name). Unresolved → warning.
`street`	string	Yes	Street. Required in origin (unless inherited from the account).
`corner`	string	No	Cross street. Max 500.
`corner2`	string	No	Second cross street. Max 500.
`door_number`	string	No	Door number (text — accepts `"1234"`, `"S/N"`, `"12-A"`). Max 50.
`apartment`	string	No	Apartment / suite. Max 50.
`facing`	string	No	Facing reference. Max 200.
`special_place`	string	No	Special place (id or name). Unresolved → warning.
`lat`	string	No	Latitude. `0` or omitted → geocoding fallback.
`lng`	string	No	Longitude. `0` or omitted → geocoding fallback.

Geocoding fallback

When lat/lng are missing or 0, the task is located using the company's own geo infrastructure (account georeference → address geocoding → geographic centroid). If nothing resolves, the task is created without coordinates (it does not fail) and a warning is returned.

`reserve` fields

Reserving a resource keeps the task in state SA (it does not assign it).

Field	Type	Description
`personnel`	string	Personnel to reserve (id or name). Unresolved → warning.
`provider`	string	Provider to reserve (id or name). Unresolved → hard fail.
`mobile`	string	Mobile to reserve (id or name). Unresolved → hard fail.
`user_email`	string	User to reserve. Unresolved → hard fail.
`notify_mobile`	boolean	Notify the mobile when reserving (default: no). If true, the reservation notification flow runs.

`assignment` fields

Assigning moves the task to state ASI and sets the assignment date. The mobile is notified only when notify_mobile is true (by default it does not notify). Assign by mobile or by provider (they are alternatives).

Field	Type	Description
`assign_vehicle`	string	Mobile to assign (id or name). Resolves the driver's active work shift. Unresolved → hard fail.
`assign_driver`	string	Driver to assign (id or name). Unresolved → hard fail.
`assign_provider`	string	Provider to assign (id or name), as an alternative to a mobile. Unresolved → hard fail.
`assign_template`	string	Communication template for the assignment. Defaults to the resource's template; a template that doesn't belong to the resource → warning + default is used.
`notify_mobile`	boolean	Notify the mobile on assignment (default: no).

`account` fields

The requesting account is mandatory. If external_code doesn't match an existing account and name is provided, the account is auto-created with the task's origin address.

Field	Type	Description
`external_code`	string	Resolves the account by external code. Max 200.
`name`	string	Account name (used on auto-create). Max 200.
`update_if_exists`	boolean	If `true`, updates non-empty fields of the existing account.
`document`	string	Document number (search key).
`phone`	string	Phone (search key).
`mobile`	string	Mobile (search key).
`email`	string	Email (search key).
`notes`	string	Account notes. Max 2000.
`address`	object	Account address. Overrides the inherited origin address. Subset of `origin`: `street`, `corner`, `door_number`, `country`, `department`, `city`, `lat`, `lng`.

`dynamic_fields` (OAV)

Dynamic fields (OAV) are defined per product. Their requirement and type come from the product's OAV definition:

If the product has mandatory OAV fields, dynamic_fields must include them with a non-empty value, or the item fails with OAV_REQUIRED_MISSING.
Each value is validated against the field's type (number, true/false, date, list option). A wrong format → OAV_TYPE_MISMATCH; a value outside the allowed list → OAV_LIST_VALUE_INVALID.
A label that doesn't match any field on the product is ignored with a warning (it does not fail the item).

Field	Type	Required	Description
`label`	string	Yes	Field label. Matched case-insensitively against the product's OAV field names.
`value`	string	No	Value, typed according to the field. Max 4000.

`attachments` fields

Field	Type	Required	Description
`name`	string	No	Display file name. Max 300.
`url`	string	Yes	HTTPS URL saved as-is as an external link (opened from web/app; not downloaded). Max 2000.
`notes`	string	No	Attachment notes. Max 2000.

A failed link doesn't fail the task

Each attachment is registered as an external link. If the link can't be registered, the task is still created and the attachment is reported in warnings[].

`load` (cargo data)

Cargo data for the task's shipment: weight, volume, package count, and special handling requirements. Every field is gated by the product's cargo profile — each product declares which cargo dimensions it handles.

Field	Type	Description
`weightKg`	number	Total weight in kilograms (≥ 0).
`volumeM3`	number	Total volume in cubic meters (≥ 0).
`packages`	integer	Number of packages (≥ 0).
`requiresCold`	boolean	Needs refrigerated handling.
`requiresFragile`	boolean	Contains fragile items.
`requiresHeavy`	boolean	Needs heavy-load handling.

Only the dimensions the product handles

If you send a load dimension the product doesn't handle, the item fails with LOAD_DIMENSION_NOT_SUPPORTED. Which dimensions a product handles is part of its configuration. On update, the product is read from the existing task (never from the body). Omit a dimension to leave it unchanged; send null to clear it.

Code Example

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT/apidev/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "Maria Gomez",
    "external_id": "CRM-90021",
    "phone_mobile": "+59899123456",
    "classification": {
      "procedence": "Call Center",
      "product": "Roadside Assistance"
    },
    "origin": {
      "country": "Uruguay",
      "department": "Montevideo",
      "city": "Montevideo",
      "street": "Av. 18 de Julio",
      "door_number": "1234"
    },
    "account": {
      "external_code": "ACC-5587",
      "name": "Maria Gomez"
    },
    "dynamic_fields": [
      { "label": "Vehicle Plate", "value": "ABC1234" }
    ]
  }'

const res = await fetch(
  `https://${TENANT}/apidev/v1/tasks`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      contact: 'Maria Gomez',
      external_id: 'CRM-90021',
      phone_mobile: '+59899123456',
      classification: { procedence: 'Call Center', product: 'Roadside Assistance' },
      origin: {
        country: 'Uruguay',
        department: 'Montevideo',
        city: 'Montevideo',
        street: 'Av. 18 de Julio',
        door_number: '1234',
      },
      account: { external_code: 'ACC-5587', name: 'Maria Gomez' },
      dynamic_fields: [{ label: 'Vehicle Plate', value: 'ABC1234' }],
    }),
  }
);
const { data, meta } = await res.json();
console.log(`Created ${meta.created}, failed ${meta.failed}. serid: ${data[0].serid}`);

import requests

response = requests.post(
    f"https://{TENANT}/apidev/v1/tasks",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    json={
        "contact": "Maria Gomez",
        "external_id": "CRM-90021",
        "phone_mobile": "+59899123456",
        "classification": {"procedence": "Call Center", "product": "Roadside Assistance"},
        "origin": {
            "country": "Uruguay",
            "department": "Montevideo",
            "city": "Montevideo",
            "street": "Av. 18 de Julio",
            "door_number": "1234",
        },
        "account": {"external_code": "ACC-5587", "name": "Maria Gomez"},
        "dynamic_fields": [{"label": "Vehicle Plate", "value": "ABC1234"}],
    },
)
result = response.json()
print(f"Created task: {result['data'][0]['serid']}")

Batch Example

Send { "items": [...] } with up to 50 tasks. The response keeps the same order via each item's index.

curl -s -X POST "https://$TENANT/apidev/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "contact": "Maria Gomez", "classification": { "motive": "Breakdown" },
        "origin": { "country": "Uruguay", "department": "Montevideo", "street": "Av. 18 de Julio" },
        "account": { "external_code": "ACC-5587", "name": "Maria Gomez" } },
      { "contact": "Juan Perez", "classification": { "procedence": "Call Center", "product": "Tow" },
        "origin": { "country": "Uruguay", "department": "Canelones", "street": "Ruta 8 km 25" },
        "account": { "external_code": "ACC-9912", "name": "Juan Perez" } }
    ]
  }'

Example Response

A successful single create returns data as an array of one item. HTTP 200 when at least one item succeeds; meta.failed counts the rest.

{
  "success": true,
  "meta": { "created": 2, "failed": 1 },
  "data": [
    {
      "index": 0,
      "success": true,
      "serid": "728193045120004001",
      "service_number": "103878",
      "assistance_number": "55012",
      "status": "SA",
      "warnings": []
    },
    {
      "index": 1,
      "success": true,
      "serid": "728193045120004002",
      "service_number": "103879",
      "assistance_number": "55013",
      "status": "SA",
      "warnings": [
        {
          "index": 1,
          "field": "origin.zone",
          "code": "GEO_ZONE_IGNORED",
          "message": "We couldn't find the zone you provided; the task was created without a zone.",
          "hint": "Check the valid zones in the geographic catalogs."
        }
      ]
    },
    {
      "index": 2,
      "success": false,
      "errors": [
        {
          "index": 2,
          "field": "classification.product",
          "code": "PRODUCT_NOT_FOUND",
          "message": "We couldn't find the product in the origin you provided.",
          "hint": "Check GET /apidev/v1/catalogs/origins/{originId}/products."
        }
      ]
    }
  ]
}

Result item fields

Field	Type	Presence	Description
`index`	number	Always	0-based position in the batch (`0` for a single object).
`success`	boolean	Always	Whether this item succeeded.
`serid`	string	If `success`	Internal task id.
`service_number`	string	If `success`	Service number.
`assistance_number`	string	If `success`	Assistance number.
`status`	string	If `success`	Behavior status. Create: `SA` (or `ASI` if assigned on creation).
`warnings`	array	If `success`	Non-blocking advisories. `[]` when none. See Issue shape.
`errors`	array	If `!success`	Per-item errors. See Issue shape.

meta carries created + failed for create, updated + failed for update, and cancelled + failed for cancel.

Update Task

PUT/apidev/v1/tasks

PermissionAPICLI_TASKS_UPDATE

Rate Limit20 req/min (sliding window)

CacheNone

Applies a partial update: only the fields you send are changed; omitted fields keep their current value. Accepts a single object or { "items": [...] }. See Partial Updates for the general pattern.

Identifying a task

Send at least one of these. They are resolved in this order until one matches a task in your company:

Field	Type	Description
`serid`	string	Preferred identity.
`service_number`	string	Second fallback.
`external_id`	string	Third fallback (your own key).

If none resolves, the item fails with TASK_NOT_FOUND. A task already in state FIN or CAN fails with TASK_ALREADY_TERMINAL.

Request Body

All Create Task business fields are accepted (all optional). Notes specific to update:

Only the fields present in the body are applied.
For OAV, only the dynamic_fields you send are updated (matched by label); fields you don't mention are left as they are. The full set of mandatory OAV fields is not re-checked on update — only the types of the ones you send are validated.
service_number = 0 / auto-numbering is not accepted (the task already exists).
assignment_alert and no_notify_mobile apply on update.

Code Example

cURL
JavaScript
Python

curl -s -X PUT "https://$TENANT/apidev/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CRM-90021",
    "phone_mobile": "+59899765432",
    "detail": "Customer added a second contact number",
    "dynamic_fields": [
      { "label": "Vehicle Plate", "value": "XYZ9876" }
    ]
  }'

const res = await fetch(
  `https://${TENANT}/apidev/v1/tasks`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      external_id: 'CRM-90021',
      phone_mobile: '+59899765432',
      detail: 'Customer added a second contact number',
      dynamic_fields: [{ label: 'Vehicle Plate', value: 'XYZ9876' }],
    }),
  }
);
const { data, meta } = await res.json();
console.log(`Updated ${meta.updated}, failed ${meta.failed}`);

import requests

response = requests.put(
    f"https://{TENANT}/apidev/v1/tasks",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    json={
        "external_id": "CRM-90021",
        "phone_mobile": "+59899765432",
        "detail": "Customer added a second contact number",
        "dynamic_fields": [{"label": "Vehicle Plate", "value": "XYZ9876"}],
    },
)
result = response.json()
print(f"Updated: {result['meta']['updated']}")

Example Response

{
  "success": true,
  "meta": { "updated": 1, "failed": 0 },
  "data": [
    {
      "index": 0,
      "success": true,
      "serid": "728193045120004001",
      "service_number": "103878",
      "assistance_number": "55012",
      "status": "SA",
      "warnings": []
    }
  ]
}

The result item shape is identical to create. On update, status reflects the task's current state after the change.

Cancel Task

DELETE/apidev/v1/tasks

PermissionAPICLI_TASKS_CANCEL

Rate Limit20 req/min (sliding window)

CacheNone

Cancels a task (state CAN) with a reason. If the task was assigned, the mobile is notified. Accepts a single object or { "items": [...] }.

Request Body

Field	Type	Required	Description
`serid`	string	One of three	Identity (preferred).
`service_number`	string	One of three	Identity (second fallback).
`external_id`	string	One of three	Identity (third fallback).
`reason`	string	Yes	Cancellation reason. Must not be empty. Max 2000.

Identity is resolved in the order serid → service_number → external_id. A task already in state FIN or CAN fails with TASK_ALREADY_TERMINAL.

Code Example

cURL
JavaScript
Python

curl -s -X DELETE "https://$TENANT/apidev/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CRM-90021",
    "reason": "Customer cancelled the request"
  }'

const res = await fetch(
  `https://${TENANT}/apidev/v1/tasks`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      external_id: 'CRM-90021',
      reason: 'Customer cancelled the request',
    }),
  }
);
const { data, meta } = await res.json();
console.log(`Cancelled ${meta.cancelled}, failed ${meta.failed}`);

import requests

response = requests.delete(
    f"https://{TENANT}/apidev/v1/tasks",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    json={
        "external_id": "CRM-90021",
        "reason": "Customer cancelled the request",
    },
)
result = response.json()
print(f"Cancelled: {result['meta']['cancelled']}")

Example Response

{
  "success": true,
  "meta": { "cancelled": 1, "failed": 0 },
  "data": [
    {
      "index": 0,
      "success": true,
      "serid": "728193045120004001",
      "service_number": "103878",
      "assistance_number": "55012",
      "status": "CAN"
    }
  ]
}

The cancel result item carries index, success, the three identifiers, and status (CAN on success) or errors[] on failure.

Errors

Two validation layers

The API validates in two distinct moments. Don't confuse them:

Layer	Detects	Response
Shape	Unknown field, wrong type, missing required field, invalid length, empty batch, batch over 50.	400 `VALIDATION_ERROR` with no `data` — the body is not processed and no item is created.
Business	Catalog not resolved, OAV mandatory/type/list, coverage quota, resource to assign/reserve, identity not found.	Per item in `data[].errors`. HTTP `200` with `meta.failed`; `400` only if all items fail (the failing `data` + `meta` are still included).

Issue shape

Each entry in errors[] and warnings[] has the same shape:

Field	Type	Description
`index`	number	0-based position in the batch.
`field`	string	Dot-path to the request field (e.g., `classification.product`, `origin.country`, `dynamic_fields.<label>`).
`code`	string	Stable error/warning code (see below).
`message`	string	Human-readable explanation.
`hint`	string	Concrete next step (which catalog to check / which field to fix).

Errors accumulate — a single item can return several at once.

Per-item error codes (hard fail — block the item)

Code	Typical field	Description
`CONTACT_REQUIRED`	`contact`	Missing the requester's name.
`ORIGIN_COUNTRY_REQUIRED`	`origin.country`	Missing the origin country.
`ORIGIN_DEPARTMENT_REQUIRED`	`origin.department`	Missing the origin department / province.
`STREET_REQUIRED`	`origin.street`	Missing the origin street.
`MOTIVE_OR_CLASSIFICATION_REQUIRED`	`classification`	Missing the motive, or the provision with its cause and subcause.
`PROCEDENCE_NOT_FOUND`	`classification.procedence`	The origin/source wasn't found.
`PRODUCT_NOT_FOUND`	`classification.product`	The product wasn't found in the given origin.
`COVERAGE_NOT_FOUND`	`classification.coverage`	The coverage wasn't found.
`MOTIVE_NOT_FOUND`	`classification.motive`	The motive wasn't found.
`PROVISION_NOT_FOUND`	`classification.provision`	The provision wasn't found.
`CAUSE_NOT_FOUND`	`classification.origin_cause` / `destination_cause`	The cause wasn't found.
`SUBCAUSE_NOT_FOUND`	`classification.origin_subcause` / `destination_subcause`	The subcause wasn't found.
`GEO_NOT_FOUND`	`origin.city` / `destination.*`	The geographic location wasn't found.
`VEHICLE_TYPE_INVALID`	`vehicle_types`	One of the requested mobile types doesn't exist.
`OAV_REQUIRED_MISSING`	`dynamic_fields.<label>`	A mandatory dynamic field for this product is missing.
`OAV_TYPE_MISMATCH`	`dynamic_fields.<label>`	The dynamic field value doesn't have the expected format.
`OAV_LIST_VALUE_INVALID`	`dynamic_fields.<label>`	The value isn't among the field's allowed options.
`ACCOUNT_NOT_RESOLVED`	`account.external_code`	The account couldn't be resolved or created.
`COVERAGE_QUOTA_EXCEEDED`	`classification.coverage`	The coverage ran out of service quota.
`RESERVE_PROVIDER_INVALID`	`reserve.provider`	The provider to reserve wasn't found.
`RESERVE_MOBILE_INVALID`	`reserve.mobile`	The mobile to reserve wasn't found.
`RESERVE_USER_INVALID`	`reserve.user_email` / `telephonist_email`	The user wasn't found.
`ASSIGN_VEHICLE_INVALID`	`assignment.assign_vehicle`	The mobile to assign wasn't found.
`ASSIGN_DRIVER_INVALID`	`assignment.assign_driver`	The driver to assign wasn't found.
`ASSIGN_PROVIDER_INVALID`	`assignment.assign_provider`	The provider to assign wasn't found.
`ASSIGN_TEMPLATE_INVALID`	`assignment.assign_template`	The communication template wasn't found.
`TASK_NOT_FOUND`	(identity)	No task matched `serid` / `service_number` / `external_id`.
`TASK_ALREADY_TERMINAL`	(identity)	The task is already finished or cancelled and can't be changed.
`LOAD_DIMENSION_NOT_SUPPORTED`	`load.<dimension>`	The task's product doesn't handle this cargo dimension (weight/volume/packages/cold/fragile/heavy).
`LOAD_VALUE_INVALID`	`load.<dimension>`	The cargo value has the wrong format (weight/volume must be numbers ≥ 0; packages a whole number ≥ 0).

Warning codes (non-blocking — go to `warnings[]`)

Code	Typical field	Meaning
`GEO_ZONE_IGNORED`	`origin.zone`	The zone wasn't found; the task was created without it.
`SPECIAL_PLACE_IGNORED`	`origin.special_place`	The special place wasn't found; ignored.
`RESERVE_PERSONNEL_IGNORED`	`reserve.personnel`	The personnel to reserve wasn't found; ignored.
`COMM_MEDIUM_IGNORED`	`communication_medium`	The communication template wasn't found; ignored.
`SHIFT_IGNORED`	`shift`	The shift wasn't found; ignored.
`ATTACHMENT_LINK_FAILED`	`attachments`	The attachment link couldn't be registered.
`OAV_FIELD_UNKNOWN_IGNORED`	`dynamic_fields.<label>`	The label doesn't match a field on the product; ignored.
`ASSIGN_TEMPLATE_IGNORED`	`assignment.assign_template`	The template doesn't belong to the resource; the resource default was used.

Transport / shape / auth errors (full-failure envelope)

HTTP	Code	Description
`400`	`VALIDATION_ERROR`	Shape validation failed (unknown field, wrong type, missing required, length, batch empty or over 50). Detail in `error.details[]`.
`401`	`UNAUTHORIZED` / `TOKEN_EXPIRED`	Missing, invalid, or expired tenant / Authorization / X-API-Key.
`403`	`FORBIDDEN`	The API key lacks `APICLI_TASKS_CREATE` / `APICLI_TASKS_UPDATE` / `APICLI_TASKS_CANCEL`.
`404`	`NOT_FOUND`	The task doesn't exist (single-object update/cancel).
`429`	`RATE_LIMITED`	Exceeded 20 req/min.
`500`	`INTERNAL_ERROR`	Unexpected server error.

POST always creates

There is no upsert on this rail. Re-sending a POST with the same external_id creates a second task. To change an existing task, use PUT.

Three identifiers in every response​

Classification — Motive OR provision+cause+subcause​

Create Task​

Request Body — top-level fields​

classification fields​

origin / destination fields​

reserve fields​

assignment fields​

account fields​

dynamic_fields (OAV)​

attachments fields​

load (cargo data)​

Code Example​

Batch Example​

Example Response​

Result item fields​

Update Task​

Identifying a task​

Request Body​

Code Example​

Example Response​

Cancel Task​

Request Body​

Code Example​

Example Response​

Errors​

Two validation layers​

Issue shape​

Per-item error codes (hard fail — block the item)​

Warning codes (non-blocking — go to warnings[])​

Transport / shape / auth errors (full-failure envelope)​

Related​

Three identifiers in every response

Classification — Motive OR provision+cause+subcause

Create Task

Request Body — top-level fields

`classification` fields

`origin` / `destination` fields

`reserve` fields

`assignment` fields

`account` fields

`dynamic_fields` (OAV)

`attachments` fields

`load` (cargo data)

Code Example

Batch Example

Example Response

Result item fields

Update Task

Identifying a task

Request Body

Code Example

Example Response

Cancel Task

Request Body

Code Example

Example Response

Errors

Two validation layers

Issue shape

Per-item error codes (hard fail — block the item)

Warning codes (non-blocking — go to `warnings[]`)

Transport / shape / auth errors (full-failure envelope)

Related