Dispatch jobs

10 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.

Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.

List jobs

GET /v1/dispatch/jobs

Scope: dispatch:read or dispatch:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Query parameter	Type	Notes
`status`	string
`pageSize`	string
`cursor`	string
`vehicleId`	—
`driverId`	—
`from`	—
`to`	—

Request

No body.

Response

200: fields the handler writes, taken from its source.

Field	Type	Notes
`items`	array of object
`items[].id`	—
`items[].number`	—
`items[].displayNumber`	—
`items[].reference`	—
`items[].status`	—
`items[].vehicleId`	—
`items[].driverId`	—
`items[].stops`	array
`items[].notes`	—
`items[].trackingUrl`	—
`items[].overviewUrl`	—
`items[].createdBy`	—
`items[].dispatchedAt`	—
`items[].completedAt`	—
`items[].cancelReason`	—
`items[].createdAt`	string
`items[].updatedAt`	string
`items[].version`	—
`nextCursor`	string

Example

curl "https://api.zaitrack.app/v1/dispatch/jobs" \
  -H "Authorization: Bearer zk_test_…"

Create a job with its stops

POST /v1/dispatch/jobs

Scope: dispatch:write or dispatch:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: no
Step-up MFA: no

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`reference`	string
`notes`	string
`vehicleId`	string	optional
`driverId`	string	optional
`stops`	array of object
`stops[].kind`	string
`stops[].name`	string
`stops[].address`	string
`stops[].lat`	number
`stops[].lon`	number
`stops[].radiusM`	number
`stops[].windowStart`	string	optional
`stops[].windowEnd`	string	optional
`stops[].contactName`	string
`stops[].contactPhone`	string
`stops[].contactEmail`	string
`stops[].contactLanguage`	string
`stops[].notify`	boolean
`stops[].items`	array of object
`stops[].items[].description`	string
`stops[].items[].quantity`	number
`stops[].items[].unit`	string
`stops[].notes`	string

Response

201: fields the handler writes, taken from its source.

Field	Type	Notes
`id`	—
`number`	—
`displayNumber`	—
`reference`	—
`status`	—
`vehicleId`	—
`driverId`	—
`stops`	array of object
`stops[].id`	—
`stops[].seq`	—
`stops[].kind`	—
`stops[].name`	—
`stops[].address`	—
`stops[].windowStart`	—
`stops[].windowEnd`	—
`stops[].status`	—
`stops[].arrivedAt`	—
`stops[].completedAt`	—
`stops[].eta`	—
`stops[].late`	—
`stops[].contactPhone`	—
`stops[].failReason`	—
`stops[].notices`	—
`stops[].contactLanguage`	—
`stops[].contactLanguage`	—
`stops[].pod`	—
`notes`	—
`trackingUrl`	—
`overviewUrl`	—
`createdBy`	—
`dispatchedAt`	—
`completedAt`	—
`cancelReason`	—
`createdAt`	string
`updatedAt`	string
`version`	—

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reference": "…", "notes": "…", "vehicleId": "…", "driverId": "…", "stops": []}'

Get a job

GET /v1/dispatch/jobs/{id}

Scope: dispatch:read or dispatch:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Path parameters: id.

Request

No body.

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create a job with its stops.

Example

curl "https://api.zaitrack.app/v1/dispatch/jobs/$ID" \
  -H "Authorization: Bearer zk_test_…"

Update a job

PATCH /v1/dispatch/jobs/{id}

Scope: dispatch:write or dispatch:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no
If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`reference`	string	optional
`notes`	string	optional
`stops`	array of object	optional
`stops[].kind`	string
`stops[].name`	string
`stops[].address`	string
`stops[].lat`	number
`stops[].lon`	number
`stops[].radiusM`	number
`stops[].windowStart`	string	optional
`stops[].windowEnd`	string	optional
`stops[].contactName`	string
`stops[].contactPhone`	string
`stops[].contactEmail`	string
`stops[].contactLanguage`	string
`stops[].notify`	boolean
`stops[].items`	array of object
`stops[].items[].description`	string
`stops[].items[].quantity`	number
`stops[].items[].unit`	string
`stops[].notes`	string

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create a job with its stops.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X PATCH "https://api.zaitrack.app/v1/dispatch/jobs/$ID" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/json" \
  -d '{"reference": "…", "notes": "…"}'

Dispatch a job to a driver and vehicle

POST /v1/dispatch/jobs/{id}:dispatch

Scope: dispatch:write or dispatch:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: no
Step-up MFA: no
If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request

Fields the handler reads, taken from its source. One handler serves several actions here, so a field may not apply to this one.

Field	Type	Notes
`vehicleId`	string
`driverId`	string	optional
`reason`	string

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create a job with its stops.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs/$ID:dispatch" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"vehicleId": "…", "driverId": "…", "reason": "…"}'

Cancel a job

POST /v1/dispatch/jobs/{id}:cancel

Scope: dispatch:write or dispatch:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: low risk
Step-up MFA: no
If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request

Fields the handler reads, taken from its source. One handler serves several actions here, so a field may not apply to this one.

The same fields as the request of Dispatch a job to a driver and vehicle.

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create a job with its stops.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs/$ID:cancel" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"vehicleId": "…", "driverId": "…", "reason": "…"}'

Mark arrival at a stop

POST /v1/dispatch/jobs/{id}/stops/{stopId}:arrive

Scope: dispatch:write or dispatch:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: no
Step-up MFA: no

Path parameters: id, stopId.

Request

No body: the handler reads none.

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create a job with its stops.

Example

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs/$ID/stops/$STOP_ID:arrive" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

Complete a stop

POST /v1/dispatch/jobs/{id}/stops/{stopId}:complete

Scope: dispatch:write or dispatch:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: no
Step-up MFA: no

Path parameters: id, stopId.

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`recipientName`	string
`note`	string
`signature`	object	optional
`signature.contentType`	string
`signature.data`	string
`photos`	array of object
`photos[].contentType`	string
`photos[].data`	string
`lat`	number	optional
`lon`	number	optional

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create a job with its stops.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs/$ID/stops/$STOP_ID:complete" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"recipientName": "…", "note": "…", "signature": {"contentType": "…", "data": "…"}, "photos": [], "lat": 0, "lon": 0}'

Fail a stop with a reason

POST /v1/dispatch/jobs/{id}/stops/{stopId}:fail

Scope: dispatch:write or dispatch:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: no
Step-up MFA: no

Path parameters: id, stopId.

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`reason`	string

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create a job with its stops.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs/$ID/stops/$STOP_ID:fail" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason": "…"}'

A job's proof-of-delivery file

GET /v1/dispatch/jobs/{id}/files/{fileId}

Scope: dispatch:read or dispatch:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Path parameters: id, fileId.

Request

No body.

Response

200: the file itself, with its content type and a Content-Disposition file name.

Example

curl "https://api.zaitrack.app/v1/dispatch/jobs/$ID/files/$FILE_ID" \
  -H "Authorization: Bearer zk_test_…"

List jobs​

Request​

Response​

Example​

Create a job with its stops​

Request​

Response​

Example​

Get a job​

Request​

Response​

Example​

Update a job​

Request​

Response​

Example​

Dispatch a job to a driver and vehicle​

Request​

Response​

Example​

Cancel a job​

Request​

Response​

Example​

Mark arrival at a stop​

Request​

Response​

Example​

Complete a stop​

Request​

Response​

Example​

Fail a stop with a reason​

Request​

Response​

Example​

A job's proof-of-delivery file​

Request​

Response​

Example​

List jobs

Request

Response

Example

Create a job with its stops

Request

Response

Example

Get a job

Request

Response

Example

Update a job

Request

Response

Example

Dispatch a job to a driver and vehicle

Request

Response

Example

Cancel a job

Request

Response

Example

Mark arrival at a stop

Request

Response

Example

Complete a stop

Request

Response

Example

Fail a stop with a reason

Request

Response

Example

A job's proof-of-delivery file

Request

Response

Example