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.

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 an account, email [email protected] to obtain credentials.

Step 2: Authenticate your API client

All API requests must be authenticated. We support industry-standard 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; ClientID and ClientSecret are provided as credentials. The API returns a successfull response with access_token if the credentials are correct:

1
2
3
4
5
{
  ...
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV...mvI1yI0",
  ...
}

Step 3: Send a test API request

To make sure that the integration works, let's send a test request (access_token is sent as an authentication header.):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl -X "POST" "https://api.shipper.superdispatch.com/v1/public/carriers/internal" \
     -H 'Authorization: Bearer <access_token>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "address": "8 Philmont Dr.",
  "phone_numbers": "202-555-0173",
  "city": "Memphis",
  "state": "TN",
  "email": "[email protected]",
  "zip": "38106",
  "name": "First Rate Choice",
  "contact_name": "Karen Rodriguez"
}'

The above request creates a new internal carrier. The response body should look like:

 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
{
  "status": "success",
  "data": {
    "object": {
      "email": "[email protected]",
      "guid": "2203c5e9-415c-4e3a-bec0-9a9dd28b4650",
      "name": "First Rate Choice",
      "dba_name": null,
      "phone_numbers": "202-555-0173",
      "fax": null,
      "website": null,
      "contact_name": "Karen Rodriguez",
      "address": "8 Philmont Dr.",
      "city": "Memphis",
      "state": "TN",
      "zip": "38106",
      "w9": null,
      "usdot_certificate": null,
      "cargo_insurance": null,
      "mc_number": null,
      "cargo_policy": null,
      "carrier_type": "INTERNAL",
      "broker_records": {
        "guid": "2203c5e9-415c-4e3a-bec0-9a9dd28b4650",
        "usdot_number": null,
        "preferred": false,
        "preferred_since": null,
        "in_blacklist": false,
        "in_blacklist_since": null,
        "insurance_certificate_holder": false,
        "insurance_certificate_holder_since": null,
        "insurance_cert_holder_file_url": null,
        "insurance_expires_at": null,
        "custom_external_id": null
      },
      "us_dot": null
    }
  }
}

Step 4: 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
84
85
86
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",
    "longitude": 0,
    "latitude": 0,
    "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",
    "longitude": 0,
    "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.

Step 5: 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.
  4. Find a carrier using our Load Matching system: our prediction system can offer carriers who may be interested to move this order. After choosing a carrier, the order can be sent to this carrier as a load offer.

Let's assume that you know the carrier's USDOT number or guid.

Step 6: Send a load offer

You can use carrier_guid or carrier_usdot to send a load offer:

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_usdot": "382"
}'

This request (reference) creates a load offer, and sends it to the carriers as an email and text message. The carrier can accept the load offer or decline it.

Each load offer has its own guid. This guid is necessary to track the its status.

Step 7: 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 8: 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 9: 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.