Getting Started with PRO Consignments APIs
Welcome to SortedPRO! Here you'll find a brief overview of PRO's Consignments APIs and how you can call them.
Consignments Overview
In PRO, a consignment is a collection of one or more packages that are shipped from the same origin address, to the same destination address, on behalf of the same Sorted customer, using the same carrier service, on the same day. Consignments form the basis of PRO's Consignments API suite, which enables you to build flexible shipping workflows that manage a consignment's journey from customer order right through to delivery.
PRO's Consignments suite offers the following APIs:
- Allocation - Allocates consignments to an appropriate carrier service.
- Carrier Services - Returns available carrier services.
- Carriers - Returns available carriers.
- Consignments - Adds, gets, updates and deletes consignment information.
- Customs Docs - Returns customs docs for international consignments.
- Delivery Options - Returns potential delivery timeslots for consignments. Access to PRO's delivery option endpoints requires a SortedHERO license. This component is sold separately to the main SortedPRO product.
- Events - Searches for specified consignment events.
- Labels - Returns labels for a consignment.
- Manifest - Adds consignments to the relevant carrier manifest.
- Orders - Adds, gets, updates and deletes order information.
- Package Sizes - Returns standardised package sizes.
- Packages - Deletes a package from a consignment.
- Pickup Options - Returns potential pickup locations and timeslots for a consignment. Access to PRO's pickup option endpoints requires a SortedHERO license. This component is sold separately to the main SortedPRO product.
- Quotes - Returns manual delivery quotes for a consignment.
- Shipping Locations - Returns pre-configured shipping locations.
- Tracking - Returns tracking information for a consignment.
Note
- For example API call flows, see the PRO Call Flows section.
- For API reference information, see the API Reference.
Authentication
You will need to provide a valid API key in every call you make to SortedPRO. When a new user account is created, PRO generates a unique API key and allocates it to the new user. To view your API key:
- Log in to the PRO dashboard and select Settings > Users & Roles > User Accounts to display the User Accounts page. A list of the user accounts that you have access to is displayed.
- Click the Edit User button for your account to display your account details.
- Click Show API Key. PRO prompts you to re-enter your UI password.
- Enter your password and click Retrieve API Key to display your API key.
To use your API key, include it in an ocp-apim-subscription-key
header when making calls to PRO. 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).
Example API key:
ocp-apim-subscription-key: NzI1M2U0MjEtOTExNy00MWI1LWFlM2MtYTYxYTMwZmQ3NWM5
Specifying Request / Response Format
PRO's APIs support both JSON
and XML
content types. You should state which content type you are sending for each API request sent to PRO. To do so, pass a content-type
header with a value of application/json
, text/xml
or application/xml
(as applicable) in your request. All other content types are invalid.
You can also specify the content type that you want PRO to use in API responses. To do so, pass an accept
header with a value of application/json
, text/xml
, or application/xml
in your request. If you don't pass an accept
header then PRO responds with application/json
.
content-type: application/json
accept: application/json
Specifying API Version
You should include an electio-api-version
header specifying the API version to use in all PRO API calls. The current version is 1.1.
electio-api-version: 1.1
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 do so, log in to the sandbox environment UI and follow the process listed in the Authentication section of this page.
To call an API in the sandbox rather than the production environment, substitute the api.electioapp.com
portion of the API's base URL with apisandbox.electioapp.com
.
Tip
Don't forget to use your sandbox API key (as opposed to your production API key) in the ocp-apim-subscription-key
header when making the call.
For example, to call the Create Consignments endpoint in the production environment, you would send a POST
request to https://api.electioapp.com/consignments
. To call the same endpoint in the sandbox, you would send a POST
request to https://apisandbox.electioapp.com/consignments
.