/drafts

Create a new transport draft. Transport drafts are used to compose and validate transports before being submitted to create orders, shipments, and / or tours.

transport shape (for product evaluation). The draft's transport field is stored leniently — drafts are work-in-progress and partial shapes are accepted. However, the draft only becomes usable for POST /products/{productId}/execute once transport parses cleanly against TransportForProducts. If you intend to evaluate a product against the draft, send a transport with these top-level keys: template, shipperId, shipperTeamId, shipperUserId, order, shipments (array), sharedShipment, tour, multiStopData, discoveredFields, confirmedSections, features, properties (with shipmentsCreator and tourBar sub-objects). Any missing or malformed top-level field surfaces from /execute as HTTP 412 with the literal TransportForProductsSchema parse failed: <serialised validation issues> so you can patch the draft and retry. Optional fields under the same root: products, productsMode (defaults to "booking"), shipperOffers, smartInsights. Country codes inside customer (and similar address sub-objects) MUST be ISO-3166 alpha-3 ("DEU", not "DE").

Set recurringSchedule to create a recurring-master draft — at least 2 stops and a vehicleClassId are then required, and startsAt (if given) must not be in the past. The draft is created with status draft; activate it via POST /drafts/{id}/actions with type=activate-recurring. Omit recurringSchedule for a regular one-off draft.

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

Request to create a transport draft. See the route description above for the transport shape required for /execute-readiness; for any other draft purpose (e.g. inbox triage), transport may be partial or omitted.

string
enum
required

Origin of the draft. One of: 'decode' (extracted from an inbound email/document via a MagicInbox), 'hub' (created in the Hub composer), 'manual' (created directly in the composer or via this API). Only 'decode' drafts may carry a payload.

Allowed:
string
enum
required

Lifecycle status at creation. Use 'draft' for 'manual'/'hub' drafts, or 'review-order'/'review-rfq' for 'decode' drafts. The recurring statuses ('active-recurring', 'paused-recurring', 'ended-recurring') cannot be set here — a recurring master is created with 'draft' and transitioned via the activate/pause/resume/end actions, which run the cross-entity validations.

boolean

Optional client-computed validity flag. Informational only — the server re-validates on submit and on recurring activation.

string

Operator-facing name for the draft. For a recurring master this may be a Liquid template: '{{ weekday }}' and '{{ date }}' are rendered per generated tour (e.g. 'Pressetour Ruhr {{ weekday }} {{ date }}').

transport
object

The transport payload — shipper, order, shipments, stops and loads ('multiStopData'), tour, products, and scheduling. Stored leniently for work-in-progress drafts (see the endpoint description for the shape required for product evaluation). For a recurring master, 'transport.multiStopData.stops' defines the recurring line — at least 2 stops are required, each with an address and a time-of-day window; a stop's optional 'dayOffset' (non-negative integer) places it on a later day of a multi-day tour relative to the cron-trigger day. 'transport.tour.vehicleClass' is required for a recurring master.

string
required

ID of the TransportShape that gates which fields are shown and validated for this draft. For a recurring master, use a shape whose recurring mode is enabled and whose outputs include 'tour'.

string

For 'decode' drafts: the ID of the MagicInbox the draft was extracted from.

payload
object

Only for 'decode' drafts: the raw extracted DecodeJob result. Must be omitted for 'manual' and 'hub' drafts.

string

When set, an existing draft is used as a template for the new draft — its fields are copied as the starting point.

recurringSchedule
object

Set this to turn the draft into a recurring master — a line that generates tours on a schedule rather than a single one-off transport. Carries the cron expressions, timezone, lead time ('leadTimeDays'), validity window ('startsAt'/'endsAt' in epoch seconds), and per-weekday time offsets. When set, extra constraints apply on create: at least 2 stops in 'transport.multiStopData.stops', a 'transport.tour.vehicleClass', and 'startsAt' must not be in the past. The draft is still created with status 'draft'; activate it via the actions endpoint to start generating tours.

Responses

400

bad request

401

unauthorized

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