API collection overview

This page contains a brief overview of Sorted Shipments API and explains how you can use them.

The Shipments API collection offers unparalleled flexibility, with support for on-demand collections from multiple locations (e.g. a ship-from-store model) as well the regular scheduled fulfillment centre collections supported in v1.

The Shipments platform also offers the ability to group shipments together for ease of management, an improved dangerous goods specification and enhanced customs functionality, among many other features.

Ship’s APIs enable you to:

  • Manage Shipments - Create, update, clone and cancel shipment records, and manually modify shipment states.
  • Allocate Shipments - Allocate shipments to the most appropriate carrier service.
  • Manage Quotes - Create and receive delivery quotes for shipments.
  • Get Customs Docs - Get customs documents for allocated international shipments.
  • Get Labels - Get delivery labels for an allocated shipment in either ZPL or PDF format.
  • Manifest Shipments - Manually manifest one or more either individually or by manifesting a shipment group.
  • Manage Shipment Groups - Group shipments together so they can be operated on as a single unit, and edit or delete shipment groups as required.
  • Get Collection Notes - Retrieve collection notes (aka driver’s manifest) by search query or by shipment group.

Making an API request in ship

This section explains the various API headers used when making a request to one of Ship’s APIs.

Example Shipments API headers

  x-api-key: [qwerrtyuiioop0987654321]
Accept: application/json
Content-Type: application/json 
Accept-Encoding: gzip 
x-api-version: 1.1

Authentication

You must provide a valid API key in every call you make to Shipments API requests. When a new user account is created, the Shipments platform generates a unique API key and allocates it to the new user. You can view your API key in the user interface.

To use your API key with the Shipments API, include it in an x-api-key header when making calls. If you make an API request to Shipments without including an API key, then an error is returned with a status code of 401 (Unauthorized).

Formats

Shipments API only works with JSON data. This is a change from v1, which accepted XML requests and responses as well as JSON.

If you provide an Accept header to indicate request format and/or a Content-Type format to indicate response format, then these keys must have a value of application/json. An error will return if you provide any other values in these headers. If you do not provide Accept and/or Content-Type headers, then Shipments uses its default value of application/json.

Shipments API is designed to work with GZIP encoding. We strongly recommend that you provide an Accept-Encoding header with a value of gzip in all requests.

Versioning

You must provide an x-api-version header in all requests. The current API version is 1.1.

Response headers

Depending on the content returned, responses may include the following headers:

  • x-api-version - The version of the API that served the request.
  • Content-Type - The format of the response body. This will ordinarily have the value application/json.
  • Content-Encoding - If you request responses in GZIP format, the Content-Encoding response header returns a value of gzipped.

Using the sandbox environment

All of the URLs and examples given in this documentation relate to the Shipment platform’s live production environment. However, the Shipments platform also offers a sandbox, enabling you to use a “safe” development environment in which you can integrate with Shipments without running the risk of inadvertently transmitting data to carriers. The sandbox works in exactly the same way as the production environment, but is entirely self-contained and uses a separate dataset.

In order to call APIs in the sandbox environment, you will first need to set up a sandbox API key. To call an API in the sandbox rather than the production environment, substitute the api.sorted.com/pro portion of the API’s base URL with api.sorted.com/pro-sandbox and make sure to use your sandbox API key (as opposed to your production API key) in the x-api-key header when making the call.

For example, to call the Create Shipment endpoint in the production environment, you would send a POST request to https://api.sorted.com/pro/shipments. To call the same endpoint in the sandbox, you would send a POST request to https://api.sorted.com/pro-sandbox/shipments.