Request rates from every eligible carrier.

Create a rating job. The response carries the job document with rates still empty; the carriers are contacted asynchronously, so poll the job until is_terminal is true.

modes accepts LTL and VLTL today. Rating handles FTL and PARCEL internally, but neither is exposed on this public surface yet — sending either is rejected.

This schema only enforces what every carrier needs just to accept a request — it does not enforce what a specific carrier needs to actually return a usable quote, because that varies by carrier. The example above is a real payload that returns usable quotes, with both stop contacts already in place so the rate can be dispatched with the smallest request. It asks R+L only; drop capacity_providers to quote every eligible carrier. Move requested_window to a future date before sending it: carriers do not quote a pickup in the past. Start from it rather than from the bare schema minimum below.

Field	Enforced by this API	Also needed for most direct carriers
`modes`	Yes
`stops` (2 or more)	Yes
`stops[].location`	Yes, an object	Full address (`line_1`, `locality`, `region`, `postal_code`, `country`) — a bare postal code round-trips but SAIA, Peninsula and Pitt Ohio reject it
`requested_window` on the pickup stop (`earliest`, `latest`)	Yes
`stops[].contact`	No	Not needed to rate, but dispatching this rate by `rate_id` needs a pickup contact (`company_name`, `first_name`, `phone`) and a delivery contact (`company_name`, `phone`). Send them here, as the example does, or later as `origin_contact` / `destination_contact`
`handling_units` (1 or more)	Yes
`handling_units[].weight` (`value`, `qualifier`)	Yes
`handling_units[].freight_class`	No	SAIA, Peninsula and Duie Pyle reject the request without it
`handling_units[].dimensions`	No	SAIA requires it
`total_linear_feet`	No	Required when `modes` includes `VLTL`
`equipment` (1 or more, `equipment_type` = `DRY_VAN`)	Yes	Every carrier: LTL and VLTL freight moves in the carrier's standard enclosed dry van, so no other type can be quoted. The rest of the list is kept for FTL and Parcel
`capacity_providers`	No	Omit it to quote every carrier eligible for the account
`accessorials`, `references`, `gross_weight`, `total_declared_value`, `customer_reference_number`, `preferred_currency`	No	Send only what applies

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 job instead of rating again. Without a key every request rates afresh, so a retry fans out to the carriers a second time.
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

	PublicLinearDimension (object) or null Trailer floor space. What volume carriers quote VLTL on.
modes required	Array of strings (Modes) non-empty Which transportation modes to request carrier quotes for. `['LTL', 'VLTL']` is the only meaningful combination: every LTL-capable carrier is rated as LTL and the VLTL allowlist carriers receive an additional volume pass. Items Enum: "LTL" "VLTL"
required	Array of objects (Stops) >= 2 items
required	Array of objects (Handling Units) non-empty
accessorials	Array of strings (Accessorials) Shipment-wide accessorials. Per-stop accessorials live on each stop. Items Enum: "AFTER_HOURS_DELIVERY" "AIRPORT_DELIVERY" "AIRPORT_PICKUP" "APPOINTMENT_DELIVERY" "BLIND_SHIPMENT" "CAMP_DELIVERY" "CAMP_PICKUP" "CAPLOAD" "CAPLOADPUP" "CAPLOADTRA" "CERTIFIED_PICKUP" "CFS_DELIVERY" "CFS_PICKUP" "CHURCH_DELIVERY" "CHURCH_PICKUP" "COMMERCIAL_DELIVERY" "COMMERCIAL_PICKUP" "CONSTRUCTION_SITE_DELIVERY" "CONSTRUCTION_SITE_PICKUP" "CONTAINER_FREIGHT_STATION_DELIVERY" "CONTAINER_FREIGHT_STATION_PICKUP" "CONVENTION_TRADESHOW_DELIVERY" "CONVENTION_TRADESHOW_PICKUP" "COUNTRY_CLUB_DELIVERY" "COUNTRY_CLUB_PICKUP" "DECLARED_VALUE_DELIVERY" "DECLARED_VALUE_PICKUP" "DELAY_CHARGE" "DELIVERY_NOTIFICATION" "DISTRIBUTION_CENTER_DELIVERY" "DOCK_DELIVERY" "DOCK_PICKUP" "DOCK_TRANSFER_DELIVERY" "DOCK_TRANSFER_PICKUP" "DRIVER_ASSIST_DELIVERY" "DROP_TRAILER_DELIVERY" "EMERGENCY_DELIVERY" "EV" "EXCESSIVE_LENGTH" "EXCESSIVE_LENGTH_6FT" "EXCESSIVE_LENGTH_7FT" "EXCESSIVE_LENGTH_8FT" "EXCESSIVE_LENGTH_9FT" "EXCESSIVE_LENGTH_10FT" "EXCESSIVE_LENGTH_11FT" "EXCESSIVE_LENGTH_12FT" "EXCESSIVE_LENGTH_13FT" "EXCESSIVE_LENGTH_14FT" "EXCESSIVE_LENGTH_15FT" "EXCESSIVE_LENGTH_16FT" "EXCESSIVE_LENGTH_17FT" "EXCESSIVE_LENGTH_18FT" "EXCESSIVE_LENGTH_19FT" "EXCESSIVE_LENGTH_20FT" "EXCESSIVE_LENGTH_21FT" "EXCESSIVE_LENGTH_22FT" "EXCESSIVE_LENGTH_23FT" "EXCESSIVE_LENGTH_24FT" "EXCESSIVE_LENGTH_25FT" "EXCESSIVE_LENGTH_26FT" "EXCESSIVE_LENGTH_27FT" "EXCESSIVE_LENGTH_28FT" "EXCESSIVE_LENGTH_29FT" "EXCESSIVE_LENGTH_30FT" "EXHIBITION" "EXPEDITED_DELIVERY" "EXPORT_SHIPMENT" "FAIR_AMUSEMENT_DELIVERY" "FAIR_AMUSEMENT_PICKUP" "FARM_DELIVERY" "FARM_PICKUP" "FLATBED" "FLATBED_PICKUP" "FOOD" "FREEZABLE" "GOVERNMENT_SITE_DELIVERY" "GOVERNMENT_SITE_PICKUP" "GROCERY_CONSOLIDATION_DELIVERY" "GROCERY_WAREHOUSE_DELIVERY" "GROCERY_WAREHOUSE_PICKUP" "GUARANTEED" "GUARANTEED_BY_10AM" "GUARANTEED_BY_11AM" "GUARANTEED_BY_15" "GUARANTEED_BY_2PM" "GUARANTEED_BY_3PM" "GUARANTEED_BY_330PM" "GUARANTEED_BY_8AM" "GUARANTEED_BY_9AM" "GUARANTEED_BY_AM" "GUARANTEED_MULTI_HOUR_WINDOW" "GUARANTEED_SINGLE_HOUR_WINDOW" "GUARANTEED_WITHIN_WINDOW" "HAZMAT" "HAZMAT_PICKUP" "HEAT" "HIGH_COST_AREA" "HOLD_AT_LOCATION" "HOLIDAY_DELIVERY" "HOLIDAY_PICKUP" "HOSPITAL_DELIVERY" "HOSPITAL_PICKUP" "HOTEL_DELIVERY" "HOTEL_PICKUP" "INBOUND_SHIPMENT" "INSIDE_DELIVERY" "INSIDE_EDELIVERY" "INSIDE_INGDELIVERY" "INSIDE_INNEDELIVERY" "INSIDE_PICKUP" "LIFT_GATE" "LIFTGATE_DELIVERY" "LIFTGATE_PICKUP" "LIMITED_ACCESS_DELIVERY" "LIMITED_ACCESS_PICKUP" "LUMPER" "MALL_DELIVERY" "MALL_PICKUP" "MILITARY_INSTALLATION_DELIVERY" "MILITARY_INSTALLATION_PICKUP" "MINE_SITE_DELIVERY" "MINE_SITE_PICKUP" "NATIVE_AMERICAN_RESERVATION_DELIVERY" "NATIVE_AMERICAN_RESERVATION_PICKUP" "NO_ROLLUP" "NON_BUSINESS_HOURS_DELIVERY" "NON_BUSINESS_HOURS_PICKUP" "NON_COMMERCIAL_DELIVERY" "NON_COMMERCIAL_PICKUP" "NOTIFY_BEFORE_DELIVERY" "NURSING_HOME_DELIVERY" "NURSING_HOME_PICKUP" "OVER_DIMENSION_FREIGHT" "OVER_LENGTH" "OVERSIZE" "OVERSIZED_DELIVERY" "OVERSIZED_PICKUP" "PALLET" "PALLET_EXCHANGE_DELIVERY" "PALLET_EXCHANGE_PICKUP" "PALLET_JACK_DELIVERY" "PALLET_JACK_PICKUP" "PICKUP_APPOINTMENT" "PICKUP_NOTIFICATION" "PIER_DELIVERY" "PIER_PICKUP" "POISON" "PORT_CUSTOMS_PAPERWORK" "PRISON_DELIVERY" "PRISON_PICKUP" "PROTECT_FROM_FREEZING" "RESIDENTIAL_DELIVERY" "RESIDENTIAL_PICKUP" "RESORT_DELIVERY" "RESORT_PICKUP" "ROOM_OF_CHOICE" "SATURDAY_DELIVERY" "SATURDAY_PICKUP" "SCHOOL_DELIVERY" "SCHOOL_PICKUP" "SELF_STORAGE_DELIVERY" "SELF_STORAGE_PICKUP" "SHIPLDPU" "SINGLE_SHIPMENT" "SORT_AND_SEGREGATE" "SORT_AND_SEGREGATE_PICKUP" "STOP_OFF" "STORAGE" "SUNDAY_DELIVERY" "SUNDAY_PICKUP" "TWO_MAN_DELIVERY" "UNLOAD_AT_DESTINATION" "UTILITY_SITE_DELIVERY" "UTILITY_SITE_PICKUP" "WEEKEND_DELIVERY" "WEEKEND_PICKUP" "WHITE_GLOVE"
required	Array of objects (Equipment) non-empty Required. LTL and VLTL freight moves in the carrier's standard enclosed dry van, so `DRY_VAN` is the only type they quote. Other types are kept for FTL and Parcel.
	Array of objects (Capacity Providers) Empty means every account eligible for the tenant and mode.
	PublicWeight (object) or null
	PublicCurrencyAmount (object) or null
	Array of objects (References) Not persisted, but forwarded to the carriers.
	Customer Reference Number (string) or Customer Reference Number (null) (Customer Reference Number)
preferred_currency	string (Preferred Currency) Default: "USD"

Responses

201

Successful Response

Response Schema: application/json

required

object (RatingJobResult)

A rating job: whether it has finished, and — once expanded — what the carriers answered.

Polling is the only completion signal. Every job reaches a terminal status within roughly rating_task_min_age_minutes (30 by default), because carrier attempts left processing longer than that are finalized as errored by the stale-task reaper.

400

Validation Error

404

The resource requested was not found either because you do not have permissions to access it or it does not exist.

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/rating/jobs

Request samples

application/json

{"accessorials": [ ],
"capacity_providers": [{"provider_code": "RLC"
}
],
"customer_reference_number": "PO-4417",
"equipment": [{"equipment_type": "DRY_VAN"
}
],
"gross_weight": {"unit": "LB",
"value": 500
},
"handling_units": [{"associated_stops": [{"reason": "LOAD",
"stop": {"sequence_id": 1
}
},
{"reason": "UNLOAD",
"stop": {"sequence_id": 2
}
}
],
"description": "Palletized boxes",
"dimensions": {"height": {"unit": "IN",
"value": 50
},
"length": {"unit": "IN",
"value": 48
},
"measurement_type": "DIMENSIONS",
"unit": "IN",
"width": {"unit": "IN",
"value": 40
}
},
"freight_class": "70",
"packaging_type": "PALLET",
"quantity": 1,
"stackable": false,
"weight": {"qualifier": "PER_ITEM",
"unit": "LB",
"value": 500
}
}
],
"modes": ["LTL",
"VLTL"
],
"preferred_currency": "USD",
"stops": [{"accessorials": ["LIFTGATE_PICKUP"
],
"contact": {"company_name": "Acme",
"email": "dock@acme.com",
"first_name": "Dock",
"last_name": "Team",
"phone": "+15125551234"
},
"location": {"country": "US",
"line_1": "515 Congress Ave",
"locality": "Austin",
"location_name": "Austin DC",
"location_type": "BUSINESS_WITH_DOCK",
"postal_code": "78701",
"region": "TX"
},
"requested_window": {"earliest": "2026-09-29T14:00:00Z",
"latest": "2026-09-29T22:00:00Z"
},
"sequence_number": 1
},
{"accessorials": [ ],
"contact": {"company_name": "Beta Receiving",
"email": "rec@beta.com",
"first_name": "Receiving",
"last_name": "Desk",
"phone": "+17135554500"
},
"location": {"country": "US",
"line_1": "4340 Directors Row",
"locality": "Houston",
"postal_code": "77092",
"region": "TX"
},
"sequence_number": 2
}
],
"total_declared_value": {"amount": 12000,
"currency": "USD"
},
"total_linear_feet": {"unit": "FT",
"value": 18
}
}

Response samples

application/json

{"data": {"created_at": "2026-08-19T15:30:32.591Z",
"id": "01HZKD8QKZQ8Z7XV9MKZ5QXW3H",
"is_terminal": false,
"resource_type": "rating_job",
"self_link": "https://api.shipwell.com/rating/jobs/01HZKD8QKZQ8Z7XV9MKZ5QXW3H",
"status": "PROCESSING"
}
}