Skip to main content
Skip table of contents

Shipping Agent Integration Specifications

While all parties involved in the container import flow will be prompted to give release information, only two parties are considered to be “data providers”. These entities, being Shipping Agents and Terminal Operators, need to give their approval before a container can be picked up.

To participate in Certified Pick up (CPu) as a Shipping Agent, you will need to follow the steps described below:

  • register and subscribe to CPu. You can find more information on this in the Getting Started with the API integration guide

  • testing must be performed on User Acceptance Testing environment before moving to Production

CPu requires you to provide the following actions / functions / transactions:

  • submit Commercial Release information

  • identify your First Release Party

These actions can be performed in a single call but are handled as separate events.

This document describes how stakeholders of type Shipping Agent 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 of the Getting Started guide 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

It is your responsibility to inform NxtPort in advance about which message type you’re using, as it requires a different setup on our end. You should have provided us this info during your onboarding as described in the Getting Started guide.

General remarks

Distinct request body fields

For different actions (submit, update, 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: both your API key and the your_ingestion_id path variable are environment specific, so these also need to be changed if you call our UAT environment.


Release Lights

Submit commercial release

The commercial release is the starting point of a Certified Pick up. To perform a commercial release, use the following information.

This will create the commercial release, set the Commercial Release Light to GREEN, while at the same time creating the first Release Right in the process.

Without having created a commercial release, no other data will be visible and no other actions will be handled in the CPu process.

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

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

  • Authorization : authorization header (Bearer token)

Path variables

  • your_ingestion_id: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding

Query Parameters:

N/A

Distinct request body fields

  • "actionType" : "Release"

Request body see the overview for an explanation of the fields

JSON
{
  "releaseIdentification": "",
  "releaseOrderReference": "",
  "emptyReturnReference": "",
  "equipmentSupplier": "",
  "equipmentStatus": "",
  "fullEmptyIndicator": "",
  "equipmentOperator": "",
  "vesselName": "",
  "vesselNumber": "",
  "stayNumber": "",
  "vesselCallSign": "",
  "voyageNumber": "",
  "equipmentType": "",
  "isCarrierHaulage": ,
  "meansOfTransport": "",
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "terminalCode": "",
  "actionType": "Release",
  "carrier": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseTo": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseDateTimeUtc": "",
  "expirationDateTimeUtc": "",
  "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 commercial release

For as long as the container is not yet picked up, the creator (Shipping Agent) is able to update the release information. This can be done for example:

  • to postpone or limit the period during which the release is allowed

  • to change the terminal where the container will be ready for pick up

All information can be updated, except for "ReleaseTo", "equipmentNumber" and "billOfLadingNumbers". If you want to make a correction on one of these, you'll have to delete the first record and send in a new Commercial Release.

If you update the commercial release, all information will be overwritten. This means you will have to provide all information concerning this release, and not only the updated fields!

The difference between using an “Update” and deleting a release/create a new release is that in the first case the Release Right remains where it is, while in the latter the release proces has to restart.

As an example we take the case that a transporter has the Release Right of a container that is about to expire tomorrow. You want to add one week to the validity period of the release.

  • If you use “update” to extend the validity of the Release Right, the Right remains at the transport company. They can pick up the container in the next days.

  • If you delete the release and create a new one, the transport company has lost its Release Right! They’ll have to receive the Release Right again before they can perform any actions!

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

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

  • Authorization : authorization header (Bearer token)

Path variables

  • your_ingestion_id: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding

Query Parameters:

N/A

Distinct request body fields

  • "actionType" : "Update"

Request body see the overview for an explanation of the fields

JSON
{
  "releaseIdentification": "",
  "releaseOrderReference": "",
  "emptyReturnReference": "",
  "equipmentSupplier": "",
  "equipmentStatus": "",
  "fullEmptyIndicator": "",
  "equipmentOperator": "",
  "vesselName": "",
  "vesselNumber": "",
  "stayNumber": "",
  "vesselCallSign": "",
  "voyageNumber": "",
  "equipmentType": "",
  "isCarrierHaulage": ,
  "billOfLadingNumbers": [
    "",
    ""
  ],
  "terminalCode": "",
  "actionType": "Update",
  "carrier": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseTo": {
    "identificationType": "",
    "identificationCode": ""
  },
  "releaseDateTimeUtc": "",
  "expirationDateTimeUtc": "",
  "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.

The endpoint to delete a commercial release is identical to the one that is used when submitting a commercial release. Therefore, the responses will also be the same.

Notifications

A successful request will generate a notification of type ReleaseLight with action Update that will be sent to

  • your own notification channel

  • the Terminal Operator and

  • the Release Right owner (if the Right was already transferred)


Block commercial release

For as long as the container is not yet picked up, the creator of the commercial release (Shipping Agent) is able to block the commercial release Light. In case a Release Right was previously granted, this remains unchanged. As such, once the commercial Release Light becomes unblocked, the process can continue without the need to restart the Release Right transfers.

This call will block the commercial release. This will put the Commercial Release Light to RED.

In the “blocked” state, the Release Right can still be transferred. However, for as long as the container is blocked, it cannot be picked up at the terminal!

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

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

  • Authorization: authorization header (Bearer token)

Path variables

  • your_ingestion_id: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding

Query Parameters:

N/A

Distinct request body fields

  • "actionType" : "Block"

Request body see the overview for an explanation of the fields

JSON
{
    "releaseIdentification": "",
    "equipmentNumber": "",
    "equipmentType": "",
    "billOfLadingNumbers": [
        "",
        ""
    ],
    "portLoCode": "",
    "terminalCode": "",
    "actionType": "Block"
}

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.

The endpoint to delete a commercial release is identical to the one that is used when submitting a commercial release. Therefore, the responses will also be the same.

Notifications

A successful request will generate a notification of type ReleaseLight with action Blocked that will be sent to

  • your own notification channel

  • the Terminal Operator and

  • the Release Right owner (if the Right was already transferred)


Unblock commercial release

When a container was previously blocked by the Shipping Agent, they can unblock it.

This call will unblock the commercial release and put the commercial light to GREEN.

“Unblock” means “if this container has been blocked (by me) before, remove this blockage”. If no blocks were present on the container, this call will do nothing.

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

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

  • Authorization: authorization header (Bearer token)

Path variables

  • your_ingestion_id: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding

Query Parameters:

N/A

Distinct request body fields

  • "actionType" : "Unblock"

Request body see the overview for an explanation of the fields

JSON
{
    "releaseIdentification": "",
    "equipmentNumber": "",
    "equipmentType": "",
    "billOfLadingNumbers": [
        "",
        ""
    ],
    "portLoCode": "",
    "terminalCode": "",
    "actionType": "Unblock"
}

It is not allowed to update other information when unblocking a Release. This will result in a 405 error message.

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.

The endpoint to delete a commercial release is identical to the one that is used when submitting a commercial release. Therefore, the responses will also be the same.

Notifications

A successful request will generate a notification of type ReleaseLight with action Unblocked that will be sent to

  • your own notification channel

  • the Terminal Operator and

  • the Release Right owner (if the Right was already transferred)


Revoke commercial release

For as long as the container is not yet picked up, the creator of the commercial release (Shipping Agent) is able to revoke the commercial release Light. In case the Release Right is returned to its originator.

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

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

  • Authorization: authorization header (Bearer token)

Path variables

  • your_ingestion_id: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding

Query Parameters:

N/A

Distinct request body fields

  • "actionType" : "Revoke"

Request body see the overview for an explanation of the fields

JSON
{
    "releaseIdentification": "",
    "equipmentNumber": "",
    "equipmentType": "",
    "billOfLadingNumbers": [
        "",
        ""
    ],
    "portLoCode": "",
    "terminalCode": "",
    "actionType": "Revoke"
}

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.


Delete commercial release

For as long as the container is not yet picked up, the creator of the commercial release (Shipping Agent) is allowed to delete the commercial release. This will remove the container from the active system.

It is not allowed to update other information when deleting a Release Light. This will result in a 405 error message.

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

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

  • Authorization: authorization header (Bearer token)

Path variables

  • your_ingestion_id: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding

Query Parameters:

N/A

Distinct request body fields

  • "actionType" : "Delete"

Request body see the overview for an explanation of the fields

JSON
{
    "releaseIdentification": "",
    "equipmentNumber": "",
    "equipmentType": "",
    "billOfLadingNumbers": [
        "",
        ""
    ],
    "portLoCode": "",
    "terminalCode": "",
    "actionType": "Delete"
}

It is not allowed to update other information when deleting a Release Light. This will result in a 405 error message.

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.

The endpoint to delete a commercial release is identical to the one that is used when submitting a commercial release. Therefore, the responses will also be the same.

Notifications

A successful request will generate a notification of type ReleaseLight with action Delete that will be sent to

  • your own notification channel

  • the Terminal Operator and

  • the Release Right owner (if the Right was already transferred)


Release Rights

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.

Every Certified Pick up user is able to retrieve the list of all Pick up Rights that he is entitled to. For a Ship’s agent, this means he can get a list of all commercially released containers for which the release right has not yet been transferred.

To maximize security, the response to this call will be a JSON file that will be sent to your notification channel and will not be returned in the result. You can read more on how to setup notification channels in our console here.

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.


Transfer your Release Rights

Transfer the Release Rights to the next company.

In case the Release Right was not provided when submitting the Release Light (the releaseTo party was not entered), the Ship Agent can (if he doesn’t decide to keep the Release Right within his own entity) transfer the Release Right to another party, allowing them to initiate the Pick up of the container.

When a “releaseTo” party was present in the “Release Lights” Submit call, you can’t use this method as the Release Right is automatically given. You need to delete and resubmit the Release Light in case you wish to transfer the Right to another party or Revoke the right if the ReleaseTo party did not yet accept it.

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 Pick up 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 header (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": "",
    "equipmentNumber": "",
    "billOfLadingNumbers": [
        "",
        ""
    ],
    "portLoCode": "",
    "terminalCode": "",
    "carrier": {
        "identificationType": "",
        "identificationCode": ""
    },
    "actionType": "Transfer",
    "reasonForAction": "",
    "releaseFrom": {
        "identificationType": "",
        "identificationCode": ""
    },
    "releaseTo": {
        "identificationType": "",
        "identificationCode": ""
    }
}

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 your Release Rights

If a release right is not Accepted or Declined by the next party then the current owner can still return the right back to them.

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 header (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": "",
    "equipmentNumber": "",
    "billOfLadingNumbers": [
        "",
        ""
    ],
    "portLoCode": "",
    "terminalCode": "",
    "carrier": {
        "identificationType": "",
        "identificationCode": ""
    },
    "actionType": "Revoke",
    "reasonForAction": "",
    "releaseFrom": {
        "identificationType": "",
        "identificationCode": ""
    },
    "releaseTo": {
        "identificationType": "",
        "identificationCode": ""
    }
}

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.


Bulk actions on Release Rights

It is possible to send multiple actions with a single request by using this bulk method. The following actions are supported: 

  • Transfer

  • Accept

  • Decline

  • Revoke

PUT 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

Distinct request body fields

"actionType": "<supported action>"

The following actions are supported: 

  • "Transfer"

  • "Accept"

  • "Decline"

  • "Revoke"

Request Body see the overview for an explanation of the fields

JSON
{
    "portLoCode": "",
    "releaseRights": [
        // Array of ReleaseRights to which the ReleaseRight action should be applied
        // repeat below releaseRight object as often as needed
        // at least one object is needed
    ],
    "actionType": "<supported action>"
}

“releaseRight” object

1 call per action type. Repeat the below object as often as needed.

JSON
{
    "releaseFrom": {
        "identificationType": "",
        "identificationCode": ""
    },
    "releaseTo": {
        "identificationType": "",
        "identificationCode": ""
    },
    "terminalCode": "",
    "billOfLadingNumbers": [
        "",
        ""
    ],
    "equipmentNumber": "",
    "releaseIdentification": ""
}

Example with two objects and action Transfer
JSON
{
    "portLoCode": "BEANR",
    "releaseRights": [
        {
            "releaseFrom": {
                "identificationType": "NxtEntityId",
                "identificationCode": "NXT220000000"
            },
            "releaseTo": {
                "identificationType": "NxtEntityId",
                "identificationCode": "NXT221111111"
            },
            "terminalCode": "01700",
            "billOfLadingNumbers": [
                "BL1234567"
            ],
            "equipmentNumber": "CAIU7654321",
            "releaseIdentification": "ReleaseID7654321"
        },
        {
            "releaseFrom": {
                "identificationType": "NxtEntityId",
                "identificationCode": "NXT220000000"
            },
            "releaseTo": {
                "identificationType": "NxtEntityId",
                "identificationCode": "NXT221111111"
            },
            "terminalCode": "01700",
            "billOfLadingNumbers": [
                "BL11223344"
            ],
            "equipmentNumber": "CAIU1234567",
            "releaseIdentification": "ReleaseID1234567"
        }
    ],
    "actionType": "Transfer"
}

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 (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

  • 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 1.0 (deprecated)

This version of the notification service will be retired with CPu release 2.25 . Please use version 2.0 (see below).

This API call allows you to retrieve the notification(s) sent to your notification channel by CPu. You will need either the equipment number OR the Public Reference ID OR the External Reference ID. Values can be combined.

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

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

Request Headers:

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

  • Authorization: authorization header (Bearer token)

Path Variables:

N/A

Query Parameters:

N/A

Request Body

JSON
{
    "equipmentNumber": "",
    "publicReferenceId": "",
    "externalReferenceId": ""
}

If you don’t supply all 3 identifiers, other values must be null

  • equipmentNumber: self-explanatory;

  • publicReferenceId: the Public Reference ID you received in the synchronous API response;

  • externalReferenceId: the External Reference ID you supplied in your call.

Response & notifications

This is an synchronous call, you will get a direct API response:

Response code

Response status

Response body

Remarks

200

OK

JSON
[
  {
    "nxtEntityId": "",
    "equipmentNumber": "",
    "publicReferenceId": "",
    "externalReferenceId": "",
    "storedOn": "",
    "message": ""
  }
  // object repeated for all notifications
]
  • nxtEntityId: your own NxtPort ID

  • equipmentNumber: self-explanatory

  • publicReferenceId: as provided in request body

  • externalReferenceId: as provided in request body

  • storedOn: the creation time (UTC) of the notification as ISO timestamp

  • message: the notification as JSON string

200

OK

JSON
[
  // empty array
]

The provided data is unknown in our system. Check your request body for any errors.

401

Unauthorized

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

Your API key is not allowed to retrieve this data. Check if your API key is correct.

401

Unauthorized

Response header:

WWW-Authenticate: Bearer error="invalid_token"

JSON
// empty object

The notification you requested was not sent to your company. Check the request body for any errors.

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.


Notification Service 2.0

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

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

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"

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

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

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

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

releaseOrderReference

string

No

Free text

Optional reference for you to identify the release internally.

3

emptyReturnReference

string

No

Free text

Self-explanatory

4

equipmentSupplier

string

No

Free text

Self-explanatory

5

equipmentStatus

Enum

No

“Import” / “Export” / “Transhipment”

Self-explanatory

6

fullEmptyIndicator

Enum

No

“Full” / “Empty“

Self-explanatory

7

equipmentOperator

string

No

Free text

Self-explanatory

8

vesselName

string

No

Free text

Self-explanatory

9

vesselCallSign

string

No

Free text

Self-explanatory

10

voyageNumber

string

No

Free text

Self-explanatory

11

equipmentType

string

No

ISO container type (e.g. “20GP“, “40HC“)

or

“Container”

Self-explanatory

12

isCarrierHaulage

boolean

Yes

true, false

A boolean value indicating if the release is carrier haulage (true) or merchant haulage (false). For invoicing purposes.

13

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.

14

terminalCode

string

Yes

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

The indicative terminal where the container will be available for pickup. Can be updated at any time using the Update Commercial Release.

15

actionType

Enum

Yes

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

Action which is sent to the CPu platform, e.g. “Release”, “Block“, “Update“

16

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.

17

carrier> identificationCode

string

No

Free text

The value that belongs to the selected identification.

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

18

releaseTo> identificationType

Enum

No

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

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

If the releaseTo party is not yet known at the moment of the commercial release, this information can be left out and updated later on in the process by using the Transfer Release Right method.

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

19

releaseTo> identificationCode

string

No

Free text

The value that belongs to the selected identification.

Note: When carrier and releaseTo are not provided, the Release Right will automatically be assigned to the submitting Shipping Agent.

20

releaseFrom> identificationType

Enum

No

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

21

releaseFrom> identificationCode

string

No

Free text

The value that belongs to the selected identification.

22

releaseDateTimeUtc

string

Yes

ISO 8601 timestamp format in UTC time. E.g. 2022-09-17T09:35:25.189Z

Date/time (UTC) from which the Commercial Release will be active.

23

expirationDateTimeUtc

string

No

ISO 8601 timestamp format in UTC time. E.g. 2022-09-17T09:35:25.189Z

Date/time (UTC) until the Commercial Release is active. If not entered, a default of 60 calendar days will be applied.

24

equipmentNumber

string

Yes

Free text

The container number. This number will be used onwards in the process.

25

portLoCode

string

Yes

UN/LoCode

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

26

reasonForAction

string

No

Free text

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

27

meansOfTransport

Enum

No

“Truck“ / “Barge“ / “Rail“ / “Unknown“

Reported means of transport for post-carriage of the container

28

vesselNumber

string

No

IMO number of vessel

Self-explanatory

29

stayNumber

string

No

Stay number assigned by port authority

e.g. V234555


Notifications

As explained about the asynchronous handling within the CPu process, you - as a Shipping Agent - 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 Shipping Agents .


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.