/tours/actions

Create a new tour by submitting a create-action payload. Accepts a 'create' type action with stops, vehicleClassId, and region. Each stop is placed at its loading point when address.shipperAddressLoadingPoint has latitude and longitude, else at the address latitude and longitude you send, else at the geocoded address.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Create-action payload (type='create', stops[min 2], vehicleClassId, region required). Optional properties sets the new tour's custom property values, keyed by the ids of property definitions defined for tours. A document-type property takes the id of an uploaded document; the property then stores the id of a link from that document to the new tour.

string
enum
required
Allowed:
stops
array of objects
required
length ≥ 2

The tour's stops in execution order; at least two are required (a pickup and a dropoff).

stops*
address
object
required

The stop's address. When shipperAddressLoadingPoint has latitude and longitude, the stop is placed at that loading point, the same position shipments to this address use. Otherwise latitude and longitude, when provided, are stored as the stop's authoritative position; when absent, the address is geocoded. Sending the exact coordinates your shipments carry keeps a kept stop and its incoming freight recognized as one site.

number
required
≥ 0

Epoch-seconds timestamp for the start of this stop's planned arrival window, interpreted in Europe/Berlin.

number
required
≥ 0

Epoch-seconds timestamp for the end of this stop's planned arrival window, interpreted in Europe/Berlin.

number
≥ 0

Expected time spent at this stop, in seconds.

pickupDocuments
array of objects
pickupDocuments
proofRequirements
array of strings

Proof types the driver must capture at this stop before completing it.

proofRequirements
Allowed:
string

Free-text note for this stop, shown to the driver.

address
object
required

The stop's address. When shipperAddressLoadingPoint has latitude and longitude, the stop is placed at that loading point, the same position shipments to this address use. Otherwise latitude and longitude, when provided, are stored as the stop's authoritative position; when absent, the address is geocoded. Sending the exact coordinates your shipments carry keeps a kept stop and its incoming freight recognized as one site.

number
required
≥ 0

Epoch-seconds timestamp for the start of this stop's planned arrival window, interpreted in Europe/Berlin.

number
required
≥ 0

Epoch-seconds timestamp for the end of this stop's planned arrival window, interpreted in Europe/Berlin.

number
≥ 0

Expected time spent at this stop, in seconds.

pickupDocuments
array of objects
pickupDocuments
proofRequirements
array of strings

Proof types the driver must capture at this stop before completing it.

proofRequirements
Allowed:
string

Free-text note for this stop, shown to the driver.

string
required

Internal VehicleClass id (UUID) for the tour.

string
required
length ≥ 1

The operational region, given as the region's identifier (a slug such as "berlin"), not its UUID id.

extras
array
extras
string
string

Public comment on the tour (visible to the carrier).

string

Internal comment on the tour (operator-only).

carrierInfo
object

Optional carrier assignment at creation; providing a carrierId makes the tour start Assigned rather than Unassigned.

string
enum

When set to preserve, rebuilds keep the created stops even when they carry no freight, until a rebuild with the purge override sweeps them or a rearrange omits them. When omitted or purge, rebuilds derive stops from freight alone (the default behavior).

Allowed:
properties
object

Custom property values for the new tour, keyed by the id of a property definition defined for tours; each value is validated against its definition. An unknown property id or a value of the wrong type is rejected with a 400 error and no tour is created. When omitted, or when every value is null, the tour has no properties. The value of a document-type property is the id of an uploaded document: the tour is created with a link from that document to the new tour, and the property stores the id of that link. A request that creates no tour creates no link.

string
length between 1 and 128

Idempotency id of this action, unique per tenant (a UUID is a good choice). Sending the same id again returns the original result with status duplicate instead of applying the action twice. Generated by the platform when omitted.

Responses

400

validation error (an unknown property id or a value of the wrong type) or invalid vehicleClassId

401

unauthorized

403

The role of the API key does not allow this action. The key needs a role with the matching permission, for example full access.

503

the request ran out of time while an external property validator was still running; the tour was not created, send it again

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json