Skip to main content

Lookup

This API is used to lookup a list of shipping rates for parcels and pallets. The results are ordered with the cheapest delivery option first.

Example

Json / XML 

// Lookup Example
{
    "lookup": {
        "shipment": {
            "type": "PARCEL",
            "collection": {
                "town": "Braintree",
                "postcode": "CM71GZ",
                "countrycode": "GB"
            },
            "destination": {
                "town": "Los Angeles",
                "postcode": "90210",
                "countrycode": "US"
            },
            "parcels": [
                {
                    "weight": "10",
                    "height": "10",
                    "length": "10",
                    "width": "10"
                }
            ]
        }
    }
}

// Lookup Example
<lookup>
    <shipment>
        <type>PARCEL</type>
        <collection>
            <town>Braintree</town>
            <postcode>CM71GZ</postcode>
            <countrycode>GB</countrycode>
        </collection>
        <destination>
            <town>Los Angeles</town>
            <postcode>90210</postcode>
            <countrycode>US</countrycode>
        </destination>
        <parcels>
            <parcel>
                <weight>10</weight>
                <length>10</length>
                <width>10</width>
                <height>10</height>
            </parcel>
        </parcels>
    </shipment>
</lookup>
Element Required Description
lookup Yes Root element
shipment Yes Shipment details
type Yes Shipment type. Can be PARCEL, PALLET or DOCUMENT
collection Yes Collection address
Collection
town Yes* Collection town
* Required when not supplying a collection postcode
postcode Yes* Collection postcode
* Required when not supplying a collection town
countrycode Yes Collection country code
destination Yes Destination address
Destination
town Yes* Destination town
* Required when not supplying a destination postcode
postcode Yes* Destination postcode
* Required when not supplying a destination town
countrycode Yes Destination country code
parcels Yes Array of parcels
Parcels
parcel Yes Parcel details
weight Yes Parcel weight in kilograms
length Yes Parcel length in centimetres
width Yes Parcel width in centimetres
height Yes Parcel height in centimetres

Example Response

// Lookup Response Example
{
  "header": {
    "status": "success"
  },
  "countrycode": "US",
  "postcode": "12345",
  "services": [
        {
            "rate_id": 107,
            "hash": "PkQauDkQnT6WY7ZPU1jKqSakOO32zeerUeXd4iTW",
            "carrier": "TNT",
            "description": "HTML Service Description",
            "name": "TNT: Express",
            "cutoff": "14:00:00",
            "printer": true,
            "business_only": false,
            "messages": [],
            "customs": true,
            "ancilleries": [
                {
                    "name": "Residential Charge",
                    "type": "RESIDENTIAL",
                    "price": 4.95
                },
                {
                    "name": "Non-Stackable",
                    "type": "NONSTACKABLE",
                    "price": 167.29
                },
                {
                    "name": "Additional Handling",
                    "type": "ADDITIONALHANDLING",
                    "price": 43.86
                }
            ],
            "information": {
                "tracking": true,
                "liability": true,
                "residential": true,
                "signature": true,
                "sameday": true,
                "futureday": true,
                "hs_code_required": true,
                "printer": true,
                "remotearea": false
            },
            "price": 72.8,
            "vatrate": 0,
            "surcharge": 0,
            "net": 72.8,
            "vat": 0,
            "total": 72.8,
            "rrp": 72.8,
            "rrp_vat": 0,
            "extlibrate": 3
        },
    ]
}

// Lookup Response Example
<response>
    <header>
        <status>Success</status>
    </header>
    <countrycode>US</countrycode>
    <postcode>90210</postcode>
    <services>
        <service>
            <rate_id>107</rate_id>
            <hash>PkQauDkQnT6WY7ZPU1jKqSakOO32zeerUeXd4iTW</hash>
            <carrier>TNT</carrier>
            <description>HTML Service description</description>
            <name>TNT: Express</name>
            <cutoff>14:00:00</cutoff>
            <printer>true</printer>
            <business_only>false</business_only>
            <messages/>
            <customs>true</customs>
            <ancilleries>
                <ancillery>
                    <name>Residential Charge</name>
                    <type>RESIDENTIAL</type>
                    <price>4.95</price>
                </ancillery>
                <ancillery>
                    <name>Non-Stackable</name>
                    <type>NONSTACKABLE</type>
                    <price>167.29</price>
                </ancillery>
                <ancillery>
                    <name>Additional Handling</name>
                    <type>ADDITIONALHANDLING</type>
                    <price>43.86</price>
                </ancillery>
            </ancilleries>
            <information>
                <tracking>true</tracking>
                <liability>true</liability>
                <residential>true</residential>
                <signature>true</signature>
                <sameday>true</sameday>
                <futureday>true</futureday>
                <hs_code_required>true</hs_code_required>
                <printer>true</printer>
                <remotearea>false</remotearea>
            </information>
            <price>72.8</price>
            <vatrate>0</vatrate>
            <surcharge>0</surcharge>
            <net>72.8</net>
            <vat>0</vat>
            <total>72.8</total>
            <rrp>72.8</rrp>
            <rrp_vat>0</rrp_vat>
            <extlibrate>3</extlibrate>
        </service>
    </services>
</response>
Element Description
response Root element
header Header element
status Response status. Can be success or error
postcode Destination postal code
countrycode Destination country code
services Array of services
Services
service Service details
rate_id Service rate ID
hash Service identifier for booking reference
carrier Service carrier
description Service description (supplied only as HTML)
name Service name
cutoff Service cutoff time
printer Whether the service requires labels to be printed
This element is parroted within the information block and remains for backwards compatibility
business_only Whether this service can only be delivered to a business premises
This element is deprecated and remains for backwards compatibility
messages Array of messages
This element is deprecated and remains for backwards compatibility
customs Whether the service requires customs information sent with the booking request
eori Whether an Eori number is required to be sent if either of the addresses are a business address
ancilleries Array of ancilleries
Ancilleries
ancillery Ancillery details
name Ancillery name
type Ancillery type
price Ancillery price
information Service information
price Service price
vatrate Service VAT rate
surcharge Service surcharge price
net Service net price
vat Service VAT price
rrp Service RRP price
This element is deprecated and remains for backwards compatibility
rrp_vat Service RRP VAT price
This element is deprecated and remains for backwards compatibility
extlibrate Extended liablity rate as a percentage