Overview

The Shipper API is based on REST. All resources have their own URLs, the API accepts and returns JSON-encoded objects, and accepts multipart/form-data for file uploads.

You can learn how to implement an API client quickly here: Quickstart.

Environments

The Shipper API supports two environments:

  • Staging: api.staging.shipper.superdispatch.org. The environment for only test purposes that may be used during the implementation process. In this environment, API clients cannot interact with real carriers.
  • Production: api.shipper.superdispatch.com. On the production environment all your changes are live and visible on Shipper TMS. You’ll interact with real data, real carriers.

Authentication

All the requests must be authenticated by the API client. We rely on the industry standard OAuth 2.0 protocol to grant access, due to its simplicity and ease of implementation.

To get Access Token that will be used with all requests later, the API client sends an authorization request by providing ClientID and ClientSecret as username and password of basic access authentication.

1
2

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

You will get a result that looks like the following:

 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"
}

Extract the access_token value and use it as a bearer token with Authorization header. Example:

1
2

curl "https://api.shipper.superdispatch.com/v1/public/carriers/full_search?query=dispath" \
     -H 'Authorization: Bearer <access_token>'

Unique identifiers

We usually prefer to use GUIDs rather than primary keys stored in the database. Some old API endpoints and webhook payloads use ids but they’re deprecated now.

Example: 8fee4ba1-ef9b-4e5c-ba0c-3a9638f4ad83

Date and time

All dates and times are formatted using ISO 8601. The date-time values are in millisecond precision and include time offset. For example, 2019-10-31T05:23:15.835+0000.

When sending date-time field you can use any offset (e.g. +0000 or -05:00). However, the server stores and returns all date-time fields at UTC+0 offset. For example, if you created an order with pickup scheduled date 2019-10-31T10:00:00.000-0500 then when you fetch this order the pickup date will be 2019-10-31T15:00:00.000Z. If you don’t get used to work with different timezones then you may be surprised by results for dates around midnight. For example, 2019-10-31T22:00:00.000-0500 becomes 2019-11-01T03:00:00.000Z. Pay attention that the 31st of October became the 1st of November.