Parcel Monkey UK Developer Documentation - API Version 3.1

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


Notice: Undefined index: user in /home/forge/www.parcelmonkey.co.uk/developers/v3.1.php on line 57
Service: HelloWorld
Service: GetQuote
Service: CreateShipment
Service: CancelShipment
Service: GetTrackingEvents

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

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

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

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

Notice: Undefined index: user in /home/forge/www.parcelmonkey.co.uk/developers/v3.1.php on line 479