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