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 (OAuth 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