Getting Consignment Data
PRO offers several endpoints that return consignment data. This page explains how to fetch data on an individual consignment, and how to search for consignments that meet a particular set of criteria.
Getting Data For a Specific Consignment
Perhaps the most straightforward way of getting PRO consignment data is to use the Get Consignment endpoint. This endpoint takes the consignmentReference
of the consignment you want to view as a path parameter, and returns full details for the specified consignment. The information returned is structured in a broadly similar way to a Create Consignment request, but can also (where applicable) include additional information, including:
- Information on the carrier service the consignment is allocated to
- Tracking references for each of the consignment's packages
- Information on the number of shipment legs required to deliver the consignment
- Label information, including whether labels have been printed yet and the date on which the labels were printed
- An
IsLate
flag indicating whether the consignment is late or not.
To call Get Consignment, send a GET
request to https://api.electioapp.com/consignments/{consignmentReference}
.
Note
For full reference information on the Get Consignment endpoint, see the API reference.
Example Get Consignment Call
The example below shows a simple Get Consignment request for an unallocated consignment containing just package and address details. For an example of a full Get Consignment request, see the Get Consignment API reference.
GET https://api.electioapp.com/consignments/EC-000-05C-ZB4
Checking a Consignment's Status
If you only need to check a consignment's status, you could use the Get Consignment Status endpoint instead of Get Consignment. Get Consignment Status takes a consignmentReference
as a path parameter, and returns only the consignment's current status and expected delivery date. Although Get Consignment returns both status and delivery date, it also returns a great deal of other information, which may not be useful if you simply want to check a consignment's progress.
To make a Get Consignment Status request, send a GET
request to https://api.electioapp.com/consignments/{consignmentReference}/status
.
GET https://api.electioapp.com/consignments/EC-000-087-01A/status
Searching For Consignments
As well as endpoints that return data based on a consignmentReference
, PRO also enables you to search for consignments that meet a particular set of criteria. PRO has two search endpoints: Get Consignments References and Search Consignments. Both of these endpoints enable you to specify consignment parameters in your request, and return any consignments that meet those parameters.
The two search endpoints differ in their responses: Get Consignments References returns only the consignmentReference
s of any consignments that meet the criteria, while Search Consignments returns a summary of each matching consignment. Search Consignments also includes a paging feature that enables you to specify how many results you want PRO to return, and to skip over a specified number of results.
Using Get Consignments References
To call Get Consignments References, send a GET
request to https://api.electioapp.com/consignments/getConsignmentReferences?{property}={value}
, where {property}
is the name of the consignment property you want to search on and {value}
is its associated value. You can separate additional properties using the &
operator. PRO then returns the consignmentReferences
of any consignments that meet all the criteria that you specify.
Note
For a full list of search properties accepted by the Get Consignments References endpoint, see the API reference
Get Consignments References Example
The example below shows a request for all inbound consignments in an Allocated state. PRO has returned two consignments.
https://api.electioapp.com/consignments/getConsignmentReferences?State=Allocated&Direction=Inbound
Using Search Consignments
To call Search Consignments, send a GET
request to https://api.electioapp.com/consignments/{take}/{skip}?{property}={value}
, where:
{take}
is the maximum number of results you want the endpoint to return{skip}
is the number of results in the list that you want to skip{property}
is the name of the consignment property you want to search on{value}
is the property value you want to search on.
As with the Get Consignments References API, you can add additional search properties and values, as long as each property/value pair is separated by an &
operator.
Note
The {take}
and {skip}
values can be used to drive paging functions in systems that present a list of consignments to the user. For example, suppose that you have 100 active consignments in an Allocated state. A call to GET https://api.electioapp.com/consignments/100/0?&State=Allocated
would return all of those consignments, as a {take}
value of 100 and a {skip}
value of 0 means that the API will return up to 100 results without skipping over any.
However, suppose that you want to split the list up into two groups of 50 (for example, because you are using the data to populate a list in a system whose UI only enables you to display 50 results at any one time). In this case, you would populate the first page of results with a call to GET https://api.electioapp.com/consignments/50/0?&State=Allocated
(max. 50 results, none skipped). If the user elects to view the second page, you would call GET https://api.electioapp.com/consignments/50/50?&State=Allocated
. The API would again return 50 results, but would skip over the first 50 in the list (i.e. those results that were displayed on the first page) and instead return results 51-100.
The Search Consignments endpoint returns a summary of each consignment that meets the request criteria. The summary object contains the following:
- The carrier service that the consignment is allocated to (where applicable) and its date of allocation
- Address information
- Requested and estimated delivery dates, and a flag indicating whether the shipment is late
- The consignment's label status (i.e. whether labels have been printed and on what date)
- The consignment reference
- The customer's reference for the consignment (where applicable)
- Creation and shipping dates
- The consignment's value and weight
Note
For full reference information on the Search Consignments endpoint, see the API reference.
Search Consignments Example
The example below shows a request for all inbound consignments in an Allocated state, with a potential maximum of 100 results returned and none skipped. PRO has returned a summary of two consignments.
https://apis.electioapp.com/consignments/100/0/?State=Allocated&Direction=Inbound
Next Steps
- Learn how to allocate consignments at the Allocating Consignments to Carriers page.
- Learn how to get and print delivery labels at the Getting Labels page.
- Learn how to add consignments to a carrier manifest at the Manifesting Consignments page.