GET /v1/delivery/jobs/{ref}

GET /v1/delivery/jobs/{ref}

Scope	Idempotency-Key	Operation ID
delivery.read	—	getJob

Authoritative job state with its customer-safe status.

Another tenant's job and an unknown reference are the same TENANT_ACCESS_DENIED. The fee is read from the frozen snapshot. Ends are human-readable descriptions, never coordinates; the partner and rider appear by name only once assigned.

Request

Signed with your API credential: see Authentication.

Parameter	In	Required	Description
ref	path	Yes	Public reference of a delivery job or Bulk child. Pattern ^DX-[0-9A-HJKMNP-TV-Z]{8}$.

Responses

200

The job.

Field	Type	Required	Description
delivery_reference	string	Yes	Public reference of a delivery job or Bulk child. Pattern ^DX-[0-9A-HJKMNP-TV-Z]{8}$.
status	string	Yes	One of: PENDING_DELIVERY, DELIVERY_REQUESTED, OFFERED, ASSIGNED, ARRIVED_AT_PICKUP, PICKED_UP, ON_THE_WAY, ARRIVED_AT_DESTINATION, RECEIPT_CONFIRMED, DELIVERED, CANCELLED, FAILED, DELIVERY_EXCEPTION, RECOVERY_REQUIRED.
customer_status	string	Yes	The customer-facing projection
delivery_fee	string or null	Yes
currency	string or null	Yes
external_order_reference	string or null	Yes
vehicle_type	string	Yes
service_type	string	Yes	One of: EXPRESS, PRIORITY, STANDARD, NEXT_DAY.
pickup	object	Yes
pickup.description	string	Yes	", " — never coordinates
dropoff	object	Yes
dropoff.description	string	Yes	", " — never coordinates
partner	object or null	Yes
partner.name	string	Yes
rider	object or null	Yes
rider.first_name	string	Yes
created_at	string, date-time	Yes
updated_at	string, date-time	Yes
tracking_links	object	No	Only on the creating 201. Each link works until it expires; open it to track.
tracking_links.sender_url	string	Yes
tracking_links.recipient_url	string	Yes

401

Unknown, revoked or wrong-environment credential, bad signature, or expired session.

The error envelope: code, message, detail, request_id.

403

Tenant access denied (existence is not disclosed), insufficient scope, MFA/step-up required, partner blocked or module disabled.

The error envelope: code, message, detail, request_id.

429

Rate limit reached; honour Retry-After.

The error envelope: code, message, detail, request_id.

500

Unexpected failure. Only code and request_id are returned.

The error envelope: code, message, detail, request_id.