Get started with Consignments APIs
Get started with the Sorted Consignments APIs. Create, allocate, and manage shipments from quote to manifest with our flexible REST endpoints.
Consignments Overview
In the Consignments platform, 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 customer, using the same carrier service, on the same day. Consignments form the basis of Sorted Ship’s Consignments API, which enables you to build flexible shipping workflows that manage a consignment’s journey from customer order right through to delivery.
The Consignments API package offers the following endpoints:
- Allocation - Allocates consignments to an appropriate carrier service.
- 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.
- Labels - Returns labels for a consignment.
- Manifest - Adds consignments to the relevant carrier manifest.
- Pickup Options - Returns potential pickup locations and timeslots for a consignment.
- Quotes - Returns manual delivery quotes for a consignment.
Authentication
You will need to provide a valid API key in every call you make to the Consignments platform. When a new user account is created, Consignments generates a unique API key and allocates it to the new user. To view your API key:
- Log in to the Consignments 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. Consignments 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 requests to Consignments. If you make an API request to Consignments without including an API key, an error with a status code of 401 (Unauthorized) will be returned.
Example API key:
ocp-apim-subscription-key: NzI1M2U0MjEtOTExNy00MWI1LWFlM2MtYTYxYTMwZmQ3NWM5
Specify response format
Consignment’s APIs support both JSON and XML content types. You should state which content type you are sending for each API request. 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 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 Consignments responds with application/json.
content-type: application/json
accept: application/json
content-type: application/xml
accept: application/xml
Specify API Version
You should include an electio-api-version header specifying the API version to use in all Consignments API requests. 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 the Consignments platform live production environment. However, we also offers a sandbox environment which provides a safe development area in which you can integrate with Consignments without running the risk of inadvertently transmitting data to carriers. The sandbox works in the same way as the production (live) environment, but is self-contained and uses a separate dataset, authentication and password.
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 user interface and follow the process listed in the authentication header in 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.
ocp-apim-subscription-key header when making the call.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.Using a password manager
A password manager is a software or internet browser tool (e.g. 1Password, NordPass, Safari and Google password manager) designed to help users securely store, manage, and generate passwords for various online accounts. It works by linking your login credentials with a corresponding URL.
When you log out of our Sandbox and Production (live) user interfaces, the URL changes from the initial URL which may be linked to your login credentials. This can prevent you from logging back in as the password manager using your stored password will attempt to log in using it’s saved URL linked to your credentials.
To resolve this, you may need to manually type your login information rather than relying on the password manager autofill data or you can include your login credentials for the additional URL that you are directed to following a log out action.