InPost UK API Specifications (0.4.0)

Download OpenAPI specification:Download

This API specification is documented in OpenAPI format and defines the processes and steps that are used to find the location of a locker, create a label or track a parcel.

Introduction

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

  • Locker (APM Locations) API: This provides the methods to be used by your integration to locate where a locker is. InPost Lockers can also be referred to as Automated Parcel Machines (or APM for short) so you will see either of these terms being used throughout the document.There are two separate methods to enable the user to search by different criteria.

  • The Label or Paperless QR Code Creation APIs: This provides the endpoints and methods which can be used by your integration to obtain shipping from InPost. You will be able to access the following products using these API's:

    • Address to Locker (Click & Collect)
    • Locker to Address (Send)
    • Labelled Returns (Printed Returns)
    • Instant Returns (Paperless Returns)
  • The Tracking API: This provides the methods to be used by your integration to request tracking information for your parcels. You can search for your parcel using the consignment ID or tracking number.

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

The Address to Locker (A2L) service is InPost’s Outbound Click & Collect service, which allows retail clients 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. Parcels should be placed onto the usual Hermes collection from warehouse – segregated only by speed of service, but can be mixed in with home delivery volume.

The parcel will go through the Hermes network and out for delivery to the chosen locker. Upon delivery the customer will receive a confirmation text message 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 Hermes 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

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 their parcel. They can then take their parcel to one of over 1500 locker locations across the UK and store their parcel in one of the lockers by scanning the barcode at the bottom of the parcel label. Once the parcel is stored in the locker, the customer will receive an email and/or text message containing a parcel tracking link – enabling them to track their parcels onward journey.

The sequence of requests for this journey are as follows:

The API's used on this journey are:

Labelled Returns

The InPost Labelled Returns service allows customers to obtain an InPost/Hermes label, which can be used to return a parcel to a retailer.

The customer should print and affix the parcel label to their parcel. They can then take their parcel to one of 1500 locker locations across the UK and store their parcel in one of the Lockers by scanning the barcode at the bottom of the printed parcel label. Once the parcel is stored in the locker, the customer will receive an email and/or text message containing a parcel tracking link – enabling them to track their parcels onward journey back to the retailer.

The sequence of requests for this journey are as follows:

The API's used on this journey are:

Instant Returns

The InPost Instant Returns service allows customers to obtain an InPost Instant Returns QR code, which can be used to return a parcel to a retailer. Instant Returns does not require the customer to print a label at any point in the journey, it is truly a paperless service to the customer. The customer can package up their items and take their parcel to one of 1500 Locker locations across the UK and store their parcel in one of the Lockers by scanning the QR code from their smartphone. Once the parcel is stored in the Locker, the customer will receive a text message containing a parcel tracking number – enabling them to track their parcels onward journey back to the retailer.

The sequence of requests for this journey are as follows:

The API's used on this journey are:

Locker (APM) Locations & Tracking

The Locker (APM) Locations and Tracking API's can be used across all of the customer journeys.

Authentication

The following endpoints are publicy available endpoints which do not have any authentication:

  • Locker (APM) Locations
  • Tracking

The Label or Paperless QR Code 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

The test and live environments will have different tokens which can be obtained from InPost. Please contact your account manager integrations@inpost.co.uk.

Locker (APM) Locations

Get Machine Locations by City, GPS or Name

This operation gets the location of the APM. when the user searches by city, name and GPS co-ordinates.The response is cached for 10 minutes.

Request
query Parameters
city
string

The city in which the search for the APM(s) will be localised.

name
string

The APM name for which data is to be retieved for.

type
string

Searches for APM(s) with a given type. For the purpose of this implementation only parcel_locker is in the scope and therefore this should be the default value.

Value: "parcel_locker"
relative_point
string

Searches for APM(s) which are the closest from the given GPS coordinates.

max_distance
number

Searches for APM(s) which are in limited distance in meters from the given GPS coordinates.

max_distance
number

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

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

Get Machine Locations by Postcode

This API v4 Operation gets the location of the APM when the user searches by postcode. The response will return a listing of all APM machines within a specified range from the postcode entered by the user. The response is cached for 10 minutes.

Request
query Parameters
location[post_code]
string

Postcode to search APM(s) from.

location[distance]
number

Distance from the given Postcode to search for APM(s) in meters.

Responses
200OK
404Data Not found.
422Validation Failed due to invalid request data.
get/machines
Request samples
curl -i -X GET \
  'https://api-uk.easypack24.net/v4/machines?location%5Bpost_code%5D=string&location%5Bdistance%5D=0'
Response samples
application/json
{
  • "total_count": 0,
  • "_embedded": {
    }
}

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:
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
200OK
post/customers/{a2lretailer}/parcels
Request samples
application/json
{
  • "size": "A",
  • "target_machine_id": "UKBAN18691",
  • "customer_reference": "Customer Ref No",
  • "receiver_email": "receiver_email@inpost.co.uk",
  • "receiver_phone": "7712345678",
  • "service_type": "NDAY",
  • "weight": 2100
}
Response samples
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": "created",
  • "status_updated_at": "2019-08-24T14:15:22Z",
  • "additional1": "string",
  • "additional2": "string",
  • "avizo_time": 0,
  • "cod_amount": "string",
  • "customer_reference": "string",
  • "expiration_time": 0,
  • "insurance_amount": "string",
  • "letter_type": "string",
  • "pickup_expiration_time": "2019-08-24T14:15:22Z",
  • "primary_parcel_id": "string",
  • "receiver": {
    },
  • "receiver_phone": "string",
  • "receiver_email": "string",
  • "return_address": {
    },
  • "sender_address": {
    },
  • "sender_email": "string",
  • "sender_phone": "string",
  • "service": "STANDARD",
  • "size": "A",
  • "skip_pickup_point": true,
  • "source_machine_id": "string",
  • "target_machine_id": "string",
  • "parcel_attributes": [
    ],
  • "service_type": "NDAY",
  • "calculated_amount": "string",
  • "charged_amount": "string",
  • "dropoff_code": "string"
}

Pay for Address to Locker Parcel

pay for the parcel for which the label was created.

Request
Security:
path Parameters
a2lconsignmentId
required
string

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

Responses
200OK
422Not 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": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": "created",
  • "status_updated_at": "2019-08-24T14:15:22Z",
  • "additional1": "string",
  • "additional2": "string",
  • "avizo_time": 0,
  • "cod_amount": "string",
  • "customer_reference": "string",
  • "expiration_time": 0,
  • "insurance_amount": "string",
  • "letter_type": "string",
  • "pickup_expiration_time": "2019-08-24T14:15:22Z",
  • "primary_parcel_id": "string",
  • "receiver": {
    },
  • "receiver_phone": "string",
  • "receiver_email": "string",
  • "return_address": {
    },
  • "sender_address": {
    },
  • "sender_email": "string",
  • "sender_phone": "string",
  • "service": "STANDARD",
  • "size": "A",
  • "skip_pickup_point": true,
  • "source_machine_id": "string",
  • "target_machine_id": "string",
  • "parcel_attributes": [
    ],
  • "service_type": "NDAY",
  • "calculated_amount": "string",
  • "charged_amount": "string",
  • "dropoff_code": "string"
}

Get Address to Locker Parcel Label

get the label. The return is a pdf document.

Request
Security:
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
200OK
404Data Not found.
422Validation 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:
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
200OK
post/customers/{l2aretailer}/parcels
Request samples
application/json
{
  • "size": "A",
  • "target_machine_id": "UKBAN18691",
  • "customer_reference": "Customer Ref No",
  • "receiver_email": "receiver_email@inpost.co.uk",
  • "receiver_phone": "7712345678",
  • "service_type": "NDAY",
  • "weight": 2100
}
Response samples
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": "created",
  • "status_updated_at": "2019-08-24T14:15:22Z",
  • "additional1": "string",
  • "additional2": "string",
  • "avizo_time": 0,
  • "cod_amount": "string",
  • "customer_reference": "string",
  • "expiration_time": 0,
  • "insurance_amount": "string",
  • "letter_type": "string",
  • "pickup_expiration_time": "2019-08-24T14:15:22Z",
  • "primary_parcel_id": "string",
  • "receiver": {
    },
  • "receiver_phone": "string",
  • "receiver_email": "string",
  • "return_address": {
    },
  • "sender_address": {
    },
  • "sender_email": "string",
  • "sender_phone": "string",
  • "service": "STANDARD",
  • "size": "A",
  • "skip_pickup_point": true,
  • "source_machine_id": "string",
  • "target_machine_id": "string",
  • "parcel_attributes": [
    ],
  • "service_type": "NDAY",
  • "calculated_amount": "string",
  • "charged_amount": "string",
  • "dropoff_code": "string"
}

Pay for Locker to Address Parcel

pay for the parcel for which the label was created.

Request
Security:
path Parameters
l2aconsignmentId
required
string

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

Responses
200OK
422Not 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": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": "created",
  • "status_updated_at": "2019-08-24T14:15:22Z",
  • "additional1": "string",
  • "additional2": "string",
  • "avizo_time": 0,
  • "cod_amount": "string",
  • "customer_reference": "string",
  • "expiration_time": 0,
  • "insurance_amount": "string",
  • "letter_type": "string",
  • "pickup_expiration_time": "2019-08-24T14:15:22Z",
  • "primary_parcel_id": "string",
  • "receiver": {
    },
  • "receiver_phone": "string",
  • "receiver_email": "string",
  • "return_address": {
    },
  • "sender_address": {
    },
  • "sender_email": "string",
  • "sender_phone": "string",
  • "service": "STANDARD",
  • "size": "A",
  • "skip_pickup_point": true,
  • "source_machine_id": "string",
  • "target_machine_id": "string",
  • "parcel_attributes": [
    ],
  • "service_type": "NDAY",
  • "calculated_amount": "string",
  • "charged_amount": "string",
  • "dropoff_code": "string"
}

Get Locker to Address Parcel Label

get the label. The return is a pdf document.

Request
Security:
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
200OK
404Data Not found.
422Validation 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:
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.

One of:
sender_email
string

Must contain a valid email address for the sending customer.

sender_phone
string

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.

Responses
200OK
422no 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"
}
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"
}

Get a Returns Parcel Label or Paperless QR Code

Operation Gets the Returns label given a consignment Id.

Request
Security:
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
200OK
404Data Not found.
422Validation 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
200OK
get/{consignmentData}
Request samples
curl -i -X GET \
  https://tracking.inpost.co.uk/api/v2.0/:consignmentData
Response samples
application/json
{
  • "property1": {
    },
  • "property2": {
    },
  • "5934024283154413": [
    ]
}