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
- 3 HTTP Status codes
- 4 Versioning
- 5 Request IDs
- 6 Shipping Methods
- 7 Avaliable directions
- 8 Shipment weights and dimensions
- 9 Shipment creation
- 10 Tracking – Webhooks
- 11 Tracking API
- 12 Tracking event catalogue
- 13 Points (Parcel Locker, ParcelPoint)
- 13.1 List of Points
- 13.2 Search criteria
- 13.3 Point details
- 14 One-Time Pickup creation
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 |
---|---|
| Locker - Automated Parcel Machine (Paczkomat®) |
| Pick-up Drop-off Point - a store, kiosk, or other establishment acting on behalf of the InPost Group as a service point |
| 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 |
Point (PUDO) | Yes | Yes | Yes | Yes | |
ES - Spain (Espania) | Point (Locker) | Yes | Yes | Yes | Yes |
Point (PUDO) | Yes | Yes | Yes | Yes | |
FR - France | Point (Locker) | Yes | Yes | Yes | Yes |
Point (PUDO) | Yes | Yes | Yes | Yes | |
IT - Italy | Point (Locker) | Yes | Yes | Yes | Yes |
Point (PUDO) | Yes | Yes | Yes | Yes | |
LU - Luxembourg | Point (Locker) | Yes | Yes | Yes | Yes |
Point (PUDO) | Yes | Yes | Yes | Yes | |
NL - Netherlands | Point (Locker) | Yes | Yes | Yes | Yes |
Point (PUDO) | Yes | Yes | Yes | Yes | |
PT - Portugal | Point (Locker) | Yes | Yes | Yes | Yes |
Point (PUDO) | Yes | Yes | Yes | Yes |
Shipment weights and dimensions
Dimensions | 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) | 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) | 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) | 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) | 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) | 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) | 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) | 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) | 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) | 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 |
| No | Enum | Available options: |
| No | Shipment Object | Data necessary for booking a shipment |
Shipment object:
Field | Nullable? | Type | Description |
| No | Sender Object | Information about the sender |
| No | String | Information about the recipient |
| No | Origin Object | Information about the origin |
| No | Destination Object | Information about the destination. |
| No | Enum | Available options: |
| Yes | Value Added Services Object | List of requested additional services and it’ details: |
| Yes | References Object | Available shipment references. |
| No | Parcel Object | Single package details. |
Origin object:
Field | Nullable? | Type | Description |
| No | String | Available options: |
| No | Shipping Methods Object | Available options: |
Destination object:
Field | Nullable? | Type | Description |
| Yes | String | Available options: |
| No | String | Name of the targeted delivery point. |
Insurance object:
Field | Nullable? | Type | Description |
| No | Decimal | Max Insurance 5000 € |
| No | String | Available options: |
Sender and recipient object:
Field | Nullable? | Type | Description |
| Yes | String | Can be used interchangeably instead of First and Last name. |
| No | String | First name |
| No | String | Last name |
| No | String | |
| No | Phone Object | Phone Number |
| Yes | Enum | Available options: " |
Phone object:
Field | Nullable? | Type | Description |
| No | Enum | Available options: |
| No | String | Phone number corresponding to a chosen prefix. |
References object:
Field | Nullable? | Type | Description |
| 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 |
| No | Enum | Available options: |
| No | Dimensions object | Shipment dimensions |
| No | Weight object | Information about weight of the parcel. |
| Yes | Label object | Information to be printed on the label. |
Dimensions object:
Field | Nullable? | Type | Description |
| No | String | Dimension of one side of the parcel |
| No | String | Dimension of one side of the parcel |
| No | String | Dimension of one side of the parcel |
| No | Enum | Available options: |
Weight object:
Field | Nullable? | Type | Description |
| No | String |
|
| No | String | Available options: |
Label object:
Field | Nullable? | Type | Description |
| Yes | String | A string to be printed on the label in the comment section. |
| 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 |
| No | Enum | Available options: |
| No | Shipment Object | Data necessary for booking a shipment |
Shipment object:
Field | Nullable? | Type | Description |
| No | Sender Object | Information about the sender |
| No | String | Information about the recipient |
| No | Origin Object | Information about the starting point of shipping. |
| No | Destination Object | Information about the destination. |
| No | Enum | Available options: |
| Yes | Value Added Services Object | List of requested additional services and it’ details. |
| Yes | References Object | Available shipment references. |
| No | Parcel Object | Single package details. |
Sender and recipient object:
Field | Nullable? | Type | Description |
| Yes | String | Can be used interchangeably instead of First and Last name. |
| No | String | first name |
| No | String | last name |
| No | String | |
| No | Phone Object | Information about the phone number |
| Yes | Enum | Available options: " |
Origin object:
Field | Nullable? | Type | Description |
| No | Address object | Information about the starting point of shipping. |
Address object:
Field | Nullable? | Type | Description |
| No | String | Available options: |
| No | String | postal ode |
| No | String | city |
| No | String | street |
| No | String | house number |
| Yes | String | flat umber |
Destination object:
Field | Nullable? | Type | Description |
| Yes | String | Available options: |
| No | String | Name of the targeted delivery point. |
Phone object:
Field | Nullable? | Type |