InPost International API Documentation (0.2)

Getting started with InPost Rest API

InPost APIs use REST, authenticate with OAuth 2.0 access tokens, and return HTTP response codes and responses encoded in JSON. You can test integrations with a sandbox environment.

Authorization

Address of production environment: https://api.inpost-group.com

Test environment address: https://sandbox-api.inpost-group.com

OAuth2 with authorization code flow and PKCE - Preferred method of authorisation

Overview

Our API is compliant with oAuth 2.1 (https://oauth.net/2.1/ ) so we require using PKCE in this authorization method. The Authorization Code Flow with Proof Key for Code Exchange (PKCE) is an extension that enhances the security of the authorization code flow. PKCE is designed to protect authorization codes from interception attacks.

Step 1: Generate Code Verifier and Code Challenge

Before initiating the authorization request, generate a code verifier and code challenge.

Code Verifier: A high-entropy cryptographic random string.
Code Challenge: A base64-url-encoded SHA256 hash of the code verifier.

import base64
import hashlib
import os

def generate_code_verifier():
    return base64.urlsafe_b64encode(os.urandom(32)).rstrip(b'=').decode('utf-8')

def generate_code_challenge(verifier):
    challenge = hashlib.sha256(verifier.encode('utf-8')).digest()
    return base64.urlsafe_b64encode(challenge).rstrip(b'=').decode('utf-8')

code_verifier = generate_code_verifier()
code_challenge = generate_code_challenge(code_verifier)

print("Code Verifier:", code_verifier)
print("Code Challenge:", code_challenge)

Step 2: Authorization Request

The next step is redirect user to our login page with following parameters.

“If you want to receive a long lived refresh token (offline token) you have to add offline_access in scopes parameter”

https://sandbox-login.inpost-group.com/realms/external/protocol/openid-connect/auth
           ?client_id=myclient
           &redirect_uri=https://myapp.com/callback
           &response_type=code
           &scope=api:shipments:write api:tracking:read api:one-time-pickups:write api:points:read
           &code_challenge=abc123def456ghi789
           &code_challenge_method=S256

Step 3: Login in and accept passing data to external system

Step 4: Exchange authorization code to receive refresh and access token

On redirect uri provided in previous step we receive one-time code that we need to exchange to obtain refresh and access token.

If you want to receive a long lived refresh token (offline token) you have to add offline_access in scopes parameter

curl --location 'https://sandbox-api.inpost-group.com/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=example' \
--data-urlencode 'client_secret=123456789xxxx' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://myapp.com/callback' \
--data-urlencode 'code=b9e50bd4-5ab0-4701-8c73-69466aa7ba21.......' \
--data-urlencode 'code_verifier=WIFPE6ylf8eGdggfT2r9zdXL8duZFrUNo0tbbHxolI4'

If offline_access scope was provided please keep refresh_token in safe place, because it does not require logging in to the system again by user

Step 5: Access token expiration

If your access_token will expire, your system need to exchange refresh_token to get a new access token.

Example requests with bearer token

OAuth2 with client_credentials flow - Alternative method of authorisation

The following examples show you how to get your access token using cURL. This flow has the limitation that we cannot use it where one app is working on behalf of multiple users. It is strictly correlated with one account and we recommend it for simple integrations.

InPost REST APIs use OAuth 2.0 access tokens to authenticate requests. Your access token authorizes you to use the InPost REST API server.

To call a REST API in your integration, you'll need to exchange your client ID and client secret for an access token.

You can make the API call in any programming language. The following examples show you how to get your access token using cURL.

Step result

InPost API returns an access token and the number of seconds the access token is valid. When you make calls to a REST API, include the access token in the authorization header: -H Authorization: Bearer ACCESS-TOKEN. When your access token expires, call /auth/token again to request a new access token.

On this page

1 Getting started with InPost Rest API
2 Authorization
- 2.1 OAuth2 with authorization code flow and PKCE - Preferred method of authorisation
- 2.2 OAuth2 with client_credentials flow - Alternative method of authorisation
3 HTTP Status codes
4 Versioning
5 Request IDs
6 Shipping Methods
7 Avaliable directions
8 Shipment weights and dimensions
9 Shipment creation
- 9.1 Service Logic and Availability Based on Delivery Type
- 9.2 Point to Point
- 9.3 Address to Point
- 9.4 Get Label
- 9.5 Get Shipments
10 Tracking – Webhooks
- 10.1 Request Authentication and verification
- 10.2 Basic Authentication
- 10.3 API Key / Custom headers
- 10.4 Digital Signature with Private Key
- 10.5 Digital Signature with Public/Private Key Pair
- 10.6 Request Versioning
- 10.7 Endpoints
- 10.8 Context specific fields
11 Tracking API
- 11.1 Endpoint: /tracking/catalogues
12 Tracking event catalogue
- 12.1 Global Tracking event Catalogue- Events
13 Points (Parcel Locker, ParcelPoint)
- 13.1 List of Points
- 13.2 Search criteria
- 13.3 Point details
14 One-Time Pickup creation
- 14.1 Retrieve cut-off time
- 14.2 Create one time pickup
- 14.3 Get one time pickup by id
- 14.4 Get multiple pickups

HTTP Status codes

Each request to the API returns an HTTP status indicating the result of the processing. The following list contains the most commonly used statuses:

200 OK Returned when the GET and PUT methods succeed.

201 Created Confirms the creation of a document using the POST method.

202 Accepted Indicates that the request has been accepted by the server, but its processing has not yet been completed (applies to asynchronous processing).

204 No Content Returned when an operation succeeds, but the request does not return any data (e.g., DELETE method).

304 Not Modified Indicates no changes in the HTTP request - no redirection.

400 Bad Request Incorrect JSON data sent.

401 Unauthorized The user is not authenticated - they should log in to Allegro and then try to make the request again.

403 Forbidden The user is authenticated but does not have rights to the requested resource.

404 Not Found The requested resource does not exist in the API.

406 Not Acceptable An unsupported data type was passed in the Accept header.

415 Unsupported Media Type An unsupported data type was passed in the Accept header.

422 Unprocessable Entity Incorrect field values were sent, e.g., object validation returned an error, or some fields do not meet the criteria imposed on them by the resource.

429 Too Many Requests The client exceeded the request limit.

503 Service Unavailable Connection to the service is not possible.

Versioning

The InPost REST API is versioned. The API version name is based on the date when the API version was released. For example, the API version 2024-06-01 was released on 01 June 2024.

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:

removing an entire operation
removing or renaming a parameter
removing or renaming a response field
adding a new required parameter
making a previously optional parameter required
changing the type of a parameter or response field
removing enum values
adding a new validation rule to an existing parameter
changing authentication or authorization requirements

Any additive (non-breaking) changes will be available in all supported API versions. Additive changes are changes that should not break an integration. Additive changes include:

adding an operation
adding an optional parameter
adding an optional request header
adding a response field
adding a response header
adding enum values

When a new REST API version is released, the previous API version will be supported for at least 12 months following the release of the new API version.

Specifying an API version

You should use the X-InPost-Api-Version header to specify an API version. For example:

Requests without the X-InPost-Api-Version header will default to use the current version, which is now 2024-06-01.

If you specify an API version that is no longer supported, you will receive a 400 error.

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under X-Request-Id.

You can provide own identifier and place it into request header and you receive it in response headers as well. We recommend using a strongly random character generator such as UUID.

To expedite the resolution process, provide the request identifier when you contact us about a specific request.

Shipping Methods

Name	Description

Name	Description
`APM` - Point (Locker)	Locker - Automated Parcel Machine (Paczkomat®)
`PUDO` - Point (PUDO)	Pick-up Drop-off Point - a store, kiosk, or other establishment acting on behalf of the InPost Group as a service point
`HUB` - Point (Hub)	InPost Group local warehouse, delivery branch, or sorting center
Address	Courier pick-up

Avaliable directions

		from: PL - Poland
to:		Point (Locker)	Point (PUDO)	Point (Hub)	Address
BE - Belgium	Point (Locker)	Yes	Yes	Yes	Yes
BE - Belgium	Point (PUDO)	Yes	Yes	Yes	Yes
ES - Spain (Espania)	Point (Locker)	Yes	Yes	Yes	Yes
ES - Spain (Espania)	Point (PUDO)	Yes	Yes	Yes	Yes
FR - France	Point (Locker)	Yes	Yes	Yes	Yes
FR - France	Point (PUDO)	Yes	Yes	Yes	Yes
IT - Italy	Point (Locker)	Yes	Yes	Yes	Yes
IT - Italy	Point (PUDO)	Yes	Yes	Yes	Yes
LU - Luxembourg	Point (Locker)	Yes	Yes	Yes	Yes
LU - Luxembourg	Point (PUDO)	Yes	Yes	Yes	Yes
NL - Netherlands	Point (Locker)	Yes	Yes	Yes	Yes
NL - Netherlands	Point (PUDO)	Yes	Yes	Yes	Yes
PT - Portugal	Point (Locker)	Yes	Yes	Yes	Yes
PT - Portugal	Point (PUDO)	Yes	Yes	Yes	Yes

Shipment weights and dimensions

Dimensions (length x width x height)	Weight	Description	Comments

Dimensions (length x width x height)	Weight	Description	Comments
64 x 38 x 8 cm	up to 25 kg	Size A	maximum dimensions and weight for size A
64 x 38 x 19 cm	up to 25 kg	Size B	maximum dimensions and weight for size B
64 x 38 x 39 cm	up to 25 kg	Size C	maximum dimensions and weight for size C

			From: PL - Poland
To:			Point (Locker)	Point (PUDO)	Point (Hub)	Address
BE - Belgium	Point (Locker)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm)	64×38×39	64×38×39	64×38×39	64×38×39
		Max Weight inclusive (kg)	25	25	25	25
	Point (PUDO)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm)	64×38×39	64×38×39	64×38×39	64×38×39
		Max Weight inclusive (kg)	25	25	25	25
ES - Spain (Espania)	Point (Locker)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm)	64×38×39	64×38×39	64×38×39	64×38×39
		Max Weight inclusive (kg)	25	25	25	25
	Point (PUDO)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm)	64×38×39	64×38×39	64×38×39	64×38×39
		Max Weight inclusive (kg)	25	25	25	25
FR - France	Point (Locker)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm)	64×38×39	64×38×39	64×38×39	64×38×39
		Max Weight inclusive (kg)	25	25	25	25
	Point (PUDO)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
IT - Italy	Point (Locker)	Min Dimenions inclusive (cm)	0,1 cm on each side	0,1 cm on each side	0,1 cm on each side	0,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
	Point (PUDO)	Min Dimenions inclusive (cm)	0,1 cm on each side	0,1 cm on each side	0,1 cm on each side	0,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
LU - Luxemburg	Point (Locker)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
	Point (PUDO)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
NL - Netherlands	Point (Locker)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
	Point (PUDO)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
PT - Portugal	Point (Locker)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25
	Point (PUDO)	Min Dimenions inclusive (cm)	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side	2,1 cm on each side
		Max dimenions inclusive (cm) `height` x `length` x `width`	39x38x64	39x38x64	39x38x64	39x38x64
		Max Weight inclusive (kg)	25	25	25	25

Shipment creation

The Create Shipment API (shipments/address-to-point, shipments/point-to-point) allows users to create a single shipment. This API is designed to streamline the shipment creation process, providing various output format options, starting with links to obtain PDF label format.

Service Logic and Availability Based on Delivery Type

Our Create Shipments API is designed to cater to a wide range of shipping needs, offering flexibility and customization in how shipments are handled. However, certain services and delivery options are subject to variations based on specific conditions, such as the delivery type or the destination country. Below, we outline how these conditions affect the availability and specifications of services like insurance, as well as the current geographical limitations on certain delivery types.

Insurance Value Variability

The insurance coverage value available for a shipment can vary depending on the chosen delivery method. This variability ensures that the insurance options offered are aligned with the risk profile and requirements of the selected delivery type. For instance: Shipments delivered to automated parcel machines (APMs) may have a different maximum insurance value compared to those delivered directly to an address.

Geographic Limitations on Delivery Types

Certain delivery options may be restricted to specific geographical regions due to operational, regulatory, or logistical considerations.

Future Expansions and Adjustments

Please note that these conditions and limitations are subject to change as we expand our services and enter into new markets or partnerships. We are continuously working to extend the range of delivery options and enhance the flexibility of our services to meet the needs of our international user base.

Point to Point

Request URL

POST /shipments/point-to-point

Request Body

The request body is a JSON object that contains detailed information about the shipment to be created, including sender and recipient details, priority, value-added services (VAS), references and parcel details within the shipment.

Label format: Label format attribute will be rolling out as a way to help merchants decide what type of shipping document will be included in the response.

Sample Request Body

Response

The response will contain details of the created shipment, including shipment id, tracking number, and any additional information pertinent to the shipment creation process.

Sample Response Body:

Root object:

Field	Nullable?	Type	Description
`labelFormat`	No	Enum	Available options: `PDF_URL`
`shipment`	No	Shipment Object	Data necessary for booking a shipment

Shipment object:

Field	Nullable?	Type	Description
`sender`	No	Sender Object	Information about the sender
`recipient`	No	String	Information about the recipient
`origin`	No	Origin Object	Information about the origin
`destination`	No	Destination Object	Information about the destination.
`priority`	No	Enum	Available options: `STANDARD`
`valueAddedServices`	Yes	Value Added Services Object	List of requested additional services and it’ details:
`references`	Yes	References Object	Available shipment references.
`parcel`	No	Parcel Object	Single package details.

Origin object:

Field	Nullable?	Type	Description
`countryCode`	No	String	Available options: `PL`
`shippingMethods`	No	Shipping Methods Object	Available options: `APM`, `PUDO`, `HUB`

Destination object:

Field	Nullable?	Type	Description
`countryCode`	Yes	String	Available options: `PL`
`pointName`	No	String	Name of the targeted delivery point.

Insurance object:

Field	Nullable?	Type	Description
`value`	No	Decimal	Max Insurance 5000 €
`currency`	No	String	Available options: `EUR`

Sender and recipient object:

Field	Nullable?	Type	Description
`companyName`	Yes	String	Can be used interchangeably instead of First and Last name.
`firstName`	No	String	First name
`lastName`	No	String	Last name
`email`	No	String	Email
`phone`	No	Phone Object	Phone Number
`languageCode`	Yes	Enum	Available options: "`pl_PL`", "`en_GB`", "`it_IT`", "`fr_FR`", "`fr_LU`", "`fr_BE`", "`nl_NL`", "`es_ES`", "`pt_PT`" Limited to sender country and destination country at a time. Ex. if sender is in Poland communication can be send in Polish.

Phone object:

Field	Nullable?	Type	Description
`prefix`	No	Enum	Available options: `+48`
`number`	No	String	Phone number corresponding to a chosen prefix.

References object:

Field	Nullable?	Type	Description
`custom`	Yes	Custom object	Individual key-value pairs with references are optional for customers. Up to three custom key-value pairs can be provided.

Parcel object:

Field	Nullable?	Type	Description
`type`	No	Enum	Available options: `STANDARD`
`dimensions`	No	Dimensions object	Shipment dimensions
`weight`	No	Weight object	Information about weight of the parcel.
`label`	Yes	Label object	Information to be printed on the label.

Dimensions object:

Field	Nullable?	Type	Description
`length`	No	String	Dimension of one side of the parcel
`width`	No	String	Dimension of one side of the parcel
`height`	No	String	Dimension of one side of the parcel
`unit`	No	Enum	Available options: `CM`

Weight object:

Field	Nullable?	Type	Description
`amount`	No	String
`unit`	No	String	Available options: `KG`

Label object:

Field	Nullable?	Type	Description
`comment`	Yes	String	A string to be printed on the label in the comment section.
`barcode`	Yes	String	Alphanumeric value to be encoded into Code-128 barcode and printed on the label.

Address to Point

Request URL

POST /shipments/address-to-point

Request Body

The request body is a JSON object that contains detailed information about the shipment to be created, including sender and recipient details, priority, value-added services (VAS), shipment references, parcel references and parcel details within the shipment.

Output options: Label format attribute will be rolling out as a way to help merchants decide what type of shipping document will be included in the response.

Sample Request Body

Response

The response will contain details of the created shipment, including shipment uuid, tracking number, and any additional information pertinent to the shipment creation process.

Sample Response Body:

Root object:

Field	Nullable?	Type	Description
`labelFormat`	No	Enum	Available options: `PDF_URL`
`shipment`	No	Shipment Object	Data necessary for booking a shipment

Shipment object:

Field	Nullable?	Type	Description
`sender`	No	Sender Object	Information about the sender
`recipient`	No	String	Information about the recipient
`origin`	No	Origin Object	Information about the starting point of shipping.
`destination`	No	Destination Object	Information about the destination.
`priority`	No	Enum	Available options: `STANDARD`
`valueAddedServices`	Yes	Value Added Services Object	List of requested additional services and it’ details.
`references`	Yes	References Object	Available shipment references.
`parcel`	No	Parcel Object	Single package details.

Sender and recipient object:

Field	Nullable?	Type	Description
`companyName`	Yes	String	Can be used interchangeably instead of First and Last name.
`firstName`	No	String	first name
`lastName`	No	String	last name
`email`	No	String	email
`phone`	No	Phone Object	Information about the phone number
`languageCode`	Yes	Enum	Available options: "`pl_PL`", "`en_GB`", "`it_IT`", "`fr_FR`", "`fr_LU`", "`fr_BE`", "`nl_NL`", "`es_ES`", "`pt_PT`" Limited to sender country and destination country at a time. Ex. if sender is in Poland communication can be send in Polish.

Origin object:

Field

Nullable?

Type

Description

address

No

Address

object

Information about the starting point of shipping.

Address object:

Field	Nullable?	Type	Description
`countryCode`	No	String	Available options: `PL`
`postalCode`	No	String	postal ode
`city`	No	String	city
`street`	No	String	street
`houseNumber`	No	String	house number
`flatNumber`	Yes	String	flat umber

Destination object:

Field	Nullable?	Type	Description
`countryCode`	Yes	String	Available options: `IT`, `FR`, `LU`, `BE`, `NL`, `ES`, `PT`
`pointName`	No	String	Name of the targeted delivery point.

Phone object:

Field	Nullable?	Type	Description
`prefix`	No	Enum	Available options: `+48`
`number`	No	String	Phone number corresponding to a chosen prefix.

References object:

Field	Nullable?	Type	Description
`custom`	Yes	Custom object	Individual key-value pairs with references are optional for customers. Up to three custom key-value pairs can be provided.

Parcel object:

Field	Nullable?	Type	Description
`type`	no	Enum	Available options: `STANDARD`
`dimensions`	no	Dimensions object	Shipment dimensions
`weight`	no	Weight object	Information about weight of the parcel.
`label`	Yes	Label object	Information to be printed on the label.

Dimensions object:

Field	Nullable?	Type	Description
`length`	no	String	Dimension of one side of the parcel
`width`	no	String	Dimension of one side of the parcel
`height`	no	String	Dimension of one side of the parcel
`unit`	no	Enum	Available options: `CM`

Weight object:

Field	Nullable?	Type	Description
`amount`	no	String	Shipment weight
`unit`	no	String	Available options: `KG`

Label object:

Field	Nullable?	Type	Description
`comment`	Yes	String	A string to be printed on the label in the comment section.
`barcode`	Yes	String	Alphanumeric value to be encoded into Code-128 barcode and printed on the label.

Get Label

Request URL

GET /shipments/{id}/label

The shipment id is the "uuid" from the response to the request creating the shipment.

Example below, correct "uuid": "f41ca12a-f04b-4ad6-b6c6-b7875347d2e2"

Sample Request Body

Sample Response Body:

Get Shipments

Request URL

GET /shipments/{id}

The shipment id is the "uuid" from the response to the request creating the shipment.

Example below, correct "uuid": "f41ca12a-f04b-4ad6-b6c6-b7875347d2e2"

Sample Request Body

Sample Response Body:

Tracking – Webhooks

Every time a tracking event occurs for a given parcel/shipment, a call will be made to the registered webhook.

Request Authentication and verification

No authentication mechanism will be enforced. Instead, webhook HTTP requests will be signed, and it is strongly recommended that consumers implement request validation to prevent external attacks on their exposed webhook endpoint. A signature will be generated based on the event payload (the request body) and request timestamp, and placed in the x-inpost-signature header. The consumer can validate the request by re-generating the signature on their side, and checking if it matches the one provided in the signature header, thus ensuring the authenticity of the request.

Refer to the authentication and verification section of the general webhook documentation for further details

Basic Authentication

Standard HTTP basic access authentication, uses the Authentication header to providea user name and password: Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of the user name and password separated by a colon (:)

API Key / Custom headers

A security key previously shared between both parties is passed in each request as an HTTP header, e.g., x-api-key. The header name can be customized, and multiple headers can be set, if needed.

Digital Signature with Private Key

HMAC with SHA256 message hashing. A private key is previously shared between both communication parties in secret. That key is used by InPost to generate a signature of the hash of the messages being sent. InPost sends the message signature in the x-inpost-signature header. The receiver should apply the same cryptographic operations to compute the signature upon reception, and then compare the signature sent by InPost with the one they computed themselves. If the signatures match then it’s guaranteed that the message content has not been tampered with and can be trusted. This method can be used to verify both the integrity and authenticity of the messages.

Digital Signature with Public/Private Key Pair

RSA with SHA256 message hashing. Similar to Digital Signature with Private Key, except a public/private key pair is used instead of single private key. Compared to the previous one, this method has the benefit of not requiring a private key to have been previously exchanged between both parties over a secure channel, at the expense of more computational power required to generate and validate signatures. In this method, InPost generates the key pairs, and shares the public key in the form of a public certificate (shared upfront). When sending messages, InPost generates a signature of the message hash with its private key, and sends it in the x-inpost-signature header of every webhook call. The receives should
perform the complementary operations on their side against the message signature to validate the message integrity and authenticity.

Request Versioning

We might need to introduce changes to the event payload after the system is up and running. If these changes are non-breaking (e.g. a new field is added to the payload), no new version will be generated. But, if we need to introduce a breaking change (e.g. renaming or removing an existing field), then a new version will be introduced to ensure backwards compatibility of existing subscriptions. When a merchant subscribes to the webhook, they are subscribing to a specific version (typically the latest version at subscription time).

All webhook calls will identify the version of the payload being passed via a dedicated HTTP header, X-InPost-Api-Version, whose value takes the form a date, e.g. 2024-06-01.

Endpoints

Request Headers

All webhook calls will contain the following headers:

Header	Example	Description
`x-inpost-api-version`	2024-06-01	Version of the payload being used in the request
`x- inpost-topic`	Shipment.Tracking	All tracking events will have topic set to “Shipment.Tracking”
`x- inpost-event-id`	XXX123	Unique id of the event
`x- inpost-timestamp`	2024-04-26T14:00:03.165Z	Date and Time when the event occurred, in UTC
`x- inpost-signature`	XXXXXXX12345	Signature of the request

Request Body

The request body will be the JSON representation of an Event object, described next.

Request Body sample for parcel creation status:

Request Body sample for first mile status:

Event Object (root object):

Field	Nullable?	Type	Description
`customerReference`	Yes	String	Reference/ID passed by the merchant when creating the shipment
`trackingNumber`	no	String	Tracking number generated by InPost
`eventId`	no	String	Unique id of the event (same as x-inpost-event-id header)
`eventCode`	no	String	Code of the event (refer to the event catalogue documentation for the possible values)
`timestamp`	no	Datetime	Date and time when the event occurred, in the local time zone (ISO 8601)
`location`	Yes	Location object	Location of the event
`delivery`	Yes	Delivery object	Information of delivery, in case it’s a delivery event.
`shipment`	Yes	Shipment object	Information about the shipment

Location object:

Field	Nullable?	Type	Description
`id`	Yes	String	ID of the location
`type`	no	String	One of: LOCKER_POINT, LOGISTIC_CENTER, PUDO_POINT, ADDRESS, MPOK_POINT
`name`	Yes	String	Name/description of PUDO/APM
`address`	Yes	String	Street, door number
`postalCode`	Yes	String	Postal code
`city`	Yes	String	City name
`country`	Yes	String	Country code (ISO2)

Delivery object:

Field	Nullable?	Type	Description
`recipientName`	Yes	String	Name of person who received the parcel
`deliveryNotes`	Yes	String	Notes provided by the courier upon delivery

Shipment object:

Field	Nullable?	Type	Description
`type`	Yes	String	One of: O`UTBOUND`, `RETURN`

Context specific fields

Some fields of the event object are applicable only in the case of certain event types (specified by the event code) and will therefore only be present in those cases. For example, the Delivery field will only be present if the event represents the delivery of a parcel/shipment. Similarly, depending on the event type, the Location object might contain only some of its sub-fields (e.g. Address will only be present in the case of a delivery to address, whereas the location Name will only be present when the location is a PUDO or an APM).

Tracking API

As an alternative to the webhooks (push mechanism), merchants can choose to obtain tracking data by calling the InPost Global Tracking API (pull mechanism). By passing one or more tracking numbers as parameters, the API will return the full tracking history of each shipment associated with those tracking numbers.

GET /tracking/parcels

Parameters:

trackingNumbers -- the list of tracking numbers
latestEvent -- if set to true then only last event is returned in events field (list of events for particular parcel history)
returnTranslations -- if set to true then fields eventTitle and eventDescription contains translated text in language set in Accept-Language request header. if set to false (default value) then fields eventTitle and eventDescription are empty.
includeNonTranslatedEvents-- Is used only if parameter returnTranslations = true. If includeNonTranslatedEvents set to true then fields eventTitle and eventDescription contains translated text in default language when no translation in language set in Accept-Language request header. If set to false (default value) then events for which there is no translations in language set in Accept-Language request header, are filtered out (not sent in the list of events in the response).
marketForCustomization – customized translations per market, default: IT
marketForFiltering – market for which we want to see events. default: IT

Response:

Parcel History with list of events. List of events will be sorted by timestamp (newest to oldest - first will be the newest event, last will be the oldest event)

Example 1 – response with event title and description sent in the language from header:

Request:

Response:

Example 2 – response with empty event title and description:

Request:

Response:

Endpoint: `/tracking/catalogues`

Parameters:

eventCodes- the list of event codes for which translations (in language set in Accept-Language request header ) should be returned. If empty then whole event catalogue (translations for all events in language set in Accept-Language request header ) will be returned
includeNonTranslatedEvents- if set to true then fields title and description contains translated text in default language when no translation in language set in Accept-Language request header. If set to false (default value) then events for which there is no translations in language set in Accept-Language request header, are filtered out (not sent in the list of items in the response).
marketForCustomization – customized translations per market, default: IT
marketForFiltering – market for which we want to see events. default: IT

Example – response when eventCodes is set and includeNonTranslatedEvents is not set:

Request:

Response:

Tracking event catalogue

The new Global Tracking Event Catalogue is designed to enhance the accuracy and granularity of tracking events by incorporating detailed event descriptions along with specific event attributes. This catalogue will now include:

Event Description: Each tracking event is accompanied by a comprehensive description, providing clear insights into what the event entails. This helps in understanding the nature and context of each event in the tracking process.

Event Location: The precise location where the event occurred is documented. This includes the geographical details such as city and country, allowing for better tracking and monitoring of the package's journey.

Event Type: This attribute describes the type of location where the scan occurred, offering more contextual information. For instance, it distinguishes between different points in the logistics network, such as a warehouse, a delivery center, or an automated parcel machine (APM).

Example of Granularity in Event Collection

For example, the event "Collect by Courier" would not just indicate that the parcel was collected but would provide additional granular details:

Event Location: The catalogue would specify the exact city and country where the collection took place.
Event Type: It would detail the type of location, such as whether the collection occurred at an APM, a customer’s residence, or a business address.

Detailed Event Example

Event: Collect by Courier

Event Description: Your parcel has started its journey and is on its way to one of our logistics centres.
Event Location: Milan, Italy
Event Type: Automated Parcel Machine (APM).

In this scenario, the granularity is provided by the detailed information that the collection happened at an APM located in Milan, Italy. This allows for a more precise understanding of the event and enhances the tracking experience for both logistics providers and customers.

By incorporating these detailed attributes, the Global Tracking Event Catalogue ensures that each event is thoroughly documented, providing a clearer picture of the parcel's journey from origin to destination.

Global Tracking event Catalogue- Events

Stage	EventCode	Event Name	Event Meaning	Details	Usage	Type of event
Parcel Creation	CRE.1001	[Generic] Parcel Creation	Your parcel has been created.		Used generically for Parcel Creation	Customer Facing
Parcel Creation	CRE.1002	[Generic] Ready for acceptance	Your parcel is ready for acceptance in the InPost Network.		Used generically for Customer Delivering	Customer Facing
First mile	FMD.1001	[Generic] Ready for courier collection	Your parcel is starting its journey and will be collected by our couriers.	Location Type	Used generically when Parcels are ready for collection	Customer Facing
First mile	FMD.1002	[Generic] Collected by courier	Your parcel has started its journey and is on its way to one of our logistics centres.	Location Type	Used generically when Parcels are collected by a courier	Customer Facing
First mile	FMD.1003	[Generic] In-transit (first-mile)	Your parcel is on the move through our network.		Used generically when Parcels are in-transit for the first mile	Customer Facing
Middle Mile	MMD.1001	[Generic] Adopted at Logistics Centre	Your parcel has been received at one of our logistics centres.	Location Type	Used generically when Parcels are adopted at a logistics centre	Customer Facing
Middle Mile	MMD.1002	[Generic] Processed at Logistics Centre	Your parcel has been processed at one of our logistics centres.	Location Type	Used generically when Parcels are processed at a logistics centre	Operational
Middle Mile	MMD.1003	[Generic] Dispatched from Logistics Centre	Your parcel has been dispatched from one of our logistics centres.	Location Type	Used generically when Parcels are dispatched from a logistics centre	Customer Facing
Middle Mile	MMD.1004	[Generic] Line-Haul	Your parcel is on the move through our network.	Location Type	Used generically when Parcels are within a line-haul	Customer Facing
Last Mile	LMD.1001	[Generic] In-transit (last-mile)	Your parcel is on its way to its final destination.	Location Type	Used generically when Parcels are in-transit for the last mile	Customer Facing
Last Mile	LMD.1002	[Generic] Arrived at destination	Your parcel has arrived at its final destination.	Location Type	Used generically when Parcels have arrived at the delivery destination	Customer Facing
Last Mile	LMD.1003	[Generic] Ready to collect	Your parcel is ready for collection from the destination.	Location Type	Used generically when Parcels are ready to collect	Customer Facing
Last Mile	LMD.3001	[Generic] Alternative collection point assigned	Your parcel has been redirected to an alternative collection location.	Location Type, Original location updated location	Used generically when Parcels have been reassigned a new collection location.	Customer Facing
Last Mile	LMD.3002	Alternative temporary collection point assigned	Your parcel has temporarily been assigned a different collection point.	Location Type, Original location updated location	Used when Parcels are to be temporarily reassigned to a different collection point.	Customer Facing
Last Mile	LMD.3003	Alternative collection point assigned	Your parcel has been assigned a different collection point.	Location Type, Original location updated location	Used when Parcels are reassigned to a different collection point.	Customer Facing
Last Mile	LMD.3004	Branch collection assigned	Your parcel has been assigned to be collected from a nearby branch.	Location Type, Original location updated location	Used when Parcels are assigned to be collected from a nearby branch.	Customer Facing
Last Mile	LMD.3005	Original collection point reassigned	Your parcel has been routed back to its original collection point.	Location Type, Original location updated location	Used when Parcels which have been reassigned a new collection point are rerouted back the original collection point.	Customer Facing
Last Mile	LMD.3006	Delivery readdressed	Your parcel has been readdressed to a new delivery location	Location Type, Original location updated location	Used when Parcels are requested to be delivered to a new delivery location	Customer Facing
Last Mile	CC.001	Parcel at customs	Your parcel has been delivered to customs to proceed with the customs clearance process	Location Type		Customer Facing
Last Mile	CC.002	Parcel customs cleared	Your parcel has being released by customs	Location Type		Customer Facing
Last Mile	CC.003	Parcel held at customs	Your parcel has being held at customs for inspection	Location Type		Operational
Last Mile	LMD.9001	Reminder to collect	Your parcel must be collected soon.	Location Type	Used generically when Parcels are nearing expiry at the delivery locker	Customer Facing
Last Mile	LMD.9002	Expired	Your parcel has not been collected on-time.	Location Type	Used when Parcels have expired at the delivery locker	Customer Facing
Last Mile	LMD.9003	Oversized	Your parcel is oversized for the destination.		Used when Parcels are oversized for the target delivery location.	Operational
Last Mile	LMD.9004	[Generic] Attempted delivery	We attempted to deliver your parcel but were unable to do this successfully. We will reattempt to deliver your parcel.	Location Type	Used generically when delivery at a location has been attempted and unsuccessful, but delivery will be reattempted.	Customer Facing
Last Mile	LMD.9005	[Generic] Undeliverable	Your parcel was undeliverable to the recipient.		Used generically when parcels are undeliverable.	Customer Facing
Last Mile	LMD.9006	Undeliverable: Rejected by recipient	Your parcel was undeliverable to the recipient, as it was rejected.		Used when Parcels have been rejected by the receiver	Customer Facing
Last Mile	LMD.9007	Undeliverable: Incorrect delivery details	Your parcel was undeliverable to the recipient, as it had incorrect delivery details.		Used when Parcels were undeliverable due to incorrect delivery data.	Operational
Last Mile	LMD.9008	Undeliverable: Receiver unknown	Your parcel was undeliverable to the recipient, as the recipient could not be identified.		Used when Parcels were undeliverable due to the recipient not being identifiable or known from the provided details.	Operational
Last Mile	LMD.9009	Undeliverable: COD conditions not met	Your parcel was undeliverable to the recipient, as the recipient did not meet the requirements for cash on delivery.		Used when Parcels have failed COD conditions and cannot be delivered.	Customer Facing
Last Mile	LMD.9010	Undeliverable: No mailbox	Your parcel was undeliverable due to no mailbox at the delivery location.		Used when Parcels were undeliverable due to lack of a mailbox or safe place.	Customer Facing
Last Mile	LMD.9011	Undeliverable: No access to location	Your parcel was undeliverable due to lack of access to the location.		Used when Parcels were undeliverable due to a lack of access to the delivery location.	Customer Facing
End of Life	EOL.1001	[Generic] Delivered	Your parcel has been delivered.	Location Type	Used generaly when a parcel is delivered	Customer Facing
End of Life	EOL.1003	Delivered at Safe Place	Your parcel had been delivered in a safe place	Location Type	Used when a Parcel is delivered on a safe location	Customer Facing
End of Life	EOL.1004	Delivered at neighbour	Your parcel had been delivered to your neighbour	Location Type	Used when a Parcel is delivered to a neighbour	Customer Facing
End of Life	EOL.1002	Parcel collected	Your parcel has been collected	Location Type	Used generically for parcels that were collected by customers in the collect points	Customer Facing
End of Life	EOL.9001	Missing	Your parcel has been marked as missing.		Used when Parcels have been definitively marked as missing	Operational
End of Life	EOL.9002	Damaged	Your parcel has been marked as damaged.		Used when Parcels have been definitively marked as damaged	Operational
End of Life	EOL.9003	Destroyed	Your parcel has been marked as destroyed.		Used when Parcels have been definitively marked as destroyed	Operational
End of Life	EOL.9004	Cancelled	Your parcel has been marked as cancelled.		Used when Parcels have been definitively marked as cancelled	Operational
End of Life	RTS.1001	[Generic] Returning to Sender	Your parcel is starting its journey back to the sender.		Used when Parcels are starting their journey back to the sender	Customer Facing
End of Life	RTS.1002	[Generic] Returned to Sender	Your parcel has been received by the sender.		Used when Parcels have been delivered to the end customer	Customer Facing
End of Life	INF.1001	COD payment received	Used when payment for COD was received
End of Life	INF.9001	Delay in Delivery	We are informing you that you may experience delays with our service in delivering your parcel.		Used when a delay in delivery must be communicated for the parcel.	Operational
Middle Mile	HAN.1001	[Generic] Handover	Your parcel is being handed over to another party.		Used generically when a parcel is handed over from one party to another.	Operational

Points (Parcel Locker, ParcelPoint)

Points resource represents the locations in which the logistics operator's services are available. Points can be self-service machines (Parcel locker, ParcelPoint) or branches, customer service points.

Accepted headers

Accept-Language: <language>

Examples

Accept-Language: pl-PL

Accept-Language: en-GB

List of Points

GET Endpoint: /Points

Sample Request Body

List of Points retrieval, the collection supports pagination.

Search criteria

Parameter	Type	Description	Example
`id`	String Array	Searches for shipments with given name. Searches for shipments with given names.	`?name=KRA02APP` `?name=KRA02APP,ADA01N`
`address.country`	String Array	Searches for points based on specific country	`?address.country=FR` `?address.country=FR,NL`
`type`	String Array	Searches for shipments with given type. Searches for shipments with given types.	`?type=APM` `?type=PUDO`
`address.postalCode`	String Array	Searches for shipments with given post code. Searches for shipments with given post codes.	`?address.postalCode` `=11-111` `?address.postalCode` `=11-111,22-222`
`address.city`	String Array	Searches for shipments with given city. Searches for shipments with given cities.	`?city=Kraków` `?city=Kraków,Warszawa`
`updatedFrom`	Date	Searches for points updated after the given date If updated_to has not been given the date cannot be earlier than 3 days before the current date	`?updatedFrom=2018-04-24`
`updatedTo`	Date	Searches for points updated before the given date Requires providing updated_from.	`?updatedTo=2018-04-26`

Search by location

Parameter	Type	Description	Example
`relativePoint`	String	Searches for points closest to the given location	`?relativePoint=52.123,19.321`
`relativePostCode`	String	Searches for points closest to the given post code	`?relativePostCode=11-111`
`maxDistance`	Double	Searches for points in distance up to the given value from relative_point or relative_post_code Parameter usage requires sorting by distance. Default value: 10000 (10km) Maximum value 50000 (50km)	`?relativePoint=52.123,19.321&maxDistance=10000`
`limit`	Integer	Point limiting parameter when using relative_point or relative_post_code	`?limit=10`

Pagination

Parameter	Type	Description	Example
`perPage`	integer	Limit records per page. Max value: 1000	`?perPage=100`
`page`	integer	number of current page	`?page=3`

Point details

Get point details.

GET /points/{:ID}

Sample Request:

Example Response

One-Time Pickup creation

Overview

The Pickups API (/one-time-pickups) enables users to submit requests for pickups, specifying details such as pickup location, desired time, and packages information. Upon placing an order, users receive confirmation with an order number and the endpoint provides ongoing status updates, allowing users to track the progress of their pickup request from confirmation to completion. Users can cancel or modify their pickup orders within a specified timeframe before the scheduled pickup.

Retrieve cut-off time

Retrieves the cutoff time for one-time pickups based on the provided postal code and country code.

Request URL

GET /cutoff-time?postalCode={string}&countryCode={string}

Parameters

postalCode (string, required): The postal code for which the cutoff time is requested. Only postal codes in PL (Poland) format (xx-xxx) are supported.
countryCode (string, required): The country code associated with the postal code. Must be set to PL (Poland).

Response

Root object:

Field	Nullable?	Type	Description
`postalCode`	No	string	The postal code for the location where the cutoff time is requested. The format follows the Polish postal code format (xx-xxx).
`cutoffTime`	No	string	he time by which a pickup can be scheduled at the specified location, formatted as "HH:MM:SS”

Create one time pickup

Request URL

POST /one-time-pickups

Request Body

The request body is a JSON object that contains detailed information about the one time pickup to be created, including address and contact person details, pickup time, volume, and references within the pickup.

Root object:

Field	Nullable?	Type	Description
`address`	No	Address Object	Information about one time pickup address
`contactPerson`	No	Contact Person Object	Information about contact person at the address
`pickupTime`	No	Pickup time Object	Information about the availability widow of the pickups.
`volume`	No	Volume Object	Information about the volume of items to be collected from the address.
`references`	Yes	Reference Object	Additional shipment description, e.g. order or client ID

Address object:

Field	Nullable?	Type	Description
`countryCode`	No	String	Available options: PL
`postalCode`	No	String	postal code
`city`	No	String	city
`street`	No	String	street
`houseNumber`	No	String	house number
`flatNumber`	Yes	String	flat number

Contact Person object:

Field	Nullable?	Type	Description
`firstName`	No	String	first name
`lastName`	No	String	last name
`email`	No	String	email
`phone`	No	String	phone

Phone object:

Field	Nullable?	Type	Description
`prefix`	No	Enum	Available options: “+48”
`number`	No	String	Phone number corresponding to a chosen prefix.

Pickup time object:

Field	Nullable?	Type	Description
`from`	No	DateTime	Date and time of the beginning of the readiness of the parcel to be pickup
`to`	No	DateTime	Date and time of the end of the parcel's readiness to be pickup

Volume object:

Field	Nullable?	Type	Description
`itemType`	No	Enum	Available options: `Parcel`
`count`	No	String	Number of shipments
`totalWeight`	No	Total Weight Object	Weight of all shipments

TotalWeight object:

Field	Nullable?	Type	Description
`amount`	No	Int	Shipment weight
`unit`	No	Enum	Available options: `KG`

References object:

Field	Nullable?	Type	Description
`custom`	Yes	Custom object	Individual key-value pairs with references are optional for customers. Up to three custom key-value pairs can be provided.

Response

The response will contain details of the created pickup, including pickup IDs, status, and any additional information pertinent to the pickup creation process.

Sample Response Body

Get one time pickup by id

Request Body

InPost International API Documentation (0.2)

Getting started with InPost Rest API

Authorization

OAuth2 with authorization code flow and PKCE - Preferred method of authorisation

OAuth2 with client_credentials flow - Alternative method of authorisation

HTTP Status codes

Versioning

Request IDs

Shipping Methods

Avaliable directions

Shipment weights and dimensions

Shipment creation

Service Logic and Availability Based on Delivery Type

Point to Point

Address to Point

Get Label

Get Shipments

Tracking – Webhooks

Request Authentication and verification

Basic Authentication

API Key / Custom headers

Digital Signature with Private Key

Digital Signature with Public/Private Key Pair

Request Versioning

Endpoints

Context specific fields

Tracking API

Endpoint: /tracking/catalogues

Tracking event catalogue

Global Tracking event Catalogue- Events

Points (Parcel Locker, ParcelPoint)

List of Points

Search criteria

Point details

One-Time Pickup creation

Retrieve cut-off time

Create one time pickup

Get one time pickup by id

Get multiple pickups

Endpoint: `/tracking/catalogues`