General Information

Here you will find general information you need to get started using PostNord APIs

Quick Start Guide

PostNord provides a range of APIs to facilitate integration with your back end systems. Integrate PostNord web services directly into your website, customs applications or e-commerce platform.

Our APIs are easy to use and customizable to meet your shipping needs.

  1. Read the developer API documentation
  2. For development
    • Sign up for a Sandbox
    • The test API key is provided to you in the registration email
    • The test URL Host is:
  3. For production
    • Sign up for Free/Premium plan
    • The production API key is provided to you in the registration email
    • The production URL Host is:

For help, contact

PostNord API Official FQDN | IP addresses

PostNord has removed the fixed IPs on the API gateway: &

Please configure Firewall rules using an alias or FQDN (e.g.

Why: With fixed IPs PostNord unable to scale the API gateway from a vendor perspective.


All of PostNord APIs requires the API key to be sent in the request as a query parameter apikey

The API key is used to identify you as a consumer of APIs.



HTTP Headers

Allows the client and the server to pass additional information with the request or the response.

The table lists recommended HTTP headers, to be set by the client.

Header Example Description
Content-Type: application/json The MIME type of the request body
X-External-Request-ID: 904344e8cde5-f058ebd6-02f7f942e Unique transaction ID, used for transactional correlation between the client and PostNord (troubleshooting)
Authorization: Bearer 1ijDG7gOOZ9Cj6VeH9tq Authentication credentials, which may contain the Access-token from the Oauth2 login

HTTP Caching

It is not recommended to cache data on the client side, this guarantees that the client always retrieves the latest data.

Note: It is ok to cache data, if the API explicitly allows that.


PostNord OAuth2 implementation supports the standard client credential grant type.

  • Each secured API has a set of scopes that defines the permissions to access their resources

    • They are listed in the API swagger definition
  • The client must be registered, to be able to perform an OAuth2 login

    • A successful login creates an Access token to the client with the assigned scopes.
    • A client can choose to request all scopes or a subset of those defined
  • The Access token is used in the calls to PostNord secured APIs

Swagger API specification

They are published under the API docs section in the developer portal.

securityDefinitions": {
"OAuth2": {
"type": "oauth2",
"tokenUrl": "",
"flow": "application",
"scopes": {
"": "Modify the resource"

APIs that require secure access (IAM)

APIs that require IAM are marked with (IAM required) in the title. For example:

Client (application)

This represents your application that want to use the protected APIs.

  1. You need to register the client
  2. Send the following information to with the subject: IAM
Client Data Description
API Key The production key from the sign up
Client Application Name The name of the client.
Redirect_URI* After successful authorization, the authorization server will redirect the user back to the application with either an authorization code or access token in the URL.
Scopes Provide a list of the scopes that the client needs access to, retrieved by looking into the APIs swagger specifications

3. PostNord will supply you the following information to be used in the OAuth2 authorizations request.

Client Data Description
client_id The client_id is a public identifier for the client
client_secret The client_secret is a secret known only to the client and authorization server

Authorization request

How to obtain an access-token for the client.

  • Test Authorization server URL:
  • Production Authorization server URL:

OAuth - Client credential flow

Request an access-token without user interact.

curl -X POST \ \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=xyzxyz&client_secret=xyzxyz'

Use HTTPS POST to the authorization server

The Content-Type Header contains

  • application/x-www-form-urlencoded

The Body contains

  • grant_type: client_credentials
  • client_id: the received PostNord client_id
  • client_secret: the received PostNord client_secret for the client_id

Response message

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
"access_token": "o5Ptk3GUEgNV3izvuDl5",
"acr": "client_credentials",
"token_type": "bearer",
"expires_in": 3599

The HTTP Headers contains

  • Content-Type: application/json Returned content type to the client
  • Cache-Control: no-store Ensures that the clients doesn't cache the request
  • Pragma: no-cache Ensures that the clients doesn't cache the request

The Body contains

  • access_token: The access token string as issued by the authorization server
  • acr: Authentication context reference
  • token_type: The type of token this is, typically just the string “bearer”
  • expires_in: The duration of seconds the access token is granted for

Request to secured API

The access token value from the Authorization response message, must be used in the request to the secured API.
Must be sent in the HTTP Header "Authorization:" with the token_type Bearer


  • The Authorization response has a value of "access_token": "o5Ptk3GUEgNV3izvuDl5"
  • Secured API request "Authorization: Bearer o5Ptk3GUEgNV3izvuDl5"

How we manage API versioning

Part of Postnord's booking clients responsibility is to keep in mind how we manage our API versioning.

vN- versioning

Defines the major version of the API e.g. /v1 , the API must be able to evolve overtime to minimize the need for new versions. The following changes can be introduced to the API that do not constitute a breaking change:

  • A new resource or API endpoint
  • A new optional parameter
  • A change to a non-public API endpoint
  • A new optional key in the JSON POST body
  • A new key returned in the JSON response body

Conversely, a breaking change included anything that could break the integration such as:

  • A new required parameter
  • A new required key in POST bodies
  • Removal of an existing endpoint
  • Removal of an existing endpoint request method
  • A materially different internal behavior of an API call — such as a change to the default behavior.