Skip to main content
Skip table of contents

Transport Operator Integration Guidelines

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. 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 Transport Operator 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 (Shipping 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 (Shipping 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

  • 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.


Pick-up Rights - Truck

Generate Pick-up Right - truck: assign driver

When your company is the (current) owner of the Release Right, you can assign a driver for the pick up of the container at the terminal. This driver needs to have a valid Alfapass.

The release information of the container (identification + Pick-up code) will be only send to the app when both Terminal and Commercial release are given. In case one of these two releases has not yet been given when assigning the pick up, the alfapass will be stored. At the moment the releases are okay, the container will be available for the driver.

When assigning a single driver to pick up a container, the driver’s Alfapass is used for identification. Therefore, the driver needs to have their personal active Alfapass. When an invalid Alfapass number is used when assigning the pick up, the pick-up will be cancelled and an error notification will be sent.

This call assigns a driver to the pick-up. Allows this driver to pick up the container at the terminal.

PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/pickup-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": "Assign"

  • pickupParty.partyType: "Truck"

  • pickupParty.identificationType: "Alfapass"

Request body see the overview for an explanation of the fields

JSON
{
  "terminalCode": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "releaseIdentification": "",
  "pickupParty": {
    "partyType": "Truck",
    "identificationType": "Alfapass",
    "identificationCode": ""
  },
  "timestamp": "",
  "actionType": "Assign",
  "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.


Update Pick-up Right - truck

Combination of Revoking the previously assigned pick-up right + Create and assign to a new driver.

PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/pickup-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": "Update"

  • pickupParty.partyType: "Truck"

  • pickupParty.identificationType: "Alfapass"

Request body see the overview for an explanation of the fields

JSON
{
  "terminalCode": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "releaseIdentification": "",
  "pickupParty": {
    "partyType": "Truck",
    "identificationType": "Alfapass",
    "identificationCode": ""
  },
  "timestamp": "",
  "actionType": "Update",
  "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 Pick-up Right - truck

Revokes the Pick-up Right from the current driver. Driver will not be able to pick up container.

In case you have already sent out the Pick up right to a driver and the container has not yet been picked up, you can revoke the right.

When you have sent out a Pick up Right, the forwarding of the Release Right is disabled. If you want to forward the Release Right to another party, you should revoke the Pick up Right first.

PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/pickup-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"

  • pickupParty.partyType: "Truck"

  • pickupParty.identificationType: "Alfapass"

Request body see the overview for an explanation of the fields

JSON
{
  "terminalCode": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "releaseIdentification": "",
  "pickupParty": {
    "partyType": "Truck",
    "identificationType": "Alfapass",
    "identificationCode": ""
  },
  "timestamp": "",
  "actionType": "Revoke",
  "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.


Pick-up Rights - Barge / Rail

Generate Pick-up Right - barge / rail

When your company is the (current) owner of the Release Right, you can assign a pick-up of the container at the terminal for either barge or rail. A pick-up right will be generated for your company’s identity.

The release information of the container will be only send to the app when both Terminal and Commercial release are given. In case one of these two releases has not yet been given when assigning the pick up, the pick-up will be stored. At the moment the releases are okay, the container will be available for the barge or rail operator

This call assigns a pick-up for either barge or rail so that your company can pick-up the container at the terminal

PUT https://api.nxtport.com/certified-pickup/v1/pickup-rights/barge-rail

Request headers

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

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

  • Authorization: authorization bearer token

Path variables

N/A

Query parameters

N/A

Distinct request body fields

  • "actionType": "0" --- use int value: “0” (Assign)

  • "meansOfTransport": "2" --- use int value: “2” (Barge) or use int value: “3” (Rail)

  • dataBrokerNxtEntityId --- can be ignored, not a mandatory value

  • Request body see the overview for an explanation of the fields

JSON
{
  "terminalCode": "string",
  "portLoCode": "string",
  "releaseIdentifier": {
    "billOfLadingNumbers": [
      "string"
    ],
    "equipmentNumber": "string",
    "releaseIdentification": "string"
  },
  "dataBrokerNxtEntityId": "string",
  "actionType": "0",
  "meansOfTransport": "2"
}

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.


Update Pick-up Right - barge / rail

Combination of Revoking the previously assigned pick-up right + Create and assign a new pick-up

PUT https://api.nxtport.com/certified-pickup/v1/pickup-rights/barge-rail

Request headers

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

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

  • Authorization: authorization bearer token

Path variables

N/A

Query parameters

N/A

Distinct request body fields

  • "actionType": "1" --- use int value: “1” (Update)

  • "meansOfTransport": "2" --- use int value: “2” (Barge) or use int value: “3” (Rail)

  • dataBrokerNxtEntityId --- can be ignored, not a mandatory value

Request body see the overview for an explanation of the fields

JSON
{
  "terminalCode": "string",
  "portLoCode": "string",
  "releaseIdentifier": {
    "billOfLadingNumbers": [
      "string"
    ],
    "equipmentNumber": "string",
    "releaseIdentification": "string"
  },
  "dataBrokerNxtEntityId": "string",
  "actionType": "1",
  "meansOfTransport": "2"
}

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. More info on notifications sent: Notifications for Transport Operators | Pick-up-Right-updated---barge-/-rail

Revoke Pick-up Right - barge / rail

Revokes the current Pick-up Right so that the container can’t be picked up with the registered means of transport.

When you have sent out a Pick up Right, the forwarding of the Release Right is disabled. If you want to forward the Release Right to another party, you should revoke the Pick up Right first.

PUT https://api.nxtport.com/certified-pickup/v1/pickup-rights/barge-rail

Request headers

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

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

  • Authorization: authorization bearer token

Path variables`

N/A

Query parameters

N/A

Distinct request body fields

  • "actionType": "Revoke" --- use int value: “2”

  • dataBrokerNxtEntityId --- can be ignored, not a mandatory value

  • Request body see the overview for an explanation of the fields

JSON
{
  "terminalCode": "string",
  "portLoCode": "string",
  "releaseIdentifier": {
    "billOfLadingNumbers": [
      "string"
    ],
    "equipmentNumber": "string",
    "releaseIdentification": "string"
  },
  "dataBrokerNxtEntityId": "string",
  "actionType": "2",
  "meansOfTransport": "2"
}

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}}?billOfLadingNumbers={{BL-numbers}}&releaseIdentification={{release-identification}}

Request Headers:

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

  • 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

  • releaseIdentification

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

JSON
{
  "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

JSON
{
    "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

JSON
{
  "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

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

N/A - fields have no meaning when 405 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. We don’t accept more than 500 calls per minute.


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

JSON
[
  {
    "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

JSON
{
    "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"

JSON
// 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

JSON
{
    "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

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

JSON
{
  "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

JSON
{
  "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:

JSON
{
    "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 endpoints (eg fill in the {portLocode} variable in the URL). 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.


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 that 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.

14

pickupParty> partyType

Enum

Yes

“Truck” / “Barge“ / “Rail“

Mode of transport with which the container will be picked up

As of , only Truck is supported. Other modes will follow shortly.

15

pickupParty> identificationType

Single value

Yes

“Alfapass“

Means of identification of the pick up party

Only Alfapass is allowed.

16

pickupParty> identificationCode

string

Yes

Free text

The value that belongs to the selected identification.

17

meansOfTransport

string

Yes

Enum: [ use int value: 0 (Truck), use int value: 1 (Barge), use int value: 2 (Rail), use int value: 99 (Unknown) ]

Mode of transport with which the container will be picked up.


Notifications

As explained about the asynchronous handling within the CPu process, you - as a Transport Operator - 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 Transport Operators .


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.