logo

InPost UK API Specifications (0.4.2)

Download OpenAPI specification:Download

E-mail: integration@inpost.co.uk

This API specification is documented in OpenAPI format and defines the processes and steps that are used to: Find the location of an InPost Locker, Create a Label/QR Code or Track a Parcel.

Introduction to InPost UK

InPost provide a network of Automated Parcel Machines (APMs) in the thousands across the UK, allowing customers to Send, Return and Collect parcels conveniently at a time that suits them.

InPost APMs contain compartments, better known as lockers. Lockers come in 3 sizes – detailed below. Each locker compartment can hold a maximum weight of 15kg.

Glossary of Terms

APM: Automated Parcel Machine, an InPost Locker bank

Compartment: A single compartment within an APM, available in sizes:

A - Small - 8cm x 38cm x 64cm

B - Medium - 19cm x 38cm x 64cm

C - Large - 41cm x 38cm x 64cm

InPost UK APIs

The InPost API set is divided into the following three main components:

Customer Journeys

The API's described above can be used together to support the key InPost customer journeys. This section defines how they can be sequenced to deliver each journey.

Address to Locker (Click & Collect)

The Address to Locker (A2L) service is the Click & Collect service - allowing parcels to be collected from an address and delivered into an APM. This service allows retailers to manifest parcel data via API and obtain InPost labels back in pdf format, which can be used to send outbound parcels to the customer’s chosen InPost Locker.

The retailer/client should affix the parcel label to the parcel as part of the standard warehouse dispatch process.

The parcel will go through the carrier network and out for delivery to the chosen APM. Upon delivery the customer will receive a confirmation SMS and email from InPost containing their unique collection QR code. The customer will have 72hrs to collect their parcel from the locker. If uncollected within 72hrs, the parcel will expire, be collected by the carrier and be returned to the retailer within 3-5 working days.

The sequence of requests for this journey are as follows:

The API's used on this journey are:

Locker to Address (Send)

The Locker to Address (L2A) service allows customers to obtain an InPost label, which can be used to Send or Return a parcel to an address.

The customer should affix the parcel label to the parcel. They can then take their parcel to any InPost APM across the UK and deposit the parcel in one of the lockers by scanning the barcode at the bottom of the parcel label. Once the parcel is deposited in the locker, the customer will receive an email and/or SMS containing a tracking link – enabling them to track their parcels journey.

The sequence of requests for this journey are as follows:

The API's used on this journey are:

Instant Returns (Returns)

The InPost Instant Returns service allows customers to obtain an Instant Returns QR Code, which can be used to return a parcel to a retailer. No printer is required for this service.

The customer can then take their parcel to any InPost APM across the UK and deposit the parcel in one of the lockers by scanning the QR Code from their smartphone. Once the parcel is deposited in the locker, the customer will receive an email and/or SMS containing a tracking link – enabling them to track their parcels journey.

The sequence of requests for this journey are as follows:

The API's used on this journey are:

APM Locations & Tracking APIs

The APM Locations API and Tracking API can be used across all of the customer journeys.

Authentication

The following endpoints are publicy available endpoints which do not have any authentication. These endpoints are only available in the LIVE production environment:

  • APM Locations API
  • Tracking API

The Parcel Creation endpoints have the following authentication required:

bearerAuth

To get your API key please contact InPost on the following email: integrations@inpost.co.uk

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

InPost will provide the following credentials for either or both stage (TEST) / production (LIVE) environments:

API Token (Bearer YOUR_TOKEN): This can be created at request, by contacting your InPost Account Manager.

Retailer Account ID: Will be provided by InPost and is in an email address format. This is a dummy email address that InPost use when setting up your client account – it is not a real mailbox. Throughout this document this value would replace "YOUR_retailer_PARAMETER".

APM Locations API

Get Operating APM Locations using a Postcode or GPS Coordinates.

This operation gets the location data of the APM when the user searches by Postcode or GPS Coordinates. The response is cached for 10 minutes.

Request
query Parameters
status
required
string

The status of APMs.

Value: "Operating"
relative_point
string

Searches for APM(s) which are the closest from the given GPS lat/long coordinates. Must be used with max_distance. e.g. 51.4327458,-0.9093087

relative_post_code
string

Use a UK Postcode to search for the closest APM(s) within a specified distance in meters. Must be used with max_distance. e.g. SG13 8DA

max_distance
number

Searches for APM(s) which are in limited distance in meters from the given Postcode or GPS coordinates. Must be used with relative_point or relative_post_code. e.g. 5000

per_page
number

Determines how many APM(s) should be displayed per single page.

Responses
200

OK

get/points
Request samples
curl -i -X GET \
  'https://api-uk-points.easypack24.net/v1/points?status=Operating&relative_point=string&relative_post_code=string&max_distance=0&per_page=0'
Response samples
application/json
{
  • "href": "string",
  • "count": 0,
  • "page": 0,
  • "per_page": 0,
  • "total_pages": 0,
  • "meta": {
    },
  • "items": [
    ]
}

Address to Locker Label Creation

Create Address to Locker Label

The A2L booking request is a POST request and is the first request that must be made to create a parcel within the InPost systems.

Request
Security:
bearerAuth
path Parameters
a2lretailer
required
string

The Retailer for whom the Address to Locker (A2L) parcel label is to be created.

Request Body schema: application/json

Body of the Address to Locker operation.

size
required
string (Size)

The size of locker chosen for the parcel delivery - if cubic size is unknown, a value of "A" should be used as a default.

Enum: "A" "B" "C"
target_machine_id
required
string

The InPost Locker id for the locker chosen for delivery.

customer_reference
string

Any value that will allow you to identify the parcel. e.g. the order number, up to 255 characters.

receiver_email
string

The email address of the recipient - InPost will use this to send the customer their collection QR code and PIN.

receiver_phone
required
string

The mobile number of the recipient - InPost will use this to send the customer their collection QR code and PIN.

service_type
required
string (ServiceType)

The speed of service required for the parcel delivery - "NDAY" = Next Day and "2DAY" = Standard 48hr service.

Enum: "NDAY" "2DAY"
weight
required
integer <int32>

The weight of the parcel in grams, should not exceed 15000 grams. If unknown, a value of "10000"can be used as a default.

Responses
200

OK

post/customers/{a2lretailer}/parcels
Request samples
application/json
{
  • "size": "A",
  • "target_machine_id": "UKLON10965",
  • "customer_reference": "Customer Order 12345",
  • "receiver_email": "joebloggs@inpost.co.uk",
  • "receiver_phone": "7000000000",
  • "service_type": "NDAY",
  • "weight": 1000
}
Response samples
application/json
{
  • "id": "5116821000000334",
  • "created_at": "2021-03-08T22:14:02.098+00:00",
  • "status": "created",
  • "status_updated_at": null,
  • "additional1": null,
  • "additional2"": null,
  • "avizo_time": 2880,
  • "cod_amount": "0.0",
  • "customer_reference": "Customer Order 12345",
  • "expiration_time": 1440,
  • "insurance_amount": null,
  • "letter_type": null,
  • "pickup_expiration_time": null,
  • "primary_parcel_id": null,
  • "receiver": {
    },
  • "return_address": { },
  • "sender_address": {
    },
  • "sender_email": "retailer@inpost.co.uk",
  • "sender_phone": "7000000000",
  • "service": "STANDARD",
  • "size": "A",
  • "skip_pickup_point": false,
  • "source_machine_id": null,
  • "target_machine_id": "UKLON10965",
  • "parcel_attributes": [ ],
  • "service_type": "NDAY",
  • "calculated_amount": "0.0",
  • "charged_amount": "0.0",
  • "dropoff_code": "0"
}

Pay for Address to Locker Parcel

pay for the parcel for which the label was created.

Request
Security:
bearerAuth
path Parameters
a2lconsignmentId
required
string

The Address to Locker (A2L) Parcel Id for which the Payment should be made for.

Responses
200

OK

422

Not enough funds.

post/parcels/{a2lconsignmentId}/pay
Request samples
curl -i -X POST \
  'https://api-uk.easypack24.net/v4/parcels/{a2lconsignmentId}/pay' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "5116821000000334",
  • "created_at": "2021-03-08T22:14:02.098+00:00",
  • "status": "created",
  • "status_updated_at": null,
  • "additional1": null,
  • "additional2"": null,
  • "avizo_time": 2880,
  • "cod_amount": "0.0",
  • "customer_reference": "Customer Order 12345",
  • "expiration_time": 1440,
  • "insurance_amount": null,
  • "letter_type": null,
  • "pickup_expiration_time": null,
  • "primary_parcel_id": null,
  • "receiver": {
    },
  • "return_address": { },
  • "sender_address": {
    },
  • "sender_email": "retailer@inpost.co.uk",
  • "sender_phone": "7000000000",
  • "service": "STANDARD",
  • "size": "A",
  • "skip_pickup_point": false,
  • "source_machine_id": null,
  • "target_machine_id": "UKLON10965",
  • "parcel_attributes": [ ],
  • "service_type": "NDAY",
  • "calculated_amount": "0.0",
  • "charged_amount": "0.0",
  • "dropoff_code": "0"
}

Get Address to Locker Parcel Label

get the label. The return is a pdf document.

Request
Security:
bearerAuth
path Parameters
a2lconsignmentId
required
string

The Address to Locker (A2L) Parcel Id for which the Payment should be made for.

query Parameters
type
string

The type of Label to return. The default value is normal.

Value: "normal"
Responses
200

OK

404

Data Not found.

422

Validation Failed due to invalid request data.

get/parcels/{a2lconsignmentId}/sticker
Request samples
curl -i -X GET \
  'https://api-uk.easypack24.net/v4/parcels/{a2lconsignmentId}/sticker?type=normal' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "status_code": 0,
  • "error_code": "string",
  • "message": "string",
  • "errors": {
    }
}

Locker to Address Label Creation

Create Locker to Address Label

The L2A booking request is a POST request and is the first request that must be made to create a parcel within the InPost systems.

Request
Security:
bearerAuth
path Parameters
l2aretailer
required
string

The Retailer for whom the Locker to Address (L2A) parcel label is to be created.

Request Body schema: application/json

Body of the L2A operation.

size
required
string (Size)

The size of locker chosen for the parcel delivery - if cubic size is unknown, a value of "A" should be used as a default.

Enum: "A" "B" "C"
target_machine_id
required
string

Fixed Value - "ADDRESS", only applies for L2A parcels.

Value: "ADDRESS"
source_machine_id
required
string

Fixed Value - "ANY-PM", only applies for L2A parcels.

Value: "ANY-PM"
customer_reference
string

Any value that will allow you to identify the parcel. e.g. the order number, up to 255 characters.

required
object (Receiver)

Not used - the value in the response is always "{}".

receiver_email
string

If populated, must contain a valid email address.

receiver_phone
string

Last 10 digits only of a valid UK mobile number, starting with ‘7’.

service_type
string (ServiceType)

The speed of service required for the parcel delivery - "NDAY" = Next Day and "2DAY" = Standard 48hr service.

Enum: "NDAY" "2DAY"
weight
required
integer <int32>

Weight Unit is gram, a valid value of weight is between 1 and 15000.

Responses
200

OK

post/customers/{l2aretailer}/parcels
Request samples
application/json
{
  • "size": "A",
  • "target_machine_id": "ADDRESS",
  • "source_machine_id": "ANY-PM",
  • "customer_reference": "Order 12345",
  • "receiver_email": "joebloggs@inpost.co.uk",
  • "receiver_phone": "7000000000",
  • "service_type": "2DAY",
  • "weight": 5000,
  • "receiver": {
    },
  • "sender_address": {
    }
}
Response samples
application/json
{
  • "id": "0301361507070979",
  • "created_at": "2021-07-14T13:02:35.755+01:00",
  • "status": "created",
  • "status_updated_at": null,
  • "additional1": null,
  • "additional2": null,
  • "avizo_time": 2880,
  • "cod_amount": "0.0",
  • "customer_reference": "Order 12345",
  • "expiration_time": 1440,
  • "insurance_amount": null,
  • "letter_type": null,
  • "pickup_expiration_time": null,
  • "primary_parcel_id": null,
  • "receiver": {
    },
  • "receiver_phone": "7000000000",
  • "receiver_email": "joebloggs@inpost.co.uk",
  • "return_address": { },
  • "sender_address": {
    },
  • "sender_email": "retailer@inpost.co.uk",
  • "sender_phone": "7000000000",
  • "service": "ADDRESS",
  • "size": "A",
  • "skip_pickup_point": false,
  • "source_machine_id": "ANY-PM",
  • "target_machine_id": "ADDRESS",
  • "parcel_attributes": [ ],
  • "service_type": "2DAY",
  • "calculated_amount": "0.0",
  • "charged_amount": "0.0",
  • "dropoff_code": "0"
}

Pay for Locker to Address Parcel

pay for the parcel for which the label was created.

Request
Security:
bearerAuth
path Parameters
l2aconsignmentId
required
string

The Locker to Address (L2A) Parcel Id for which the Payment should be made for.

Responses
200

OK

422

Not enough funds.

post/parcels/{l2aconsignmentId}/pay
Request samples
curl -i -X POST \
  'https://api-uk.easypack24.net/v4/parcels/{l2aconsignmentId}/pay' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "0301361507070979",
  • "created_at": "2021-07-14T13:02:35.755+01:00",
  • "status": "created",
  • "status_updated_at": null,
  • "additional1": null,
  • "additional2": null,
  • "avizo_time": 2880,
  • "cod_amount": "0.0",
  • "customer_reference": "Order 12345",
  • "expiration_time": 1440,
  • "insurance_amount": null,
  • "letter_type": null,
  • "pickup_expiration_time": null,
  • "primary_parcel_id": null,
  • "receiver": {
    },
  • "receiver_phone": "7000000000",
  • "receiver_email": "joebloggs@inpost.co.uk",
  • "return_address": { },
  • "sender_address": {
    },
  • "sender_email": "retailer@inpost.co.uk",
  • "sender_phone": "7000000000",
  • "service": "ADDRESS",
  • "size": "A",
  • "skip_pickup_point": false,
  • "source_machine_id": "ANY-PM",
  • "target_machine_id": "ADDRESS",
  • "parcel_attributes": [ ],
  • "service_type": "2DAY",
  • "calculated_amount": "0.0",
  • "charged_amount": "0.0",
  • "dropoff_code": "0"
}

Get Locker to Address Parcel Label

get the label. The return is a pdf document.

Request
Security:
bearerAuth
path Parameters
l2aconsignmentId
required
string

The Locker to Address (L2A) Parcel Id for which the Payment should be made for.

query Parameters
type
string

The type of Label to return. The default value is normal.

Value: "normal"
Responses
200

OK

404

Data Not found.

422

Validation Failed due to invalid request data.

get/parcels/{l2aconsignmentId}/sticker
Request samples
curl -i -X GET \
  'https://api-uk.easypack24.net/v4/parcels/{l2aconsignmentId}/sticker?type=normal' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "status_code": 0,
  • "error_code": "string",
  • "message": "string",
  • "errors": {
    }
}

Returns

Create a Returns Request

Initiate a returns request.

Request
Security:
bearerAuth
path Parameters
retailer
required
string

The Retailer for whom the parcel label is to be created.

Request Body schema: application/json

Body of the returns.

sender_email
string

Mandatory. Must contain a valid email address for the sending customer.

sender_phone
string

Mandatory. Last 10 digits of a valid UK mobile phone number, starting with ‘7’.

size
string (Size)

The size of locker chosen for the parcel delivery - if cubic size is unknown, a value of "A" should be used as a default.

Enum: "A" "B" "C"
customer_reference
string

Any value that will allow you to identify the parcel (e.g. the order number). Up to 255 characters.

show_quick_send_code
string

Should be set to ‘true’ if the client plans on building the QR code themselves to send to the customer. If not included, the other option is to obtain a pre-built PDF containing a QR code.

Responses
200

OK

422

no have permission for reverse return.

post/customers/{retailer}/returns/v2
Request samples
application/json
{
  • "sender_email": "customer_email@inpost.co.uk",
  • "sender_phone": "7000000000",
  • "size": "A",
  • "customer_reference": "customer reference number",
  • "show_quick_send_code": "true"
}
Response samples
application/json
{
  • "id": "3400003000111803",
  • "sender_email": "customer_email@inpost.co.uk",
  • "sender_phone": "7000000000",
  • "size": "A",
  • "status": "customer_delivering",
  • "customer_reference": "customer reference number",
  • "created_at": "2021-07-16T09:48:13.815+01:00",
  • "quick_send_code"": "405524059"
}

Get Returns QR Code

This request, will respond with the Returns QR Code as a PDF, or as raw data where show_quick_send_code has been set to true in the Create a Returns Request.

Request
Security:
bearerAuth
path Parameters
consignmentId
required
string

The Parcel Id for which the Payment should be made.

query Parameters
type
string

The type of Label to return. The default value is normal.

Value: "normal"
Responses
200

OK

404

Data Not found.

422

Validation Failed due to invalid request data.

get/returns/v2/{consignmentId}/sticker
Request samples
curl -i -X GET \
  'https://api-uk.easypack24.net/v4/returns/v2/{consignmentId}/sticker?type=normal' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "status_code": 0,
  • "error_code": "string",
  • "message": "string",
  • "errors": {
    }
}

Tracking

Request Tracking Data

Obtain the details of all the parcel ids in the consignmentData. If tracking is required for more than one Consigment, the Consignment data is a list of ids separated by ;

Request
path Parameters
consignmentData
required
string

List of consignmentIds which are to be tracked. Each consignmentId is separated by an ;.

Responses
200

OK

get/{consignmentData}
Request samples
curl -i -X GET \
  'https://tracking.inpost.co.uk/api/v2.0/{consignmentData}'
Response samples
application/json
{
  • "property1": {
    },
  • "property2": {
    },
  • "5934024283154413": [
    ]
}