Specification

The Event Subscription API works on a per container basis. Requests to create a subscription for a container must include a valid booking or a bill of lading that is associated with the container. Requests must also include a callback URL where future events will be sent. Subscriptions will automatically expire a few days after the container leaves the terminal.

Once a subscription is created, users can request all past events for the container or delete the subscription. When new events for subscribed containers occur, the event data will be pushed to the callback URL provided when the subscription was created.

This API offers the same data as the Container Event History API, but with a specification that resembles the DCSA Track & Trace Standard.

Endpoints

POST /event-subscriptions
GET /event-subscriptions/:id
GET /event-subscriptions/:id/events
DELETE /event-subscriptions/:id
GET /event-subscriptions
Supported Event Types

Container Position

ShiftCell

Container Availability

ContainerFullRelease
CustomsHold
CustomsRelease

Rail

ActualRailArrival
ActualRailDeparture
ActualDischargeFromRail
ActualLoadedOnRail

Truck

EstimatedGateIn
EstimatedGateOut
ActualGateIn
ActualGateOut

Vessel

EstimatedVesselArrival
EstimatedVesselDeparture
ActualVesselArrival
ActualVesselDeparture
ActualDischargeFromVessel
ActualLoadedOnVessel

Barge

EstimatedBargeArrival
EstimatedBargeDeparture
ActualBargeArrival
ActualBargeDeparture
UnitBargeDischargeActual
ActualLoadedOnBarge
The subscription object

Attributes

subscriptionID string($uuid)
Unique identifier for the object.
callbackUrl string($uri)
Your server, where the API server should send the event data.
bookingReference string
The identifier for a shipment, which is issued by and unique within each of the carriers.
transportDocumentID string
The Transport Document ID number is an identifier that links to a shipment, i.e. a Bill of Lading. A bill of lading is the document of title to the goods issued to the customer which confirms the carrier's receipt of the cargo from the customer, acknowledging goods being shipped and specifying the terms of delivery.
transportDocumentType string
The Transport Document Type is used to identify which type of document, the value of "transportDocumentID" represents. The values available are: BOL
equipmentReference string
The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. If a container is not yet assigned to a shipment, the interface cannot return any information when an equipment reference is given as input. If a container is assigned to an (active) shipment, the interface returns information on the active shipment.

The subscription object

{
    "subscriptionID": "123e4567-e89b-12d3-a456-426614174000",
    "callbackUrl": "https://myserver.com/send/callback/here",
    "bookingReference": "ABC709951",
    "transportDocumentID": "ABCD421911263977",
    "transportDocumentType": "BOL",
    "equipmentReference": "APZU4812090"
}
The event object

The event object models are based on the TradeLens Event Publish API. Refer to their documentation for detailed model attributes.

Please note that TradeLens specifies the event type in the POST URL and not in the model attributes. The callback URL provided in the subscription request will be used as the base URL for these TradeLens endpoints. For a subscription created with the callback URL https://myserver.com/send/callback/here an Actual Gate Out event will be posted to https://myserver.com/send/callback/here/api/v1/transportEvents/actualGateOut.

Create a subscription

Requests to create a subscription for a container must include a valid booking or a bill of lading that is associated with the container.

Parameters

callbackUrl
Required.
bookingReference
Required if transportDocumentID is NULL.
transportDocumentID
Required if bookingReference is NULL.
transportDocumentType
Required if transportDocumentID is set. Only the value BOL is currently supported.
equipmentReference
Required.

Returns

Status 201

The subscription object.

POST /event-subscriptions

curl https://subscriptions.portofvirginia.com/event-subscriptions
-H "X-API-KEY: 1234567890abcdef"
-H 'Content-Type: application/json'
-d '{"CallbackUrl": "https://myserver.com/send/callback/here",
"BookingReference": null,
"transportDocumentID": "ABCD421911263977",
"transportDocumentType": "BOL",
"EquipmentReference": "APZU4812090"}'

RESPONSE

{
    "subscriptionID": "123e4567-e89b-12d3-a456-426614174000",
    "callbackUrl": "https://myserver.com/send/callback/here",
    "bookingReference": "null",
    "transportDocumentID": "ABCD421911263977",
    "transportDocumentType": "BOL",
    "equipmentReference": "APZU4812090"
}
Retrieve a subscription

Retrieves the details of an existing subscription.

Parameters

No Parameters

Returns

Status 200

The subscription object.

GET /event-subscriptions/:id

curl https://subscriptions.portofvirginia.com/event-subscriptions/123e4567-e89b-12d3-a456-426614174000
-H "X-API-KEY: 1234567890abcdef"

RESPONSE

{
    "subscriptionID": "123e4567-e89b-12d3-a456-426614174000",
    "callbackUrl": "https://myserver.com/send/callback/here",
    "bookingReference": "null",
    "transportDocumentID": "ABCD421911263977",
    "transportDocumentType": "BOL",
    "equipmentReference": "APZU4812090"
}
Retrieve past events

List all past events for a subscription. The event object models are based on the TradeLens Event Publish API. Refer to their documentation for detailed model attributes. These object models have no attribute for the event type, so this endpoint returns a wrapper object that includes the event type.

Parameters

No Parameters

Returns

Status 200

List of event object wrappers.

Attributes

eventType string
The TradeLens event type.
eventData object($event)
The TradeLens event object.

GET /event-subscriptions/:id/events

curl https://subscriptions.portofvirginia.com/event-subscriptions/123e4567-e89b-12d3-a456-426614174000/events
-H "X-API-KEY: 1234567890abcdef"

RESPONSE

[
    {
        "eventType": "actualGateIn",
        "eventData": {
            "originatorName": "A Container Moving Enterprise",
            "originatorId": "ACME",
            "eventSubmissionTime8601": "2018-03-10T11:30:00.000-05:00",
            "transportEquipmentId": "d6ab2fe6-8331-623s-2173-kjshf76ehd",
            "transportEquipmentRef": null,
            "equipmentNumber": null,
            "carrierBookingNumber": null,
            "billOfLadingNumber": null,
            "eventOccurrenceTime8601": "2018-03-13T11:30:00.000-05:00",
            "transportationPhase": "Import",
            "location": {
            "unlocode": "NLRTM"
            },
            "vehicleId": "VEH625-259",
            "vehicleName": "Vehicle Name",
            "fullStatus": "Full",
            "terminal": null
        }
    }
]
Delete a subscription

Deletes the subscription. Events for this container will no longer be pushed to the callback URL.

Parameters

No Parameters

Returns

Status 204

DELETE /event-subscriptions/:id

curl https://subscriptions.portofvirginia.com/event-subscriptions/123e4567-e89b-12d3-a456-426614174000
-H "X-API-KEY: 1234567890abcdef"

RESPONSE

List all subscriptions

List all active subscriptions.

Parameters

No Parameters

Returns

Status 200

List of subscription objects.

GET /event-subscriptions

curl https://subscriptions.portofvirginia.com/event-subscriptions
-H "X-API-KEY: 1234567890abcdef"

RESPONSE

[
    {
        "subscriptionID": "123e4567-e89b-12d3-a456-426614174000",
        "callbackUrl": "https://myserver.com/send/callback/here",
        "bookingReference": null,
        "transportDocumentID": "ABCD421911263977",
        "transportDocumentType": "BOL",
        "equipmentReference": "APZU4812090"
    }
]
;