Skip to main content
Skip table of contents

Release Party Integration Specifications

When an import container is commercially released, a Shipping Agent typically sends a PIN code to the Terminal and shares this code with the next party in the release chain (e.g. Forwarder, Transport Company, Beneficial Cargo Owner, …). This code, which is required to be granted access to the terminal and release the container, is distributed further in the supply chain until a party, which knows the PIN code, claims the container for pick up at the terminal.

By using the Certified Pick up (CPu) platform, a Shipping Agent will not create and distribute a PIN code to the Terminal, increasing the security of the release chain. Instead, the Shipping Agent sends the commercial release information towards the CPu platform, which vouches for a secure transfer of the “Release Right” until it is assigned to an entitled transporter to pick up the container at the terminal. The code to release the container will be sent via a secured and audited communication channel towards the Terminal.

This document describes how stakeholders of type Release Party should integrate the CPu process within their applications.


Setting up your endpoint connection

To ensure our high security standards at NxtPort, we do not allow any anonymous API connection and we require of course a minimum set of security measures to be applied on any API connection. To that end, you will need to follow the steps below to set up the secure API connection with NxtPort.

You need to have completed the steps described on Getting Started with the API integration in order to proceed.

Asynchronous processing in CPu

To correctly integrate the set of API comprehended in the CPu application, it is important to be aware of the fact that CPu mainly works in an asynchronous fashion.

This means that you when making an API call, you will not get the result to your request in the response to your API call, but NxtPort will process your request and then send you a notification through the endpoint you have configured in the Getting Started process. To that end we advise you to pay quite close attention to the use of the Public Reference Id. This is the GUID you receive in the response of your API call.

This will allow you to keep track of the notifications in line with the request calls you have made.

When a API call returns a synchronous response, it is clearly marked in this guide.

Integration API calls

General remarks

Distinct request body fields

For different actions (accept, decline, revoke etc.) you need to provide different actionType values in the request body. These different fields are highlighted under distinct request body fields in the descriptions to help you use the correct ones.

URL’s provided are PRD

The request URL’s provided are for the PRD environment. For the UAT environment, replace api.nxtport.com with api-uat.nxtport.com . Important: your API key is environment specific, so this also needs to be changed if you call our UAT environment.


Release Rights

Accept Release Right

Once another party (Ship Agent or another CPu Party) has transferred the Release Right of a container to your entity, you will receive a notification of type ReleaseRight and event Transferred. This will place the Release Right in a "queue", awaiting your acceptance or denial. It is not possible to transfer the Right of the container prior to either of these actions.

This action accepts the Release Right.

PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/release-rights

Request headers

  • External-Reference-Id (optional): your own reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization bearer token

Path variables

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

  • equipment_number: container number

Query parameters

N/A

Distinct request body fields

  • "actionType": "Accept"

Request body see the overview for an explanation of the fields

JSON
{
  "releaseIdentification": "",
  "terminalCode": "",
  "actionType": "Accept",
  "reasonForAction": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "releaseFrom": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseTo": {
    "identificationType": "",
    "identificationCode": ""
  },
  "carrier": {
    "identificationType": "",
    "identificationCode": ""
  },
  "equipmentNumber": "",
  "portLoCode": ""
}

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.


Decline Release Right

Once another party (Ship Agent or another CPu Party) has transferred the Release Right of a container to your entity, you will receive a notification of type ReleaseRight and event Transferred. This will place the Release Right in a "queue", awaiting your acceptance or denial. It is not possible to transfer the Right of the container prior to either of these actions.

This action declines the Release Right and returns it to the sender.

PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/release-rights

Request headers

  • External-Reference-Id (optional): your own reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization bearer token

Path variables

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

  • equipment_number: container number

Query parameters

N/A

Distinct request body fields

  • "actionType": "Decline"

Request Body see the overview for an explanation of the fields

JSON
{
  "releaseIdentification": "",
  "terminalCode": "",
  "actionType": "Decline",
  "reasonForAction": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "releaseFrom": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseTo": {
    "identificationType": "",
    "identificationCode": ""
  },
  "carrier": {
    "identificationType": "",
    "identificationCode": ""
  },
  "equipmentNumber": "",
  "portLoCode": ""
}

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.


Transfer Release Right

In case you received and accepted a Release Right from a previous party (can be either the original Ship Agent or another Party in the supply chain), you can transfer the right to the next party in the chain.

This call allows you to transfer a Release Right to another stakeholder. As soon as the other stakeholder accepts the Right, they will hold & be able to manage the Right themselves.

When transferring a container, the transferring party is required to provide detailed information about the Release Right which he received in the previous steps. We verify if the provided information matches with the information that we have received from the original source and send via notifications to the Right owners, increasing the security about Release Right transfers.

PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/release-rights

Request headers

  • External-Reference-Id (optional): your own reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization bearer token

Path variables

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

  • equipment_number: container number

Query parameters

N/A

Distinct request body fields

  • "actionType": "Transfer"

Request body see the overview for an explanation of the fields

JSON
{
  "releaseIdentification": "",
  "terminalCode": "",
  "actionType": "Transfer",
  "reasonForAction": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "releaseFrom": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseTo": {
    "identificationType": "",
    "identificationCode": ""
  },
  "carrier": {
    "identificationType": "",
    "identificationCode": ""
  },
  "equipmentNumber": "",
  "portLoCode": ""
}

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.


Revoke Release Right

This call allows you to revoke a Release Right which you previously transferred to another stakeholder. The Release Right will return to your company. The other stakeholder won’t be able to transfer the Right or pick up the container anymore.

Since release 3.1.0 a release right can be revoked as well if it has been accepted by the next entity or another entity down the chain.

PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/release-rights

Request headers

  • External-Reference-Id (optional): your own reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization bearer token

Path variables

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

  • equipment_number: container number

Query parameters

N/A

Distinct request body fields

  • "actionType": "Revoke"

Request body see the overview for an explanation of the fields

JSON
{
  "releaseIdentification": "",
  "terminalCode": "",
  "actionType": "Revoke",
  "reasonForAction": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "releaseFrom": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseTo": {
    "identificationType": "",
    "identificationCode": ""
  },
  "carrier": {
    "identificationType": "",
    "identificationCode": ""
  },
  "equipmentNumber": "",
  "portLoCode": ""
}

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.


Get list of Release Rights assigned to my company

This will trigger you to receive a notification on your predefined notification channel. Within you will receive the details of all Release Rights currently assigned to your company with their corresponding Green Lights.

GET https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/import/release-rights

Request Headers:

  • External-Reference-Id (optional): your own reference (string)

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization header (Bearer token)

Path Variables:

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

Query Parameters:

N/A

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.


Generic Services

Get Release Detail

At any time, stakeholders that are allowed to see the information, can retrieve the detail and greenlights of a specific container release.

This will trigger you to receive a notification on your predefined notification channel. Within you will receive the detail of the container with its corresponding Green Lights.

GET https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/import/release-rights/{{equipment_number}}

Request Headers:

  • External-Reference-Id (optional): your own reference (string)

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization header (Bearer token)

Path Variables:

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

  • equipment_number: container number

Query Parameters:

  • billOfLadingNumbers: array [string]

  • releaseIdentification: string

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.


Company Registry

This a synchronous call available to all CPu parties, which allows for querying the NxtPort register for other existing CPu parties and their respective identification values.

At any time, stakeholders that are allowed to see the information, can retrieve the details of any CPu connected party.

GET https://api.nxtport.com/certified-pickup/v1/entities?<query-params>

Request Headers:

  • External-Reference-Id (optional): your own reference (string)

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization header (Bearer token)

Path Variables:

N/A

Query Parameters:

At least one of the optional query parameters needs to be provided, please keep in mind that providing multiple optional parameters at once combines the filters with an AND expression.

  • EORI (optional) : an entity with matching EORI will be queried in our register;

  • DUNS (optional) : an entity with matching DUNS will be queried in our register;

  • VAT (optional) : an entity with matching VAT will be queried in our register;

  • NxtEntityId (optional) : an entity with matching NxtEntityId will be queried in our register;

  • entityName (optional) : an entity with a (partially) matching name will be queried in our register;

  • apcsCode (optional) : an entity with matching APCS code will be queried in our register;

  • page (default to 1) : determine which page of the results is queried;

  • pageSize (default to 25) : determine the page size of the queried results.

Response & notifications

This is an synchronous call, you will get a direct API response (see below)

Synchronous Responses

Response code

Response status

Response body

Response body fields

Action to take

200

OK

CODE
{
  "searchFilter": {
    "eori": "string",
    "duns": "string",
    "vat": "string",
    "entityName": "string",
    "apcsCode": "string",
    "page": 1,
    "pageSize": 25
  },
  "phoneBookItems": [
    {
      "apcsCode": "string",
      "addresses": [
        {
          "addressTypeCode": "string",
          "street": "string",
          "postalCode": "string",
          "city": "string",
          "country": "string",
          "contactName": "string",
          "contactEmail": "string"
        }
      ],
      "nxtEntityId": "string",
      "name": "string",
      "vat": "string",
      "duns": "string",
      "eori": "string",
      "scac": "string",
      "apcs": "string"
    }
  ],
  "totalRows": 0,
  "totalPages": 0,
  "publicReferenceId": "string",
  "externalReferenceId": "string"
}

searchfilter: values you entered in the call, other values will be null;

  • eori: self-explanatory;

  • duns: Data Universal Numbering System (not always known);

  • vat: self-explanatory;

  • entityName: self-explanatory;

  • apcsCode: self-explanatory;

  • page: 1 (default)

  • pageSize: 25 (default)

phoneBookItems (returned values of requested company)

  • apcsCode: self-explanatory;

  • addresses

    • addressTypeCode: 1 for main address, 2 for billing address;

    • street: self-explanatory;

    • postalCode: self-explanatory;

    • city: self-explanatory;

    • country: self-explanatory;

    • contactName: self-explanatory;

    • contactEmail: self-explanatory;

  • nxtentityid: self-explanatory;

  • name: self-explanatory;

  • vat: self-explanatory;

  • duns: Data Universal Numbering System (not always known);

  • eori: self-explanatory;

  • scac: if applicable;

  • apcs: self-explanatory;

totalRows: self-explanatory;

totalPages: self-explanatory;

publicReferenceId: GUID generated by NxtPort to identify the call;

externalReferenceId: optional id you provided in request.

N/A - all is good

400

Bad Request

CODE
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-1fa221c60594f6428678fd0fe54140a8-d1aecb5a9485b64d-00",
    "errors": {
        "Page": [
            "'Page' must be greater than or equal to '1'."
        ]
    }
}

N/A

Check the errors field for the error message

If you would run into any issues and not find the solution, please contact our Customer Success Team

401

Unauthorized - role or scope forbids you from taking this action

CODE
{
  "type": "string",
  "title": "string",
  "status": 401,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

N/A - fields have no meaning when 401 is returned

  • Check your credentials

  • Make sure you have a role assigned to your entity

If you would run into any issues and not find the solution, please contact our Customer Success Team

405

Method not allowed

CODE
{
  "type": "string",
  "title": "string",
  "status": 405,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

N/A - fields have no meaning when 401 is returned

  • check the call you made and make sure you have entered valid information

if you would run into any issues and not find the solution, please contact our Customer Success Team

500

Internal Server Error

N/A

 N/A

CPu API not accessible - check our statuspage to see if there is any downtime and try again later

429

Too Many Requests

N/A

N/A

You sent too many requests. This is the maximum amount of calls you’re allowed to do:

  • 10 calls per second

  • 500 calls per minute

  • 1000 calls per hour

  • 8000 calls per 24 hours


Notification Service

This API call allows you to retrieve notifications sent to your company.

Notifications can be retrieved up to 168 hours in the past from the time of your request (e.g. on 08 April at 13h00 you can retrieve all notifications dating from 01 April 13h00 onwards).

The timeWindowFrom and timeWindowTo query parameters will be available starting from version 3.11.0 of the API.

GET https://api.nxtport.com/certified-pickup/v1/notifications

Request Headers

  • External-Reference-Id (optional): your own reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization : authorization header (Bearer token)

Path variables

N/A

Query Parameters

At least 1 parameter is needed, multiple parameters will be queried using an AND operator.

  • notificationEvent: event of the corresponding notification

notificationEvent - enum
  • NotValidated

  • Transferred

  • AcceptedByNextParty

  • DeclinedByNextParty

  • RevokedByPreviousParty

  • ReleaseLightChanged

  • Update

  • GateOut

  • equipmentNumber: self-explanatory

  • publicReferenceId: GUID you received in the synchronous response

  • releaseId: ID (GUID) of the Release Right, returned in the notifications

  • storedOn: ISO timestamp of creation date/time of the notification

  • timeWindowFrom (optional): The starting time of the window for filtering notifications. Expects a time in ISO format ("07:30").

  • timeWindowTo (optional): The ending time of the window for filtering notifications. Expects a time in ISO format ("19:25").

Note: The timeWindowFrom and timeWindowTo parameters allow for a more precise filtering of notifications within a specified time range on the date provided in storedOn. Both parameters should be used together to define the start and end of the desired time window. The timeWindowTo may not be earlier than timeWindowFrom.

Responses

Status

Body

Explanation

200 - Success

CODE
[
  {
    "nxtEntityId": "string",
    "equipmentNumber": "string",
    "publicReferenceId": "string",
    "releaseId": "string",
    "externalReferenceId": "string",
    "storedOn": "ISO_Timestamp",
    "message": "string",
    "type": "string",
    "event": "string"
  }
  // object repeated for all notifications
]
  • nxtEntityId: your NxtPort ID

  • equipmentNumber: self-explanatory

  • publicReferenceId: GUID of the notification

  • releaseId: ID (GUID) of the Release Right

  • externalReferenceId: reference you provided in the request header

  • storedOn: ISO timestamp of creation date/time of the notification

  • message: notification as JSON string

  • type: ReleaseLight, ReleaseRight, TerminalEvent

  • event: event of the corresponding notification (see query parameters)

401 - Unauthorized

CODE
{
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

Missing API key or authorization token

403 - Forbidden

Response header:

WWW-Authenticate: Bearer error="invalid_token"

CODE
// empty object

The notification you requested was not sent to your company, you are not allowed to view the contents

405 - Invalid Input

N/A

No matching notifications found, check your query parameters

500 - Internal Server Error

CODE
{
    "identifier": "2304c375-30e2-408b-ac74-4c1b67ceaabf",
    "error": "An unexpected error has occured, please try again later. If the problem persists, please contact NxtPort Support.",
    "extraInfo": null
}

Please ensure that you are using the correct endpoint. If this is the case, something is probably wrong at our side. Don’t worry, we are already notified, so you don’t have to take action.

Check our statuspage for any possible downtime. The API could be temporarily out of service due to maintenance, incident, …

Make sure you build in a retry mechanism on your end.

429

Too Many Requests

N/A

N/A

You sent too many requests. We don’t accept more than 500 calls per minute.


Additional information

Direct API responses to asynchronous calls

This overview contains the direct responses you might receive to the asynchronous calls.

Response code

Response status

Response body

What to do?

200

OK

CODE
{
  "publicReferenceId": "GUID",
  "externalReferenceId": "string"
}

Nothing, all is good - the information you sent in has been received and will be processed. Any response will be provided through a notification with corresponding public reference id.

202

Accepted

CODE
{
  "publicReferenceId": "GUID",
  "externalReferenceId": "string"
}

Nothing, all is good - the information you sent in has been received and will be processed. Any response will be provided through a notification with corresponding public reference id.

400

Bad Request

Example if equipmentNumber & portLoCode have been omitted in request body:

CODE
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-a5601c96c250de464a5305102370cc7e-011ec98b63cf25c4-00",
    "errors": {
        "PortLoCode": [
            "'Port Lo Code' must not be empty.",
            "'Port Lo Code' must be equal to 'BEANR'."
        ],
        "EquipmentNumber": [
            "'Equipment Number' must not be empty."
        ]
    }
}

Review the request you have sent for syntax errors or conditions for the API call.

401

Unauthorized

N/A

You are not authorized to make that API call - this could be either because it is not available for your roll or because you are not allowed due to another CPU specific condition not being met (eg. the release right is not assigned to you… ). Please check if you:

  • are registered on the Certified Pick up platform;

  • you have the correct role;

  • your credentials (username, password, Oauth access token) are ok.

500

Internal Server Error

N/A

Please ensure that you are using the correct endpoint. If this is the case, something is probably wrong at our side. Don’t worry, we are already notified, so you don’t have to take action.

Check our statuspage for any possible downtime. The API could be temporarily out of service due to maintenance, incident, …

Make sure you build in a retry mechanism on your end.

429

Too Many Requests

N/A

You sent too many requests. We don’t accept more than 500 calls per minute.


Request body fields

Below you can find the overview of all the request body field keys which are used in the API calls.

This overview acts like a reference guide, not all fields are to be included in each call. The request bodies are always marked with the calls.

Field name

Type

Mandatory?

Allowed values

Field description

1

releaseIdentification

string

Yes

Free text

Unique release identification (per carrier).

2

billOfLadingNumbers

Array of strings

Yes

Free text

Bill of Lading number(s) of the container. The unique combination of container/BL will be used for the identification of the container release.

3

terminalCode

string

Yes

Terminal code provided to NxtPort during onboarding (for correct mapping)

The indicative terminal where the container will be available for pickup.

4

actionType

Enum

Yes

Different per action you need to perform. Check the specific action.

Action which is sent to the CPu platform, e.g. “Transfer”, “Accept“.

5

carrier> identificationType

Enum

No

“TIN” / “NxtEntityId” / “Eori” / “Duns” / “APCS

Enter the type of identification of the carrier.

Remark: TIN should be used for the VAT number of a company.

6

carrier> identificationCode

string

No

Free text

The value that belongs to the selected identification.

Note: carrier is not mandatory, but if filled, a check will occur if the identificationCode is known

7

releaseTo> identificationType

Enum

Yes

“TIN” / “NxtEntityId” / “Eori” / “Duns” / “APCS

Enter the type of identification of the party that will receive the Release Right.

Remark: TIN should be used for the VAT number of a company.

8

releaseTo> identificationCode

string

Yes

Free text

The value that belongs to the selected identification.

9

releaseFrom> identificationType

Enum

Yes

“TIN” / “NxtEntityId” / “Eori” / “Duns” / “APCS

Enter the type of identification of the party transfers the Release Right.

Remark: TIN should be used for the VAT number of a company.

10

releaseFrom> identificationCode

string

Yes

Free text

The value that belongs to the selected identification.

11

equipmentNumber

string

Yes

Free text

The container number.

12

portLoCode

string

Yes

UN/LoCode

The UN/Locode of the operational port. For Antwerp this is BEANR.

13

reasonForAction

string

No

Free text

Free text to provide, is displayed in the audit trail of the Release Right.


Notifications

As explained about the asynchronous handling within the CPu process, you - as a Release Party - will receive various notifications.

Some of these will be asynchronous responses to calls you have submitted, some will be notifications triggered by actions performed by other parties in the release process.

You will find detailed information tailored to your role in CPu on Notifications for Release Parties .


Need any further assistance?

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.