This document describes quick API implementation details of a simple workflow to create and manage an order. All examples are provided as
curl commands. Review API reference to learn more about requests and responses.
Table of Contents
- Step 1: Obtain ClientID and ClientSecret
- Step 2: Authenticate your API client
- Step 3: Create an order
- Step 4: Find a carrier
- Step 5: Send a load offer
- Step 6: Track
- Step 7: Get a BOL
- Step 8: Mark as paid to a carrier
Step 1: Obtain ClientID and ClientSecret
ClientID and ClientSecret are available after creating an account on Shipper TMS. Request access if you don't have an account yet.
Step 2: Authenticate your API client
All API requests must be authenticated. The API supports OAuth 2.0.
Our first request is to send an authentication request:
This API request uses basic access authentication. Use
ClientSecret as credentials. The API returns a successfull response with
access_token if the credentials are correct:
Step 3: Create an order
To follow the simple workflow, the API client should:
- Create an order
- Find a carrier
- Send the order to the carrier as a load offer
- Track the status(es) of the load offer and order
- Get BOL
- Mark the order as paid to the carrier
Create an order by sending a
POST request to
This request creates an order and returns its details with the unique global identifier:
guid. The API client should use this field to find, update, manage, or delete the order (or any object in the system).
A sample response can be reviewed on the API reference: Create an order.
To partially update an order
In order to perform the partial update, you should send a payload with a set of fields that needs to be updated. The content type of the request should be
application/merge-patch+json (the partial update is implemented according to JSON Merge Patch standard proposed in RFC 7396). Field values that are included in the payload replace old values. Fields that aren't included in the payload remain untouched.
Notice that according to the standard it is not possible to patch part of an array. For example, if you send a nested
vehicles array field in a payload, the vehicle list in the order will be completely overwritten by the content of this array.
The following example demonstrates a partial update of
Please, see details on how to use the HTTP PATCH method for partial order update from the API reference.
Step 4: Find a carrier
When the order is ready to ship, it's time to find a carrier who can move this order. We support the flows below that help shippers and brokers to move loads:
- Via Super Loadboard: the order is posted to Super Loadboard and Super Dispatch notifies carriers who can move this order. Preferred carriers can book this order immediately. Other carriers can send a load request. The process is fully automated here.
- Via Central Dispatch: the order is posted to Central Dispatch and interested carriers will call you using more traditional methods. Later, this order can be assigned to a carrier, and the carrier may use Super Dispatch to move the order.
- The API client does know what carrier can move this order: the carrier's
guidor USDOT number is stored somewhere. In this case, the order can be sent to the carrier directly as a load offer.
Let's assume that you know the carrier's USDOT number or
Step 5: Send a load offer
You can use
carrier_usdot to send a load offer to a carrier that is registered in Super Dispatch:
This request (reference) creates a load offer, and sends it to the carrier as an email and text message. The carrier can accept the load offer or decline it.
If carrier is not yet registered in Super Dispatch, you can indicate
carrier_phone to create a load offer.
Carrier will be created in our system provided if they accept the load offer.
Each load offer has its own
guid is necessary to track the offer's status.
Step 6: Track
All the statuses are tracked via webhooks. A webhook action is sent to a URL when the load offer or order status is changed, for example: the carrier accepted or declined the offer, a driver picked up or delivered the order.
Read more about Webhooks.
Step 7: Get a BOL
The order BOL can be accessed by sending a GET request to
The response contains the BOL URL (a PDF file):
Step 8: Mark as paid to a carrier
When you send money to the carrier, you can document it using the endpoint
The response is a full order object. Reference: Mark an order as paid to the carrier.