Book freight with a carrier.

Create a dispatch job. The response carries the job document in PROCESSING with nothing from the carrier yet; the carrier is tendered asynchronously, so poll the job until is_terminal is true.

Two request shapes, told apart by rate_id. With it, everything about the shipment comes from the rate. Without it, the shipment is stated in full and the carrier account is named — which only an account with COLLECT billing terms may do.

LTL and VLTL are the only modes this surface books today. FTL and PARCEL dispatch are not yet available here — a rate quoted for either cannot be booked through this endpoint, even though the rate itself exists.

Rated with both stop contacts? Send only rate_id — the Book a rate example. That is the case when the rating pickup stop carried company_name, first_name and phone and the delivery stop company_name and phone, as the create_rating_job example does.

Rated without them? Add origin_contact and/or destination_contact for the stop that falls short — the Book a rate, adding contacts example.

Field Required
rate_id Yes
origin_contact (company_name, first_name, phone) Only if the rating pickup stop carried no contact with all three; not checked here, but the carrier rejects a pickup with nobody to call
destination_contact (company_name, phone) Only if the rating delivery stop carried no contact with both; rejected with 400 missing_delivery_contact otherwise
origin_planned_window / destination_planned_window No — only if the date moved since rating
references / notes_for_carrier No

No rate to book against? Send the shipment in full — the Book without a rate example. Sending rate_id alongside any of these fields is rejected: the two shapes cannot mix.

Field Required
account_id Yes
provider_code Yes
mode Yes
stops (2 or more) Yes
requested_window on the pickup stop (earliest, latest) Yes
contact.company_name / first_name / phone on the pickup stop Yes
contact.company_name / phone on the delivery stop Yes
handling_units (1 or more) Yes
equipment, accessorials, service_code, carrier_rate_id, gross_weight, total_declared_value, customer_reference_number No
SecurityAPIKeyHeader
Request
header Parameters
Idempotency-Key
string (Idempotency-Key) <= 255 characters

Optional client-generated key making the create safe to retry. Replaying the same key with the same body returns the original dispatch instead of booking again. Without a key every request books afresh, so a retry tenders a second pickup.

X-Shipwell-Version
string (X-Shipwell-Version)

Pins this request to the API as it behaved on the given ISO date, e.g. 2026-08-25. Omitted or unparseable means the oldest behaviour, so a client that never sends it keeps the behaviour it was written against.

Request Body schema: application/json
required
One of:

Book the carrier that produced a rate.

Everything about the shipment — the carrier account, the mode, the stops, the freight, the price — comes from the rate and the rating request behind it. The four override fields exist because the rate is a snapshot: rating stops routinely carry no contact, and carriers that reject dates at rating time carry carrier-generated timestamps instead of the window the customer asked for. So rate_id alone is a complete request only when the rating pickup contact has company_name, first_name and phone and the delivery contact has company_name and phone; otherwise send the override for the stop that falls short. The example sends both, which is the smallest request that always books.

Use this shape whenever you already called Rating. If you have not rated this shipment, use PublicObjectDispatchRequest instead — sending rate_id is what selects this shape. See the create_dispatch_job operation description for the full field breakdown.

Array of objects (References)

Identifiers forwarded to the carrier and echoed back on the response. A public dispatch has no Shipwell shipment behind it, so Shipwell never generates a BOL_NUMBER for one: if the carrier needs one, supply it here.

Notes For Carrier (string) or Notes For Carrier (null) (Notes For Carrier)

Free text the carrier sees on the tender.

rate_id
required
string (Rate Id)

The id of the rate to book, as returned by the rating API.

PublicContact (object) or null

Replaces the contact on the pickup stop the rate carries.

PublicContact (object) or null

Replaces the contact on the delivery stop the rate carries. Required when that contact lacks a company_name or phone: the bill of lading names the consignee.

PublicTimeWindow (object) or null

Replaces the pickup window the rate carries, when it has since moved.

PublicTimeWindow (object) or null

Replaces the delivery window the rate carries.

Responses
201

Successful Response

Response Schema: application/json
required
object (DispatchResult)

A dispatch job: whether the carrier has answered, and what it said.

Polling is the only completion signal, and it is bounded: a dispatch the carrier never confirms is expired by the stale-dispatch cron, so is_terminal arrives either way.

400

Validation Error

404

No such rate, or no such dispatch job for this tenant.

409

The Idempotency-Key is claimed by a create that has not finished.

500

An unknown internal server issue occured while processing a request. A report is created and logged.

post/dispatching/jobs
Request samples
application/json

The rating request carried both stop contacts, so the rate is a complete booking.

{
  • "rate_id": "01HZKD9M4TQ4Z8XW0NKZ6RYX4J"
}
Response samples
application/json
{
  • "data": {
    }
}
Copyright © Shipwell 2025. All right reserved.