NAV Navbar
XML
  • API v1.0 - Getting Started
  • Service Preference Lists
  • Retrieve Old Shipments - Shipment Controller
  • Tracking API
  • API Store Locker Locator
  • API v1.0 - Getting Started

    What is it?

    The Parcelhub desktop application allows you to send shipments using a variety of carriers all from the same Parcelhub interface. By using the API, computer programmers can write programs that do the same thing automatically. This opens up the possibility of sending large numbers of parcels automatically, or integrating Parcelhub's range of carrier services into other software that needs to send parcels, such as order management software or eBay integration.

    This guide will go over how to create a shipment in the Parcelhub system using the API.

    Calling API functions

    The API uses a RESTful interface. What that means in practice is that you use standard HTTP requests to make requests and receive data from the API. With the exception of authenticating, all of the requests involve POSTing a piece of XML to the API, and getting a piece of XML back.

    You can program using the API in any programming language that can create and consume XML, and can make HTTP requests.

    The format of the XML used by the API is described in an XML Schema which you should have a copy of. All of the API XML is in the XML Namespace https://api.test.parcelhub.net/1.0/schemas/api/parcelhub-api-v1.0.xsd

    The compatible HTTP protocol versions to make requests are v1-v1.2. Using anything outside of this range will return one of the following:

    1. HTTP Error 400. The request is badly formed. (HTTP v0.9)
    2. HTTP Error 505. The HTTP Version in the request is not supported. (HTTP v2.0)

    A Shipment is described using XML beginning with the tag. To create a shipment, you need to produce XML representing the Shipment you want to send.

    Debugging HTTP Requests

    To try out the API properly you need a way of creating HTTP requests and seeing what you get back. I recommend using one of two programs:

    1. Fiddler ( http://www.telerik.com/fiddler) is a web debugger. You can use it to see all the traffic between your applications and the API. You can also use the Compose tab to construct API calls by hand to try the API out before writing any code.
    2. http://hurl.it is a website that allows you to craft HTTP requests and see what you get back.

    Whatever you use will need a way of adding headers to the HTTP Request.

    The API controllers

    The API is made up of 4 controllers

    Controller Test server Address Live server Address Description
    Token https://api.test.parcelhub.net/1.0/token https://api.parcelhub.net/1.0/token Used for authentication
    Service https://api.test.parcelhub.net/1.0/Service https://api.parcelhub.net/1.0/Service Used for getting services that can be used to send a shipment
    Shipment https://api.test.parcelhub.net/1.0/Shipment https://api.parcelhub.net/1.0/Shipment Used for creating shipments, deleting shipments, retrieving old shipments, and updating shipments
    ServiceProvider https://api.test.parcelhub.net/1.0/ServiceProviders https://api.parcelhub.net/1.0/ServiceProviders Provides a list of Service Providers

    Authentication (API)

    Authentication Example (Raw)

    POST https://api.test.parcelhub.net/1.0/token HTTP/1.1
    username: TEST001
    Host: api.test.parcelhub.net
    Content-Type: application/json; charset=utf-8
    Content-Length: 57
    
    grant_type=password&username=TEST001&password=TEST001
    

    To use most of the above controllers, first you must authenticate. Parcelhub has a simple username and password system for all our users. If you are a Parcelhub customer, you should have a username and password for the account you wish to use. The test server username and password is TEST001/TEST001.

    Disclaimer: Our public test account is open and available to potentially anyone from the public. We do not take responsbility for information sent and received from this account. Due to this, do not use personal information with this account in any way.

    As of version 1.0, you have to include username in your request headers. Failing to do this will result in a response that looks like this:
    <Error>
          <Message>Missing Username header</Message>
    </Error>

    The API now uses a token system for authentication. To get a token, you need to do a HTTP POST to the token API address, with the username and password:

    POSTing the following body to https://api.test.parcelhub.net/1.0/token:

    grant_type=password&username=TEST001&password=TEST001

    returns something similar to:

    BODY

    {"access_token": "Ab9AI-k1cyzY3HMTr_9jJTNx5J_jxM-c2c1gdhK7ggZVX2YJSWaNZHZ7xr31Cn7A0IMoBr- lxF2oRDEfoRR0ZQXkrVQtSa8cQyAwqggBf5nxPEVOyftnBtPm_H03Bfsf3Ojae9zGV2Kbxvez E1ZIxB0eNxL8vbh8uHRZ3ccr26bjOh2PVnTb7jL8f5bVXIHiyiyvXyQw0aoJEqD5uky6TXjeGg WeUjdtFQFru9k1n8DVJNK0mJnhjEiI2UZxtvuHMRUm31bTZGLI0kJemPxgkleoblt5LJNA9vkE 9ytrA4wMN8L9EnW1YSlItIgzBAcXCFr_g3-Cu6TnkxRYptROjvmaY4FVKf3lrELLLWlbegVzH vGIDI81BiDmPMGPt2rAdCfjte7w_2myi44TsXOGXSsaGG9IR1qZDgbfU0rPSTQtvVG8fG7CUM OS6mzuvNIT-A77Ra4vqFu4QCf8zisj1X4P3xQy5l4TN55oteq8pJw",
    "token_type":"bearer",
    "expires_in":7199,
    "userName":"TEST001",
    ".issued":"Fri, 19 Sep 2014 16:35:56 GMT",
    ".expires":"Fri, 19 Sep 2014 18:35:56 GMT"}

    You will need to keep two key parts for use later: 1. The first of these is the Access Token. You will need to supply this to all subsequent web requests that need to be authenticated. 2. The other part you need is the time this token expires (.expires field). Once you have a token you can store it in your application and use it over and over again until it expires.

    As you have probably noticed this response is JSON. The token is the only use of JSON in the entire API- the rest of the API uses XML. We are working on making this part produce XML too so you don't have to deal with JSON at any point (not that we have anything against JSON, it would just be easier to only use XML throughout). Hopefully the token and date will be fairly easy retrieve to process so there is no need to use a big JSON parser in your application if you don't want to.

    Creating authenticated requests

    Request

    
    HEADERS
    
    Accept:  */*
    username: TEST001
    Accept-Encoding:  gzip, deflate
    
    Authorization:  bearer Ab9AI-k1cyzY3HMTr\_9jJTNx5J\_jxM-c2c1gdhK7ggZVX2YJSWaNZHZ7xr31Cn7A0IMoBr-
    lxF2oRDEfoRR0ZQXkrVQtSa8cQyAwqggBf5nxPEVOyftnBtPm\_H03Bfsf3Ojae9zGV2KbxvezE1ZIxB0eNxL8vbh8uHRZ3
    ccr26bjOh2PVnTb7jL8f5bVXIHiyiyvXyQw0aoJEqD5uky6TXjeGgWeUjdtFQFru9k1n8DVJNK0mJnhjEiI2UZxtvuHMRUm
    31bTZGLI0kJemPxgkleoblt5LJNA9vkE9ytrA4wMN8L9EnW1YSlItIgzBAcXCFr\_g3-Cu6TnkxRYptROjvmaY4FVKf3lrE
    LLLWlbegVzHvGIDI81BiDmPMGPt2rAdCfjte7w\_2myi44TsXOGXSsaGG9IR1qZDgbfU0rPSTQtvVG8fG7CUMOS6mzuvNIT
    -A77Ra4vqFu4QCf8zisj1X4P3xQy5l4TN55oteq8pJw
    

    Response

    HEADERS
    
    Cache-Control:  no-cache
    
    Content-Length:  828
    
    Content-Type:  application/xml; charset=utf-8
    
    Date:  Fri, 19 Sep 2017 17:15:09 GMT
    
    Expires:  -1
    
    Pragma:  no-cache
    
    Server:  Microsoft-IIS/7.5
    
    X-Aspnet-Version:  4.0.30319
    
    BODY
    
    <ShipmentSummaryList xmlns="https://api.test.parcelhub.net/1.0/schemas/api/parcelhub-api-v1.0.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <ShipmentSummary>
            <Account>TEST001</Account>
            <ParcelhubShipmentId>720857415358544877</ParcelhubShipmentId>
            <ServiceInfo>
                <ServiceId>56</ServiceId>
                <ServiceCustomerUID>6450</ServiceCustomerUID>
                <ServiceProviderId>10</ServiceProviderId>
            </ServiceInfo>
            <DeliveryCompanyName>API Test Company</DeliveryCompanyName>
            <DeliveryContactName>Mr API Test</DeliveryContactName>
            <DeliveryPostcode>NG1 1AA</DeliveryPostcode>
            <CollectionDate>2017-09-18T00:00:00</CollectionDate>
            <PackageCount>1</PackageCount>
            <CourierTrackingNumber>JD0005555517277919</CourierTrackingNumber>
            <Reference1>Test</Reference1>
            <Reference2>Test2</Reference2>
        </ShipmentSummary>
    </ShipmentSummaryList>
    

    To call the Service or Shipment controller you need to authenticate your requests (otherwise you will get 401 unauthenticated errors).

    To authenticate your requests first get a token as above. Then add the header Authorization: bearer tokengoeshere to the HTTP headers of your request (where tokengoeshere is the token you got in the previous section). Here is an example when doing a GET on https://api.parcelhub.net/1.0/Shipment (this shows all shipments for that user)

    Acting as an owned user

    Accounts which own sub-acounts can send requests on behalf of these sub-acounts. This allows you to do anything things such as get services and create shipments for owned accounts.

    The table below demonstrates which endpoints can be accessed on behalf of owned accounts:

    Endpoint Method Parameter Name
    https://api.test.parcelhub.net/1.0/Service POST AccountId
    https://api.test.parcelhub.net/1.0/Service GET AccountId
    https://api.test.parcelhub.net/1.0/Service/ServiceUsingServicePreference POST AccountId
    https://api.test.parcelhub.net/1.0/Shipment GET AccountId
    https://api.test.parcelhub.net/1.0/Shipment POST Account
    https://api.test.parcelhub.net/1.0/Shipment PUT Account

    To act as another account you must add the AccountId field into your request. For POST requests, this resides in the body. For GET requests, this must be sent via url parameters.

    Example POST with AccountId in body:

    <Shipment xmlns http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
          <AccountId>TEST002</AccountId>
          ...
    </Shipment>

    Example GET with AccountId as Parameter:

    https://api.parcelhub.net/1.0/Service?AccountId=TEST002

    The authentication details in the request header must remain the same. So if you're acting as 'TEST002' which is owned by 'TEST001' then the username header would be 'TEST001'. Similarly, you will still need the same authorization token that you retrieved for TEST001 earlier.

    Finally, the fact that an account is owned does not affect its ability to post requests. To post from an owned account you would just send requests as if the owner doesn't exist. I.e. to post as TEST002 you would need to request a token with TEST002 as the username header and then post every subsequent request with the same username header and the token you've just recieved.

    How to create a shipment

    The first step in creating a shipment is to make a piece of XML with the root tag that describes the shipment you want to send.

    Not all parts of the Shipment need to be filled in to begin with. As you go through the process of sending a shipment the element gets more and more detail added to it until you get to the end and it is complete.

    Very frequently you already know the carrier and service you want to send this shipment with and a list of service codes that match your contract can be obtained from Parcelhub Sales Admin. Even so, you should always send your shipment to Get Services first. This allows you to confirm that the service is available to the address you have stipulated.

    Shipment XML

    Shipment Request

    <Shipment
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Account>TEST001</Account>
        <CollectionDetails>
            <CollectionDate>2017-09-19</CollectionDate>
            <CollectionReadyTime>12:00:00</CollectionReadyTime>
            <LocationCloseTime>17:00:00</LocationCloseTime>
        </CollectionDetails>
        <CollectionAddress>
            <ContactName>Mr Api Tester</ContactName>
            <CompanyName>API Test Company</CompanyName>
            <Email>Api@apitestco.com</Email>
            <Phone>07777777777</Phone>
            <Address1>108 Test Road</Address1>
            <Address2>Apiville</Address2>
            <City>Nottingham</City>
            <Postcode>NG1 1AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </CollectionAddress>
        <DeliveryAddress>
            <ContactName>Mr Api Tester</ContactName>
            <CompanyName>API Test Company</CompanyName>
            <Email>Api@apitestco.com</Email>
            <Phone>07777777777</Phone>
            <Address1>108 Test Road</Address1>
            <Address2>Apiville</Address2>
            <City>Nottingham</City>
            <Postcode>NG1 1AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </DeliveryAddress>
        <Reference1>Test</Reference1>
        <Reference2>Test2</Reference2>
        <ContentsDescription>Fruit</ContentsDescription>
        <Packages>
            <Package>
                <PackageType>Parcel</PackageType>
                <Dimensions>
                    <Length>10</Length>
                    <Width>10</Width>
                    <Height>10</Height>
                </Dimensions>
                <Weight>2</Weight>
                <Value Currency="GBP">5
                </Value>
                <Contents>Bananas</Contents>
            </Package>
        </Packages>
        <Enhancements />
        <ShipmentTags />
        <ProductTypeCode>LA</ProductTypeCode>
    </Shipment>
    

    Here is an example you can POST to the Service controller to find services:

    Notes:

    1. The namespace declaration xmlns= http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd must be included.
    2. You can send multiple packages in one shipment by duplicating the package section.
    3. This Shipment is UK only, if you want to send parcels abroad you need to add CustomsDeclaration information to the and nodes
    4. The product type code is only relevent when using Arrow XL. You can get a list of product type codes from the 'Product Type Codes' section of this documentation

    Sending the Shipment to Get Services

    Get Services Response

    <?xmlversion="1.0"encoding="utf-8"?>
    <GetServicesResponse
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Services>
            <Service>
                <ServiceIds>
                    <ServiceId>50</ServiceId>
                    <ServiceCustomerUID>5</ServiceCustomerUID>
                    <ServiceProviderId>10</ServiceProviderId>
                </ServiceIds>
                <ServiceName>@HOME72 TR</ServiceName>
                <ServiceDesc>POD </ServiceDesc>
                <ServiceProviderName>YODEL </ServiceProviderName>
                <ServiceCountryCodes>
                    <ServiceCountryCode>GB</ServiceCountryCode>
                </ServiceCountryCodes>
                <AllowableDimensions>
                    <MinWeight>0.00</MinWeight>
                    <MaxWeight>15.00</MaxWeight>
                    <MinVolume>0.00</MinVolume>
                    <MaxVolume>1.00</MaxVolume>
                    <MaxLength>0</MaxLength>
                    <MaxGirth>0.00</MaxGirth>
                </AllowableDimensions>
                <MultiPackages>true</MultiPackages>
                <TimedService>false</TimedService>
                <WeekendService>false</WeekendService>
                <BusinessAddresses>true</BusinessAddresses>
                <ResidentialAddresses>true</ResidentialAddresses>
                <ServiceOutOfArea>false</ServiceOutOfArea>
                <DeliveryExpectation />
                <AvailableEnhancements>
                    <Enhancementname="EML">
                        <Parameters>
                            <Parameterkey="ADDRESS">EMail
                            </Parameter>
                        </Parameters>
                    </Enhancement>
                </AvailableEnhancements>
                <AvailableLabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>EPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>ZPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>NONE</LabelFormat>
                    </LabelSpec>
                </AvailableLabelSpec>
            </Service>
            <Service>
                <ServiceIds>
                    <ServiceId>53</ServiceId>
                    <ServiceCustomerUID>1006</ServiceCustomerUID>
                    <ServiceProviderId>10</ServiceProviderId>
                </ServiceIds>
                <ServiceName>@HOME72 TR</ServiceName>
                <ServiceDesc>NONPOD </ServiceDesc>
                <ServiceProviderName>YODEL </ServiceProviderName>
                <ServiceCountryCodes>
                    <ServiceCountryCode>GB</ServiceCountryCode>
                </ServiceCountryCodes>
                <AllowableDimensions>
                    <MinWeight>0.00</MinWeight>
                    <MaxWeight>15.00</MaxWeight>
                    <MinVolume>0.00</MinVolume>
                    <MaxVolume>1.00</MaxVolume>
                    <MaxLength>0</MaxLength>
                    <MaxGirth>0.00</MaxGirth>
                </AllowableDimensions>
                <MultiPackages>true</MultiPackages>
                <TimedService>false</TimedService>
                <WeekendService>false</WeekendService>
                <BusinessAddresses>true</BusinessAddresses>
                <ResidentialAddresses>true</ResidentialAddresses>
                <ServiceOutOfArea>false</ServiceOutOfArea>
                <DeliveryExpectation />
                <AvailableEnhancements>
                    <Enhancementname="EML">
                        <Parameters>
                            <Parameterkey="ADDRESS">EMail
                            </Parameter>
                        </Parameters>
                    </Enhancement>
                </AvailableEnhancements>
                <AvailableLabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>EPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>EPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>NONE</LabelFormat>
                    </LabelSpec>
                </AvailableLabelSpec>
            </Service>
            <!--… many more services here… -->
        </Services>
        <NearMissServices />
        <UnsuitableServices />
        <UnsuitableServiceProviders>
            <UnsuitableServiceProvider>
                <ServiceProviderId>11</ServiceProviderId>
                <UnsuitableServiceMessage>HDNL only deliver to Guernsey, Jersey and the Republic of Ireland.</UnsuitableServiceMessage>
                <Reason>UNSUITABLEDELIVERYADDRESS</Reason>
            </UnsuitableServiceProvider>
            <UnsuitableServiceProvider>
                <ServiceProviderId>17</ServiceProviderId>
                <UnsuitableServiceMessage>Service Provider doesn't take Parcels</UnsuitableServiceMessage>
                <Reason>BADTYPEOFPACKAGE</Reason>
            </UnsuitableServiceProvider>
        </UnsuitableServiceProviders>
        <ServiceProviderWarnings />
    </GetServicesResponse>
    

    If you POST the above XML to https://api.parcelhub.net/1.0/Service, you get back a document with a list of potential services you can use to send the Shipment:

    (We've cut out a lot of services- there are more than this). Each <Service> is a service you could use to send your shipment. You will get a different list depending on the size, weight and destination address of your shipment. Most of the rest of the information are parameters and a description of the service.

    If you are writing an application with an interactive UI, you could present this list to the user and the user could pick the service they want to use. If you are using the application in support of an ecommerce website, again you could present this list to the customer at point of check-out.

    The most important part are the 3 IDs, as that's what you will need to create the shipment. The second most important part is the AvailableLabelSpec section- this tells you what kind of labels this service provider can produce.

    Understanding the 3 IDs that identify a service

    There are 3 IDs that uniquely identify a service. They are the <ServiceId>, <ServiceProviderId>, and <ServiceCustomerUID>, and they are listed in the <ServiceIds> portion of the the <Service> response. To create a shipment, you will need to use all of these 3 IDs.

    ID Meaning
    ServiceProviderId Which Service Provider (carrier) this service is for.
    ServiceId Identifies a Service from that service provider
    ServiceCustomerUID A unique ID for just this customer, service provider and service.

    The reason there is a ServiceCustomerUID is because sometimes one customer can have several different versions of the same service. We also change this number frequently.

    The key point is: ServiceProviderId and ServiceId never change (or nearly never change). If we do have to change them we will let you know. But ServiceCustomerUID will change all the time and we won't give you any warning at all. You need to run GetServices every time, even if you already know which service you want to send the shipment via since you need to retrieve the ServiceCustomerUID.

    AvailableLabelSpec

    The AvailableLabelSpec section contains a list of LabelSpec elements. Each one of these describes a size and format of label available from this service provider. So for ServiceProviderId 10 and Service Id 50, the first element tells us we can ask for and 8 inch EPL label.

    Creating the shipment

    Request

    <Shipment
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Account>TEST001</Account>
        <CollectionDetails>
            <CollectionDate>2017-09-19</CollectionDate>
            <CollectionReadyTime>12:00:00</CollectionReadyTime>
            <LocationCloseTime>17:00:00</LocationCloseTime>
        </CollectionDetails>
        <CollectionAddress>
            <ContactName>Mr Api Tester</ContactName>
            <CompanyName>API Test Company</CompanyName>
            <Email>Api@apitest.com</Email>
            <Phone>07777777777</Phone>
            <Address1>108 Apitest Road</Address1>
            <Address2>Apiville</Address2>
            <City>Nottingham</City>
            <Postcode>NG1 1AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </CollectionAddress>
        <DeliveryAddress>
            <ContactName>Api Delivery</ContactName>
            <CompanyName>Test Co</CompanyName>
            <Email>test@apitester.com</Email>
            <Phone>015671234567</Phone>
            <Address1>1 Test Lane</Address1>
            <City>East Apiville</City>
            <Postcode>LE1 0AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </DeliveryAddress>
        <Reference1>Test</Reference1>
        <Reference2>Test2</Reference2>
        <ContentsDescription>Fruit</ContentsDescription>
        <Packages>
            <Package>
                <PackageType>Parcel</PackageType>
                <Dimensions>
                    <Length>10</Length>
                    <Width>10</Width>
                    <Height>10</Height>
                </Dimensions>
                <Weight>2</Weight>
                <ValueCurrency="GBP">5
                </Value>
                <Contents>Bananas</Contents>
            </Package>
        </Packages>
        <Enhancements />
        <ShipmentTags />
        <ServiceInfo>
            <ServiceId>50</ServiceId>
            <ServiceProviderId>10</ServiceProviderId>
            <ServiceCustomerUID>5</ServiceCustomerUID>
        </ServiceInfo>
    </Shipment>
    

    Response

    <Shipment
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Account>TEST001</Account>
        <ServiceInfo>
            <ServiceId>50</ServiceId>
            <ServiceCustomerUID>5</ServiceCustomerUID>
            <ServiceProviderId>10</ServiceProviderId>
        </ServiceInfo>
        <ParcelhubShipmentId>720857415356019616</ParcelhubShipmentId>
        <ShippingInfo>
            <CourierTrackingNumber>JD0002212345002894</CourierTrackingNumber>
            <ParcelhubTrackingNumber>TEST001+010A000032000009779</ParcelhubTrackingNumber>
            <CreationDate>2017-09-24T15:09:06.7262611+01:00</CreationDate>
            <CreatingClientSoftware />
            <ShipmentLabels />
        </ShippingInfo>
        <CollectionDetails>
            <CollectionDate>2017-09-19</CollectionDate>
            <CollectionReadyTime>12:00:00</CollectionReadyTime>
            <LocationCloseTime>17:00:00</LocationCloseTime>
        </CollectionDetails>
        <CollectionAddress>
            <ContactName>Mr Api Tester</ContactName>
            <CompanyName>API Test Company</CompanyName>
            <Email>Api@apitest.com</Email>
            <Phone>07777777777</Phone>
            <Address1>108 Apitest Road</Address1>
            <Address2>Apiville</Address2>
            <City>Nottingham</City>
            <Postcode>NG1 1AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </CollectionAddress>
        <DeliveryAddress>
            <ContactName>Api Delivery</ContactName>
            <CompanyName>Test Co</CompanyName>
            <Email>test@apitester.com</Email>
            <Phone>015671234567</Phone>
            <Address1>1 Test Lane</Address1>
            <City>East Apiville</City>
            <Postcode>LE1 0AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </DeliveryAddress>
        <Reference1>Test</Reference1>
        <Reference2>Test2</Reference2>
        <ContentsDescription>Fruit</ContentsDescription>
        <Packages>
            <Package>
                <PackageType>Parcel</PackageType>
                <Labels>
                    <Label>
                        <LabelData>iVBORw0KGgoAAAANSUhEUgAABJ0AAAmwCAI \*snip\*
    
    l//33Pyi/G3MfJ6/QAAAAAElFTkSuQmCC</LabelData>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                        <RawLabelData>
                            <YodelLabelModel
                                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                xmlns="">
                                <ProductName>@HOME</ProductName>
                                <ServiceDescription>@HOME 72</ServiceDescription>
                                <FromCompanyName>Test Man</FromCompanyName>
                                <FromAddressLine1>1 TEST PLACE</FromAddressLine1>
                                <FromAddressLine2>COLWICK</FromAddressLine2>
                                <FromTownCity>NOTTINGHAM</FromTownCity>
                                <FromArea />
                                <FromPostcode>NG2 4EU</FromPostcode>
                                <ToCompanyName>Tester Co</ToCompanyName>
                                <ToAddressLine1>11 TESTING GARDENS</ToAddressLine1>
                                <ToAddressLine2 />
                                <ToTownCity>EAST APIVILLE</ToTownCity>
                                <ToArea />
                                <ToPostcode>NG1 1AA</ToPostcode>
                                <ToContactName>MR API TESTER</ToContactName>
                                <ToContactTel>07777777777</ToContactTel>
                                <MeterNumber>12345</MeterNumber>
                                <ServiceCode>3H</ServiceCode>
                                <DayCode />
                                <TimeCode />
                                <Reference>
                                    <Ref1>TEST</Ref1>
                                    <Ref2>TEST2</Ref2>
                                </Reference>
                                <ShipmentDate>2017/09/19</ShipmentDate>
                                <ServiceCentreLocationName>7258\_LOUG\_85</ServiceCentreLocationName>
                                <HubLocationName>YODEL126</HubLocationName>
                                <RoutingBarcode>2LGBNG72LF+99000018</RoutingBarcode>
                                <SpecialInstruction />
                                <TrackingNumbers>
                                    <JDNumbers>
                                        <DataIdentifier>J</DataIdentifier>
                                        <Barcode>JD0002212345002894</Barcode>
                                        <HumanReadable>(J)JD00 022 123 4500 2894</HumanReadable>
                                        <ReturnCode>1000429810</ReturnCode>
                                        <PackNumber>1</PackNumber>
                                        <PackageWeight>2.00</PackageWeight>
                                    </JDNumbers>
                                </TrackingNumbers>
                            </YodelLabelModel>
                        </RawLabelData>
                        <Printed>false</Printed>
                    </Label>
                </Labels>
                <CourierTrackingNumber>(J)JD00 022 123 4500 2894</CourierTrackingNumber>
                <Dimensions>
                    <Length>10</Length>
                    <Width>10</Width>
                    <Height>10</Height>
                </Dimensions>
                <Weight>2</Weight>
                <ValueCurrency="GBP">5
                </Value>
                <Contents>Bananas</Contents>
            </Package>
        </Packages>
        <Enhancements />
        <ModifiedTime>2014-09-24T15:09:06.7262611+01:00</ModifiedTime>
        <Deleted>false</Deleted>
        <HasBeenManifested>false</HasBeenManifested>
        <ShipmentTags />
    </Shipment>
    

    To create a shipment, you need to POST the same piece of shipment XML that you posted to the Shipment Controller. This shipment XML also needs the service you have decided to use. So the XML becomes the request shown on the right.

    This the bit that you have to add to create a shipment:

    <ServiceInfo>
    <ServiceId>50</ServiceId>
    <ServiceProviderId>10</ServiceProviderId>
    <ServiceCustomerUID>5</ServiceCustomerUID>
    </ServiceInfo>

    As you can see, I've added the 3 IDs from before.

    POST this shipment to:

    https://api.parcelhub.net/1.0/Shipment?RequestedLabelSize=8&RequestedLabelFormat=PNG

    This will return the response on the right.

    The response is a piece of Shipment XML again, but with more detail filled in. As you can see we now have some tracking information and labels in the XML. You have successfully booked a shipment!

    The LabelData section inside the Label inside the package is the PNG of the label Base64 encoded.

    By changing RequestedLabelSize or RequestedLabelFormat in the POST URL you can get labels in different formats. You can get all the possible types you can use when you do GetServices, but the typical options are PDF, PNG, JPG and EPL or ZPL for label printers.

    Important note: The create shipment controller uses validation methods to ensure shipment details are correct. You will need to change the address from the one in the example to a real address to recieve a valid service and to successfully create a shipment.

    Enhancements

    Enhancement get services example:

    <GetServicesResponse>
        <Services>
            <Service>
            ...
                <AvailableEnhancements>
                    <Enhancement name="BKI">
                        <Parameters>
                            <Parameter key="TRUEFALSE">Book-In</Parameter>
                        </Parameters>
                    </Enhancement>
                    <Enhancement name="INS">
                        <Parameters>
                            <Parameter key="INSVALUE">Insurance</Parameter>
                        </Parameters>
                        </Enhancement>
                </AvailableEnhancements>
            ...
            </Service>
        </Services>
    </GetServicesResponse>
    

    Enhancement create shipment example

    <Shipment>
    ...
        <Enhancements>
          <Enhancement>
            <Key>INS</Key>
            <Value>
              <EnhancementDetails>
                <Key>INSVALUE</Key>
                <Value>5</Value>
              </EnhancementDetails>
            </Value>
          </Enhancement>
        </Enhancements>
    ...
    </Shipment>
    

    When creating a shipment, some services allow you to add enhancements. These are addons such as insurance and package status notifications. Which enhancements you are able to use is controlled and handled by the carrier.

    To add an enhancement to a shipment, first make note of the available enhancements when you do your initial service request. This will look something like the 'Enhancement get services example' on the right.

    Once you know which enhancement you want, all you have to do is send back that enhancement in your create shipment request. Look at the 'Enhancement create shipment example' on the right for an example of how this should look.

    From the information you received in your get service response, you must take the 'Enhancement name' and the 'Parameter key' for your create shipment request. The create shipment request enhancements requires a key value pair (KVP) within a key value pair. The top level key will be your enhancement name. The value for this is then the second KVP. The key for the second KVP is your parameter key. The value for this should be fairly self explanatory. In this case we are adding insurance to a shipment so the value we use is the value of the shipment that we want to send.

    Error handling

    If the request is successful you'll get a HTTP 200 OK code and some XML.

    If there is an error of some sort, the HTTP return code will vary between one of the HTTP error return codes and there will be some error XML returned (unless there has been a terrible error and the software has stopped working altogether). Very typically you will get a 400 error if it doesn't like your incoming XML.

    You will also get a bit of XML back that typically looks like this:

    <Error><Message>Error message</Message></Error>

    Some Pseudocode use cases:

    Use case 1 example:

    Get username
    
    Get password
    
    Get desired ServiceProviderId
    
    Get desired ServiceId
    
    Get a token for the username and password
    
    foreach (shipment you want to send)
    
    {
    
     Translate the information you have for this shipment into our shipment XML
    
     POST this XML to the Shipment Controller using the token and store returned XML document
    
    Look through returned XML document for a service that matches the one you want and store the ServiceCustomerUID
    
    Add the ShipmentInfo section to the shipment XML using the desired ServiceProviderId, ServiceId and the ServiceCustomerUID you just found.
    
    POST this document to the Shipment controller
    
    Get the returned XML.
    
    Retrieve and decode the label from the returned XML.
    
    Print label
    
    }
    

    Use case 1: You want to send lots of parcels, and you already know which service you want to use

    Before you start, find out the ServiceProviderId and ServiceId for the service you want to use. You could do this by:

    1. Running a GetServices by hand and finding the service in the resulting list or
    2. Asking someone who works at Parcelhub

    Use case 2 example

    Collect the Parcelhub username and password from the user
    
    Get a token for this username and password
    
    Collect from user the details of their shipment e.g. from address, to address, number of parcels, weight
    
    Make a Shipment XML snippet from this data
    
    Post that XML to the Services controller and store the returned XML document
    
    Using the returned XML document to produce a menu so the user can select which service they think is the most suitable
    
    Add this service to a ShipmentInfo XML section of the Shipment XML.
    
    Post this document to the Shipment Controller
    
    Get the returned XML.
    
    Retrieve and decode the label from the returned XML.
    
    Print label
    
    Tell user tracking details
    

    Use case 2: You want a desktop app that allows a user to send parcels

    The psuedo code on the right explains this.

    DeleteShipment - a very quick guide

    To delete a shipment in the new API is very easy. All you have to do is send a DELETE HTTP request to the Shipment controller with the ParcelhubShipmentId. E.g. sending a DELETE request to https://api.parcelhub.net/1.0/Shipment/235678 will try and delete shipment number 235678. Requests need to be authenticated with an Authorization: bearer header. After successfully deleting a shipment, the server will send back a 204 response.

    Product Type Codes

    The below table shows the product type codes for when using Arrow XL and their characteristics

    ProductTypeCode ProductCategory ProductCharacteristic
    BL BROWN GOODS - LARGE TV > 26" screen, Audio > 35 kg Music keyboard
    BM BROWN GOODS - MEDIUM TV up to 26" screen, Home theatre kit Audio 25 kg to 35 kg
    BS BROWN GOODS - SMALL VCR/DVD, Camcorder, Audio < 25 kg
    CB CANE SOFA BED
    CC CANE SINGLE CHAIR
    CP CARPET
    CS CANE SUITE
    CY CYCLE
    F1 FLAT PACK - 1 PACK Flat packed item in 1 pack (Note: Also includes headboards and awnings)
    F2 FLAT PACK - 2 PACKS Flat packed item in 2 packs
    F3 FLAT PACK - 3 PACKS Flat packed item in 3 packs (Note: Also includes imported multi-pack table and chair packs (even though not true flat packed))
    F4 FLAT PACK - 4 PACKS Flat packed item in 4 or more packs
    FE GYM EQUIPMENT Walker, Treadmill, Weight bench, Weight set, Trampoline
    FI FIRE SURROUND Note: Fire surround only, for gas and electric fire suites use WG
    GB GARDEN EQUIPMENT - LARGE Patio set with 5 pieces or more (Bench, Pergola, Gazebo, Large barbecue, Patio heater)
    GS GARDEN EQUIPMENT - SMALL Small patio set < 5 pieces (Lounger, Lawnmower Generator, Chimenea)
    HT HEAVY TOY Battery-powered car, Playhouse, Games table, Paddling pool, Drum kit
    LA LADDER
    LD BED - LARGE - DIVAN Divan Bed 4' & larger (Note: If flat packed, use F1, F2, F3 or F4)
    LM BED - LARGE - MATTRESS Bed Mattress 4' & larger
    PB BED - PAIR OF SINGLES - DIVAN
    PM BED - PAIR OF SINGLES - MATTRESS
    RL RIGID FURNITURE - LARGE Assembled furniture > 1.90 m and/or > 55 kg in weight
    RM RIGID FURNITURE - MEDIUM Assembled furniture > 1.25 m to 1.90 m and/or 35 kg to 55 kg in weight
    RS RIGID FURNITURE - SMALL Assembled furniture < 1.25 m and/or < 35 kg in weight
    SD BED - SMALL - DIVAN Divan Bed 2'6" and 3' (Note: If flat packed, use F1, F2, F3 or F4)
    SH GARDEN SHED Shed, Greenhouse , Tool-store etc.
    SM BED - SMALL - MATTRESS Bed Mattress 2'6" and 3'
    SO SUNBED
    ST SNOOKER TABLE Snooker table, Pool table
    U2 UPHOLSTERY - 2-SEATER 2-Seater settee sold as single unit, Chaise longue
    U3 UPHOLSTERY - 3-SEATER 3-Seater settee sold as single unit
    UB UPHOLSTERY - SOFA BED Note: Includes futons
    UC UPHOLSTERY - SINGLE CHAIR Single chair Recliner chair
    UF UPHOLSTERY - FOOTSTOOL Footstool sold as single unit Small/light foam chair bed
    UG UPHOLSTERY - CORNER GROUP
    US UPHOLSTERY - SUITE - 3-PIECE 3-Piece suite
    UT UPHOLSTERY - SUITE - 2-PIECE 2-Piece suite
    WC WHITE GOODS - COOKER Standard size gas/electric cooker
    WD WHITE GOODS - WASHER/DRYER Washer/Dryer (single item)
    WF WHITE GOODS - FRIDGE/FREEZER Fridge/Freezer
    WG WHITE GOODS - GENERIC - SMALL Larder fridge, Small freezer, Hob, Cooker hood, Gas/electric fires, Microwave
    WH WHITE GOODS - DISHWASHER
    WL WHITE GOODS - DRYER Tumble/Spin dryer
    WP WHITE GOODS - PACKED - 2 UNITS Washer/Dryer package (separate items) Fridge/Freezer package (separate items)
    WW WHITE GOODS -WASHING MACHINE Washing machine
    XR RIGID FURNITURE - EXTRA LARGE Assembled furniture > 2.00 m and/or 55 kg to 75 kg in weight

    Service Preference Lists

    This document assumes you already know how to use the 1.0 API. If not, then look at the Getting Started guide.

    What's a Service Preference List and what can I do with it?

    A service preference list is a list of services that the customer has in a preference order. They are used for automatic service selection.

    Customers can edit their service preferences using the Parcelhub website, or you can edit them using your own software.

    A user can have as many Service Preference Lists as they like. Each service preference list belongs to one Parcelhub Account.

    When you create a shipment using the traditional method you first send a shipment to Get Services which returns a list of services you could use to send this parcel. Using the Service Preference Lists you can send a shipment and the service preference list and it will tell you which service to use (or no service, if it can't find a suitable one in the list).

    Example

    Here is a sample Service Preference List displayed on the website:

    If you submit a shipment you want to the service controller using the service preference list option, it will return a service that is suitable. Since the packet service is cheaper than the full parcel service, we've put this higher up the list. If you are sending a shipment that is small enough for a packet service, you will get the packet service back. But if the parcel is too big, you will get one of the parcel services back.

    Yodel don't deliver to all postcodes on their ordinary service- some postcodes require a special islands service. We've included the islands services in our sample service preference list. If you send a shipment to the service controller using this service list you'll automatically get the islands service when you need it, and not when you don't.

    Previously some customers have been writing software that attempts to store the 'rules'for picking services in the software. By using this service, you can automatically pick the service needed without the need for lots of programming.

    Service Preference List Ids

    Every service preference list has an Id. You can find out the Id from the website Service Preference page. The Ids are unique across the entire of Parcelhub, so one user might have Ids 1,55, and 172 belong to them. Id 2, 52 might belong to someone else. And so on. You can only use service preference lists that belong to the Parcelhub user you are logged in.

    Running Get Services against a Service Preference List - a comparison

    Shipment

    <Shipment xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <CollectionDetails>
            <CollectionDate>2014-09-19</CollectionDate>
            <CollectionReadyTime>12:00:00</CollectionReadyTime>
            <LocationCloseTime>17:00:00</LocationCloseTime>
        </CollectionDetails>
        <CollectionAddress>
            <ContactName>Fred Person</ContactName>
            <CompanyName>Fred Person</CompanyName>
            <Email>email@parcelhub.co.uk</Email>
            <Phone>07772123654</Phone>
            <Address1>108 Ashdown Road</Address1>
            <Address2>Ashdown Place</Address2>
            <City>Nottingham</City>
            <Postcode>NG2 4EU</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </CollectionAddress>
        <DeliveryAddress>
            <ContactName>Bob Person</ContactName>
            <CompanyName>Bob Person</CompanyName>
            <Email>bob@person.co.uk</Email>
            <Phone>015451234567</Phone>
            <Address1>1 Potters Lane</Address1>
            <City>East Beak</City>
            <Postcode>LE11 6NA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </DeliveryAddress>
        <Reference1>Test</Reference1>
        <Reference2>Test2</Reference2>
        <ContentsDescription>Fruit</ContentsDescription>
        <Packages>
            <Package>
                <PackageType>Parcel</PackageType>
                <Dimensions>
                    <Length>10</Length>
                    <Width>10</Width>
                    <Height>10</Height>
                </Dimensions>
                <Weight>2</Weight>
                <Value Currency="GBP">5</Value>
                <Contents>Bananas</Contents>
            </Package>
        </Packages>
        <Enhancements />
        <ShipmentTags />
    </Shipment>
    

    Here is a comparison with how the Get Services step works between using a service preference list and not.

    Consider 'Shipment' on the right

    GetServicesResponse

    <?xml version="1.0" encoding="utf-8"?>
    <GetServicesResponse xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Services>
            <Service>
                <ServiceIds>
                    <ServiceId>50</ServiceId>
                    <ServiceCustomerUID>5</ServiceCustomerUID>
                    <ServiceProviderId>10</ServiceProviderId>
                </ServiceIds>
                <ServiceName>@HOME72 TR</ServiceName>
                <ServiceDesc>POD</ServiceDesc>
                <ServiceProviderName>YODEL</ServiceProviderName>
                <ServiceCountryCodes>
                    <ServiceCountryCode>GB</ServiceCountryCode>
                </ServiceCountryCodes>
                <AllowableDimensions>
                    <MinWeight>0.00</MinWeight>
                    <MaxWeight>30.00</MaxWeight>
                    <MinVolume>0.00</MinVolume>
                    <MaxVolume>1.00</MaxVolume>
                    <MaxLength>0</MaxLength>
                    <MaxGirth>0.00</MaxGirth>
                </AllowableDimensions>
                <MultiPackages>true</MultiPackages>
                <TimedService>false</TimedService>
                <WeekendService>false</WeekendService>
                <BusinessAddresses>true</BusinessAddresses>
                <ResidentialAddresses>true</ResidentialAddresses>
                <ServiceOutOfArea>false</ServiceOutOfArea>
                <DeliveryExpectation />
                <AvailableEnhancements>
                    <Enhancement name="EML">
                        <Parameters>
                            <Parameter key="ADDRESS">EMail</Parameter>
                        </Parameters>
                    </Enhancement>
                </AvailableEnhancements>
                <AvailableLabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>EPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>EPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>NONE</LabelFormat>
                    </LabelSpec>
                </AvailableLabelSpec>
            </Service>
            <Service>
                <ServiceIds>
                    <ServiceId>53</ServiceId>
                    <ServiceCustomerUID>1006</ServiceCustomerUID>
                    <ServiceProviderId>10</ServiceProviderId>
                </ServiceIds>
                <ServiceName>@HOME72 TR</ServiceName>
                <ServiceDesc>NONPOD</ServiceDesc>
                <ServiceProviderName>YODEL</ServiceProviderName>
                <ServiceCountryCodes>
                    <ServiceCountryCode>GB</ServiceCountryCode>
                </ServiceCountryCodes>
                <AllowableDimensions>
                    <MinWeight>0.00</MinWeight>
                    <MaxWeight>30.00</MaxWeight>
                    <MinVolume>0.00</MinVolume>
                    <MaxVolume>1.00</MaxVolume>
                    <MaxLength>0</MaxLength>
                    <MaxGirth>0.00</MaxGirth>
                </AllowableDimensions>
                <MultiPackages>true</MultiPackages>
                <TimedService>false</TimedService>
                <WeekendService>false</WeekendService>
                <BusinessAddresses>true</BusinessAddresses>
                <ResidentialAddresses>true</ResidentialAddresses>
                <ServiceOutOfArea>false</ServiceOutOfArea>
                <DeliveryExpectation />
                <AvailableEnhancements>
                    <Enhancement name="EML">
                        <Parameters>
                            <Parameter key="ADDRESS">EMail</Parameter>
                        </Parameters>
                    </Enhancement>
                </AvailableEnhancements>
                <AvailableLabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>EPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>EPL</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PNG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>PDF</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>8</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>JPG</LabelFormat>
                    </LabelSpec>
                    <LabelSpec>
                        <LabelSize>6</LabelSize>
                        <LabelFormat>NONE</LabelFormat>
                    </LabelSpec>
                </AvailableLabelSpec>
            </Service>
            <!--... many more services here... -->
        </Services>
        <NearMissServices />
        <UnsuitableServices />
        <UnsuitableServiceProviders>
            <UnsuitableServiceProvider>
                <ServiceProviderId>11</ServiceProviderId>
                <UnsuitableServiceMessage>HDNL only deliver to Guernsey, Jersey
    and the Republic of Ireland.</UnsuitableServiceMessage>
                <Reason>UNSUITABLEDELIVERYADDRESS</Reason>
            </UnsuitableServiceProvider>
            <UnsuitableServiceProvider>
                <ServiceProviderId>17</ServiceProviderId>
                <UnsuitableServiceMessage>Service Provider doesn't take
    Parcels</UnsuitableServiceMessage>
                <Reason>BADTYPEOFPACKAGE</Reason>
            </UnsuitableServiceProvider>
        </UnsuitableServiceProviders>
        <ServiceProviderWarnings />
    </GetServicesResponse>
    

    If we POST it to the service controller (either http://api.parcelhub.net/api/1.0/Service or http://api.test.parcelhub.net/1.0) you get a list of potential services you could use as shown in GetServicesResponse (on the right).

    Service

    <Service xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <ServiceIds>
            <ServiceId>56</ServiceId>
            <ServiceCustomerUID>1007</ServiceCustomerUID>
            <ServiceProviderId>10</ServiceProviderId>
        </ServiceIds>
        <ServiceName>@HOME72 TR</ServiceName>
        <ServiceDesc>NHOOD POD</ServiceDesc>
        <ServiceProviderName>YODEL</ServiceProviderName>
        <ServiceCountryCodes>
            <ServiceCountryCode>GB</ServiceCountryCode>
        </ServiceCountryCodes>
        <AllowableDimensions>
            <MinWeight>0.00</MinWeight>
            <MaxWeight>30.00</MaxWeight>
            <MinVolume>0.00</MinVolume>
            <MaxVolume>1.00</MaxVolume>
            <MaxLength>0</MaxLength>
            <MaxGirth>0.00</MaxGirth>
        </AllowableDimensions>
        <MultiPackages>true</MultiPackages>
        <TimedService>false</TimedService>
        <WeekendService>false</WeekendService>
        <BusinessAddresses>true</BusinessAddresses>
        <ResidentialAddresses>true</ResidentialAddresses>
        <ServiceOutOfArea>false</ServiceOutOfArea>
        <DeliveryExpectation />
        <AvailableEnhancements>
            <Enhancement name="EML">
                <Parameters>
                    <Parameter key="ADDRESS">EMail</Parameter>
                </Parameters>
            </Enhancement>
        </AvailableEnhancements>
        <AvailableLabelSpec>
            <LabelSpec>
                <LabelSize>8</LabelSize>
                <LabelFormat>EPL</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>6</LabelSize>
                <LabelFormat>EPL</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>8</LabelSize>
                <LabelFormat>PNG</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>6</LabelSize>
                <LabelFormat>PNG</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>8</LabelSize>
                <LabelFormat>PDF</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>6</LabelSize>
                <LabelFormat>PDF</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>8</LabelSize>
                <LabelFormat>JPG</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>6</LabelSize>
                <LabelFormat>JPG</LabelFormat>
            </LabelSpec>
            <LabelSpec>
                <LabelSize>NONE</LabelSize>
                <LabelFormat>NONE</LabelFormat>
            </LabelSpec>
        </AvailableLabelSpec>
    </Service>
    

    To use the Service Provider List version of Get Services, instead POST to http://api.test.parcelhub.net/1.0/Service/ServiceUsingServicePreference?ServicePreferenceListId=XX or

    http://api.parcelhub.net/api/1.0/Service/ServiceUsingServicePreference?ServicePreferenceListId=XX *where XX is the ServicePreferenceListId number you want to use, you will get just one service back as shown in service (on the right).

    Which is the best service to use, according to that service preference list.

    If you try and send a shipment which no services match, you will get a 404 not found response.

    Editing Service Preference Lists via code - a very rough guide

    ServicePreferenceList request

    <ServicePreferenceList xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
    
    <Account>TEST001</Account>
    <Name>Test List</Name>
    <ServicePreferences>
        <ServicePreference>
            <ServiceId>56</ServiceId>
            <ServiceProviderId>10</ServiceProviderId>
            <ServiceCustomerUID>1007</ServiceCustomerUID>
        </ServicePreference>
        <ServicePreference>
            <ServiceId>50</ServiceId>
            <ServiceProviderId>10</ServiceProviderId>
            <ServiceCustomerUID>5</ServiceCustomerUID>
        </ServicePreference>
    </ServicePreferences>
    </ServicePreferenceList>
    

    If you want to embed the ability to edit Service Preference Lists in your application you can do that using the ServicePreferenceList controller (http://api.parcelhub.net/api/1.0/ServicePreferenceList).

    You can GET, PUT, POST to this controller.

    To create a Service Preference List POST the XML in ServicePreferenceList request to the above URL

    Important note: The ServiceId, ServiceProviderId and ServiceCustomerUID all need to be valid when testing this feature. The values in the example given are dummy numbers and will return a 500 (internal server error) response.

    ServicePreferenceList response

    <ServicePreferenceList xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Id>1</Id>
        <Account>TEST001</Account>
        <Name>Test List</Name>
        <CreationDate>2015-02-24T15:10:07.61</CreationDate>
        <ModifiedTime>2015-02-24T15:15:19.337</ModifiedTime>
        <UserAgent>Parcelhub Test Web</UserAgent>
        <ServicePreferences>
            <ServicePreference>
                <ServiceId>56</ServiceId>
                <ServiceProviderId>10</ServiceProviderId>
                <ServiceCustomerUID>1007</ServiceCustomerUID>
            </ServicePreference>
            <ServicePreference>
                <ServiceId>50</ServiceId>
                <ServiceProviderId>10</ServiceProviderId>
                <ServiceCustomerUID>5</ServiceCustomerUID>
            </ServicePreference>
        </ServicePreferences>
    </ServicePreferenceList>
    

    The list of services identified by their Service Ids is in the second part, in order.

    You'll get a completed Service Preference List back as shown in the ServicePreferenceList response.

    Note the Id- this is the Id you need to use when referring to this service provider list in future.

    You can also view all the service provider lists you have access to GET http://api.test.parcelhub.net/1.0/ServicePreferenceList , get a specific service preference list GET http://api.test.parcelhub.net/1.0/ServicePreferenceList/Id and update a service preference list PUT http://api.test.parcelhub.net/1.0/ServicePreferenceList . If you need any help, contact Parcelhub Support.

    Retrieve Old Shipments - Shipment Controller

    Introduction

    Hopefully if you are reading this you have mastered creating shipments using the API (if not see “Getting Started”). To create shipments there are two phases- you find the services you can use by POSTing your shipment XML to the Services controller. Once you’ve picked a service then you add the service info section to the shipment XML and you book the shipment by POSTing it to the Shipment controller.

    This document is about other things you can do with the Shipment controller. The Shipment controller implements a RESTful interface to shipments. RESTful interfaces use standard HTTP verbs (GET, POST, PUT, DELETE) to create, read, update and delete resources.

    You’ve already seen how to create a shipment by POSTing a shipment to this controller. This document is about how use the other functions of the Shipment controller to retrieve shipments you’ve already made.

    Some app ideas

    You could write a program that generates a report about how many parcels you sent using each carrier in the last month. Or you could write a program that fetches all labels for all parcels you have made today and sends them to a printer. Or you could send write a program that creates all the shipments in the morning and stores and Order Id in one of the reference fields, and write a program to retrieve the label for a shipment when the products get picked in the afternoon.

    Understanding how to use this controller will help when learning about Draft Shipments.

    Authentication

    You need to use a token in the header to use all the Shipment controller features, just like when creating shipment.

    Error Codes

    RESTful services like these return an HTTP status code depending on whether the result was successful or not. HTTP status codes are 3 digits long. Status codes beginning 2XX indicate success, 4xx are failures that are the fault of the users, and 5xx are server errors.

    Shipment Controller Functions

    Return

    <ShipmentSummaryList
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v1.0.xsd">
        <ShipmentSummary>
            <Account>TEST001</Account>
            <ParcelhubShipmentId>1689949371895939</ParcelhubShipmentId>
            <ServiceInfo>
                <ServiceId>2005</ServiceId>
                <ServiceCustomerUID>22</ServiceCustomerUID>
                <ServiceProviderId>6</ServiceProviderId>
            </ServiceInfo>
            <DeliveryCompanyName>Dolby Theatre</DeliveryCompanyName>
            <DeliveryContactName>Billy Crystal</DeliveryContactName>
            <DeliveryPostcode>90028</DeliveryPostcode>
            <CollectionDate>2015-06-03T00:00:00</CollectionDate>
            <PackageCount>1</PackageCount>
            <CourierTrackingNumber>9565078666</CourierTrackingNumber>
            <Reference1>Statues</Reference1>
            <ContentsDescription>Goods</ContentsDescription>
            <ShipmentTags />
        </ShipmentSummary>
        <ShipmentSummary>
            <Account>TEST001</Account>
            <ParcelhubShipmentId>2815849278799509</ParcelhubShipmentId>
            <ServiceInfo>
                <ServiceId>56</ServiceId>
                <ServiceCustomerUID>1007</ServiceCustomerUID>
                <ServiceProviderId>10</ServiceProviderId>
            </ServiceInfo>
            <DeliveryCompanyName>Rachel Goody</DeliveryCompanyName>
            <DeliveryContactName>Rachel Goody</DeliveryContactName>
            <DeliveryPostcode>AA1 1BB</DeliveryPostcode>
            <CollectionDate>2015-06-02T00:00:00</CollectionDate>
            <PackageCount>1</PackageCount>
            <CourierTrackingNumber>JD0002212345008618</CourierTrackingNumber>
            <Reference1>1355269</Reference1>
            <Reference2>204-0273234-9724359</Reference2>
            <ContentsDescription>Goods</ContentsDescription>
            <ShipmentTags />
        </ShipmentSummary>
        <ShipmentSummary>
            <Account>TEST001</Account>
            <ParcelhubShipmentId>2815849278799509</ParcelhubShipmentId>
            <ServiceInfo>
                <ServiceId>56</ServiceId>
                <ServiceCustomerUID>1007</ServiceCustomerUID>
                <ServiceProviderId>10</ServiceProviderId>
            </ServiceInfo>
            <DeliveryCompanyName>Rachel Goody</DeliveryCompanyName>
            <DeliveryContactName>Rachel Goody</DeliveryContactName>
            <DeliveryPostcode>AA1 1BB</DeliveryPostcode>
            <CollectionDate>2015-06-02T00:00:00</CollectionDate>
            <PackageCount>1</PackageCount>
            <CourierTrackingNumber>JD0002212345008618</CourierTrackingNumber>
            <Reference1>1355269</Reference1>
            <Reference2>204-0273234-9724359</Reference2>
            <ContentsDescription>Goods</ContentsDescription>
            <ShipmentTags />
        </ShipmentSummary>
    
    …etc…
    
    </ShipmentSummaryList>
    

    The shipment controller is at http://api.parcelhub.net/api/1.0/Shipment on the live API and http://api.test.parcelhub.net/1.0/Shipment on the test. We’ll be using the live as an example.

    GET http://api.parcelhub.net/api/1.0/Shipment - gives a list of shipments you’ve created

    This returns a list of the last 200 shipments you’ve created by collection date. It returns each shipment as a ShipmentSummary which contains some details about the shipment. If you want to find out more details about any one shipment you can use the ParcelhubShipmentId with the next call.

    GET http://api.parcelhub.net/api/1.0/Shipment/XXXXX - gets a Shipment where XXXXX is a ParcelhubShipmentId

    If you have a ParcelhubShipmentId you can get individual shipments using this call. This returns the Shipment XML for a Shipment, or 404 if this shipment cannot be found.

    POST http://api.parcelhub.net/api/1.0/Shipment?RequestedLabelFormat=X&RequestedLabelSize=Y- Creates a shipment

    This is the Create Shipment method discussed elsewhere.

    PUT http://api.parcelhub.net/api/1.0/Shipment

    Put modifies a shipment that has already been created. To use it, PUT some shipment XML back in the same way as you use POST. Typically you would GET some XML, change something then POST it back.

    There isn’t much you can do with this as it doesn’t make sense to change much about a submitted shipment. The only things you can change is ShipmentTags and whether labels are printed – this is how web.parcelhub.net knows which labels have been printed.

    To add a tag to the shipment you have to embed <ShipmentTag> within <ShipmentTags> like so:

    <ShipmentTags>
          <ShipmentTag>Test Tag 1</ShipmentTag>
          <ShipmentTag>Test Tag 2</ShipmentTag>
    <\ShipmentTags>

    DELETE http://api.parcelhub.net/api/1.0/Shipment/XXXXXX

    Deletes a shipment with ParcelhubShipmentId XXXXXX. Returns code 203 if successful.

    POST http://api.parcelhub.net/api/1.0/Shipment/Search

    This allows you to search for shipments based on a list of criteria. It then returns a ShipmentSummaryList like the GET method.

    The search query is a special piece of XML that you POST to specify which shipments you want to retrieve. Take a look at 'search query example'.

    Search query example

    <?xml version="1.0" encoding="utf-16"?>
    <SearchQuery
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Condition field="CollectionDetails.CollectionDate"
    greaterthan="01/06/2015 00:00:00" />
    </SearchQuery>
    

    This example searches for all shipments later than the 1st of July 2015.

    A search is made up of a series of Condition, all of which must match.

    Every condition has a field that you are trying to match and one or more condition. There are some example searches on the right.

    Get all DHL shipments:

    <?xml version="1.0"?>
    <SearchQuery
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Condition field="ServiceInfo.ServiceProviderId" equals="6" />
    </SearchQuery>
    

    Get all shipments sent using UKMail that are multiples

    <?xml version="1.0"?>
    <SearchQuery
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Condition field="ServiceInfo.ServiceProviderId" equals="19" />
        <Condition field="NumberOfPackages" greaterthan="2" />
    </SearchQuery>
    

    Please note: greaterthan and lessthan are really “greater or equals” and “less than or equals”.

    Complete list of things you can search for

    CollectionDetails.CollectionDate CollectionAddress.AddressType ServiceInfo.ServiceId
    ModifiedTime DeliveryAddress.ContactName ServiceInfo.ServiceProviderId
    ShippingInfo.CreationDate DeliveryAddress.CompanyName ServiceInfo.ServiceCustomerUID
    CreatingClientSoftware DeliveryAddress.Address1 ShipmentTags
    Account DeliveryAddress.Address2 ShippingInfo.CourierTrackingNumber
    CollectionAddress.ContactName DeliveryAddress.City ParcelhubShipmentId
    CollectionAddress.CompanyName DeliveryAddress.Area AllText
    CollectionAddress.Address1 DeliveryAddress.Postcode NumberOfPackages
    CollectionAddress.Address2 DeliveryAddress.Country
    CollectionAddress.City DeliveryAddress.Email
    CollectionAddress.Area DeliveryAddress.Phone
    CollectionAddress.Postcode DeliveryAddress.AddressType
    CollectionAddress.Country ContentsDescription
    CollectionAddress.Email Reference1
    CollectionAddress.Phone Reference2

    Tracking API

    API End Points

    Examples of success and error ServiceResults:

    Request

    ...
    <ServiceResult>
      <Success>true</Success>
      <ErrorCode>0</ErrorCode>
      <ErrorMessage />
      <InternalErrorMessage />
      <HasWarning>false</HasWarning>
      <WarningMessage />
    </ServiceResult>
    ...
    
    

    Error

    ...
    <ServiceResult>
      <Success>false</Success>
      <ErrorCode>200006</ErrorCode>
      <ErrorMessage>Error authenticate request</ErrorMessage>
      <InternalErrorMessage>Error authenticate request</InternalErrorMessage>
      <HasWarning>false</HasWarning>
      <WarningMessage />
    </ServiceResult>
    ...
    
    

    The tracking API url is: https://trackapi.parcelhub.net The tracking API consists of 4 xml end points:

    1. /v1/trackingservice/listshipments
    2. /v1/trackingservice/getlatesttrackingevent
    3. /v1/trackingservice/gettrackinghistory
    4. /v1/trackingservice/searchshipment

    All API response includes a ServiceResult object which denotes whether the request sent to the API was successful or not. If the API encountered an error or there’s an error in the data within the request it is sent to the API. The success field will be set to false and the other fields (ErrorCode, ErrorMessage, InternalErrorMessage) will be provided with the relevant information relating to the nature of the error. In certain circumstances where the request is successful but contains some warning information in the response the HasWarning will be set to true and the message will be provided in the WarningMessage field.

    All requests sent to the API require Content-Type in the header. The following content type is supported by the API

    Authentication (Tracking)

    In order to make API request a Parcelhub Account ID and an Access Code is required to access the API. If you do not have the above information, please request the details from Parcelhub Sales Admin 01159503018.

    End Point - List Shipments

    Request

    <?xml version="1.0" encoding="utf-8" ?>
    <ListShipmentsRequest>
      <Authentication>
        <AccountID>TEST</AccountID>
        <AccessCode>0123456789abcdefghijklmnopqrstuv</AccessCode>
      </Authentication>
      <TransactionMessageID>TEST Transaction Message</TransactionMessageID>
      <FromDate></FromDate>
      <ToDate></ToDate>
    </ListShipmentsRequest>
    

    Response - Success

    <?xml version="1.0" encoding="utf-8"?>
    <ListShipmentsResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <TransactionMessageID>TEST Transaction Message</TransactionMessageID>
      <ServiceResult>
        <Success>true</Success>
        <ErrorCode>0</ErrorCode>
        <ErrorMessage />
        <InternalErrorMessage />
        <HasWarning>false</HasWarning>
        <WarningMessage />
      </ServiceResult>
      <FromDate>2017-02-17</FromDate>
      <ToDate>2017-02-17</ToDate>
      <Shipments>
        <Shipment>
          <ShipmentKey>OTE0Nzg2OA==</ShipmentKey>
          <AccountID>TEST</AccountID>
          <CourierName>Hermes</CourierName>
          <CourierTrackingNumber>3544780616381281</CourierTrackingNumber>
          <EventCategoryID>5</EventCategoryID>
          <EventCategoryDescription>Customer Action</EventCategoryDescription>
          <EventSubCategoryID>32</EventSubCategoryID>
          <EventSubCategoryDescription>Shipment deleted</EventSubCategoryDescription>
          <EventLocation />
          <EventDescription>Shipment Deleted</EventDescription>
          <EventSignatory />
          <EventTimestamp>2017-02-17T11:45:19</EventTimestamp>
          <Longitude>0</Longitude>
          <Latitude>0</Latitude>
          <CourierTrackingEventCode>T2SD</CourierTrackingEventCode>
        </Shipment>
        <Shipment>
          <ShipmentKey>OTE0Nzg4Ng==</ShipmentKey>
          <AccountID>TEST</AccountID>
          <CourierName>Hermes</CourierName>
          <CourierTrackingNumber>3547780636381350</CourierTrackingNumber>
          <EventCategoryID>5</EventCategoryID>
          <EventCategoryDescription>Customer Action</EventCategoryDescription>
          <EventSubCategoryID>32</EventSubCategoryID>
          <EventSubCategoryDescription>Shipment deleted</EventSubCategoryDescription>
          <EventLocation />
          <EventDescription>Shipment Deleted</EventDescription>
          <EventSignatory />
          <EventTimestamp>2017-02-17T11:45:19</EventTimestamp>
          <Longitude>0</Longitude>
          <Latitude>0</Latitude>
          <CourierTrackingEventCode>T2SD</CourierTrackingEventCode>
        </Shipment>
        ...
      </Shipments>
    </ListShipmentsResponse>
    

    Response – Error

    <?xml version="1.0" encoding="utf-8"?>
    <ListShipmentsResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <TransactionMessageID />
      <ServiceResult>
        <Success>false</Success>
        <ErrorCode>200006</ErrorCode>
        <ErrorMessage>Error authenticate request</ErrorMessage>
        <InternalErrorMessage>Error authenticate request</InternalErrorMessage>
        <HasWarning>false</HasWarning>
        <WarningMessage />
      </ServiceResult>
      <Shipments />
    </ListShipmentsResponse>
    

    This end point will list all shipments created by the Parcelhub Account ID along with their last tracking status, either with or without a date range.

    If the date range is not specified in the request, the API will automatically default the date range to 14 days prior to the current date.

    All dates must be formed like: YYYY-MM-DD.

    List Shipment Request Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    ListShipmentsRequest /ListShipmentsRequest Container N/A N/A Root Element
    Authentication /ListShpmentsRequest/Authentication Container N/A N/A Authentication Element
    AccountID /ListShpmentsRequest/Authentication/AccountID String False 50 Parcelhub Account ID
    AccessCode /ListShpmentsRequest/Authentication/AccessCode String False 32 API Access Code
    TransactionMessageID /ListShpmentsRequest/TransactionMessageID String False 100 Message ID to identify request and response
    FromDate /ListShipmentsRequest/FromDate Date True 10 From Date YYYY-MM-DD
    ToDate /ListShipmentsRequest/ToDate Date True 10 To Date YYYY-MM-DD

    List Shipment Response Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    ListShipmentsResponse /ListShipmentsResponse Container N/A N/A XML Root Element
    TransactionMessageID /ListShipmentsResponse/TransactionMessageID String N/A 100 Transaction Message ID specified in request
    ServiceResult /ListShipmentsResponse/ServiceResult Container N/A N/A ServiceResult Container
    Success /ListShipmentsResponse/ServiceResult/Success Boolean False N/A Whether the request was successful
    ErrorCode /ListShipmentsResponse/ServiceResult/ErrorCode Integer False N/A Response Error code
    ErrorMessage /ListShipmentsResponse/ServiceResult/ErrorMessage String False 100 Response Error Message
    HasWarning /ListShipmentsResponse/ServiceResult/HasWarning Boolean False N/A Response contained warning message
    WarningMessage /ListShipmentsResponse/ServiceResult/WarningMessage String False 255 Response warning message only contain message when HasWarning boolean is True
    FromDate /ListShipmentsResponse/FromDate Date True 10 From Date YYYY-MM-DD
    ToDate /ListShipmentsResponse/ToDate Date True 10 To Date YYYY-MM-DD
    Shipments /ListShipmentsResponse/Shipments Container Array N/A N/A XML Array of all shipment
    Shipment /ListShipmentsResponse/Shipments/Shipment Container N/A N/A Shipment container
    AccountID /ListShipmentsResponse/Shipments/Shipment/AccountID String False 50 Parcelhub Account ID
    CourierName /ListShipmentsResponse/Shipments/Shipment/CourierName String False 50 Name of the Courier
    CourierTrackingNumber /ListShipmentsResponse/Shipments/Shipment/CourierTrackingNumber String False 50 Courier Tracking number
    EventCategoryID /ListShipmentsResponse/Shipments/Shipment/EventCategoryID Integer False N/A Event Category
    EventCategoryDescription /ListShipmentsResponse/Shipments/Shipment/EventCategoryDescription String False 50 Description of event category
    EventSubCategoryID /ListShipmentsResponse/Shipments/Shipment/EventSubCategoryID Integer False Event Sub Category ID
    EventSubCategoryDescription /ListShipmentsResponse/Shipments/Shipment/EventSubCategoryDescription String False 50 Description of event sub category
    EventLocation /ListShipmentsResponse/Shipments/Shipment/EventLocation String False 255 Location where the event occurred
    EventDescription /ListShipmentsResponse/Shipments/Shipment/EventDescription String False 255 Tracking event description
    EventSignatory /ListShipmentsResponse/Shipments/Shipment/EventSignatory String False 255 Name of recipient
    EventTimestamp /ListShipmentsResponse/Shipments/Shipment/EventTimestamp DateTime False N/A Timestamp of the tracking event when not initialised default value 0001-01-01 00:00:00
    Longitude /ListShipmentsResponse/Shipments/Shipment/Longitude Float False GPS longitude value (Default value 0 if not used or unavailable)
    Latitude /ListShipmentsResponse/Shipments/Shipment/Latitude Float False GPS Latitude value (Default value 0 if not used or unavailable)
    CourierTrackingEventCode /ListShipmentsResponse/Shipments/Shipment/ CourierTrackingEventCode String False 50 Courier tracking event code

    End Point – Get Latest Tracking Event

    Request

    <?xml version="1.0" encoding="utf-8" ?>
    <GetLatestTrackingEventRequest>
      <Authentication>
        <AccountID>TEST</AccountID>
        <AccessCode>0123456789abcdefghijklmnopqrstuv</AccessCode>
      </Authentication>
      <TransactionMessageID>TEST Transaction Message</TransactionMessageID>
      <TrackingNumbers>
        <TrackingNumber>JD0002254419165667</TrackingNumber>
        <TrackingNumber>JD0002254419165666</TrackingNumber>
        <TrackingNumber>JD0002254419165665</TrackingNumber>
      </TrackingNumbers>
    </GetLatestTrackingEventRequest>
    

    Response

    <?xml version="1.0" encoding="utf-8"?>
    <GetLatestTrackingEventResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <TransactionMessageID>TEST Transaction Message</TransactionMessageID>
      <ServiceResult>
        <Success>true</Success>
        <ErrorCode>0</ErrorCode>
        <ErrorMessage />
        <InternalErrorMessage />
        <HasWarning>false</HasWarning>
        <WarningMessage />
      </ServiceResult>
      <TrackingResult>
        <SearchResult>
          <ShipmentKey>Nzk2MzYwMw==</ShipmentKey>
          <CourierName>Yodel</CourierName>
          <TrackingNumber>JD0002254419165667</TrackingNumber>
          <HasShipmentTracking>false</HasShipmentTracking>
          <ShipmentTracking>
            <EventTimestamp>0001-01-01T00:00:00</EventTimestamp>
            <Longitude>0</Longitude>
            <Latitude>0</Latitude>
          </ShipmentTracking>
          <PackageTrackingEvent>
            <EventCategoryID>1</EventCategoryID>
            <EventCategoryDescription>Delivered</EventCategoryDescription>
            <EventSubCategoryID>1</EventSubCategoryID>
            <EventSubCategoryDescription>Delivered</EventSubCategoryDescription>
            <EventLocation>GATESHEAD HOME DELIVERY</EventLocation>
            <EventDescription>Delivered</EventDescription>
            <EventSignatory>Api Tester</EventSignatory>
            <EventTimestamp>2015-11-03T13:32:01</EventTimestamp>
            <Longitude>0</Longitude>
            <Latitude>0</Latitude>
          <CourierTrackingEventCode>Z</CourierTrackingEventCode>
          </PackageTrackingEvent>
          <Successful>true</Successful>
          <SearchErrorMessage />
        </SearchResult>
        <SearchResult>
          <ShipmentKey>Nzk2MzYwMg==</ShipmentKey>
          <CourierName>Yodel</CourierName>
          <TrackingNumber>JD0002254419165666</TrackingNumber>
          <HasConsignmentLevelTracking>false</HasConsignmentLevelTracking>
          <ShipmentTracking>
            <EventTimestamp>0001-01-01T00:00:00</EventTimestamp>
            <Longitude>0</Longitude>
            <Latitude>0</Latitude>
          </ShipmentTracking>
          <PackageTrackingEvent>
            <EventCategoryID>1</EventCategoryID>
            <EventCategoryDescription>Delivered</EventCategoryDescription>
            <EventSubCategoryID>1</EventSubCategoryID>
            <EventSubCategoryDescription>Delivered</EventSubCategoryDescription>
            <EventLocation>SELBY SERVICE CENTRE</EventLocation>
            <EventDescription>Delivered</EventDescription>
            <EventSignatory>OBRYAN</EventSignatory>
            <EventTimestamp>2015-11-03T15:34:01</EventTimestamp>
            <Longitude>0</Longitude>
            <Latitude>0</Latitude>
          <CourierTrackingEventCode>Z</CourierTrackingEventCode>
          </PackageTrackingEvent>
          <Successful>true</Successful>
          <SearchErrorMessage />
        </SearchResult>
        <SearchResult>
          <ShipmentKey>Nzk2MzYwMQ==</ShipmentKey>
          <CourierName>Yodel</CourierName>
          <TrackingNumber>JD0002254419165665</TrackingNumber>
          <HasConsignmentLevelTracking>false</HasConsignmentLevelTracking>
          <ShipmentLevelTracking>
            <EventTimestamp>0001-01-01T00:00:00</EventTimestamp>
            <Longitude>0</Longitude>
            <Latitude>0</Latitude>
          </ShipmentTracking>
          <PackageTrackingEvent>
            <EventCategoryID>1</EventCategoryID>
            <EventCategoryDescription>Delivered</EventCategoryDescription>
            <EventSubCategoryID>1</EventSubCategoryID>
            <EventSubCategoryDescription>Delivered</EventSubCategoryDescription>
            <EventLocation>GLASGOW SERVICE CENTRE</EventLocation>
            <EventDescription>Delivered</EventDescription>
            <EventSignatory>TESTER</EventSignatory>
            <EventTimestamp>2015-11-04T19:30:01</EventTimestamp>
            <Longitude>0</Longitude>
            <Latitude>0</Latitude>
            <CourierTrackingEventCode>Z</CourierTrackingEventCode>
          </PackageTrackingEvent>
          <Successful>true</Successful>
          <SearchErrorMessage />
        </SearchResult>
      </TrackingResult>
    </GetLatestTrackingEventResponse>
    

    This end point will return the latest tracking events from a list of tracking numbers sent in on the request.

    Get Latest Tracking Event Request Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    GetLatestTrackingEventRequest /GetLatestTrackingEventRequest Container N/A N/A Root Element
    Authentication /GetLatestTrackingEventRequest/Authentication Container N/A N/A Authentication Element
    AccountID /GetLatestTrackingEventRequest/Authentication/AccountID String False 50 Parcelhub Account ID
    AccessCode /GetLatestTrackingEventRequest/Authentication/AccessCode String False 32 API Access Code
    TransactionMessageID /GetLatestTrackingEventRequest/TransactionMessageID String False 100 Message ID to identify request and response
    TrackingNumbers /GetLatestTrackingEventRequest/TrackingNumbers Container Array N/A N/A Array of Tracking numbers
    TrackingNumber /GetLatestTrackingEventRequest/TrackingNumbers/TrackingNumber String False 50 Tracking Number to query

    Get Latest Tracking Event Response Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    GetLatestTrackingEventResponse /GetLatestTrackingEventResponse Container N/A N/A Xml Root Element
    TransactionMessageID /GetLatestTrackingEventResponse/TransactionMessageID String N/A 100 Transaction Message ID specified in request
    ServiceResult /GetLatestTrackingEventResponse/ServiceResult Container N/A N/A ServiceResult Container
    Success /GetLatestTrackingEventResponse/ServiceResult/Success Boolean False N/A Whether the request was successful
    ErrorCode /GetLatestTrackingEventResponse/ServiceResult/ErrorCode Integer False N/A Response Error code
    ErrorMessage /GetLatestTrackingEventResponse/ServiceResult/ErrorMessage String False 100 Response Error Message
    HasWarning /GetLatestTrackingEventResponse/ServiceResult/HasWarning Boolean False N/A Response contained warning message
    WarningMessage /GetLatestTrackingEventResponse/ServiceResult/WarningMessage String False 255 Response warning message only contain message when HasWarning boolean is True
    TrackingResult /GetLatestTrackingEventResponse/TrackingResult Container Array N/A N/A Array of all tracking results
    SearchResult /GetLatestTrackingEventResponse/TrackingResult/SearchResult Container N/A N/A Search Result container
    ShipmentKey /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentKey String False 50 Shipment key
    CourierName /GetLatestTrackingEventResponse/TrackingResult/SearchResult/CourierName String False 50 Name of the courier
    TrackingNumber /GetLatestTrackingEventResponse/TrackingResult/SearchResult/TrackingNumber String False 50 Searched tracking number
    HasShipmentTracking /GetLatestTrackingEventResponse/TrackingResult/SearchResult/HasShipmentTracking Boolean False N/A Determined whether if there’s shipment tracking that courier provides
    ShipmentTrackingEvent /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent Container False N/A Container for latest shipment tracking events
    EventCategoryID /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/EventCategoryID Integer False N/A Event Category
    EventCategoryDescription /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/EventCategoryDescription String False 50 Description of event category
    EventSubCategoryID /GetLatestTrackingEventResponse/TrackingResult/SeearchResult/ShipmentTrackingEvent/EventSubCategoryID Integer False N/A Event Sub Category ID
    EventSubCategoryDescription /GetLatestTrackingEventResponse/TrackingResult/SeearchResult/ShipmentTrackingEvent/EventSubCategoryDescription String False 50 Description of event sub category
    EventLocation /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/EventLocation String False 255 Location where the event occurred
    EventDescription /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/EventDescription String False 255 Tracking event description
    EventSignatory /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/EventSignatory String False 255 Name of recipient
    EventTimestamp /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/EventTimestamp DateTime False N/A Timestamp of the tracking event when not initialised default value 0001-01-01 00:00:00
    Longitude /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/Longitude Float False GPS longitude value (Default value 0 if not used or unavailable)
    Latitude /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/Latitude Float False GPS Latitude value (Default value 0 if not used or unavailable)
    CourierTrackingEventCode /GetLatestTrackingEventResponse/TrackingResult/SearchResult/ShipmentTrackingEvent/CourierTrackingEventCode String False 50 Courier Tracking Status Code
    PackageTrackingEvent /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent Container False N/A Container for latest package tracking events
    EventCategoryID /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/EventCategoryID Integer False N/A Event Category
    EventCategoryDescription /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/EventCategoryDescription String False 50 Description of event category
    EventSubCategoryID /GetLatestTrackingEventResponse/TrackingResult/SeearchResult/PackageTrackingEvent/EventSubCategoryID Integer False N/A Event Sub Category ID
    EventSubCategoryDescription /GetLatestTrackingEventResponse/TrackingResult/SeearchResult/PackageTrackingEvent/EventSubCategoryDescription String False 50 Description of event sub category
    EventLocation /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/EventLocation String False 255 Location where the event occurred
    EventDescription /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/EventDescription String False 255 Tracking event description
    EventSignatory /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/EventSignatory String False 255 Name of recipient
    EventTimestamp /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/EventTimestamp DateTime False N/A Timestamp of the tracking event when not initialised default value 0001-01-01 00:00:00
    Longitude /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/Longitude Float False N/A GPS longitude value (Default value 0 if not used or unavailable)
    Latitude /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/Latitude Float False N/A GPS Latitude value (Default value 0 if not used or unavailable)
    CourierTrackingEventCode /GetLatestTrackingEventResponse/TrackingResult/SearchResult/PackageTrackingEvent/CourierTrackingEventCode String False 50 Courier tracking event code
    Success /GetLatestTrackingEventResponse/TrackingResult/SearchResult/Success Boolean False N/A Whether the search was successful
    SearchErrorMessage /GetLatestTrackingEventResponse/TrackingResult/SearchResult/SearchErrorMessage String False 255 Search error message if Success is false

    End Point – Get Tracking History

    Request

    <?xml version="1.0" encoding="UTF-8"?>
    <GetTrackingHistoryRequest>
        <Authentication>
            <AccountID>TEST</AccountID>
            <AccessCode>0123456789abcdefghijklmnopqrstuv</AccessCode>
        </Authentication>
        <TransactionMessageID>TEST Transaction
    Message</TransactionMessageID>
        <SearchType>ByTrackingNumber</SearchType>
        <SearchTerm>JD0002235399161670</SearchTerm>
    </GetTrackingHistoryRequest>
    

    Response

    <?xml version="1.0" encoding="UTF-8"?>
    <GetTrackingHistoryResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <TransactionMessageID>TEST Transaction Message</TransactionMessageID>
        <ServiceResult>
            <Success>true</Success>
            <ErrorCode>0</ErrorCode>
            <ErrorMessage />
            <InternalErrorMessage />
            <HasWarning>false</HasWarning>
            <WarningMessage />
        </ServiceResult>
        <ShipmentKey>NjM0MTkwMA==</ShipmentKey>
        <CourierName>Yodel</CourierName>
        <TrackingNumber>JD0002235399161670</TrackingNumber>
        <HasShipmentTracking>false</HasShipmentTracking>
        <ShipmentTrackingEvents />
        <Packages>
            <Package>
                <TrackingNumber>JD0002235399161670</TrackingNumber>
                <PackageTrackingEvents>
                    <TrackingEvent>
                        <EventCategoryID>5</EventCategoryID>
                        <EventCategoryDescription>Customer Action</EventCategoryDescription>
                        <EventSubCategoryID>32</EventSubCategoryID>
                        <EventSubCategoryDescription>Shipment deleted</EventSubCategoryDescription>
                        <EventLocation />
                        <EventDescription>Shipment Deleted</EventDescription>
                        <EventSignatory />
                        <EventTimestamp>2015-04-13T14:53:15</EventTimestamp>
                        <Longitude>0</Longitude>
                        <Latitude>0</Latitude>
                        <CourierTrackingEventCode>T2SD</CourierTrackingEventCode>
                    </TrackingEvent>
                    <TrackingEvent>
                        <EventCategoryID>7</EventCategoryID>
                        <EventCategoryDescription>Information</EventCategoryDescription>
                        <EventSubCategoryID>54</EventSubCategoryID>
                        <EventSubCategoryDescription>Shipment Created</EventSubCategoryDescription>
                        <EventLocation />
                        <EventDescription>Shipment Created</EventDescription>
                        <EventSignatory />
                        <EventTimestamp>2015-04-13T14:52:54</EventTimestamp>
                        <Longitude>0</Longitude>
                        <Latitude>0</Latitude>
                        <CourierTrackingEventCode>T2SC</CourierTrackingEventCode>
                    </TrackingEvent>
                </PackageTrackingEvents>
            </Package>
        </Packages>
    </GetTrackingHistoryResponse>
    

    This end point will return the full tracking history for a shipment by either using the Shipment Key in the response from ListShipments or GetLatestTrackingEvent end points. Alternatively you can use a tracking number as the search term.

    Get Tracking History Request Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    GetTrackingHistoryRequest /GetTrackingHistoryRequest Container N/A N/A Root Element
    Authentication /GetTrackingHistoryRequest/Authentication Container N/A N/A Authentication Element
    AccountID /GetTrackingHistoryRequest/Authentication/AccountID String False 50 Parcelhub Account ID
    AccessCode /GetTrackingHistoryRequest/Authentication/AccessCode String False 32 API Access Code
    TransactionMessageID /GetTrackingHistoryRequest/TransactionMessageID String False 100 Message ID to identify request and response
    SearchType /GetTrackingHistoryRequest /SearchType String N/A N/A The type of search to perform to get the complete tracking history Use either ‘ByTrackingNumber’ or ‘ByShipmentKey’
    SearchTerm /GetTrackingHistoryRequest/SearchTerm String False 50 Search term to get full tracking history

    Get Tracking History Response Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    GetTrackingHistoryResponse /GetTrackingHistoryResponse Container N/A N/A Xml Root Element
    TransactionMessageID /GetTrackingHistoryResponse/TransactionMessageID String N/A 100 Transaction Message ID specified in request
    ServiceResult /GetTrackingHistoryResponse/ServiceResult Container N/A N/A ServiceResult Container
    Success /GetTrackingHistoryResponse/ServiceResult/Success Boolean False N/A Whether the request was successful
    ErrorCode /GetTrackingHistoryResponse/ServiceResult/ErrorCode Integer False N/A Response Error code
    ErrorMessage /GetTrackingHistoryResponse/ServiceResult/ErrorMessage String False 100 Response Error Message
    HasWarning /GetTrackingHistoryResponse/ServiceResult/HasWarning Boolean False N/A Response contained warning message
    WarningMessage /GetTrackingHistoryResponse/ServiceResult/WarningMessage String False 255 Response warning message only contain message when HasWarning boolean is True
    ShipmentKey /GetTrackingHistoryResponse/ShipmentKey String False 50 Shipment key
    CourierName /GetTrackingHistoryResponse/CourierName String False 50 Name of the courier
    TrackingNumber /GetTrackingHistoryResponse/TrackingNumber String False 50 Searched tracking number
    HasShipmentTracking /GetTrackingHistoryResponse/HasShipmentTracking Boolean False N/A Determined whether if there’s shipment tracking that courier provides
    ShipmentTrackingEvents /GetTrackingHistoryResponse/ShipmentTrackingEvents Container Array False N/A Container array for list of shipment tracking events
    TrackingEvent /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent Container False N/A Tracking event container
    EventCategoryID /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventCategoryID Integer False N/A Event Category
    EventCategoryDescription /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventCategoryDescription String False 50 Description of event category
    EventSubCategoryID /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventSubCategoryID Integer False N/A Event Sub Category ID
    EventSubCategoryDescription /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventSubCategoryDescription String False 50 Description of event sub category
    EventLocation /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventLocation String False 255 Location where the event occurred
    EventDescription /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventDescription String False 255 Tracking event description
    EventSignatory /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventSignatory String False 255 Name of recipient
    EventTimestamp /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/EventTimestamp DateTime False N/A Timestamp of the tracking event when not initialised default value 0001-01-01 00:00:00
    Longitude /GetTrackingHistoryResponse/ShipmentTrackingEvents/TrackingEvent/Longitude Float False GPS longitude value (Default value 0 if not used or unavailable)
    Latitude /GetTrackingHistoryResponse/ShipmentLevelTrackingEvents/TrackingEvent/Latitude Float False GPS Latitude value (Default value 0 if not used or unavailable)
    CourierTrackingEventCode /GetTrackingHistoryResponse/ShipmentLevelTrackingEvents/TrackingEvent/CourierTrackingEventCode String False 50 Courier tracking event code
    Packages /GetTrackingHistoryResponse/Packages Container Array False N/A Package container array. If more than 1 package in the shipment then there would be multiple packages in the array
    Package /GetTrackingHistoryResponse/Packages/Package Container False N/A Container for package tracking information.
    TrackingNumber /GetTrackingHistoryResponse/Packages/Package/TrackingNumber String False 50 Package tracking number
    PackageTrackingEvents /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents Container Array False N/A Container for latest package tracking events
    TrackingEvent /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent Container False N/A Tracking event container
    EventCategoryID /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventCategoryID Integer False N/A Event Category
    EventCategoryDescription /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventCategoryDescription String False 50 Description of event category
    EventSubCategoryID /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventSubCategoryID Integer False N/A Event Sub Category ID
    EventSubCategoryDescription /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventSubCategoryDescription String False 50 Description of event sub category
    EventLocation /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventLocation String False 255 Location where the event occurred
    EventDescription /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventDescription String False 255 Tracking event description
    EventSignatory /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventSignatory String False 255 Name of recipient
    EventTimestamp /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/EventTimestamp DateTime False N/A Timestamp of the tracking event when not initialised default value 0001-01-01 00:00:00
    Longitude /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/Longitude Float False N/A GPS longitude value (Default value 0 if not used or unavailable)
    Latitude /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent/Latitude Float False N/A GPS Latitude value (Default value 0 if not used or unavailable)
    CourierTrackingEventCode /GetTrackingHistoryResponse/Packages/Package/PackageTrackingEvents/TrackingEvent//CourierTrackingEventCode String False 50 Courier tracking event code

    End Point – Search Shipment

    This end point allows you to search shipments when a match has found on the below list.

    The supported field this end point can search with are:

    Request

    <?xml version="1.0" encoding="UTF-8"?>
    <SearchShipmentRequest>
        <Authentication>
            <AccountID>TEST</AccountID>
            <AccessCode>0123456789abcdefghijklmnopqrstuv</AccessCode>
        </Authentication>
        <TransactionMessageID />
        <SearchTerm>TEST</SearchTerm>
    </SearchShipmentRequest>
    

    Response

    <?xml version="1.0" encoding="UTF-8"?>
    <SearchShipmentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <TransactionMessageID />
        <ServiceResult>
            <Success>true</Success>
            <ErrorCode>0</ErrorCode>
            <ErrorMessage />
            <InternalErrorMessage />
            <HasWarning>false</HasWarning>
            <WarningMessage />
        </ServiceResult>
        <Shipments>
            <Shipment>
                <ShipmentKey>MTI2OTA2NTQ=</ShipmentKey>
                <AccountID>TEST</AccountID>
                <CourierName>Yodel</CourierName>
                <CourierTrackingNumber>JD0002200000000001</CourierTrackingNumber>
                <DeliveryPostcode>NG1 1AA</DeliveryPostcode>
                <Reference1>TEST</Reference1>
                <Reference2>TESTING REF 2</Reference2>
                <Deleted>false</Deleted>
                <EventCategoryID>7</EventCategoryID>
                <EventCategoryDescription>Information</EventCategoryDescription>
                <EventSubCategoryID>54</EventSubCategoryID>
                <EventSubCategoryDescription>Shipment Created</EventSubCategoryDescription>
                <EventLocation />
                <EventDescription>Shipment Created</EventDescription>
                <EventSignatory />
                <EventTimestamp>2016-12-07T00:40:19</EventTimestamp>
                <Longitude>0</Longitude>
                <Latitude>0</Latitude>
                <CourierTrackingEventCode>T2SC</CourierTrackingEventCode>
            </Shipment>
        </Shipments>
    </SearchShipmentResponse>
    

    Search Shipment Request Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    SearchShipmentRequest /SearchShipmentRequest Container N/A N/A Root Element
    Authentication / SearchShipmentRequest/Authentication Container N/A N/A Authentication Element
    AccountID /SearchShipmentRequest/Authentication/AccountID String False 50 Parcelhub Account ID
    AccessCode /SearchShipmentRequest/Authentication/AccessCode String False 32 API Access Code
    TransactionMessageID /SearchShipmentRequest/TransactionMessageID String False 100 Message ID to identify request and response
    SearchTerm /SearchShipmentRequest/SearchTerm String False 50 Search term to get full tracking history

    Search Shipment Response Data Type

    Elements XPath Type Allow Null Max Length Descriptions Validation Rule
    SearchShipmentResponse /SearchShipmentResponse Container N/A N/A Xml Root Element
    TransactionMessageID /SearchShipmentResponse/TransactionMessageID String N/A 100 Transaction Message ID specified in request
    ServiceResult /SearchShipmentResponse/ServiceResult Container N/A N/A ServiceResult Container
    Success /SearchShipmentResponse/ServiceResult/Success Boolean False N/A Whether the request was successful
    ErrorCode /SearchShipmentResponse/ServiceResult/ErrorCode Integer False N/A Response Error code
    ErrorMessage /SearchShipmentResponse/ServiceResult/ErrorMessage String False 100 Response Error Message
    HasWarning /SearchShipmentResponse/ServiceResult/HasWarning Boolean False N/A Response contained warning message
    WarningMessage /SearchShipmentResponse/ServiceResult/WarningMessage String False 255 Response warning message only contain message when HasWarning boolean is True
    Shipments /SearchShipmentResponse/Shipments Container Array N/A N/A Array of all Shipment
    Shipment /SearchShipmentResponse/Shipments/Shipment Container N/A N/A Shipment Container
    ShipmentKey /SearchShipmentResponse/Shipments/Shipment/ShipmentKey String False 50 Shipment key
    CourierName /SearchShipmentResponse/Shipments/Shipment/CourierName String False 50 Name of the courier
    TrackingNumber /SearchShipmentResponse/Shipments/Shipment/TrackingNumber String False 50 Searched tracking number
    DeliveryPostcode /SearchShipmentResponse/Shipments/Shipment/DeliveryPostcode String False 50 Delivery Postcode
    Reference1 /SearchShipmentResponse/Shipments/Shipment/Reference1 String False 50 Shipment Sender’s Reference
    Reference2 /SearchShipmentResponse/Shipments/Shipment/Reference2 String False 50 Shipment Receiver’s Reference
    Deleted /SearchShipmentResponse/Shipments/Shipment/Deleted Boolean False Whether if the shipment is Deleted
    EventCategoryID /SearchShipmentResponse/Shipments/Shipment/EventCategoryID Integer False N/A Event Category
    EventCategoryDescription /SearchShipmentResponse/Shipments/Shipment/EventCategoryDescription String False 50 Description of event category
    EventSubCategoryID /SearchShipmentResponse/Shipments/Shipment/EventSubCategoryID Integer False N/A Event Sub Category ID
    EventSubCategoryDescription /SearchShipmentResponse/Shipments/Shipment/EventSubCategoryDescription String False 50 Description of event sub category
    EventLocation /SearchShipmentResponse/Shipments/Shipment/EventLocation String False 255 Location where the event occurred
    EventDescription /SearchShipmentResponse/Shipments/Shipment/EventDescription String False 255 Tracking event description
    EventSignatory /SearchShipmentResponse/Shipments/Shipment/EventSignatory String False 255 Name of recipient
    EventTimestamp /SearchShipmentResponse/Shipments/Shipment/EventTimestamp DateTime False N/A Timestamp of the tracking event when not initialised default value 0001-01-01 00:00:00
    Longitude /SearchShipmentResponse/Shipments/Shipment/Longitude Float False GPS longitude value (Default value 0 if not used or unavailable)
    Latitude /SearchShipmentResponse/Shipments/Shipment/Latitude Float False GPS Latitude value (Default value 0 if not used or unavailable)
    CourierTrackingEventCode /SearchShipmentResponse/Shipments/Shipment/CourierTrackingEventCode String False 50 Courier tracking event code

    Appendix A – Event Category ID

    Event Category ID Category Name
    1 Delivered
    2 Delayed
    3 In-Transit
    4 Problem
    5 Customer Action
    7 Information
    8 Advised to claim

    Appendix B – Sub Event Category ID

    Sub Event Category ID Sub Category Description Sub Event Category ID Sub Category Description
    1 Delivered 66 Disputed Delivery
    2 With POD 67 Loss
    3 No POD 68 Damage
    4 Left with Neighbour 69 Non-Compliance
    5 Left in a safe place 70 Carriage
    6 Customer collected 71 Claim Submitted
    7 Delayed 73 Processed At Hub
    8 No-one to receive 74 Collected From Customer
    9 Adverse weather 75 Return Processed At Hub
    10 Awaiting instruction
    11 Awaiting booking-in date
    12 Recipient will collect
    13 In transit
    14 Collected
    15 Arrived at collection depot
    16 Arrived at delivery depot
    17 Out for delivery
    18 Released to third party
    19 Resealed
    20 Problem
    21 Bad Address
    22 Item damaged
    23 Item hazardous
    24 Item prohibited
    25 Item overweight
    26 Item oversized
    27 Invalid Service
    28 Held by customs
    29 Recipient not known
    30 Refused
    31 Customer Action
    32 Shipment deleted
    33 Reroute requested
    34 Recall requested
    35 POD requested
    36 Claim submitted
    46 Information
    47 Delivered col. point
    48 Returned to sender
    50 Tracking Status Overdue
    53 Processed at hub
    54 Shipment Created
    55 Shipment Deleted
    59 Part Delivered
    60 Collection Failed
    65 Assigned to Customer Services

    API Store Locker Locator

    Overview

    The store locker locator endpoint provides a list of publicly available locations to which you can deliver parcels. This allows your customers to choose a convenient location for delivery where their normal address may not be.

    After calling the store locker locator endpoint, you can select the store where you want to deliver and then create a shipment using those details provided.

    Endpoint and Data

    Store Locker Locator Request

    https://api.test.parcelhub.net/1.0/StoreLockerLocator
    Accept: */*
    username: TEST001
    Accept-Encoding: gzip, deflate
    Authorization: bearer [TOKEN GOES HERE]
    Content-Type: application/xml; charset=utf-8
    
    <StoreLockerLocatorRequest xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
    <Account>TEST001</Account>
    <Postcode>NG2 4EL</Postcode>
    </StoreLockerLocatorRequest>
    

    Use the following endpoints to call the store locker locator:

    Environment Address
    TEST https://api.test.parcelhub.net/1.0/StoreLockerLocator
    LIVE https://api.parcelhub.net/1.0/StoreLockerLocator

    As with other API requests, you must provide a username and authorization token in the header. The body should contain your account ID and the postcode where a customer wants their shipment to be delivered.

    Handling Responses

    Store Locker Locator Response

    <StoreLockerLocatorResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <StoreLockerLocatorList>
            <StoreLockerLocation>
                <ServiceProviderID>9</ServiceProviderID>
                <ServiceProviderName>Hermes</ServiceProviderName>
                <StoreLockerID>S02696</StoreLockerID>
                <Postcode>NG2 5BX</Postcode>
                <MapUrl />
                <CompanyName>N &amp; S LIFESTYLE EXPRESS - NG2 5B</CompanyName>
                <AddressLine1>165 Trent Boulevard</AddressLine1>
                <AddressLine2 />
                <PostTownCity>West Brigford</PostTownCity>
                <Area />
                <CountryCode>GB</CountryCode>
                <Longitude>-1.116618</Longitude>
                <Latitude>52.93832</Latitude>
                <Distance>0</Distance>
                <HasOpeningHours>true</HasOpeningHours>
                <OpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Sunday</DayOfWeek>
                        <TimeOpen>09:00</TimeOpen>
                        <TimeClose>21:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Monday</DayOfWeek>
                        <TimeOpen>09:00</TimeOpen>
                        <TimeClose>21:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Tuesday</DayOfWeek>
                        <TimeOpen>09:00</TimeOpen>
                        <TimeClose>21:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Wednesday</DayOfWeek>
                        <TimeOpen>09:00</TimeOpen>
                        <TimeClose>21:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Thursday</DayOfWeek>
                        <TimeOpen>09:00</TimeOpen>
                        <TimeClose>21:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Friday</DayOfWeek>
                        <TimeOpen>09:00</TimeOpen>
                        <TimeClose>22:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Saturday</DayOfWeek>
                        <TimeOpen>09:00</TimeOpen>
                        <TimeClose>22:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                </OpeningHours>
                <AdditionalLocation1 />
                <AdditionalLocation2 />
                <AdditionalLocation3 />
            </StoreLockerLocation>
            <StoreLockerLocation>
                <ServiceProviderID>9</ServiceProviderID>
                <ServiceProviderName>Hermes</ServiceProviderName>
                <StoreLockerID>S32686</StoreLockerID>
                <Postcode>NG2 4HU</Postcode>
                <MapUrl />
                <CompanyName>BEST ONE</CompanyName>
                <AddressLine1>197 Sneinton Dale</AddressLine1>
                <AddressLine2 />
                <PostTownCity>Nottingham</PostTownCity>
                <Area />
                <CountryCode>GB</CountryCode>
                <Longitude>-1.121553</Longitude>
                <Latitude>52.954792</Latitude>
                <Distance>0</Distance>
                <HasOpeningHours>true</HasOpeningHours>
                <OpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Sunday</DayOfWeek>
                        <TimeOpen>00:00</TimeOpen>
                        <TimeClose>00:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Monday</DayOfWeek>
                        <TimeOpen>08:00</TimeOpen>
                        <TimeClose>19:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Tuesday</DayOfWeek>
                        <TimeOpen>08:00</TimeOpen>
                        <TimeClose>19:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Wednesday</DayOfWeek>
                        <TimeOpen>08:00</TimeOpen>
                        <TimeClose>19:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Thursday</DayOfWeek>
                        <TimeOpen>08:00</TimeOpen>
                        <TimeClose>19:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Friday</DayOfWeek>
                        <TimeOpen>08:00</TimeOpen>
                        <TimeClose>19:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                    <StoreLockerOpeningHours>
                        <DayOfWeek>Saturday</DayOfWeek>
                        <TimeOpen>08:30</TimeOpen>
                        <TimeClose>19:00</TimeClose>
                        <TimeCloseForLunch />
                        <TimeOpenAfterLunch />
                    </StoreLockerOpeningHours>
                </OpeningHours>
                <AdditionalLocation1 />
                <AdditionalLocation2 />
                <AdditionalLocation3 />
            </StoreLockerLocation>
        </StoreLockerLocatorList>
        <ServiceProviderWarnings />
    </StoreLockerLocatorResponse>
    

    After sending your request, you will receive a store locker locator response. This is a list of locations that you can deliver to based on the services available to your account and the postcode you have sent in your request. Locations are ordered by distance from the postcode provided.

    The important parts of this list are the the address, store location ID and service provider id as we will use these properties to create a shipment.

    Getting Services

    Get Service Request

    Accept: */*
    username: TEST001
    Accept-Encoding: gzip, deflate
    Authorization: bearer [TOKEN GOES HERE]
    Content-Type: application/xml; charset=utf-8
    
    <Shipment
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Account>TEST001</Account>
        <CollectionDetails>
            <CollectionDate>2018-07-16</CollectionDate>
            <CollectionReadyTime>12:00:00</CollectionReadyTime>
            <LocationCloseTime>17:00:00</LocationCloseTime>
        </CollectionDetails>
        <DeliverToStoreOrLockerID>S32686</DeliverToStoreOrLockerID>
        <CollectionAddress>
            <ContactName>Mr Api Tester</ContactName>
            <CompanyName>API Test Company</CompanyName>
            <Email>Api@apitestco.com</Email>
            <Phone>07777777777</Phone>
            <Address1>108 Test Road</Address1>
            <Address2>Apiville</Address2>
            <City>Nottingham</City>
            <Postcode>NG1 1AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </CollectionAddress>
      <DeliveryAddress>
        <ContactName>Mr Api Tester</ContactName>
        <CompanyName>PARCELHUB LTD</CompanyName>
        <Email>Api@apitestco.com</Email>
        <Phone>07777777777</Phone>
        <Address1>18 LITTLE TENNIS STREET</Address1>
        <Address2/>
        <City>NOTTINGHAM</City>
        <Postcode>NG2 4EL</Postcode>
        <Country>GB</Country>
        <AddressType>Residential</AddressType>
      </DeliveryAddress>
        <Reference1>Test</Reference1>
        <Reference2>Test2</Reference2>
        <ContentsDescription>Fruit</ContentsDescription>
        <Packages>
            <Package>
                <PackageType>Parcel</PackageType>
                <Dimensions>
                    <Length>10</Length>
                    <Width>10</Width>
                    <Height>10</Height>
                </Dimensions>
                <Weight>2</Weight>
                <Value Currency="GBP">5
                </Value>
                <Contents>Bananas</Contents>
            </Package>
        </Packages>
        <Enhancements />
        <ShipmentTags />
    </Shipment>
    

    Now that you have your list of locations you can begin creating your shipment. When delivering to a store you will need to include customer's address and not the store address as the delivery address.

    In this example we are sending via Hermes who require the store address to be the delivery address.

    In the previous step, you should have selected a store locker location with a corresponding ID. In this example we will use details from the second item in the list from our response:

    <ServiceProviderID>9</ServiceProviderID>
    <ServiceProviderName>Hermes</ServiceProviderName>
    <StoreLockerID>S32686</StoreLockerID>

    POST these details in your body to the service endpoint as shown on the right. Since we already have our service provider ID, we can send this via url parameter to only recieve a response for the correct service provider.

    http://api.test.parcelhub.net/1.0/Service?RequestedServiceProviderId=9

    As always, your service response will give a detailed list of service options to create a shipment with.

    Creating a Shipment

    Create Shipment Request

    <Shipment
        xmlns="http://api.parcelhub.net/schemas/api/parcelhub-api-v0.4.xsd">
        <Account>TEST001</Account>
        <ServiceInfo>
        <ServiceId>5022</ServiceId>
        <ServiceCustomerUID>2167</ServiceCustomerUID>
        <ServiceProviderId>9</ServiceProviderId>
      </ServiceInfo>
        <DeliverToStoreOrLockerID>S32686</DeliverToStoreOrLockerID>
        <CollectionDetails>
            <CollectionDate>2018-07-16</CollectionDate>
            <CollectionReadyTime>12:00:00</CollectionReadyTime>
            <LocationCloseTime>17:00:00</LocationCloseTime>
        </CollectionDetails>
        <CollectionAddress>
            <ContactName>Mr Api Tester</ContactName>
            <CompanyName>API Test Company</CompanyName>
            <Email>Api@apitestco.com</Email>
            <Phone>07777777777</Phone>
            <Address1>108 Test Road</Address1>
            <Address2>Apiville</Address2>
            <City>Nottingham</City>
            <Postcode>NG1 1AA</Postcode>
            <Country>GB</Country>
            <AddressType>Residential</AddressType>
        </CollectionAddress>
        <DeliveryAddress>
          <ContactName>Mr Api Tester</ContactName>
          <CompanyName>PARCELHUB LTD</CompanyName>
          <Email>Api@apitestco.com</Email>
          <Phone>07777777777</Phone>
          <Address1>18 LITTLE TENNIS STREET</Address1>
          <Address2/>
          <City>NOTTINGHAM</City>
          <Postcode>NG2 4EL</Postcode>
          <Country>GB</Country>
          <AddressType>Residential</AddressType>
        </DeliveryAddress>
        <Reference1>Test</Reference1>
        <Reference2>Test2</Reference2>
        <ContentsDescription>Fruit</ContentsDescription>
        <Packages>
            <Package>
                <PackageType>Parcel</PackageType>
                <Dimensions>
                    <Length>10</Length>
                    <Width>10</Width>
                    <Height>10</Height>
                </Dimensions>
                <Weight>2</Weight>
                <Value Currency="GBP">5
                </Value>
                <Contents>Bananas</Contents>
            </Package>
        </Packages>
        <Enhancements />
        <ShipmentTags />
    </Shipment>
    

    In your get service response once you should have several varying services available to you. For store delivery you should choose a service with the following property:

    <ServiceDescription>Deliver to Shop</ServiceDescription>

    Further to this, you should take note of the following properties to insert into your create shipment request:

    <ServiceIds>
    <ServiceId>5022</ServiceId>
    <ServiceCustomerUID>2163</ServiceCustomerUID>
    <ServiceProviderId>9</ServiceProviderId>
    </ServiceIds>
    <LabelSpec>
    <LabelSize>8</LabelSize>
    <LabelFormat>ZPL</LabelFormat>
    </LabelSpec>

    You can now create a shipment as normal with some small changes. You will need your store locker ID from our Store Locker Locator response. This should be posted along with the rest of your request body with the following xml tags:

    <DeliverToStoreOrLockerID>S02696<DeliverToStoreOrLockerID/>

    Finally, you will need to POST to the normal create shipment endpoint with your selected label size and format:

    http://api.test.parcelhub.net/1.0/Shipment?RequestedLabelSize=8&RequestedLabelFormat=ZPL

    With the above information, you can now construct a create shipment request as demonstrated on the right.

    XML