Specification

The Container Events API provides a list of events that affect a specific container.

In addition to retrieving past container events, users can receive a message when a new event occurs by subscribing to a container with a callback URL.

Endpoints

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

Container Position

UnitShiftCell
UnitShiftPier

Container Availability

UnitAvailable
UnitUnavailable
UnitCustomsRelease
UnitCustomsExamRequired
UnitCustomsExamCompleted

Rail

UnitRailInActual
UnitRailOutActual
UnitRailDischargeActual
UnitRailLoadActual

Truck

UnitGateInEstimated
UnitGateOutEstimated
UnitGateInActual
UnitGateOutActual
UnitTruckLoadActual
UnitTruckDischargeActual
UnitEmptyReturn

Vessel

UnitVesselArrivalEstimated
UnitVesselDepartureEstimated
UnitVesselArrivalActual
UnitVesselDepartureActual
UnitVesselDischargeActual
UnitVesselLoadActual
UnitVesselPhaseUpdate

Barge

UnitBargeArrivalEstimated
UnitBargeDepartureEstimated
UnitBargeArrivalActual
UnitBargeDepartureActual
UnitBargeDischargeActual
UnitBargeLoadActual
UnitBargePhaseUpdate
The container events object

Attributes

container string
The container number.
details object($containerDetails)
Container details and current status information.
events array of object($containerEvent)
The list of container events.

The container events object

{
    "container": "APZU4812090",
    "details": { ... },
    "events": [ ... ]
}
The container details object

Attributes

freightKind string
LADEN or EMPTY
iso string
Container size and type
terminal string
The port facility handling the container
shipmentState string
ADVISED, INBOUND, ECIN, YARD, ECOUT, LOADED, or DEPARTED
shipmentStatus string
Available or Not Available
shipmentAction string
EDI 315 shipment status code
carrierBookingNumber string
billOfLadingNumber string
carrierScac string
carrierName string
yardBlock string
Yard location
isHazardous boolean
isReefer boolean
holds array of string
List of reasons the container is on hold
freeTimeExpiration datetime
weight string
weightUnit string
weightQualifier string
inTime datetime
Date and time the container arrived at the terminal
inCarrierMode string
TRAIN, TRUCK, or VESSEL
inCarrierScac string
SCAC of the carrier that arrived the container
outTime datetime
Date and time the container departed the terminal
outCarrierMode string
TRAIN, TRUCK, or VESSEL
outCarrierScac string
SCAC of the carrier that departed the container

The container details object

{
    "freightKind": "LADEN",
    "iso": "4500",
    "terminal": "NIT",
    "shipmentState": "DEPARTED",
    "shipmentStatus": "Not Available",
    "shipmentAction": null,
    "carrierBookingNumber": null,
    "billOfLadingNumber": "123456789",
    "carrierScac": "SQQY",
    "carrierName": "SLS",
    "yardBlock": null,
    "isHazardous": false,
    "isReefer": false,
    "holds": [ ],
    "freeTimeExpiration": null,
    "weight": "10700",
    "weightUnit": "K",
    "weightQualifier": "N",
    "inTime": "2022-05-15T15:35:53.471",
    "inCarrierMode": "VESSEL",
    "inCarrierScac": "SQQY",
    "outTime": "2022-05-18T13:55:49.465",
    "outCarrierMode": "TRUCK",
    "outCarrierScac": "ABCD"
}
The container event object

Attributes

eventType string
eventTime datetime
The time of the event.
eventCreatedTime datetime
The time the event was created. Same as the event time, unless the it's an estimated event and the event time represents a future time.
eventData object($eventData)
Container status and details at the time the event was created.
notes string
Event specific details.

The container event object

{
    "eventType": "UnitGateOutEstimated",
    "eventTime": "2022-05-18T12:00:00",
    "eventCreatedTime": "2022-05-18T11:45:19.104",
    "eventData": { ... },
    "notes": "License Plate: VTW-9999"
}
The event data object

Attributes

terminal string
The port facility handling the container at the time of the event.
holds array of string
List of holds on the container at the time of the event.
yardSlot string
Position in yard at the time of event.
chassis string
chassisType string
carrierScac string
vehicleId string
voyageId string
vesselPhase string
CREATED, INBOUND, ARRIVED, WORKING, COMPLETE, or DEPARTED
vesselType string
BARGE or DEEPSEA
vesselCell string
Position on vessel at the time of the event.

The event data object

{
    "terminal": "NIT",
    "holds": null,
    "yardSlot": null,
    "chassis": "CHAZ123456",
    "chassisType": "CH40",
    "carrierScac": "ABCD",
    "vehicleId": "9354167",
    "voyageId": "2202E",
    "vesselPhase": "INBOUND",
    "vesselType": "DEEPSEA",
    "vesselCell": "221214"
}
Get Conatiner Events

Query Parameters

equipmentId
The container number. Required.
referenceId
The bill of lading number or booking number. Required.

Returns

Status 200

The container events object.

GET /container-events

curl https://subscriptions.portofvirginia.com/container-events?
equipmentId=CONTAINER_NUMBER&
referenceId=BOL_OR_BOOKING&
key=YOUR_API_KEY

RESPONSE

{
    "container": "BEAU2752848",
    "details": { ... },
    "events": [
        {
            "eventType": "UnitVesselArrivalEstimated",
            "eventTime": "2022-05-10T08:00:00",
            "eventCreatedTime": "2022-05-01T11:14:08.2066667",
            "eventData": { ... },
            "notes": "HAKM-2202W ETA is 5/10/2022 8:00:00 AM."
        },
        {
            "eventType": "UnitCustomsRelease",
            "eventTime": "2022-05-11T03:05:55.4223484",
            "eventCreatedTime": "2022-05-11T03:05:55.4223484",
            "eventData": { ... },
            "notes": null
        },
        {
            "eventType": "UnitVesselDischargeActual",
            "eventTime": "2022-05-15T15:35:53.485",
            "eventCreatedTime": "2022-05-15T15:35:53.485",
            "eventData": { ... },
            "notes": null
        }
    ]
}
Get Conatiner Events (Bulk)

Get container events for up to 100 containers.

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

The endpoint takes a JSON encoded list of up to 100 container event request objects in the POST body and returns a list of container event response objects.

Parameters

A list of container event request objects (100 max). Each object must contain the following properties:

equipmentId
The container number. Required.
referenceId
The bill of lading number or booking number. Required.

Returns

Status 200

A list of container event response objects.

equipmentId
The container number from the request object.
referenceId
The bill of lading number or booking number from the request object.
data
The container events object.
message
The reason why event data was not populated.

POST /container-events

curl -X POST https://subscriptions.portofvirginia.com/container-events
-H "X-API-KEY: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '[ { "equipmentId": "BEAU2752848", "referenceId": "123456789" } ]'

RESPONSE

[
    {
        "equipmentId":  "BEAU2752848",
        "referenceId": "123456789",
        "data": {
            "container": "BEAU2752848",
            "details": { ... },
            "events": [ ... ]
        }
    }
]
Create Subscriptions

Subscribe to container events. Each time a new event occurs, the container event object will be POST-ed to the callback URL provided. Only new events will be included in these messages. There may be multiple events in a single message if they occur closely in time.

The endpoint takes a JSON encoded list of up to 100 container event request objects in the POST body and returns a list of container event response objects.

Parameters

A list of container event request objects (100 max). Each object must contain the following properties:

equipmentId
The container number. Required.
referenceId
The bill of lading number or booking number. Required.
callback
The url to receive events. Required.

Returns

Status 200

A list of container event response objects.

equipmentId
The container number from the request object.
referenceId
The bill of lading number or booking number from the request object.
data
The subscription object.
message
The reason why the subscription could not be created.

POST /container-events

curl -X POST https://subscriptions.portofvirginia.com/container-events/subscriptions
-H "X-API-KEY: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '[ { "equipmentId": "BEAU2752848",
"referenceId": "123456789",
"callback" : "https://www.portofvirginia.com/container-events" } ]'

RESPONSE

[
    {
        "equipmentId":  "BEAU2752848",
        "referenceId": "123456789",
        "data": {
            "subscriptionId": "0382b97e-0a51-4b10-883e-a5e822d18d3f",
            "callbackUrl": "https://www.portofvirginia.com/container-events",
            "equipmentId": "BEAU2752848",
            "referenceId": "123456789",
            "terminal": "NIT"
        },
        "message": null
    }
]
Create Subscriptions from File

Subscribe to container events. Each time a new event occurs, the container event object will be POST-ed to the callback URL provided. Only new events will be included in these messages. There may be multiple events in a single message if they occur closely in time.

The endpoint takes a presigned url in the POST body. The url should point to a file that contains a list of containers and BOLs for which subscriptions will be created.

Parameters

An object with the following properties:

presignedUrl
The URL of the file containing the list of containers and BOLs. Required.
fileType
The type of file to be downloaded. Optional. Default value is CSV.
callback
The url to receive events. Optional.
callbackMessageType
The type of message that will be sent to the callback url. Optional.

Returns

Status 200

A request id that can be used to reference the file processing request. The file will be processed by a background job.

requestId
A GUID that can be used to reference the request.
message
The reason why the request could not be processed.

POST /container-events/subscriptions/file

curl -X POST https://subscriptions.portofvirginia.com/container-events/subscriptions/file
-H "X-API-KEY: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{ "presignedUrl": "https://www.presignedurl.com/abcd-efrg.txt",
"fileType": "CSV",
"callbackMessageType": "JSON",
"callback" : "https://www.your-server.com/container-events" }'

RESPONSE

{
    "requestId": "0382b97e-0a51-4b10-883e-a5e822d18d3f",
    "message": null
}
Get Subscriptions File Status

Returns the status of the subscription file

Query Parameters

None

Returns

Status 200

A subscription request status object.

GET /container-events/subscriptions/file/{id}

curl https://subscriptions.portofvirginia.com/container-events/subscriptions/file/0382b97e-0a51-4b10-883e-a5e822d18d3f?
key=YOUR_API_KEY

RESPONSE

{
    "requestId": "0382b97e-0a51-4b10-883e-a5e822d18d3f",
    "createdTime": "2023-06-09T09:19:42.1633333",
    "processedTime": "2023-06-09T09:23:00.6866667",
    "processedSuccessfully": true,
    "processingError": null,
    "itemsCreated": 100,
    "itemsDuplicated": 0,
    "itemsNotFound": 0,
    "itemsErrored": 0
}
Get Subscriptions

This endpoint returns container event subscriptions. A maxmium of 100 subscriptions are returned at a time.

Query Parameters

page
The page number. Optional.

Returns

Status 200

A list of subscription objects.

GET /container-events/subscriptions

curl https://subscriptions.portofvirginia.com/container-events/subscriptions?
page=0&
key=YOUR_API_KEY

RESPONSE

[
    {
        "subscriptionId": "0382b97e-0a51-4b10-883e-a5e822d18d3f",
        "callbackUrl": "https://www.portofvirginia.com/container-events",
        "equipmentId": "BEAU2752848",
        "referenceId": "123456789",
        "terminal": "NIT"
    }
]
Remove Subscription

This endpoint removes a container events subscription. Once the subscription is removed, you will no longer receive events at your endpoint for the container. Removing subscriptions is not required, as they will automatically expire after the container leaves the terminal. Use this endpoint if you need to remove a subscription before it expires.

Query Parameters

None

Returns

Status 200

DELETE /container-events/subscriptions/{id}

curl -X DELETE https://subscriptions.portofvirginia.com/container-events/subscriptions/0382b97e-0a51-4b10-883e-a5e822d18d3f?
key=YOUR_API_KEY

RESPONSE

None
;