Getting Started with PRO's APIs
Welcome to SortedPRO! This page contains a brief overview of PRO version 2's APIs and explains how you can use them.
API Collection Overview
PRO's Shipments functionality was introduced in version 2 as an extension to the Consignments API suite used in version 1. PRO's 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 fulfilment centre collections supported in v1.
PRO 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.
For more information on the differences between the Shipments API suite used in v2 and the Consignments API suite used in v1, see the Consignments vs Shipments page.
PRO'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 shipments, 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.
For example API call flows and reference information, see the PRO v2 API reference.
Making an API Request in PRO
This section explains the various API headers used when making a request to one of PRO's APIs.
x-api-key: [qwerrtyuiioop0987654321] Accept: application/json Content-Type: application/json Accept-Encoding: gzip x-api-version: 1.1
You must provide a valid API key in every call you make to PRO. When a new user account is created, PRO generates a unique API key and allocates it to the new user. You can view your API key in the PRO UI.
PRO admins can manage users in the UI. For information on configuring PRO user accounts and permissions, see the Managing Users and Roles page of the Sorted Admin Portal Guide.
To use your API key with PRO v2, include it in an
x-api-key header when making calls. If you make an API call to PRO without including an API key, then PRO returns an error with a status code of 401 (Unauthorized).
PRO v2 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. PRO will return an error if you provide any other values in these headers. If you do not provide
Content-Type headers, then PRO uses its default value of application/json.
PRO 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.
You must provide an
x-api-version header in all requests. The current API version is 1.1.
The API version provided in the
x-api-version header is a purely technical property, and should not be confused with the version of PRO you are using. At present, the
x-api-version should always 1.1, irrespective of whether you are calling PRO v2 (Shipments) or PRO v1 (Consignments) endpoints. This is because both versions of PRO share certain back-end processes.
Depending on the content returned, PRO's 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-Encodingresponse header returns a value of gzipped.
Using the Sandbox Environment
All of the URLs and examples given in this documentation relate to PRO's live production environment. However, PRO also offers a sandbox, enabling you to use a "safe" development environment in which you can integrate with PRO 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