Skip to main content

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.

Shipper API domains​

  • 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.

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:

{
  "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:

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

:::warning ClientID and ClientSecret ClientID and ClientSecret are required to use this API. They can be obtained by sending a request to our Customer Success: support@superdispatch.com :::

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're not used to working 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.