Stage - Fulfillment API
Get Dispatches (Batch)
Get a collection of dispatches for the provided dispatch IDs or URLs
post
https://fulfillment-api.centraldispatch.com/api/fulfillments/batch
Query Parameters
includeChangesboolean
Indicates whether the response should include change records (dispatch status change and additional information records with the dispatch and dispatch vehicle status change and dispatch vehicle date change records with the dispatch vehicle).
Default:false
Example:true
includeNotesboolean
Indicates whether the response should include internal load notes for the dispatch. Notes are scoped to the caller’s customer ID and profile type.
Default:false
Example:false
Headers
Content-Typestringrequired
The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.
Example:application/vnd.coxauto.v1+json
Body
application/json
Body
application/json
An array of dispatch IDs and/or dispatch URLs.
array | null[string]
Response
application/json
Response
application/json
OK. Successful request.
DispatchCollection
A collection of dispatches.
hrefstring
The URL used to query the current collection of the resource.
Example:https://fulfillment-api.centraldispatch.com/api/fulfillments/id/d159acc0-e89b-12d3-a456-426614174000
countinteger(int32)
The total count of resources in the collection.
Example:23
itemsarray[object]
Details of a dispatch.
Show Child Parameters
post/api/fulfillments/batch
Authentication
Query Parameters
Headers
Body
[
"d159acc0-e89b-12d3-a456-426614174000",
"157a16f0-503d-4256-ba60-a4876e8eb9bb"
]
application/json
Search Dispatches
Get a collection of dispatch IDs based on the specified search criteria.
📝 Important Notes
- If calling as a broker the
X-Profile-Typeheader must be included to distinguish between calling as a dealer or carrier. - Possible values:
carrier,dealer.
post
https://fulfillment-api.centraldispatch.com/api/fulfillments/search
Headers
X-Profile-Typestring
Required when calling as a broker, use to specify the caller’s role. The value must be either carrier or shipper. Default is shipper
Example:carrier
Content-Typestringrequired
The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.
Example:application/vnd.coxauto.v1+json
Body
application/json
Body
application/json
DispatchSearchRequest
DispatchSearchRequest
Details of the dispatch search.
searchFieldsobject
Details of search fields.
Show Child Parameters
offsetinteger(int32)
Determines which record in the collection will be the first one displayed. This value is 1-based, meaning the count starts at 1. Please put this and limit at the end of the request.
Example:10
limitinteger | null(int32)
The maximum number of items to be returned in the response. Please put this and offset at the end of the request.
Default:50
Example:1
sortFieldsarray | null[object]
Details of search sort.
Show Child Parameters
Response
application/json
Response
application/json
OK. Successful request.
SearchDispatchResult
Details of a dispatch search.
itemsarray | null[string]
A collection of dispatch IDs.
Example:["d159acc0-e89b-12d3-a456-426614174000"]
countinteger(int32)
The maximum number of items to be returned in the response.
Example:1
totalRecordsinteger(int64)
The total count of resources in the collection.
Example:100
post/api/fulfillments/search
Authentication
Headers
Body
{
"searchFields": {
"dispatchStatus": [
"PENDING_PICKUP",
"DELIVERED"
],
"dispatchDate": {
"op": "RANGE",
"startDateTime": "2024-08-01T00:00:00Z",
"endDateTime": "2024-09-10T00:00:00Z"
}
},
"sortFields": [
{
"name": "actualPickUpDateTime",
"direction": "ASCENDING"
},
{
"name": "estimatedDropOffDateTime",
"direction": "ASCENDING"
},
{
"name": "needAction",
"direction": "DESCENDING"
}
],
"limit": 10,
"offset": 0
}
application/json
Update Dispatch
Update an existing dispatch.
📝 Important Notes
- Every desired property must be sent, null properties will be deleted.
- The
If-Matchheader is required and its value can be found in theETagresponse header of the resource’s GET by ID endpoint. - The ID of the resource is returned in resource’s create endpoint. The response will contain a
Locationheader that contains the fully qualified URL of the newly created resource. The final segment of the URL will be the ID of the resource.
post
https://fulfillment-api.centraldispatch.com/api/fulfillments/update
Headers
If-Matchintegerrequired
This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the ETag header that was received on the preceding get call.
Example:8675309
Content-Typestringrequired
The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.
Example:application/vnd.coxauto.v1+json
Body
application/json
Body
application/json
UpdateDispatchRequest
UpdateDispatchRequest
Details of a dispatch.
dispatchIdstring(uuid)
The ID of the dispatch.
Example:d159acc0-e89b-12d3-a456-426614174000
externalOrderIdstring | null
The identifier of the order that created the dispatch in the shipper system managed by the user. This value is not visible on the Central Dispatch website.
Example:ORD-2023-0001
externalIdstring | null
An identifier managed by the user. Shippers can use this field to map a record (e.g. order, shipment, dispatch) in their local TMS to a Central Dispatch record. This value is displayed as the load number on the Central Dispatch website.
Example:RND10 CHEV
priceobject
Details of the dispatch price.
Show Child Parameters
stopsarray[object]
Details of a stop.
Show Child Parameters
vehiclesarray[object]
Details of a vehicle.
Show Child Parameters
additionalInformationarray | null[object]
Details of additional information.
Show Child Parameters
balanceAmountnumber(double)
The balance amount that will be due after the COD/COP payment is applied.
>= 0
Example:300
balanceAmountCurrencystring | null
The currency of balanceAmount.
Default:USD
Example:USD
balancePaymentMethodstring | null
The payment method with which the balance due payment will be paid. Required if balanceAmount is greater than 0. This list is not exhaustive and additional values may be added at any time.
Allowed values:CASHCERTIFIED_FUNDSCOMPANY_CHECKCOMCHEKTCH
Example:CASH
balancePaymentTermsBeginOnstring | null
The terms for beginning balance payment. Required if balanceAmount is greater than 0. This list is not exhaustive and additional values may be added at any time.
Allowed values:PICKUPDELIVERYRECEIVING_SIGNED_BOL
Example:PICKUP
balancePaymentTimestring | null
The time frame when the balance payment is due. Required if balanceAmount is greater than 0. This list is not exhaustive and additional values may be added at any time.
Allowed values:IMMEDIATELYTWO_BUSINESS_DAYS_QUICK_PAYFIVE_BUSINESS_DAYSTEN_BUSINESS_DAYSFIFTEEN_BUSINESS_DAYSTHIRTY_BUSINESS_DAYS
Example:IMMEDIATELY
codAmountnumber(double)
The cash on delivery (COD) or cash on pick up (COP) amount due.
>= 0
Example:200
codAmountCurrencystring | null
The currency of codAmount.
Default:USD
Example:USD
codPaymentLocationstring | null
The location that COD/COP payment is due. Required if codAmount is greater than 0. This list is not exhaustive and additional values may be added at any time.
Allowed values:PICKUPDELIVERY
Example:PICKUP
codPaymentMethodstring | null
The method for the COD/COP payment. Required if codAmount is greater than 0. This list is not exhaustive and additional values may be added at any time.
Allowed values:CHECKCASH_CERTIFIED_FUNDS
Example:CASH_CERTIFIED_FUNDS
instructionsstring | null
Displayed in Central Dispatch website/app as “Load-Specific Terms”, these are provisions added to a contract that specify extra obligations, rights, or conditions beyond the standard terms.
Real Life Example: Charging cables need to be picked up with vehicles and if left behind a $200 fee will be applied.
Rules: This information will be visible only to the assigned carrier after the load is dispatched, and it will no longer be editable at that point.
Note: The original instructions value must be sent in any update request. If a different value is provided, the update will be rejected with status code 422 Unprocessable Entity.
Example:Charging cables need to be picked up with vehicles and if left behind a $200 fee will be applied.
preDispatchNotesstring | null
Provides general preparation instructions for shipments. This should not contain sensitive data as it is made available prior to acceptance of terms by a carrier.
Rules: This information will always be visible to carriers, and it will no longer be editable once the load is dispatched.
Note: The original preDispatchNotes value must be sent in any update request. If a different value is provided, the update will be rejected with status code 422 Unprocessable Entity.
Example:In order to pick up the keys you will have to walk through a lot with a big dog that protects it, he's chained but will bark at you.
transportationReleaseNotesstring | null
Displayed in Central Dispatch website/app as “Transport Special Instructions”, these are specific guidelines or details for the safe and efficient pick up, delivery, or transportation of a load. This may contain sensitive data and is not available prior to acceptance of terms by a carrier.
Rules: This information is visible only to the assigned carrier after the load is dispatched and remains editable at any time.
Example:You will need special clearance to get in the lot. Call Jean at 303-999-1212.
requiresDriverVerificationAtPickUpboolean | null
Indicates if the driver verification process is required. A driver must be assigned to the load before delivery. Information will be emailed to the contact physically present at the pickup location for use in verifying the driver’s identification. The Central Dispatch Mobile App must be used to perform the pickup and delivery inspection. (Only currently applicable to select private Marketplaces).
Default:false
Example:true
Response
Response
No Content. Successful request.
post/api/fulfillments/update
Authentication
Headers
Body
{
"dispatchId": "d159acc0-e89b-12d3-a456-426614174000",
"externalId": "RND10 CHEV",
"externalOrderId": "ORD-2023-0001",
"price": {
"totalPrice": 500,
"priceUnits": "USD"
},
"codAmount": 200,
"codAmountCurrency": "USD",
"codPaymentMethod": "CASH_CERTIFIED_FUNDS",
"codPaymentLocation": "PICKUP",
"balanceAmount": 300,
"balanceAmountCurrency": "USD",
"balancePaymentTime": "IMMEDIATELY",
"balancePaymentTermsBeginOn": "PICKUP",
"balancePaymentMethod": "CASH",
"preDispatchNotes": "In order to pick up the keys you will have to walk through a lot with a big dog that protects it, he's chained but will bark at you.",
"transportationReleaseNotes": "You will need special clearance to get in the lot. Call Jean at 303-999-1212.",
"stops": [
{
"stopNumber": 1,
"stopType": "DEALER",
"name": "ABC Cars lot",
"address": {
"address1": "345 W Elm St.",
"address2": "2nd Floor",
"city": "Anaheim",
"state": "CA",
"zipCode": "92802",
"countryCode": "US"
},
"contact": {
"name": "Mickey Smith",
"phone": "949-555-0101",
"phone1": "949-555-1323",
"phone2": "949-555-2434",
"phone3": "949-555-3545",
"cellPhone": "949-555-1212",
"email": "mickey@snoogle.com"
},
"externalLocationId": "Loc123",
"isTWIC": true,
"siteId": "ABC",
"latitude": "33.81228788622535",
"longitude": "-117.91836265987132",
"buyerNumber": "12345"
},
{
"stopNumber": 2,
"stopType": "COMMERCIAL_BUSINESS",
"name": "XYZ Inc.",
"address": {
"address1": "255 Sands Ave.",
"city": "Las Vegas",
"state": "NV",
"zipCode": "89169",
"countryCode": "US"
},
"contact": {
"name": "Dean Vega",
"phone": "702-555-0101",
"phone2": "702-555-0101",
"cellPhone": "702-555-1212",
"email": "dvega@doogle.com"
},
"externalLocationId": "Loc777",
"isTWIC": true,
"siteId": "Spere",
"latitude": "36.121343020081525",
"longitude": "-115.16195281104913",
"buyerNumber": "9876"
}
],
"vehicles": [
{
"vehicleAttributes": [
{
"type": "damage",
"name": "hasKeys",
"value": false
}
],
"vehicleId": "b331c130-e89b-12d3-a456-426614174000",
"externalVehicleId": "EXT123456",
"vin": "KL8CH6SA6NC001234",
"distance": 267,
"distanceUnits": "MILES",
"pickUpLocationId": 1,
"dropOffLocationId": 2,
"carrierPrice": 500,
"carrierPriceUnits": "USD",
"type": "CAR",
"size": "MEDIUM",
"shipperRequestedPickupDate": "2025-09-30T00:00:00.000Z",
"shipperRequestedDropOffDate": "2025-10-15T00:00:00.000Z",
"color": "Red",
"isInOperable": false,
"isEnclosed": true,
"year": 2022,
"make": "Chevrolet",
"model": "Spark",
"subModel": "ACTIV",
"weight": 2246,
"weightUnits": "lbs",
"inspectionType": "ART",
"isDriveAway": false,
"licensePlate": "B314PIE",
"licensePlateState": "CA",
"lotNumber": "LOT789",
"additionalInformation": "The vehicle is in the back of the lot behind the big tree.",
"pickUpDateType": "NO_EARLIER_THAN",
"dropOffDateType": "ESTIMATED"
}
],
"additionalInformation": [
{
"name": "1d1d1d1d-e89b-12d3-a456-426614174000",
"value": "The number one"
}
]
}
Update Dispatch Dates
Update the pick up and/or delivery dates of an existing dispatch.
put
https://fulfillment-api.centraldispatch.com/api/fulfillments/id/{dispatchId}/dates
Path Parameters
dispatchIdstring(uuid)required
The ID of the dispatch.
Example:d159acc0-e89b-12d3-a456-426614174000
Headers
If-Matchintegerrequired
This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the ETag header that was received on the preceding get call.
Example:8675309
Content-Typestringrequired
The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.
Example:application/vnd.coxauto.v1+json
Body
application/json
Body
application/json
UpdateDispatchDatesRequest
UpdateDispatchDatesRequest
Details of dispatch vehicle date item.
dispatchIdstring(uuid)
The ID of the dispatch.
Example:d159acc0-e89b-12d3-a456-426614174000
dispatchVehiclesarray[object]
Details of dispatch vehicle dates.
Show Child Parameters
Response
Response
Accepted. Successful request.
put/api/fulfillments/id/{dispatchId}/dates
Authentication
Path Parameters
Headers
Body
{
"dispatchId": "d159acc0-e89b-12d3-a456-426614174000",
"etag": 1234567,
"dispatchVehicles": [
{
"dispatchVehicleId": "b331c130-e89b-12d3-a456-426614174000",
"dateChanges": [
{
"dateType": "ESTIMATED_PICKUP",
"dateValue": "2025-11-05T00:00:00.000Z",
"dateChangeReasonId": "da1e0000-e89b-12d3-a456-426614174000",
"notes": "Weather delay."
}
]
}
]
}
Respond to Dispatch
A carrier can accept or decline a load that has been assigned to them by the shipper.
👥 Customer Type
- Carrier
📝 Important Notes
- May only be used by the assigned carrier or a broker with the carrier profile that is assigned to.
- Only dispatches with a status of
NOT_SIGNEDwill be processed.
post
https://fulfillment-api.centraldispatch.com/api/fulfillments/id/{dispatchId}/respond
Path Parameters
dispatchIdstring(uuid)required
The ID of the dispatch to respond to.
Example:d159acc0-e89b-12d3-a456-426614174000
Headers
If-Matchintegerrequired
This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the ETag header that was received on the preceding get call.
Example:8675309
Content-Typestringrequired
The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.
Example:application/vnd.coxauto.v1+json
Body
application/json
Body
application/json
RespondToDispatchRequest
RespondToDispatchRequest
Details of the respond request.
acceptboolean
Indicates whether the dispatch should be accepted or declined.
Example:true
inspectionAcknowledgedboolean
Indicates whether the require inspection requirement was acknoowledged.
Default:false
Example:true
carrierEstimatedPickupDatestring | null(date-time)
The date the carrier estimates the vehicle will be picked up, in UTC/ISO 8601 format. Only the date portion of the value passed will be saved.
Example:2025-07-15T00:00:00.000Z
carrierEstimatedDeliveryDatestring | null(date-time)
The type of delivery date. Only the date portion of the value passed will be saved.
Example:2025-08-15T00:00:00.000Z
Response
Response
Accepted. Successful request.
post/api/fulfillments/id/{dispatchId}/respond
Authentication
Path Parameters
Headers
Body
{
"accept": true
}