Parcel Monkey - Developer Information

Introduction

This page contains documentation (and examples) defining how you can interact with the Parcel Monkey API v3 to get quotes and book shipments.

This is a RESTful API that accepts JSON payloads and and synchronously replies with JSON responses. You must always include a Version Header with every request and some endpoints require Authentication Headers too. If successful the API will respond with a 200 HTTP Response Code. If there is an error you will receive a different HTTP Response Code (eg. 400 Bad Request) and an error message.

Endpoints
API Version Header
Authentication Headers

Service: HelloWorld
Service: GetQuote
Service: CreateShipment
Service: CancelShipment
Service: GetTrackingEvents
Service: GetPaymentLink

Endpoints

The root endpoint for all requests is:

https://api.parcelmonkey.co.uk

You then append the service endpoint for the fully qualified URL, for example, the URL for the 'HelloWorld' service would be:

https://api.parcelmonkey.co.uk/HelloWorld

API Version Header

You must always pass a header with the version of the API you are using.

Header	Example
apiversion	3.1

Authentication Headers

Services with the icon displayed require you to be authenticated to use them. In order to authenticate you need to obtain your API credentials from https://www.parcelmonkey.co.uk/apiSettings.php. You then pass the API key as an additional header.

Header	Example
userid	{Your User ID}
token	{Your API Key}

HelloWorld

You can use this service to test your connectivity with the API. You can (optionally) pass in a string that the server will send back to you. You do not need to authenticate to use this endpoint.

POST

/HelloWorld

Request Parameter	Mandatory	Description
echo	No	Test123

Example Request

{
    "echo": "Test123"
}

Example Response

{
    "hello": "Success!",
    "echo": "Test123"
}

Back to the top

GetQuote

This service returns a list of quotes for services suitable for the parcel parameters you specify in the request.

POST

/GetQuote

Request Parameter	Mandatory	Description
origin	Yes	ISO Country Code of origin Country. eg. "GB"
destination	Yes	ISO Country Code of destination Country. eg. "US"
boxes	Yes	Array of parcels and their dimensions
boxes.length	Yes	Length in CM of this box
boxes.width	Yes	Width in CM of this box
boxes.height	Yes	Height in CM of this box
boxes.weight	Yes	Weight in KG of this box
goods_value	Yes	Value of the consignment in GBP
collection_date	No	Collection date (for collected services). Optional but recommended.
sender	Yes	Details of the sender.
sender.name	Yes	Name of the sender.
sender.phone	No	Phone number of the sender.
sender.email	No	Email address of the sender.
sender.address1	Yes	Address Line 1 of the sender.
sender.address2	No	Address Line 2 of the sender.
sender.address3	No	Address Line 3 of the sender.
sender.town	Yes	Address Town of the sender.
sender.county	Yes	Address County of the sender.
sender.postcode	Yes	Address Postcode of the sender.
recpient	Yes	Details of the recpient.
recpient.name	Yes	Name of the recpient.
recpient.phone	No	Phone number of the recpient.
recpient.email	No	Email address of the recpient.
recpient.address1	Yes	Address Line 1 of the recpient.
recpient.address2	No	Address Line 2 of the recpient.
recpient.address3	No	Address Line 3 of the recpient.
recpient.town	Yes	Address Town of the recpient.
recpient.county	Yes	Address County of the recpient.
recpient.postcode	Yes	Address Postcode of the recpient.

Example Request

{
    "origin": "GB",
    "destination": "US",
    "boxes": [
        {
            "length": 10,
            "width": 10,
            "height": 10,
            "weight": 1
        }
    ],
    "goods_value": 150,
    "sender": {
        "name": "Rich",
        "phone": "01234567890",
        "address1": "Unit 21 Tollgate",
        "town": "Eastleigh",
        "county": "Greater Manchester",
        "postcode": "SO53 3TG"
    },
    "recipient": {
        "name": "Nicola",
        "phone": "01234567890",
        "email": "[email protected]",
        "address1": "Hilton Midtown",
        "address2": "1335 6th Avenue",
        "town": "New York",
        "county": "NY",
        "postcode": "10019"
    }
}

Example Response

[
    {
        "service": "international_asendiayodel",
        "carrier": "Asendia",
        "service_name": "Worldwide Parcels",
        "service_description": "Delivery in 8-11 days.",
        "customs_invoice_required": true,
        "shipping_price_net": "19.00",
        "protection_price_net": 1.79,
        "total_price_net": "20.79",
        "total_price_gross": "20.79"
    },
    {
        "service": "international_pmair",
        "carrier": "Parcel Monkey",
        "service_name": "Air Express",
        "service_description": "Delivery by Air in 2-3 days.",
        "customs_invoice_required": true,
        "shipping_price_net": "27.32",
        "protection_price_net": 1.79,
        "total_price_net": "29.11",
        "total_price_gross": "29.11"
    }
]

Back to the top

CreateShipment

This service creates a shipment and puts it in your Parcel Monkey basket.

Required fields vary between different services.

In instances where customs documentation needs to be generated you will need to pass details for that too - this is noted in the quote response with the parameter customs_invoice_required.

You will receive back a ShipmentId reference for your parcel, and URLs for the label and tracking. Labels may take up to 30 minutes to be available - the label URL will return a HTTP response code of 200 when the label is available and 404 if it is not yet available. We recommend polling for labels a maximum of once every 5 minutes.

POST

/CreateShipment

Request Parameter	Mandatory	Description
service	Yes	Service Code from the list of quotes obtained with GetQuote service
origin	Yes	ISO Country Code of origin Country. eg. "GB"
destination	Yes	ISO Country Code of destination Country. eg. "US"
boxes	Yes	Array of parcels and their dimensions
boxes.length	Yes	Length in CM of this box
boxes.width	Yes	Width in CM of this box
boxes.height	Yes	Height in CM of this box
boxes.weight	Yes	Weight in KG of this box
goods_value	Yes	Value of the consignment in GBP
goods_description	Yes	Description of the contents of the parcel
delivery_notes	No	A text note for the delivery driver
collection_date	Yes	Collection date (for collected services). Optional but recommended.
sender	Yes	Details of the sender.
sender.name	Yes	Name of the sender.
sender.phone	No	Phone number of the sender.
sender.email	No	Email address of the sender.
sender.address1	Yes	Address Line 1 of the sender.
sender.address2	No	Address Line 2 of the sender.
sender.address3	No	Address Line 3 of the sender.
sender.town	Yes	Address Town of the sender.
sender.county	Yes	Address County of the sender.
sender.postcode	Yes	Address Postcode of the sender.
recpient	Yes	Details of the recpient.
recpient.name	Yes	Name of the recpient.
recpient.phone	No	Phone number of the recpient.
recpient.email	Sometimes	Email address of the recpient.
recpient.address1	Yes	Address Line 1 of the recpient.
recpient.address2	No	Address Line 2 of the recpient.
recpient.address3	No	Address Line 3 of the recpient.
recpient.town	Yes	Address Town of the recpient.
recpient.county	Yes	Address County of the recpient.
recpient.postcode	Yes	Address Postcode of the recpient.
customs	Sometimes	Include below parameters for services with customs_invoice_required = true.
customs.doc_type	Yes (dependent)	Type of customs document (proforma, commercial).
customs.reason	Yes (dependent)	Reason for export (Sold, Gift, Sample, Repair, Documents, Intra Company Transfer, Temporary Export, Return, Personal Effects).
customs.sender_name	Yes (dependent)	Senders name (can be a company name).
customs.sender_tax_reference	Yes (dependent)	Senders tax reference ("Private Individual" or VAT number).
customs.recipient_name	Yes (dependent)	Recipient name (can be a company name).
customs.recipient_tax_reference	Yes (dependent)	Recipient tax reference ("Private Individual" or Local Tax Reference).
customs.country_of_manufacture	Yes (dependent)	Country of manufacture for parcel contents.
customs.items	Yes (dependent)	Array of items contained in the parcel(s).
customs.items.quantity	Yes (dependent)	Quantity of this particular item
customs.items.description	Yes (dependent)	Description of this particular item
customs.items.value_per_unit	Yes (dependent)	Unit value of this particular item

Example Request

{
    "service": "international_pmair",
    "origin": "GB",
    "destination": "US",
    "boxes": [
        {
            "length": 10,
            "width": 10,
            "height": 10,
            "weight": 1
        }
    ],
    "goods_value": 150,
    "goods_description": "Books",
    "delivery_notes": "It is the red door",
    "collection_date": "2017-05-31",
    "sender": {
        "name": "Rich",
        "phone": "01234567890",
        "address1": "Unit 21 Tollgate",
        "town": "Eastleigh",
        "county": "Greater Manchester",
        "postcode": "SO53 3TG"
    },
    "recipient": {
        "name": "Nicola",
        "phone": "01234567890",
        "email": "[email protected]",
        "address1": "Hilton Midtown",
        "address2": "1335 6th Avenue",
        "town": "New York",
        "county": "NY",
        "postcode": "10019"
    },
    "customs": {
        "doc_type": "proforma",
        "reason": "Sold",
        "sender_name": "Rich",
        "sender_tax_reference": "VAT No 12345678",
        "recipient_name": "Nicola",
        "recipient_tax_reference": "Private Individual",
        "country_of_manufacture": "GB",
        "items": [
            {
                "quantity": "1",
                "description": "book",
                "value_per_unit": 150
            }
        ]
    }
}

Example Response

{
    "ShipmentId": 4749253,
    "label_url": "https://www.parcelmonkey.co.uk/shippinglabel.php?id=4749253&key=5a697",
    "tracking_url": "https://www.parcelmonkey.co.uk/tracking.php?PMID=4749253&ShipmentDeliveryPostcode=10019"
}

Back to the top

CancelShipment

You can use this service to request cancellation of your shipment.

POST

/CancelShipment

Request Parameter	Mandatory	Description
ShipmentId	Yes	1234567

Example Request

{
    "ShipmentId": "1234567"
}

Example Response

{
    "ShipmentId": "1234567",
    "ShipmentCancelled": "Y"
}

Back to the top

GetTrackingEvents

You can use this service to get tracking events for your shipment.

We harmonise all carrier tracking into a singular set of statuses. This makes it easier for you to translate statuses or filter the data, for to highlight exceptions or set a delivered status. Click here for the full list of statuses.

Status codes are in the format PARENT_STATUS__SUB_STATUS or just PARENT_STATUS where no sub status exists.

POST

/GetTrackingEvents

Request Parameter	Mandatory	Description
ShipmentId	Yes	1234567

Example Request

{
    "ShipmentId": "1234567"
}

Example Response

[
    {
        "ShipmentId": "1234567",
        "time": "2017-10-18 12:20:00+0000",
        "status": "DELIVERED__SIGNED_FOR_BY_RECIPIENT",
        "location": "RAUNDS",
        "carrier_message": "Raunds - Delivered, signed for by COKE",
        "carrier_reference": "123123123132",
        "carrier_url": "http://www.example-carrier-website.com/track/?reference=123123123132&postcode=AB11AB"
    },
    {
        "ShipmentId": "1234567",
        "time": "2017-10-18 08:02:00+0000",
        "status": "DEPARTED_FROM_FACILITY__HAS_LOCATION",
        "location": "RAUNDS",
        "carrier_message": "Raunds - On vehicle for delivery Out For Delivery e-mail notification sent",
        "carrier_reference": "123123123132",
        "carrier_url": "http://www.example-carrier-website.com/track/?reference=123123123132&postcode=AB11AB"
    },
    {
        "ShipmentId": "1234567",
        "time": "2017-10-18 01:31:00+0000",
        "status": "ARRIVED_AT_FACILITY__HAS_LOCATION",
        "location": "RAUNDS",
        "carrier_message": "Raunds - Confirmed at depot",
        "carrier_reference": "123123123132",
        "carrier_url": "http://www.example-carrier-website.com/track/?reference=123123123132&postcode=AB11AB"
    },
    {
        "ShipmentId": "1234567",
        "time": "2017-10-17 14:53:00+0000",
        "status": "COLLECTED_OR_DROPPED_OFF__COLLECTED",
        "location": "SOUTHAMPTON",
        "carrier_message": "Southampton - Collected from self-labeller",
        "carrier_reference": "123123123132",
        "carrier_url": "http://www.example-carrier-website.com/track/?reference=123123123132&postcode=AB11AB"
    },
    {
        "ShipmentId": "1234567",
        "time": "2017-10-17 11:45:00+0000",
        "status": "NO_TRACKING_EVENTS_YET",
        "location": "SOUTHAMPTON",
        "carrier_message": "Southampton - Customer data received Consignment Shipped e-mail notification sent",
        "carrier_reference": "123123123132",
        "carrier_url": "http://www.example-carrier-website.com/track/?reference=123123123132&postcode=AB11AB"
    }
]

Back to the top

GetPaymentLink

Use this service to obtain a temporary signed URL to redirect the user to the checkout for a set of shipments

POST

/GetPaymentLink

Example Request

[
    "1234567",
    "1234568"
]

Example Response

{
    "OrderId": 1234567,
    "Shipments": [
        "1234567",
        "1234568"
    ],
    "url": "http://www.parcelmonkey.co.uk/2falogin.php?UserId=12345&hash=43f58c5017d6e83f6985a1b2ee9b7476&return=%2Fcheckout.php%3Fsub%3Dresume%26OrderId%3D1234567"
}

Back to the top

Parcel Monkey UK Developer Documentation - API Version 3.1

Introduction

Contents

Endpoints

API Version Header

Authentication Headers

HelloWorld

Example Request

Example Response

GetQuote

Example Request

Example Response

CreateShipment

Example Request

Example Response

CancelShipment

Example Request

Example Response

GetTrackingEvents

Example Request

Example Response

GetPaymentLink

Example Request

Example Response