Documentation

Integration guidelines for the Certified Pick up API for the stakeholders with role Ship Agent

Ship Agent Integration guidelines

  1. Home
  2. Documentation
  3. Certified Pick-Up
  4. Ship Agent Integration guidelines

Quick links

Download the factsheet

Integration guidelines

Other


Introduction

This document describes how stakeholders of type “Ship Agent” should integrate the Certified Pick up process within their applications.

When an import container is commercially released, the Ship’s Agent typically sends a PIN code to the terminal and shares this code with the next party in the release chain (e.g. Forwarder, Transporter,…). 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 platform, the Ship Agent does not create and distribute a PIN code, increasing the security of the release chain. Instead, the Ship Agent sends the commercial release information towards the Certified Pick up 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.

This process runs in parallel with the existing sharing of CUSCAR information through the “Import Consignment” API.

By accepting the API specific Terms & Conditions of the Certified Pick up process, we can use your CUSCAR data to increase the data quality. This information will not be shared with external sources for other purposes, following our general Terms & Conditions.

Integrate using existing messages

The Certified Pick up (CPu) process consists of multiple data elements and actions. Most of these will be provided through dedicated API’s. However, to facilitate the integration of CPu with existing processes, it is possible for Ship Agents and Terminals to communicate with existing message types to the CPu Backbone.

Read more about integrating with existing message types (Coarri & Codeco).

Integrate using API's

Release Lights vs Release Rights

To ensure a secure container release at the terminal, three questions are vital: “Is it okay for the terminal that the container leaves the yard?” ,“Is it okay for the ship agent that a container leaves the terminal?” and “Which party is authorised to pick up the container?”.

Release Lights

Just like traffic lights indicate that you can cross a street, the Release Lights API is used to obtain/capture information about the “release status” of a container, i.e. can this container leave the terminal or not.
At this moment, two parties will need to give their permission concerning this departure, being the Terminal and the Ship Agent. Only these two parties will use the Release Lights API.

NxtPort is also integrating the Customs Release Light (CCRM). Until the direct link with Customs is functional, this light is included in the Terminal Release.

Release Rights

To know which party has the right to pick up a container at the terminal (assuming that both Terminal and Ship Agent have given their consent with the Release Lights API), a different API is used. When a commercial release has occurred, a “Release Right” is created and can be transferred from one party to another.

Your role as a Ship Agent

The Ship Agent provides crucial information that initiates the release proces: the Commercial release.
The most straightforward way to implement this, is by using the Release Lights API. Even more, if your call also provides information concerning the party you would like to give the Release Right to (e.g. Forwarder, BCO,…), the Release Lights API will be the only API you’ll need to integrate!

Process

Swagger files

Hostnames

Certified Pick-Up uses a separate API to ingest the Commercial Release information. Ship Agents therefore need to use two different endpoint hostnames when providing us the necessary information. Each of the API's described below will either mention {{HOST - Ingestion}} or {{HOST - CPU API}}. 

 

Receive and process Certified Pick up notifications

Certified Pick up uses a real-time asynchronous notification mechanism. GET requests are sent using the same mechanism to retrieve information from the platform. Even though this may be seen as a cumbersome solution while integration the Certified Pick up process, it increases security by adding a sort of “Two-factor Authentication” and prevents unauthorised access to information by 3rd parties. 

Each of the notifications that is triggered by the below API calls is listed. You can however also find the entire list of all notifications that are sent out, what triggers them and where you receive them on the Notification overview page. 

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.
Endpoint - Release Light

POST - {{HOST - Ingestion}}/[your dedicated channel-ID]

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
  "releaseIdentification": "string",
  "releaseOrderReference": "string",
  "equipmentNumber": "string",
  "equipmentType": "string",
  "billOfLadingNumbers": [
    "string"
  ],
  "portLoCode": "string",
  "terminalCode": "string",
  "actionType": "Release",
  "carrier": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
  },
  "releaseTo": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
  },
  "releaseDateTimeUtc": "2020-04-30T13:06:11.385Z",
  "expirationDateTimeUtc": "2020-04-30T13:06:11.385Z"
}
Field name
Type
Mandatory
Allowed value
Field Description
releaseIdentification String Yes Free text Unique release identification (per carrier)
releaseOrderReference String No Free text Release Order Reference
equipmentNumber String Yes Free text Container number
equipmentType String No Free text Use this field to indicate the type of equipment. You could use “Container” or the ISO container type code (eg 20GP or 22RT)
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
portLoCode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
terminalCode String Yes Free text The terminal where the container will be available for pickUp. Can be updated later on in the process.
actionType Enum Yes Release You can only use the value Release when you wish to do a commercial release
carrier >
identificationType 		String Yes Tin, Eori, Duns or APCS Enter the type of identification of the carrier.
Remark: Tin should be used for the VAT number of a company
carrier >
identificationCode 		String Yes String The value that belongs to the selected identification
releaseTo > identificationType String No Tin, Eori, Duns or 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 “Release Rights ” method.
Remark: Tin should be used for the VAT number of a company
releaseTo > identificationCode String No String The value that belongs to the selected identification. If the entry is valid, the release right will be given to the stated entity.
If the entry is not valid, you will still receive a 200 success response. A separate notification will be sent to your notification channel(s).
releaseDateTimeUtc DateTimeUTC Yes Date Time Date from which the Commercial release will be active
expirationDateTimeUtc DateTimeUTC No Date Time Date until which the Commercial release will be active. If not entered, there is no expiration date applied

When the 200 result is returned, the state of the container will be set to “Released”.

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

Notifications

  • In case the releaseTo party was entered, that party will receive a push notification of type “Release-Right” with action Transfer with the provided information about the container.
  • If the releaseTo party was not entered, the Release will remain with the Ship Agent that initiated the commercial release. He can decide later on to transfer the right to another party.
  • The terminal will receive a notification of type Release-Light with action “Release”
  • You will also receive a notification of type Release-Light with action “Release” as a confirmation of the action, including all details that you presented

The Certified Pick up API uses an async mechanism that does not allow to return a full json body. To verify the information that was stored, you can process the notification that will be sent to your notification channel(s) or use the "Get status of the release light" request.

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship agent” role

The below error message will be sent to your notification channel(s)


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

Update commercial release

For as long as the container is not yet picked up, the creator (the Ship 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
Endpoint - Release Light

POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
  "releaseIdentification": "string",
  "releaseOrderReference": "string",
  "equipmentNumber": "string",
  "equipmentType": "string",
  "billOfLadingNumbers": [
    "string"
  ],
  "portLoCode": "string",
  "terminalCode": "string",
  "actionType": "Update",
  "carrier": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
  },
  "releaseTo": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
  },
  "releaseDateTimeUtc": "2020-04-30T13:06:11.385Z",
  "expirationDateTimeUtc": "2020-04-30T13:06:11.385Z"
}
Field name
Type
Mandatory
Allowed value
Field Description
releaseIdentification String Yes Free text Unique release identification (per carrier)
releaseOrderReference String No Free text Release Order Reference
equipmentNumber String Yes Free text Container number
equipmentType String No Free text Use this field to indicate the type of equipment. You could use “Container” or the ISO container type code (eg 20GP or 22RT)
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
portLoCode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
terminalCode String Yes Free text The terminal where the container will be available for pickUp. Can be updated later on in the process.
actionType Enum Yes Update You can only use the value Update when you wish to do a commercial release
carrier >
identificationType 		String Yes Tin, Eori, Duns or APCS Enter the type of identification of the carrier.
Remark: Tin should be used for the VAT number of a company
carrier >
identificationCode 		String Yes String The value that belongs to the selected identification
releaseTo > identificationType String No Tin, Eori, Duns or 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 “Release Rights ” method.
Remark: Tin should be used for the VAT number of a company
releaseTo > identificationCode String No String The value that belongs to the selected identification. If the entry is valid, the release right will be given to the stated entity.
If the entry is not valid, you will still receive a 200 success response. A separate notification will be sent to your notification channel(s).
releaseDateTimeUtc DateTimeUTC Yes Date Time Date from which the Commercial release will be active
expirationDateTimeUtc DateTimeUTC No Date Time Date until which the Commercial release will be active. If not entered, there is no expiration date applied

When the 200 result is returned, the state of the container will be updated. The state will not change.

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

Notifications

A successful request will generate a notification of type Release-Light with action update that will be sent to

  • Your own notification channel  
  • The Terminal
  • The current Release Right owner (if the right was previously given)

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship agent” role

The below error message will be sent to your notification channel(s)


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

Block commercial release

For as long as the container is not yet picked up, the creator of the commercial release (the Ship 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.
Endpoint - Release Light

POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
 "releaseIdentification": "string",
 "equipmentNumber": "string",
 "billOfLadingNumbers": [
 "string"
 ],
 "actionType": "Block"
}
Field name
Type
Mandatory
Allowed value
Field Description
releaseIdentification String Yes Free text Unique release identification (per carrier)
equipmentNumber String Yes Free text Container number
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
actionType Enum Yes Block You can only use the value Block when you wish to block a commercial release

When the 200 result is returned, the state of the container will be set to “Blocked”.

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

Notifications

A successful request will generate a notification of type Release-Light with action blocked that will be sent to

  • Your own notification channel
  • The Terminal Towards
  • The Release Right owner (if the right was previously given)

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship agent” role

The below error message will be sent to your notification channel(s)


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

Unblock commercial release

When a container was previously blocked by the Ship Agent, he can unblock it.
Endpoint - Release Light

POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
 "releaseIdentification": "string",
 "equipmentNumber": "string",
 "billOfLadingNumbers": [
 "string"
 ],
 "actionType": "Unblock"
}
Field name
Type
Mandatory
Allowed value
Field Description
releaseIdentification String Yes Free text Unique release identification (per carrier)
equipmentNumber String Yes Free text Container number
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
actionType Enum Yes Unblock You can only use the value Unblock when you wish to block a commercial release

When the 200 result is returned, the state of the container will be set to “Released”.

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

Notifications

A successful request will generate a notification of type Release-Light with action unblocked that will be sent to

  • Your own notification channel
  • The Terminal Towards
  • The Release Right owner (if the right was previously given)

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship agent” role

The below error message will be sent to your notification channel(s)


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

Delete commercial release

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

POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
 "releaseIdentification": "string",
 "equipmentNumber": "string",
 "billOfLadingNumbers": [
 "string"
 ],
 "actionType": "Delete",
}
Field name
Type
Mandatory
Allowed value
Field Description
releaseIdentification String Yes Free text Unique release identification (per carrier)
equipmentNumber String Yes Free text Container number
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
actionType Enum Yes Delete You can only use the value Delete when you wish to delete a commercial release

When the 200 result is returned, the container will no longer be listed.

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

Notifications

  • If release right was previously transferred, the current release right owner will receive a push notification of type “Release-Right” with action Delete with the provided information about the container.
  • The terminal will receive a notification of type Release-Light with action “Delete”
  • You will also receive a notification of type Release-Light with action “Delete” as a confirmation of the action, including all details that you presented

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship agent” role

The below error message will be sent to your notification channel(s)


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

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.

Endpoint - Release Detail

GET - {Host}/certified-pickup/v1/{port-locode}/containers/import/release-rights/{equipment-number}

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter
  • billOfLadingNumbers: Bill of Lading number(s) of the container. Mandatory parameter.
  • releaseIdentification: The unique identification for te release. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

N/A

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

Notification

This is an example of the response you can expect over the predefined notification channel.

{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "equipmentNumber": "TTTT1234567",
    "releaseIdentification": "ReleaseID1",
    "billOfLadingNumbers": [
      "BOL001"
    ],
    "releaseOrderReference": "TTTT1234567",
    "terminalName": "Terminal name",
    "terminalCode": "01700",
    "portLoCode": "BEANR",
    "lights": [
      {
        "greenLightName": "CommercialRelease",
        "greenLightValue": "OK",
        "color": 1,
        "label": "Commercial Release",
        "isEnabled": true,
        "isVisible": true
      },
      {
        "greenLightName": "TerminalReady",
        "greenLightValue": "RELEASED",
        "color": 1,
        "label": "Terminal Ready",
        "isEnabled": true,
        "isVisible": true
      },
      {
        "greenLightName": "TerminalOperation",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Terminal Operation",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "CCRM",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Customs Release",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "NGPS",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Customs Status",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "GateOperation",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Gate Operation",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "PickupLight",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Pick-up Light",
        "isEnabled": true,
        "isVisible": true
      }
    ],
    "releaseDateTimeUtc": "2020-12-19T00:00:00Z",
    "expirationDateTimeUtc": "2020-12-20T00:00:00Z",
    "shippingAgentName": "agent name",
    "publicReferenceId": "498ea4e5-6b32-4020-8254-66695d03c194",
    "externalReferenceId": null
  },
  "errors": [],
  "event": "GetReleaseDetail",
  "externalReferenceId": null,
  "id": "Unknown",
  "publicReferenceId": "498ea4e5-6b32-4020-8254-66695d03c194",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T09:01:09.4563365Z",
  "type": "ReleaseRight",
  "warnings": []
}
{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notification

This is an example of the response you can expect over the predefined notification channel.

{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": "Could not find release right for unique key TCLU1036476, BOL0001 BOL0002, ReleaseIdentifcation01"
  "errors": [],
  "event": "NotValidated",
  "externalReferenceId": null,
  "id": "TCLU1036476",
  "publicReferenceId": "f7f13626-b1d5-40ed-a3c4-5cfffb852d57",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T09:44:34.8243447Z",
  "type": "ReleaseRight",
  "warnings": []
}

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship Agent” role OR
  • You are the current owner of the Release Right of the requested container

The below error message will be sent to your notification channel(s)


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

Release Rights

Get your release rights

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.
Endpoint - Release Rights

GET - {{HOST - CPU API}}/certified-pickup/v1/{port-locode}/containers/import/release-rights

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.

Headers

  • External-Reference-Id (optional); Your own reference (string)

When performing the get method, a list of parameters can be used to filter the results. All results will automatically be filtered to list only Pick up Rights linked to the Stakeholder that performs the request.

Available filters

Field name
Type
Mandatory
Allowed value
Field Description
billofladingnumberfilter String No Free text Filters the rights depending on the Bill of Lading number. Uses the %like% statement. Not case sensitive.
currentstakeholdernamefilter String No Free text Filters the rights depending on the current stakeholder. This allows you
  • To filter pending rights from a specific Stakeholder which you still need to accept.
  • Return all rights where you are the owner (which you already accepted)
equipmentnumberfilter String No Free text Filters the rights depending on the Equipment number. Uses the %like% statement allowing you to filter through all containers of a specific carrier. Not case sensitive.
page Integer Yes Defaults to 1 The response uses paging. Page numbering starts at 1. Default is 1.
pageSize Integer Yes Number The response uses paging. No default set. To reduce process time we suggest to limit between 25 to 100 in pageSize
portLoCode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
status Enumeration No Unknown, Assigned, Pending, Accepted, Declined, Revoked, Archived, Paused, Expired, Resumed Returns only the rights in the specified status.
status Enumeration Yes Active, Pending
  • Active will return all release rights that are assigned to you
  • Pending will return all release rights which are awaiting acceptance from you

Body

N/A

Response fields

Field name Type Mandatory Allowed value Field Description
equipmentNumber String Yes Free text Container number
billOfLadingNumbers String Yes Free text Bill of Lading number(s) of the container
releaseFrom > identificationType Sting Yes Tin, Eori, Duns or APCS Enter the type of identification of the party that will forward the Release Right.
releaseFrom > identificationCode String Yes String The value that belongs to the selected identification
releaseTo > identificationType String Yes Tin, Eori, Duns or APCS Enter the type of identification of the party that will receive the Release Right
releaseTo > identificationCode String Yes String The value that belongs to the selected identification
actionType Enum Yes Accept You can only use the value “Accept” when you wish to accept a transferrede Release Right. The right will be transferred to your entity.
actionReason String No Free text Can be used to add a comment or reason for accepting the Pick up right

When the 200 result is returned, the call was successful and the information of the requested container will be sent to your Notification Channel(s). This is the information that will be sent to the notification channel with type Release-Right and action “overview”

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

Notifications

 {
        "timestamp": "2019-08-28T09:41:18Z",
        "publicReferenceId": "6d113ff6-4805-430f-be32-d8918fab83f1",
        "privateReference": "your-reference-here",
        "senderId": "NxtDummy001",
        "receiverId": "NxtDummy002",
        "asset": "Certified Pick Up",
        "id": "your-reference-here",
        "type": "Commercial Release Right",
        "action": "overview",
        "body": {
            "currentStakeholder": {
                "identificationType": "Eori",
                "identificationCode": "string"
            },
            "page": 0,
            "pageSize": 0,
            "dateStart": "2020-05-05T15:06:23.642Z",
            "dateEnd": "2020-05-05T15:06:23.642Z",
            "status": "string",
            "billOfLadingNumberFilter": "string",
            "shippingAgentNameFilter": "string",
            "shippingAgentTinFilter": "string",
            "currentStakeholderNameFilter": "string",
            "currentStakeholderTinFilter": "string",
            "releaseRightStatusFilter": "Unknown",
            "result": [
                {
                    "equipmentNumber": "string",
                    "expirationDateTimeUtc": "2020-05-05T15:06:23.642Z",
                    "operationalStatus": "Unknown",
                    "originatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "originatorName": "string",
                    "releaseDateTimeUtc": "2020-05-05T15:06:23.642Z",
                    "terminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "terminalName": "string",
                    "terminalCode": "string",
                    "portLoCode": "string",
                    "startDate": "2020-05-05T15:06:23.642Z",
                    "releaseFromId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "releaseFromName": "string",
                    "releaseFromNxtEntityId": "string",
                    "releaseFromVatNumber": "string",
                    "releaseToId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "releaseToName": "string",
                    "releaseToNxtEntityId": "string",
                    "releaseToVatNumber": "string",
                    "releaseRightStatus": "Unknown",
                    "billOfLadingNumbers": [
                        "string"
                      ],
                    "actions": [
                        {
                            "label": "string",
                            "isEnabled": true
                        }
                      ]
                }
            ]
        },
        "errors": [],
        "warnings": []
    }

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform

The below error message will be sent to your notification channel(s)


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

Transfer a release right

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.
Endpoint - Release Right

PUT - {{HOST - CPU API}}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/release-rights

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
  "releaseIdentification": "string",
  "equipmentNumber": "string",  
  "billOfLadingNumbers": [
    "string"
  ],
  "portLoCode": "string",
  "terminalCode": "string",
  "carrier": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
  },
  "actionType": "Transfer",
  "reasonForAction": "string",
  "releaseFrom": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
  },
  "releaseTo": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
}
Field name Type Mandatory Allowed value Field Description
releaseIdentification String Yes Free text Unique release identification (per carrier)
equipmentNumber String Yes Free text Container number
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
portLoCode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
terminalCode String No Free text The terminal where the container will be available for pickUp. Can be updated later on in the process
actionType Enum Yes Transfer You can only use the value Transfer when you wish to transfer the Release Right
carrier >
identificationType 		String Yes Tin, Eori, Duns or APCS Enter the type of identification of the carrier.
carrier >
identificationCode 		String Yes String The value that belongs to the selected identification
releaseFrom > identificationType String Yes Tin, Eori, Duns or APCS Enter the type of identification of the party that will send the Release Right.
releaseFrom > identificationCode String Yes String The value that belongs to the selected identification. If the entry is valid, the release right will be taken from the stated entity.This information will be validated against the current Release Right owner in the Certified Pick up database.
releaseTo > identificationType String Yes Tin, Eori, Duns or 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
releaseTo > identificationCode String Yes String The value that belongs to the selected identification. If the entry is valid, the release right will be given to the stated entity.

When the 200 result is returned, the right to Pick up the container will be transferred to the provided recipient. He will have the possibility to accept or decline this right.

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

Notifications

  • A notification of type Release-Right with event transferSent will be to your own notification channel
  • A notification of type Release-Right with event transferred will be sent to the party that needs to accept or decline the right

To get the current state of a container, please refer to to the Get status of the release light section of this document.

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You are the Ship agent that released the container
The below error message will be sent to your notification channel(s)

 


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
HTML
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.

Revoke a release right

For as long as the Release Right has not been accepted by the next party, the transfer of the Release Right can be revoked.
Endpoint - Release Right

PUT - {{HOST - CPU API}}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/release-rights

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
 "releaseIdentification": "string",
 "equipmentNumber": "string",
 "billOfLadingNumbers": [
 "string"
 ],
 "actionType": "Revoke",
 "reasonForAction": "string",
}

 

Field name Type Mandatory Allowed value Field Description
releaseIdentification String Yes Free text Unique release identification (per carrier)
equipmentNumber String Yes Free text Container number
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
actionType Enum Yes Revoke You can only use the value Revoke when you wish to revoke the Release Right

When the 200 result is returned, your request has been successfully received. A notification of type “revoked” will be sent to your notification channel(s). 

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

Notifications

  • A notification of type Release-Right with event revoked will be to your own notification channel
  • A notification of type Release-Right with event revokedByPreviousParty will be sent to the party that needs to accept or decline the right

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You are the current owner of the Release Right of the container
The below error message will be sent to your notification channel(s)

 


{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}
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.

Bulk actions for 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
Endpoint - Release Right

PUT - {Host}/certified-pickup/v1/{port-locode}/containers/import/release-rights

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.

Body

{
  "portLoCode": "string",
  "releaseRights": [
    {
      "releaseFrom": {
        "identificationType": "NxtEntityId",
        "identificationCode": "string"
      },
      "releaseTo": {
        "identificationType": "NxtEntityId",
        "identificationCode": "string"
      },
      "terminalCode": "string",
      "billOfLadingNumbers": [
        "string"
      ],
      "equipmentNumber": "string",
      "releaseIdentification": "string"
    }
  ],
  "actionType": "Transfer"
}
Field Name Type Mandatory Allowed Value Field Description
portLocode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
releaseRights Array of ReleaseRights to which the ReleaseRight action should be applied Yes (at least one) N/A  
releaseFrom > identificationType String Yes Tin, Eori, Duns or APCS Enter the type of identification of the party that will send the Release Right. Remark: Tin should be used for the VAT number of a company If this information is not included in the body, Eori will be automatically filled.
releaseFrom > identificationCode String Yes String The value that belongs to the selected identification.
releaseTo > identificationType String Yes Tin, Eori, Duns or 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
releaseTo > identificationCode String Yes String The value that belongs to the selected identification. If the entry is valid, the release right will be given to the stated entity.
terminalCode String Yes Free text The terminal where the container will be available for pickUp.
billOfLadingNumbers Array of strings Yes Free text The unique combination of Container/BL/ReleaseIdentification will be used for the identification of the Container Release
equipmentNumber String Yes Free text Container number
releaseIdentification String Yes Free text Unique release identification
actionType Enum Yes Transfer / Accept / Decline / Revoke  

When the 202 result is returned, the right to Pick up the container will be granted to your entity. 

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

Notifications

A notification of type ReleaseRight with event Transferred, Accepted or Declined will be to

  • Your own notification channel
  • The ship agent
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT20000012345",
      "name": "sender name",
      "eori": "",
      "tin": "sender vat"
    },
    "carrier": {
      "nxtEntityId": "NXT20000012345",
      "name": "carrier name",
      "eori": "",
      "tin": "carrier vat"
    },
    "releaseTo": {
      "nxtEntityId": "NXT20000012345",
      "name": "releaseto name",
      "eori": "",
      "tin": "release to vat"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT20000013245",
      "name": "release form name",
      "eori": "",
      "tin": "release from vat"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "12345",
    "actionType": "Transfer",
    "reasonForAction": null,
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
    "expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
  },
  "errors": [],
  "event": "Transferred",
  "externalReferenceId": null,
  "id": "test1234",
  "publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
  "receiverId": "NXT20000012345",
  "senderId": null,
  "timestamp": "2021-01-04T15:28:35.9434964Z",
  "type": "ReleaseRight",
  "warnings": []
}

Response from the webservice

{

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

Notifications

When a SubmitReleaseRightAction with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer, revoke) or next owner (during accept, decline), a notification of type ReleaseRight with event NotValidated will be sent to

  • Your own notification channel
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": "Unable to perform SubmitReleaseRight action 'Accept' on TCLU1036476 due to invalid identification",
  "errors": [],
  "event": "NotValidated",
  "externalReferenceId": null,
  "id": "TCLU1036476",
  "publicReferenceId": "f7f13626-b1d5-40ed-a3c4-5cfffb852d57",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T09:44:34.8243447Z",
  "type": "ReleaseRight",
  "warnings": []
}

Response from the webservice

{

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

Notifications

When a SubmitReleaseRightAction with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer, revoke) or next owner (during accept, decline), a notification of type ReleaseRight with event NotValidated will be sent to

  • Your own notification channel
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": "Could not find release right for unique key TCLU1036476, BOL0001 BOL0002, ReleaseIdentifcation01,
  "errors": [],
  "event": "NotValidated",
  "externalReferenceId": null,
  "id": "TCLU1036476",
  "publicReferenceId": "f7f13626-b1d5-40ed-a3c4-5cfffb852d57",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T09:44:34.8243447Z",
  "type": "ReleaseRight",
  "warnings": []
}

Response from the webservice

{

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

Notifications

When a SubmitReleaseRight revoke is performed on on a releaseright that is not ‘pending’ (awaiting accept or decline) but instead is f.e. active, a notification of type ReleaseRight with event NotValidated will be sent to

  • Your own notification channel
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": ""Unable to perform SubmitReleaseRight action 'Revoke' on TCLU1036476 because Release right is not 'Pending' but 'Accepted'",
  "errors": [],
  "event": "NotValidated",
  "externalReferenceId": null,
  "id": "TCLU1036476",
  "publicReferenceId": "f7f13626-b1d5-40ed-a3c4-5cfffb852d57",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T09:44:34.8243447Z",
  "type": "ReleaseRight",
  "warnings": []
}

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-6ac8efacdba6f34aaf1718ce200618cd-05fdac685dad4745-00",
    "errors": {
        "PortLoCode": [
            "'Port Lo Code' must be equal to 'BEANR'."
        ]
    }
}

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You are the current owner of the Release Right of the container
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.

Company Registery

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.

Applies to

  • Forwarders
  • Terminals
  • Ship agents
Endpoint - Company Registry

GET - {Host}/certified-pickup/v1/entities

Swagger link
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
  • EntityName (optional) : an entity with a (partially) matching name will be queried in our register
  • ApcsCode (optional) : an entity with matching ApcsCode will be queried in our register
  • Page (default to 1) : determine which page of the results is queried
  • PageSize (default to 25) : determine the pagesize of the queried results 
{
  "searchFilter": {
    "eori": "string",
    "duns": "string",
    "vat": "string",
    "entityName": "string",
    "apcsCode": "string",
    "page": 0,
    "pageSize": 0
  },
  "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"
    }
  ],
  "totalRows": 0,
  "totalPages": 0,
  "publicReferenceId": "string",
  "externalReferenceId": "string"
}
{
    "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'."
        ]
    }
}

Solutions built for ports

We introduce you to the port of tomorrow. Join the community and help your port be on the forefront of innovation!

Documentation

Contact

The Beacon - 5th floor Sint-Pietersvliet 7 2000 Antwerp Belgium

More info

Register your company