Quickstart

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

ClientID and ClientSecret are available after creating an account on Shipper TMS. Request access if you don’t have an account yet.

If you have a shipper account contact the technical support via email [email protected] or phone +1 (816) 974-7002 to obtain your API credentials.

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:

1
2

curl -X "POST" "https://api.shipper.superdispatch.com/oauth/token?grant_type=client_credentials" \
     -u 'ClientID:ClientSecret'

This API request uses basic access authentication. Use ClientID and ClientSecret as credentials. The API returns a successfull response with access_token if the credentials are correct:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...o2KLfb1YmrHYu2pycLgXrGN3gqWeFN1ggUhGq1HQBt8",
  "token_type": "bearer",
  "expires_in": 863999,
  "scope": "read write",
  "aud": ["BTMS", "SLB"],
  "sub": "4e31edcf-768c-4766-8d18-b023a1dcc086",
  "org_guid": "dfbe298a-a7bd-4bb2-bc48-d4a512c2a592",
  "purpose": "public_broker_api",
  "iss": "BTMS",
  "iat": 1614678384,
  "jti": "fdd71132-0d28-472d-bb36-d6af47ee7ed4"
}

Step 3: Create an order

To follow the simple workflow, the API client should:

  1. Create an order
  2. Find a carrier
  3. Send the order to the carrier as a load offer
  4. Track the status(es) of the load offer and order
  5. Get BOL
  6. Mark the order as paid to the carrier

Create an order by sending a POST request to /v1/public/orders:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

curl -X "POST" "https://api.shipper.superdispatch.com/v1/public/orders" \
     -H 'Authorization: Bearer <access_token>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "number": "ORDER-4532",
  "instructions": "",
  "inspection_type": "standard"
  "broker_fee": "50.00",
  "dispatcher_name": "Sherry Turner",
  "transport_type": "OPEN",
  "sales_representative": "Alma Dubois",
  "price": "650.00",
  "loadboard_instructions": "",
  "pickup": {
    "date_type": "estimated",
    "venue": {
      "address": "8 Philmont Dr.",
      "city": "Memphis",
      "contact_name": "Mary Johnson",
      "contact_email": "[email protected]",
      "zip": "38106",
      "contact_phone": "202-555-0147",
      "state": "TN",
      "name": "First Rate Choice"
    },
    "notes": "",
    "scheduled_ends_at": "2019-11-22T10:33:29.112+0000",
    "scheduled_at": "2019-11-20T10:33:29.112+0000",
    "adjusted_date": "2019-11-22T10:33:29.112+0000"
  },
  "delivery": {
    "date_type": "estimated",
    "venue": {
      "address": "8 Philmont Dr.",
      "city": "Memphis",
      "contact_name": "Mary Johnson",
      "contact_email": "[email protected]",
      "zip": "38106",
      "contact_phone": "202-555-0147",
      "state": "TN",
      "name": "First Rate Choice"
    },
    "notes": "",
    "scheduled_ends_at": "2019-11-22T10:33:29.112+0000",
    "scheduled_at": "2019-11-20T10:33:29.112+0000",
    "adjusted_date": null,
    "latitude": 0
  },
  "customer": {
    "address": "8 Philmont Dr.",
    "city": "Memphis",
    "contact_name": "Karen Rodriguez",
    "phone": "202-555-0173",
    "zip": 38106,
    "email": "[email protected]",
    "state": "TN",
    "name": "First Rate Choice"
  },
  "payment": {
    "terms": "5_days",
    "amount": "550.00",
    "method": "cash",
    "notes": null,
    "reference_number": ""
  },
  "vehicles": [
    {
      "vin": "1G8AL52F03Z157046",
      "lot_number": "",
      "type": "sedan",
      "color": "",
      "is_inoperable": false,
      "curb_weight": 2729,
      "price": 60,
      "year": 2012,
      "make": "BMW",
      "tariff": "3.00",
      "model": "X6",
      "curb_weight_unit": "lbs",
      "inspection_type": "standard"
    }
  ]
}'

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 price, pickup.scheduled_at, and delivery.scheduled_at fields:

1
2
3
4
5
6
7
8
9

    {
        "price": 123.99,
        "pickup": {
            "scheduled_at": "2020-12-22T10:33:29.112+0000"
        },
        "delivery": {
            "scheduled_at": "2020-12-28T10:33:29.112+0000"
        }
    }

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:

  1. 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.
  2. 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.
  3. The API client does know what carrier can move this order: the carrier’s guid or 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 guid.

Step 5: Send a load offer

You can use carrier_guid or carrier_usdot to send a load offer to a carrier that is registered in Super Dispatch:

1
2
3
4
5
6

curl -X "POST" "https://api.shipper.superdispatch.com/v1/public/orders/<order_guid>/offers" \
     -H 'Authorization: Bearer <access_token>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "carrier_guid": "9ea8edaf-874b-4dee-8be7-29ab169a21ea"
}'

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_email or 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. This 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 /v1/public/orders/<order_guid>/bol:

1
2

curl "https://api.shipper.superdispatch.com/v1/public/orders/<order_guid>/bol" \
     -H 'Authorization: Bearer <access_token>'

The response contains the BOL URL (a PDF file):

1
2
3
4
5
6
7
8

{
  "status": "success",
  "data": {
    "object": {
      "url": "https://carrier.superdispatch.com/orders/pdf-bol/wZQ4rMx?template=default"
    }
  }
}

Step 8: Mark as paid to a carrier

When you send money to the carrier, you can document it using the endpoint /v1/public/orders/<order_guid>/mark_as_paid:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

curl -X "PUT" "https://api.shipper.superdispatch.com/v1/public/orders/<order_guid>/mark_as_paid" \
     -H 'Authorization: Bearer <access_token>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "terms": "5_days",
  "amount": "550.00",
  "method": "cash",
  "notes": "...",
  "sent_date": "2019-11-18T05:27:36.095+0000",
  "reference_number": "443344"
}'

The response is a full order object. Reference: Mark an order as paid to the carrier.