Getting Quotes
This page explains how got get delivery quotes based on consignment details.
Overview
PRO has two endpoints that take the details of an as-yet uncreated consignment and return quotes for it:
- Get Quotes returns a simple list of delivery quotes for the potential consignment.
- Get Service Group Quotes returns a list of current service groups, along with quotes from the eligible services in each group.
Note
Both the Get Quotes and Get Service Group Quotes endpoints take a consignment object in the body of the request. However, they do not create consignments in and of themselves. In order to allocate to one of the quotes returned by these endpoints, you would need to first create the consignment.
For more information on creating consignments, see the Creating Consignments page.
Sending a Get Quotes Request
To call Get Quotes, send a POST
request to https://api.electioapp.com/quotes/
. The body of the request should contain a consignment object.
As a minimum, the Get Quotes endpoint requires you to send package weights and dimensions, origin address, and destination address data. You can either specify package weights and dimension via the Weight
and Dimensions
properties, or by supplying a PackageSizeReference
.
Note
A PackageSizeReference
is a unique identifier for a pre-defined, standardised package size.
To configure standard package sizes, use the Configuration > Packaging Sizes page of the PRO UI. You can also view a list of your available standard package sizes by making a call to the Get Package Sizes API.
Either the consignment's destination
address, its origin
address (if it has one), or both, must include a valid ShippingLocationReference
. For information on how to obtain a list of your organisation's shipping locations, see the Get Shipping Locations page of the API reference.
There are lots of optional properties you can send when getting quotes for a consignment, including:
- Your own consignment reference.
- Details of the specific items inside the consignment's packages.
- The consignment's source.
- Shipping and delivery dates.
- Customs documentation.
- The consignment's direction of travel.
- Metadata. PRO metadata enables you to us custom fields to record additional data about a consignment. For more information on using metadata in PRO, see the Metadata page.
- Tags. Allocation tags enable you to filter the list of carrier services that a particular consignment could be allocated to. For more information on allocation tags, see the Tags page.
Adding optional properties can help to improve the relevance and accuracy of the quote results that you get back from PRO.
The Get Quotes Response
Once it has received the request, PRO returns a quote result. The quote result object includes two lists: one containing Quotes
and one containing UnqualifiedServices
(that is, eligible services for which it was not possible to obtain a delivery quote).
Each Quote
object contains the following information:
- A unique reference for the quote. This property is important, as it is used when allocating consignments to the quote via the Allocate With Quote endpoint.
- Creation and expiry dates.
- The name and reference of the relevant carrier and carrier service.
- Origin and destination addresses.
- Collection date, and a delivery date range.
- Pricing information.
- Details on each leg of the journey (where applicable).
- The service direction.
At this point, you would be able to display the relevant quote information to your customer service operative.
Note
For full reference information on the Get Quotes endpoint, see the API Reference.
Example Get Quotes Call
The example below shows a Get Quotes call for a fairly simple consignment. PRO has responded with one quote and two unavailable services.
POST https://api.electioapp.com/quotes/
{
"Packages": [
{
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Dimensions": {
"Unit": "Cm",
"Width": 10.0,
"Length": 10.0,
"Height": 10.0
},
"Description": "Socks",
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
}
}
],
"Addresses": [
{
"AddressType": "Origin",
"ShippingLocationReference": "Sorted1",
"IsCached": false
},
{
"AddressType": "Destination",
"Contact": {
"Title": "Mr",
"FirstName": "Peter",
"LastName": "McPetersson",
"Telephone": "07702123456",
"Mobile": "07702123456",
"LandLine": "0161544123",
"Email": "peter.mcpetersson@test.com"
},
"AddressLine1": "13 Porter Street",
"Region": "Greater Manchester",
"Postcode": "M1 5WG",
"Country": {
"Name": "Great Britain",
"IsoCode": {
"TwoLetterCode": "GB"
}
},
"IsCached": false
}
]
}
Getting Service Group Quotes
To call Get Service Group Quotes, send a POST
request to https://api.electioapp.com/quotes/serviceGroups
. The body of the request should contain a consignment object, structured in the same way as the Get Quotes request detailed above.
Once it has received the request, PRO returns a list of available service groups, identified by Name
and Reference
. Each service group contains a CheapestQuote
detailing the cheapest service in that group. The service group object also contains a list of Quotes
for the services in the group (including the service detailed in the CheapestQuote
property) and a list of UnqualifiedServices
(that is, eligible services within the group for which it was not possible to obtain a delivery quote).
Note
For full reference information on the Get Service Group Quotes endpoint, see the API Reference.
Get Service Group Quotes Example
This simplified example shows a Get Service Group Quotes request for an outbound consignment. In this case, there is one service group configured in PRO, with the name Example Service Group. The group contains two services, with the service references SAMPLE_SERVICE01 and SAMPLE_SERVICE02.
PRO returns a single service group object. In this case, SAMPLE_SERVICE01 is the only eligible service, and so is displayed as both the CheapestQuote
and the only entry in the Quotes
array. SAMPLE_SERVICE02 is returned in the list of unqualified services.
POST https://api.electioapp.com/quotes/serviceGroups
{
"MetaData": [
{
"KeyValue": "IsExample",
"BoolValue": true
}
],
"Source": "API",
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
},
"CustomsDocumentation": {
"DesignatedPersonResponsible": "Peter McPetersson",
"ImportersVatNumber": "02345555",
"CategoryType": "Other",
"ShipperCustomsReference": "CREF0001",
"ImportersTaxCode": "TC001",
"ImportersTelephone": "0161123456",
"ImportersFax": "01611124547",
"ImportersEmail": "peter.mcpetersson@test.com",
"CN23Comments": "Comments",
"ReferencesOfAttachedInvoices": [
"INV001"
],
"ReferencesOfAttachedCertificates": [
"CERT001"
],
"ReferencesOfAttachedLicences": [
"LIC001"
],
"CategoryTypeExplanation": "Explanation",
"DeclarationDate": "2020-02-11T00:00:00+00:00",
"OfficeOfPosting": "Manchester",
"ReasonForExport": "Sale",
"ShippingTerms": "CFR",
"ShippersVatNumber": "874541414",
"ReceiversTaxCode": "TC5454",
"ReceiversVatNumber": "8745474",
"InvoiceDate": "2020-02-11T00:00:00+00:00"
},
"Direction": "Outbound",
"ShippingDate": "2020-02-11T00:00:00+00:00",
"RequestedDeliveryDate": {
"Date": "2020-02-13T00:00:00+00:00",
"IsToBeExactlyOnTheDateSpecified": false
},
"ConsignmentReferenceProvidedByCustomer": "Your custom reference",
"Addresses": [
{
"AddressType": "Origin",
"ShippingLocationReference": "Shipping_Location_Reference",
"IsCached": false
},
{
"AddressType": "Destination",
"Contact": {
"Title": "Mr",
"FirstName": "Peter",
"LastName": "McPetersson",
"Telephone": "07702123456",
"Mobile": "07702123456",
"LandLine": "0161544123",
"Email": "peter.mcpetersson@test.com"
},
"CompanyName": "Test Company (UK) Ltd.",
"AddressLine1": "13 Porter Street",
"AddressLine2": "Pressington",
"AddressLine3": "Carlsby",
"Town": "Manchester",
"Region": "Greater Manchester",
"Postcode": "M1 5WG",
"Country": {
"Name": "Great Britain",
"IsoCode": {
"TwoLetterCode": "GB"
}
},
"SpecialInstructions": "Gate code: 4454",
"LatLong": {
"Latitude": 53.474220,
"Longitude": -2.246049
},
"IsCached": false
}
],
"Packages": [
{
"Items": [
{
"Sku": "SKU093434",
"Model": "ITM-002",
"Description": "Striped Bamboo Red/White",
"CountryOfOrigin": {
"IsoCode": {
"TwoLetterCode": "GB"
}
},
"HarmonisationCode": "Harmonisation_Code",
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Dimensions": {
"Unit": "Cm",
"Width": 10.0,
"Length": 10.0,
"Height": 10.0
},
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
},
"ItemReferenceProvidedByCustomer": "ITEMREF-098",
"Barcode": {
"Code": "09887-091221",
"BarcodeType": "Code39"
},
"MetaData": [
{
"KeyValue": "Picker",
"StringValue": "David Thomas"
}
],
"Quantity": 1,
"Unit": "Box",
"HarmonisationKeyWords": [
"Keyword1"
],
"ContentClassification": "Unrestricted",
"ContentClassificationDetails": "NotSpecified"
}
],
"PackageReferenceProvidedByCustomer": "MYPACK-00923",
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Dimensions": {
"Unit": "Cm",
"Width": 10.0,
"Length": 10.0,
"Height": 10.0
},
"Description": "Socks",
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
},
"Barcode": {
"Code": "09887-091221",
"BarcodeType": "Code39"
},
"MetaData": [
{
"KeyValue": "WMS-REF",
"IntValue": 77656555
}
]
},
{
"Items": [
{
"Sku": "SKU093434",
"Model": "ITM-002",
"Description": "Striped Bamboo Red/White",
"CountryOfOrigin": {
"IsoCode": {
"TwoLetterCode": "GB"
}
},
"HarmonisationCode": "Harmonisation_Code",
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Dimensions": {
"Unit": "Cm",
"Width": 10.0,
"Length": 10.0,
"Height": 10.0
},
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
},
"ItemReferenceProvidedByCustomer": "ITEMREF-098",
"Barcode": {
"Code": "09887-091221",
"BarcodeType": "Code39"
},
"MetaData": [
{
"KeyValue": "Picker",
"StringValue": "David Thomas"
}
],
"Quantity": 1,
"Unit": "Box",
"HarmonisationKeyWords": [
"Keyword1"
],
"ContentClassification": "Unrestricted",
"ContentClassificationDetails": "NotSpecified"
}
],
"PackageReferenceProvidedByCustomer": "MYPACK-00923",
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Dimensions": {
"Unit": "Cm",
"Width": 10.0,
"Length": 10.0,
"Height": 10.0
},
"Description": "Socks",
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
},
"Barcode": {
"Code": "09887-091221",
"BarcodeType": "Code39"
},
"MetaData": [
{
"KeyValue": "WMS-REF",
"IntValue": 77656555
}
]
}
]
}
Next Steps
- Learn how to get quotes using a consignment reference at the Getting Quotes For An Existing Consignment page.
- Learn how to create consignments at the Creating New Consignments page.
- Learn how to allocate consignments to your chosen quote at the Allocating to a Specific Quote page.