InPost International API Documentation (0.2)
- Michał Machowski
- Gdowski Marcin
- Maciej Prucnal
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
- 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 | 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 | Shipment weight |
| 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. |
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 |
| 2024-06-01 | Version of the payload being used in the request |
| Shipment.Tracking | All tracking events will have topic set to “Shipment.Tracking” |
| XXX123 | Unique id of the event |
| 2024-04-26T14:00:03.165Z | Date and Time when the event occurred, in UTC |
| 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 |
| Yes | String | Reference/ID passed by the merchant when creating the shipment |
| no | String | Tracking number generated by InPost |
| no | String | Unique id of the event (same as x-inpost-event-id header) |
| no | String | Code of the event (refer to the event catalogue documentation for the possible values) |
| no | Datetime | Date and time when the event occurred, in the local time zone (ISO 8601) |
| Yes | Location object | Location of the event |
| Yes | Delivery object | Information of delivery, in case it’s a delivery event. |
| Yes | Shipment object | Information about the shipment |
Location object:
Field | Nullable? | Type | Description |
| Yes | String | ID of the location |
| no | String | One of: LOCKER_POINT, LOGISTIC_CENTER, PUDO_POINT, ADDRESS, MPOK_POINT |
| Yes | String | Name/description of PUDO/APM |
| Yes | String | Street, door number |
| Yes | String | Postal code |
| Yes | String | City name |
| Yes | String | Country code (ISO2) |
Delivery object:
Field | Nullable? | Type | Description |
| Yes | String | Name of person who received the parcel |
| Yes | String | Notes provided by the courier upon delivery |
Shipment object:
Field | Nullable? | Type | Description |
| Yes | String | One of: O |
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 numberslatestEvent-- 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: ITmarketForFiltering– 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 returnedincludeNonTranslatedEvents- 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: ITmarketForFiltering– 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 |
| String Array | Searches for shipments with given name. Searches for shipments with given names. |
|
| String Array | Searches for points based on specific country |
|
| String Array | Searches for shipments with given type. Searches for shipments with given types. |
|
| String Array | Searches for shipments with given post code. Searches for shipments with given post codes. |
|
| String Array | Searches for shipments with given city. Searches for shipments with given cities. |
|
| 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 |
|
| Date | Searches for points updated before the given date Requires providing updated_from. |
|
Search by location
Parameter | Type | Description | Example |
| String | Searches for points closest to the given location |
|
| String | Searches for points closest to the given post code |
|
| 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) |
|
| Integer | Point limiting parameter when using relative_point or relative_post_code |
|
Pagination
Parameter | Type | Description | Example |
| integer | Limit records per page. Max value: 1000 |
|
| integer | number of current page |
|
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 |
| No | string | The postal code for the location where the cutoff time is requested. The format follows the Polish postal code format (xx-xxx). |
| 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 |
| No | Address Object | Information about one time pickup address |
| No | Contact Person Object | Information about contact person at the address |
| No | Pickup time Object | Information about the availability widow of the pickups. |
| No | Volume Object | Information about the volume of items to be collected from the address. |
| Yes | Reference Object | Additional shipment description, e.g. order or client ID |
Address object:
Field | Nullable? | Type | Description |
| No | String | Available options: PL |
| No | String | postal code |
| No | String | city |
| No | String | street |
| No | String | house number |
| Yes | String | flat number |
Contact Person object:
Field | Nullable? | Type | Description |
| No | String | first name |
| No | String | last name |
| No | String | |
| No | String | phone |
Phone object:
Field | Nullable? | Type | Description |
| No | Enum | Available options: “+48” |
| No | String | Phone number corresponding to a chosen prefix. |
Pickup time object:
Field | Nullable? | Type | Description |
| No | DateTime | Date and time of the beginning of the readiness of the parcel to be pickup |
| No | DateTime | Date and time of the end of the parcel's readiness to be pickup |
Volume object:
Field | Nullable? | Type | Description |
| No | Enum | Available options: |
| No | String | Number of shipments |
| No | Total Weight Object | Weight of all shipments |
TotalWeight object:
Field | Nullable? | Type | Description |
| No | Int | Shipment weight |
| No | Enum | Available options: |
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. |
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
Get multiple pickups