Parcel Monkey UK Developer Documentation - API Version 3.0

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.

Contents

Endpoints
API Version Header
Authentication Headers

Service: HelloWorld
Service: GetQuote
Service: CreateShipment

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.0

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" }

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": "Hampshire", "postcode": "SO53 3TG" }, "recipient": { "name": "Nicola", "phone": "01234567890", "email": "nicola@example.com", "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" } ]

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 503 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": "Hampshire", "postcode": "SO53 3TG" }, "recipient": { "name": "Nicola", "phone": "01234567890", "email": "nicola@example.com", "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" }