Pickup Point API contains all Posti pick-up points in Finland and Baltics (SmartPosti) and the pickup points of Posti’s partner networks in Sweden and Denmark. By using this information on your online retail business, your customers can choose the most convenient pickup point for their needs.
Users of the API can:
Posti APIs are secured with authentication and authorization flows based on OAuth 2.0. The production credentials (client ID and secret) can be ordered from the LogEDI@posti.com. Required information in the credentials order: Posti contract number, Organization number (Business ID), contact information.
(Access credentials can be created directly from the new Developer Portal NOTE: available in August 2025.)
application/x-www-form-urlencoded.
Production authentication token request URL:
https://gateway-auth.posti.fi/api/v1/token
Sample access token cURL request:
curl -X POST https://gateway-auth.posti.fi/api/v1/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=<DEMO-USER-ID>" \
--data-urlencode "client_secret=<DEMO-SECRET-ID>"
If the client is successfully authenticated, an access token is returned. The content of the token_value is encrypted. The targets list the available APIs that are allowed to be used with the token.
{
"access_token": "",
"token_type": "Bearer",
"expires_in": 3600,
"posti_fi": {
"targets": {
"2025-04": {
"url": "https://gateway.posti.fi/2025-04",
"tier": 0
}
}
}
}
To use the access token to authenticate API request, construct a normal HTTPS request and include an Authorization header with the value of Bearer <token_value>.
Sample Pickup Point API cURL request:
curl -X POST https://gateway.posti.fi/2025-04/pickuppoints \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <token_value>" \
--data "{"searchCriteria":{"location":{"postcode":"20100","countryCode":"FI"}},"limit":20}"
Access tokens obtained from the token endpoint expire in one hour (3600 seconds).
You can view the OpenAPI specification here.
Pickup Point API is part of Posti APIs and follows a long-term version numbering, visible in the path in “yyyy-mm” format. Yearly releases will be published, and each version is supported for three years.
Currently only a production environment is available for customers.
Production Pickup Point API endpoints
Querying the nearest pickup points:
POST https://gateway.posti.fi/2025-04/pickuppoints
Fetching a single pickup point with id value:
GET https://gateway.posti.fi/2025-04/pickuppoints/{countryCode}/{id}
Fetching all pickup points for one country (paged results with a continuation token in the response):
GET https://gateway.posti.fi/2025-04/pickuppoints/{countryCode}
And with continuation token as an URL parameter:
GET https://gateway.posti.fi/2025-04/pickuppoints/{countryCode}?pagingContinuationToken=<continuation_token>
The API has a set of common query options that can be used for specific actions, such as: selecting language, filtering, and limiting. There are two types of query options: header parameter for language and the JSON body for filtering and limiting, depending on the use case.
The search location is given also in the JSON body either as a postal code, street address, or coordinates.
Data subjected to language variation will be provided in a single requested language, if available. The requested language is controlled by the 'Accept-Language' header.
If 'Accept-Language' header is omitted from the request, the default language for the country (if known) is returned. E.g Finnish is used in Finland as the default language.
Example header value for returning pickup point names in Finnish:
Accept-Language: fi
Number of search results returned needs to be defined with a limit. The maximum is 50.
Example to fetch first five pickup points:
{
"searchCriteria": {
"location": {
"postcode": "20100",
"countryCode": "FI"
}
},
"limit": 20
}
The nearest pickup points can be searched by giving location details in the searchCriteria.location object. The search can be done with either postal code or with street address information (both require country information). Or the search can be done with coordinates, which has two options: circle with radius or a rectangle area with two corner points (southwest and northeast). The rectangle details are not given in the searchCriteria.location object, but in the searchCriteria.rectangle object. Examples are below.
Example to fetch pickup points near Finnish postal code 20100:
{
"searchCriteria": {
"location": {
"postcode": "20100",
"countryCode": "FI"
}
},
"limit": 20
}
Example to fetch pickup points near Finnish street address:
{
"searchCriteria": {
"location": {
"street": "Elielinaukio 2",
"postcode": "00100",
"city": "Helsinki",
"countryCode": "FI"
},
"serviceFilters": {}
},
"limit": 20
}
Example to fetch pickup points with coordinates (circle with radius):
{
"searchCriteria": {
"location": {
"coordinates": {
"latitude": 60.314331,
"longitude": 25.022741
},
"radius": {
"unit": "m",
"value": 3450
}
},
"serviceFilters": {}
},
"limit": 20
}
Example to fetch pickup points with coordinates (rectangle with corners):
{
"searchCriteria": {
"rectangle": {
"swLatitude": 60.160476,
"swLongitude": 24.928801,
"neLatitude": 60.167428,
"neLongitude": 24.953952
},
"serviceFilters": {}
},
"limit": 20
}
The pickup points can be filtered, so that only the ones with certain capabilities are returned. The searchCriteria.serviceFilters object is used for this purpose. E.g. the search could exclude parcel lockers that are outdoors or have wheelchair access. The filters are Boolean fields.
List of service filters:
| Filter name | Description |
|---|---|
| outdoorLocker | Set to false, if outdoor lockers should be excluded from the results. |
| wheelchairAccessibility | Set to true, if only pickup points that are accessible with a wheelchair should be included in the results. |
| openOnWeekends | Set to true, if only pickup points that are open on Saturdays or Sundays should be included in the results. |
| ADRLimitedQuantities | Set to true, if only pickup points that accept shipments containing limited quantity substances should be included in the results. |
| saturdayDelivery | Set to true, if only pickup points that can receive inbound parcels on Saturdays should be included in the results. |
Example for filtering out outdoor parcel lockers:
{
"searchCriteria": {
"location": {
"postcode": "33100",
"countryCode": "FI"
},
"serviceFilters": {
"outdoorLocker": false
}
},
"limit": 20
}
The type of the pickup point can be filtered with the Boolean field searchCriteria.parcelLocker, in case only parcel lockers or manned service points should be listed. Example is below:
Example for querying only parcel lockers:
{
"searchCriteria": {
"location": {
"postcode": "00100",
"countryCode": "FI"
},
"parcelLocker": true,
"serviceFilters": {}
},
"limit": 20
}
The response format for non-error responses conforms to the format and guidelines specified by REST JSON.
The pickup points are listed inside the pickupPoints object.
For full description of the response models please refer to the API specification.
Date and Time is always presented in ISO 8601 format except for localized data containing formatted date and/or time representations (e.g. availability string).
Examples of date and time format:
If no timezone information is provided the timezone should be interpreted as the default one in the locality for the location in question.
The language used to describe the API and its documentation is English including e.g. field names and enumeration values.
The API might return localized data (e.g. human readable description of the location name), to control returned localized data see Localization below.
Each pickup point has information about the.
| Pickup point parameter | Description |
|---|---|
| id | Unique pick up point code in the country. Previously known as the pupCode. |
| publicName | Public name of the location. This is the marketing name of pickup points. Show this name on your web shop checkout user interface. |
| careOf | Pickup point’s label name. This name is only used on parcel labels. Use publicName on web shop user interface. Use careOf name also in the shipment orders as Name 2 value of the recipient/delivery information (e.g. in Postra API). |
| parcelLocker | Boolean parameter. True for parcel lockers and false for manned service points. |
| routingServiceCode | Routing service code for the location. Used as the additional service code in shipment orders (e.g in Postra API). |
The availability object has information about the opening hours per each weekday.
Example for availability for Monday:
"availability": {
"openingHours": [
{
"closes": "20:00:00",
"dayOfWeek": "MONDAY",
"open24h": false,
"opens": "08:00:00",
"closed": false
}
]
}
The location object has information about the pickup point address and coordinates. In some pickupPoints the specificLocation field can tell extra information about the location (like “next to the cash registers”).
Example for location information:
"location": {
"countryCode": "FI",
"street": "Elielinaukio 2 F",
"postcode": "00100",
"city": "HELSINKI",
"municipality": "Helsinki",
"specificLocation": "Pääpostitalo",
"coordinates": {
"latitude": 60.17176,
"longitude": 24.93841
}
}
The API classifies pickup points according to their capabilities: whether it is possible to receive parcels, if the pickup point is accessible with a wheelchair, etc. The API specification describes the exact technical format in which the capabilities are presented, but they are basically key-value pairs. The following is a list of the various capabilities that the service points may have. Note that a single capability may appear multiple times! Each key-value pair thus describes only one of the options, even if several ones apply.
| Capability name | Value | Explanation |
|---|---|---|
| accessibility | WHEELCHAIR | Accessible with a wheelchair. |
| identityCheck | STRONG, NONE | Whether the recipient's identity can be checked at this pickup point. Identity check is required so that, for example, shipments with the "handing over to the addressee in person" (henkilökohtainen luovuttaminen) additional service can be handed out. NONE is the same as not having this capability at all. |
| ADRLimitedQuantities | ALLOWED, NOT_ALLOWED | Whether shipments containing limited quantity substances, such as flammable liquids, are allowed in this location. |
| parcelDropoff | PAYMENT, MANUAL_DROP, NO_DROPOFF, HELPOSTI_CODE, RESERVATION | If and how one can send a (pre-bought) parcel on its way from this location. NO_DROPOFF is the same as not having this capability at all. Certain parcel lockers can be used to send parcels with a Helposti code (HELPOSTI_CODE), while for others one needs to make a reservation beforehand (RESERVATION). Yet in some other locations there is a container into which one can just drop off their parcel (MANUAL_DROP), and in some locations one can buy a parcel (PAYMENT) instead of just dropping off pre-bought parcels. |
| parcelPickup | AVAILABLE, NOT_AVAILABLE | Whether this is a location from which one might need to pick up their incoming parcel from. |
| parcelReturn | PAYMENT, MANUAL_DROP, NO_DROPOFF, HELPOSTI_CODE, RESERVATION | Whether or not one can return parcels from this location. The values are the same as in the parcelDropoff capability. |
| saturdayDelivery | POSSIBLE, NOT_POSSIBLE | Whether or not this location receives inbound parcels on Saturdays. |
| sundayDelivery | POSSIBLE, NOT_POSSIBLE | Whether or not this location receives inbound parcels on Sundays. |
| storageSize | XXL | Note: this capability may only be present for parcel lockers. The value XXL means that this locker can accept XXL-sized parcels. This interface does not consider the real-time situation, i.e. it is possible that the XXL lockers have already been reserved and that none are actually free. |
| outdoors | OUTDOORS | Location that is outdoors. |
| expressDelivery | POSSIBLE, NOT_POSSIBLE | Whether or not this location has capability for BtoB parcel products |