/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), per-weekday time offsets, and the vehicle-class policy for rebuilds of the generated tours ('vehicleClassAdjustmentStrategy' — set 'preserve' when the class is contractually fixed for this line; omitted behaves as 'recalculate'). 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

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.

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