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 enviroment 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'

Authentication request and response in the reference: Authenticate an API client.

Use bearer auth with your access token: send an Authorization header with the value Bearer <your access token>. 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. Examples:

  • 2019-10-31T05:23:15.835+0000
  • 2019-10-31

All times in the UTC+0 timezone.