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

 

image-20240621-102549.png

 

image-20240621-102904.png

 

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.

 



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

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
(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 (LINK PENDING)

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: OUTBOUND, 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