Documentation

Integration guidelines for the Certified Pick up API for the stakeholders with role Forwarder/Transport Company and BCO

Forwarder Integration guidelines

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

Quick links

Download the factsheet

Integration guidelines

Other

Two environments

Certified Pick up uses two different environments. A UAT or testing environment (operational as of September 2020) and a Production environment (operational as of December 15th 2020). When reading this document, please use the relevant environment URL's and credentials. When you intend to use both environments, please remember that each of the environments will require each of the steps (signup, credentials, ...)

Asynchronous Notification response (webhooks)

Certified Pick up uses an asynchronous notification mechanism using HTTP post end points/webhooks. This means GET or POST calls will not generate a response with a body other than a Public Reference ID. Any response will be sent to your configured HTTPS endpoint(s). For further information on how to setup your notification channels, please refer to the corresponding tutorial.

Introduction

This document describes how stakeholders of type “Forwarder”, “Transport Company” or “Beneficial Cargo Owner (BCO)” should integrate the Certified Pick up process within their applications.

When an import container is commercially released, a 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, Transport Company, BCO,…). 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, a Ship Agent will not create and distribute a PIN code to the Terminal, 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. The code to release the container will be sent via a secured and audited communication channel towards the Terminal.

Your role in the supply chain

Forwarders, Transport Companies or BCO’s can receive the right to pick up cargo (ie a container) from the Ship Agent, once they have completed all necessary commercial agreements. As soon as the Terminal provides the terminal release (including the discharge confirmation and customs release), the container will be ready for pick up at the yard. The owner of the Pick up right can either decide to pick up the cargo themselves or distribute the right to pick up the container further down the supply chain.

The most straightforward way to implement this, is by using the Release Lights API.

Process

Swagger files

Hostnames 

Receive and process Certified Pick up notifications

Certified Pick up uses a real-time asynchronous notification mechanism. This means that, once the right to pick up a container is submitted or transferred, a notification is sent towards the other stakeholders. (the new Release Right owner.)

Several notifications, can be received. In the notification, the “Event” field allows to identify one of the following actions:

  • Transferred, in case you have received a Release Right from a previous party
  • Accepted, in case you successfully accepted a Release Righ from a previous party
  • Declined, in case you successfully declined a Release Righ from a previous party
  • revokedByPreviousParty, in case you successfully revoked a Release Right from the next Party

To setup your notification channels, you can find detailed information on our Wiki pages.

Every notification that is sent by NxtPort will be built up with a generic part, allowing integrators to identify the asset, sender, error or warning messages and a Use case or type specific body. 

Each of the below requests will show you an example of the possible notifications that can be sent. You call view them by clicking on the title, which will unfold a json file. 


Manage Release Rights

Accept release Rights

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

PUT - {Host}/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"
    ],
    "releaseFrom": {
        "identificationType": "string",
        "identificationCode": "string"
    },
    "releaseTo": {
        "identificationType": "string",
        "identificationCode": "string"
    },
    "actionType": "Accept",
    "actionReason": "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 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

Webservice response

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

Notifications

If the release right request was successfully processed, a notification of type "ReleaseRight" and action "Accepted" is sent to
  • your own notification channel
  • the ship agent (in case the ship agent is the current owner)
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT2000001234",
      "name": "sender name",
      "eori": "",
      "tin": "Sender vat"
    },
    "carrier": {
      "nxtEntityId": "NXT2000001234",
      "name": "carrier name",
      "eori": "",
      "tin": "carrier vat"
    },
    "releaseTo": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasto name",
      "eori": "",
      "tin": "releaseto vat"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasefrom name",
      "eori": "",
      "tin": "releaseFrom vat"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "1234",
    "actionType": "Accept",
    "reasonForAction": null,
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
    "expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
  },
  "errors": [],
  "event": "Accepted",
  "externalReferenceId": null,
  "id": "test1234",
  "publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T15:28:35.9434964Z",
  "type": "ReleaseRight",
  "warnings": []
}

Webservice response

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

Notifications

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

  • your own notification channel
  • the ship agent (if the ship agent is the current owner and in case of accept or decline)
{
  "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": []
}

Webservice response

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

Notifications

When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is 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": []
}

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

Webservice response


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

Decline release right

Once another party (Ship Agent or another Certified Pick up Party) has transferred the right to Pick up a container to your entity, you will receive a notification of type Transfer. This will place the Pick up right in a “queue”, awaiting your acceptance or denial. It is not possible to transfer the right to pick up the container prior to either of these actions.
Endpoint - Release Right

PUT - {Host}/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"
    ],
    "releaseFrom": {
        "identificationType": "string",
        "identificationCode": "string"
    },
    "releaseTo": {
        "identificationType": "string",
        "identificationCode": "string"
    },
    "actionType": "Decline",
    "actionReason": "string"
}
Field name Type Mandatory Allowed value Field Description
releaseIdentification String Yes Free text Unique release identification
equipmentNumber String Yes Free text Container number
billOfLadingNumbers String Yes Free text Bill of Lading number(s) of the container
releaseFrom > identificationType String 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 Decline You can only use the value “Decline” 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

Webservice response

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

Notifications

If the release right request was successfully processed, a notification of type "ReleaseRight" and action "Declined" is sent to

  • your own notification channel
  • the ship agent (in case the ship agent is the current owner)
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT2000001234",
      "name": "sender name",
      "eori": "",
      "tin": "Sender vat"
    },
    "carrier": {
      "nxtEntityId": "NXT2000001234",
      "name": "carrier name",
      "eori": "",
      "tin": "carrier vat"
    },
    "releaseTo": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasto name",
      "eori": "",
      "tin": "releaseto vat"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasefrom name",
      "eori": "",
      "tin": "releaseFrom vat"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "1234",
    "actionType": "Decline",
    "reasonForAction": null,
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
    "expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
  },
  "errors": [],
  "event": "Declined",
  "externalReferenceId": null,
  "id": "test1234",
  "publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T15:28:35.9434964Z",
  "type": "ReleaseRight",
  "warnings": []
}

Webservice response

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

Notifications

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

  • your own notification channel
  • the ship agent (if the ship agent is the current owner and in case of accept or decline)
{
  "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": []
}

Webservice response

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

Notifications

When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is 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": []
}

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

Webservice response


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

Transfer a release right

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

PUT - {Host}/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": "Eori",
        "identificationCode": "string"
    },
    "actionType": "Transfer",
    "reasonForAction": "string",
    "releaseFrom": {
        "identificationType": "Eori",
        "identificationCode": "string"
    },
    "releaseTo": {
        "identificationType": "Eori",
        "identificationCode": "string"
    }
}

 

Field name Type Mandatory Allowed value Field Description
releaseIdentification String No 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.

Webservice response

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

Notifications

If the release right request was successfully processed, a notification of type "ReleaseRight" and action "Transfered" is sent to

  • your own notification channel
  • the ship agent (in case the ship agent is the current owner)
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT2000001234",
      "name": "sender name",
      "eori": "",
      "tin": "Sender vat"
    },
    "carrier": {
      "nxtEntityId": "NXT2000001234",
      "name": "carrier name",
      "eori": "",
      "tin": "carrier vat"
    },
    "releaseTo": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasto name",
      "eori": "",
      "tin": "releaseto vat"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasefrom name",
      "eori": "",
      "tin": "releaseFrom vat"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "1234",
    "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": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T15:28:35.9434964Z",
  "type": "ReleaseRight",
  "warnings": []
}

Webservice response

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

Notifications

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

  • your own notification channel
  • the ship agent (if the ship agent is the current owner and in case of accept or decline)
{
  "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": []
}

Webservice response

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

Notifications

When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is 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": []
}

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

Webservice response


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

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}/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": "Eori",
        "identificationCode": "string"
    },
    "actionType": "Revoke",
    "reasonForAction": "string",
    "releaseFrom": {
        "identificationType": "Eori",
        "identificationCode": "string"
    },
    "releaseTo": {
        "identificationType": "Eori",
        "identificationCode": "string"
    }
}

 

Field name Type Mandatory Allowed value Field Description
releaseIdentification String Yes Free text Unique release identification
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.
actionType Enum Yes Revoke You can only use the value Revoke when you wish to revoke the Release Right
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
releaseFrom > identificationType String Yes Tin, Eori, Duns or APCS Enter the type of identification of the party that had sent 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. 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.
If this information is not included in the body, the Eori from the credentials that perform the API call will be filled.
releaseTo > identificationType String Yes Tin, Eori, Duns or APCS Enter the type of identification of the party that would have received 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. 

Webservice response

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

Notifications

If the release right request was successfully processed, a notification of type "ReleaseRight" and action "Revoked" is sent to

  • Your own notification channel
  • The release Party that had to accept or decline your transferred Right
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT2000001234",
      "name": "sender name",
      "eori": "",
      "tin": "Sender vat"
    },
    "carrier": {
      "nxtEntityId": "NXT2000001234",
      "name": "carrier name",
      "eori": "",
      "tin": "carrier vat"
    },
    "releaseTo": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasto name",
      "eori": "",
      "tin": "releaseto vat"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT2000001234",
      "name": "releasefrom name",
      "eori": "",
      "tin": "releaseFrom vat"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "1234",
    "actionType": "Revoke",
    "reasonForAction": null,
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
    "expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
  },
  "errors": [],
  "event": "RevokedByPreviousParty",
  "externalReferenceId": null,
  "id": "test1234",
  "publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T15:28:35.9434964Z",
  "type": "ReleaseRight",
  "warnings": []
}

Webservice response

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

Notifications

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

  • your own notification channel
  • the ship agent (if the ship agent is the current owner and in case of accept or decline)
{
  "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": []
}

Webservice response

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

Notifications

When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is 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": []
}

Webservice response

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

Notifications

When a 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" and event "NotValidated" is 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

Webservice response


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

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.

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.

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.

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'."
        ]
    }
}


Manage Pick up of the container

Assign a driver

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

Endpoint - Pick up Right

PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/pickup-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

{
  "equipmentNumber": "string",
  "portLocode": "string",
  "terminalCode": "string",
  "billOfLadingNumbers": [
    "string"
  ],
  "actionType": "Assign",
  "pickupParty": {
    "partyType": "Truck",
    "identificationType": "alfapass",
    "identificationCode": "0123456"
  },
  "timestamp": "2020-05-20T21:47:03.931Z"
}
Field name Type Mandatory Allowed value Field Description
equipmentNumber String Yes Free text Container number
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
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 Assign You can only use the value Transfer when you wish to transfer the Release Right
pickupParty >
partyType 		String Yes Truck
Barge
Rail 		Enter the type of the mode of transport
pickupParty >
identificationType 		String Yes alfapass
Enter the type of the method used to identify the Pick up party. Currently only "alfapass" is allowed as value. 
pickupParty >
identificationCode          		 String Yes Free text

The code that is linked to the given identificationType. In case of alfapass, this is the number of the alfapass that is unique to the owner of the pass. 

If an invalid code is provided, this will return an error message to your notification channel. 
timestamp DateTimeUTC Yes Date Time Timestamp when you send the assign the pick up right to the driver 

When the 200 result is returned, your request has been successfully received.

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

Notifications

  • A notification of type Pick up-Right with event driverAssigned will be sent to your own notification channel
  • An alert will be sent to the driver in the mobile application on his/her smartphone

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.

Update pick-up right

When you wish to update the driver (or the mode of transport in the future) that is selected to perform the Pick up, you can update the Pick up Right owner. This will Revoke the right from the current assigned driver and recreate a new pick up right for the new driver. Obviously, the new driver needs to have a valid Alfapass.

Endpoint - Pick up Right

PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/pickup-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) 
{
  "equipmentNumber": "string",
  "portLocode": "string",
  "terminalCode": "string",
  "billOfLadingNumbers": [
    "string"
  ],
  "actionType": "Update",
  "pickupParty": {
    "partyType": "Truck",
    "identificationType": "alfapass",
    "identificationCode": "0123456"
  },
  "timestamp": "2020-05-20T21:47:03.931Z"
}
Field name Type Mandatory Allowed value Field Description
equipmentNumber String Yes Free text Container number
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
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 Update You can only use the value Update when you wish to update the Release Right
pickupParty >
partyType 		String Yes Truck Barge Rail Enter the type of the mode of transport
pickupParty >
identificationType 		String Yes alfapass
Enter the type of the method used to identify the Pick up party. Currently only "alfapass" is allowed as value. 
pickupParty >
identificationCode          		 String Yes Free text

The code that is linked to the given identificationType. In case of alfapass, this is the number of the alfapass that is unique to the owner of the pass. 

If an invalid code is provided, this will return an error message to your notification channel. 
timestamp DateTimeUTC Yes Date Time Timestamp when you send the assign the pick up right to the driver

When the 200 result is returned, your request has been successfully received.

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

Notifications

  • A notification of type Pick up-Right with event driverAssigned will be sent to your own notification channel
  • An alert will be sent to the driver in the mobile application on his/her smartphone
  • The previous driver will no longer have the container listed in the mobile application

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.

Revoke pick-up right

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

Endpoint - Pick up Right

PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/pickup-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

{
  "equipmentNumber": "string",
  "portLocode": "string",
  "terminalCode": "string",
  "billOfLadingNumbers": [
    "string"
  ],
  "actionType": "Revoke",
  "timestamp": "2020-05-20T21:47:03.931Z"
}
Field name Type Mandatory Allowed value Field Description
equipmentNumber String Yes Free text Container number
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
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
timestamp DateTimeUTC Yes Date Time Timestamp when you send the assign the pick up right to the driver

When the 200 result is returned, your request has been successfully received.

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

Notifications

  • A notification of type Pick up-Right with event evoked will be sent to your own notification channel
  • The previous driver will no longer have the container listed in the mobile application

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.

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