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 Pick up right from a previous party
  • Accepted, in case you successfully accepted a Pick up right from a previous party
  • Declined, in case you successfully declined a Pick up right from a previous party
  • Revoked, in case you successfully revoked a Pick up right from the next Party
  • acceptedByNextParty, in case the Next party accepted a release Right you had transferred to them
  • declinedByNextParty, in case the Next party declined a release Right you had transferred to them
  • transferSent, in case you have sent a release Right to a next party
  • revokedByPreviousParty, in case the Previous party revoked the release Right they had transferred to you (only possible before you accepted or denied the right)
  • driverAssigned, in case you assigned the right to pick up a container to a driver
  • driverRevoked, in case you revoked the driver to pick up the container

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.

Generic notification fields

Field name Type Allowed values Field Description

timestamp

DateTime

UTC datetime stamp

The timestamp when the notification was created by the Certified Pick up platform

PublicReferenceId

GUID

GUID

Automatically generated response

externalReferenceId

String

String

Your own reference, as provided in the request header (optional). Will be empty in case the notification was triggered by another party.

senderId

String

APCS code

The APCS code of the owner that generated the notification. If a 3rd party triggered the event, this information will still be the owner of the original source that will be listed here.

receiverId

String

APCS code

This should always be your APCS code as you are the receiver of this message.

asset

String

Free Text

Name of the asset that generated the notification. For the Certified Pick up this will always be “Certified Pick up”.

id

String

Free Text

For the Certified Pick up, this value will list the Equipment number, allowing integrators to quickly process the json message

type

String

Release-Right or pick up-right

Will always contain Release Right

event

Enumeration

transferred, revoked, accepted, declined, declinedByNextParty, acceptedByNextParty, transferSent,revokedByPreviousParty for Release Rights
driverAssigned, driverRevoked for Pick up rights

See above

errors

Array

Free text

list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION

warnings

Array

Free text

list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION

Body fields for the notifications of type Release Right

Field name Type Allowed values Field Description
sender> tinNumber String TIN number The TIN (VAT) number of the entity that caused the notification. This is the number that is stored in the NxtPort entity database. Will always contain a value.
sender> name String Free text The name of the entity that caused the notification. This is the name that is stored in the NxtPort entity database. Will always contain a value.
sender> eori String EORI number The EORI number of the entity that caused the notification. This is the EORI nu,ber that is stored in the NxtPort entity database. Can be empty
releaseIdentification String Free text Unique release identification (per carrier)
equipmentNumber String Free text Container number
equipmentType String 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)
portLoCode String UNLocode The UNLocode of the port. For Antwerp, this is BEANR
terminalCode String Free text The terminal yard where the container will be available for pickUp.
actionType Enumeration transfer, revoke, accept, decline Identifies the action that was taken to trigger the Release Light notification. This is the real action that was performed. not to be mistaken with the type of the Notification that might contain similar information.
reasonForAction String Free Text If you want to let a party know why you didn’t accept a Release Right, you can fill it in here
billOfLadingNumbers Array of strings Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
releaseFrom> tinNumber String TIN number The TIN (VAT) number of the entity described in the ReleaseFrom field. This is the number that is stored in the NxtPort entity database. Will always contain a value.
releaseFrom> name String Free text The name of the entity described in the ReleaseFrom field. This is the number that is stored in the NxtPort entity database. Will always contain a value.
releaseFrom> eori String EORI number The EORI number of the entity described in the ReleaseFrom field. This is the number that is stored in the NxtPort entity database. Can be empty
releaseTo> tinNumber String TIN number The TIN (VAT) number of the entity described in the ReleaseTo field. This is the number that is stored in the NxtPort entity database. Will always contain a value.
releaseTo> name String Free text The name of the entity described in the ReleaseTo field. This is the number that is stored in the NxtPort entity database. Will always contain a value.
releaseTo> eori String EORI number The EORI number of the entity described in the ReleaseTo field. This is the number that is stored in the NxtPort entity database. Can be empty
carrier> tinNumber String TIN number The TIN (VAT) number of the entity described in the carrier field. This is the number that is stored in the NxtPort entity database. Will always contain a value.
carrier> name String Free text The TIN (VAT) number of the entity described in the carrier field. This is the number that is stored in the NxtPort entity database. Will always contain a value.
carrier> eori String EORI number The TIN (VAT) number of the entity described in the carrier field. This is the number that is stored in the NxtPort entity database. Can be empty
releaseDateTimeUtc DateTimeUTC Date Time Date from which the Commercial release will be active
expirationDateTimeUtc DateTimeUTC Date Time Date until which the Commercial release will be active. If not entered, there is no expiration date applied
errors Array Free text list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION
warnings Array Free text list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION

Notification example 

{
    "timestamp": "2019-08-28T09:41:18Z",
    "publicReferenceId": "6d113ff6-4805-430f-be32-d8918fab83f1",
    "externalReferenceId": "your-reference-here",
    "senderId": "APCS001",
    "receiverId": "APCS002",
    "asset": "Certified Pick Up",
    "id": "ABCU1234560",
    "type": "Commercial Release Right",
    "event": "transfer",
    "body": {
        "sender": {
          "tinNumber": "BE0123456789",
          "name": "Shipping agent name",
          "eori": ""
        },
        "releaseIdentification": "xxxxx",
        "equipmentNumber": "ABCU1234560",
        "equipmentType": "Container",
        "portLoCode": "BEANR",
        "terminalCode": "K12345",
        "actionType": "transfer",
        "reasonForAction": "string",
        "billOfLadingNumbers": [
          "ABCUAA123456"
        ],
        "releaseFrom": {
          "tinNumber": "BE0123456789",
          "name": "Shipping agent name",
          "eori": ""
        },
        "releaseTo": {
          "tinNumber": "BE0123456789",
          "name": "forwarder name",
          "eori": ""
        },
        "carrier": {
          "tinNumber": "BE0123456789",
          "name": "carrier name",
          "eori": ""
        },
        "releaseDateTimeUtc": "2020-05-14T12:42:00.422Z",
        "expirationDateTimeUtc": "2020-05-14T12:42:00.422Z",
        "validFrom": "2020-05-14T12:42:00.422Z",
        "errors": [],
        "warnings": []
    },
    "errors": [],
    "warnings": []
}


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

When the 200 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 Release-Right with event accepted will be to your own notification channel
  • A notification of type Release-Right with event acceptedByNextParty will be to party that transferred the pick up right
{
    "timestamp": "2019-08-28T09:41:18Z",
    "publicReferenceId": "GUID",
    "externalReferenceId": "string",
    "senderId": "APCS001",
    "receiverId": "APCS002",
    "asset": "Certified Pick Up",
    "id": "ABCU1234560",
    "type": "Commercial Release Right",
    "event": "Accept",
    "body": {
        "sender": {
          "tinNumber": "BE0123456789",
          "name": "Shipping agent name",
          "eori": ""
        }
        "equipmentNumber": "ABCU1234560",
        action: "accept",
        "errors": [{
          {
              "type": "403",
              "title": "Forbidden",
              "status": 0,
              "detail": "Unable to perform SubmitReleaseRight action 'Accept' 
                on {command.EquipmentNumber} due to invalid identification"",
              "instance": "string",
              "additionalProp1": {},
              "additionalProp2": {},
              "additionalProp3": {}
            }
        }],
        "warnings": []
    },
    "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
  • 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.

Notification

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


{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "carrier": {
      "nxtEntityId": "NXT20000050989",
      "name": "Katoen Natie ",
      "eori": "",
      "tin": "BE0404778426"
    },
    "releaseTo": {
      "nxtEntityId": "NXT20000050989",
      "name": "Katoen Natie ",
      "eori": "",
      "tin": "BE0404778426"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "01700",
    "actionType": "Accept",
    "reasonForAction": null,
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseDatetimeUtc": "2021-01-04T16:19:38.4720593Z",
    "expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
  },
  "errors": [],
  "event": "AcceptedByNextParty",
  "externalReferenceId": null,
  "id": "test1234",
  "publicReferenceId": "f003cbac-b6e5-4091-9f75-eee02a4b5c52",
  "receiverId": "NXT20000050989",
  "senderId": null,
  "timestamp": "2021-01-04T16:20:17.3856965Z",
  "type": "ReleaseRight",
  "warnings": []
}

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

When the 200 result is returned, the right to Pick up the container will be declined and will remain at the entity that transferred it to you.

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

Notifications

  • A notification of type Release-Right with event declined will be to your own notification channel
  • A notification of type Release-Right with event declinedByNextParty will be to party that transferred the pick up 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.

Notification

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


{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "carrier": {
      "nxtEntityId": "NXT20000050989",
      "name": "Katoen Natie ",
      "eori": "",
      "tin": "BE0404778426"
    },
    "releaseTo": {
      "nxtEntityId": "NXT20000050989",
      "name": "Katoen Natie ",
      "eori": "",
      "tin": "BE0404778426"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "01700",
    "actionType": "Decline",
    "reasonForAction": null,
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseDatetimeUtc": "2021-01-04T16:25:00.2049701Z",
    "expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
  },
  "errors": [],
  "event": "DeclinedByNextParty",
  "externalReferenceId": null,
  "id": "test1234",
  "publicReferenceId": "d0f57aa8-7f56-4731-86e7-97c4ac2e3996",
  "receiverId": "NXT20000050989",
  "senderId": null,
  "timestamp": "2021-01-04T16:25:15.1097306Z",
  "type": "ReleaseRight",
  "warnings": []
}

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.

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

Notification

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


{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "carrier": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "releaseTo": {
      "nxtEntityId": "NXT20000050989",
      "name": "Katoen Natie ",
      "eori": "",
      "tin": "BE0404778426"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "01700",
    "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": []
}

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. 

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.

Notification

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


{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "sender": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "carrier": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "releaseTo": {
      "nxtEntityId": "NXT20000050989",
      "name": "Katoen Natie ",
      "eori": "",
      "tin": "BE0404778426"
    },
    "releaseFrom": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC",
      "eori": "",
      "tin": "BE0464255361"
    },
    "equipmentNumber": "test1234",
    "equipmentType": "",
    "portLoCode": "BEANR",
    "terminalCode": "01700",
    "actionType": "Revoke",
    "reasonForAction": null,
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseDatetimeUtc": "2021-01-04T15:28:35.725305Z",
    "expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
  },
  "errors": [],
  "event": "RevokedByPreviousParty",
  "externalReferenceId": null,
  "id": "test1234",
  "publicReferenceId": "7957d0a4-b2ab-40f2-bfd7-f80dfa88bbdf",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T16:14:48.0367377Z",
  "type": "ReleaseRight",
  "warnings": []
}

Release Lights

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"
}

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

{
  "publicRefernceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalReferenceId": "string" 
  "portLoCode": "string",
  "equipmentNumber": "string",
  "billOfLadingNumbers": [
    "string"
  ], 
  "terminalCode": "string",
  "state": "Unknown"
}

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.

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": "MPET",
    "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": "MSC",
    "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": []
}


Manage Pick up of the container

Pick-up right transfer documentation in development

Before a container can be picked up at the terminal, the identity of the person mandated to do this, needs to be inserted (and validated) in the CPu backbone. The documentation of this call will be released in January 2021.

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!

See what's going on

Contact

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

More info

Register your company