Specification

The Import Availability API provides information on inbound containers, in particular their availability status and hold information. Users must provide the container number and the associated bill of lading number in the request.

In addition to retrieving availability data, users can receive a message when a container's availability status changes by subscribing to a container with a callback URL.

Endpoints

GET /import-availability
POST /import-availability
POST /import-availability/subscriptions
GET /import-availability/subscriptions
DELETE /import-availability/subscriptions/:id
Get Import

Requests for import availability must include a valid bill of lading that is associated with the container.

Query Parameters

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

Returns

Status 200

The import availability object.

GET /import-availability

curl https://subscriptions.portofvirginia.com/import-availability?
equipmentId=CONTAINER_NUMBER&
referenceId=BILL_OF_LADING&
key=YOUR_API_KEY

RESPONSE

{
    "container": "GLDU1234567",
    "billOfLading": "AAA123999",
    "category": "IMPRT",
    "freightKind": "LADEN",
    "iso": "22G0",
    "terminal": "NIT",
    "shipmentStatus": "Available",
    "shipmentAction": "UV",
    "carrierScac": "CMDU",
    "carrierName": "CMA",
    "yardBlock": null,
    "isHazardous": false,
    "isReefer": false,
    "holds": [],
    "freeTimeExpiration": null,
    "voyageLloyds": "9321263",
    "voyageCode": "COUR-1247",
    "voyageVesselName": "MOL COURAGE",
    "weight": "18750",
    "weightUnit": "K",
    "weightQualifier": "N",   
    "chassis": "CHAZ123456",
    "outTime": "2022-02-15T18:16:13.973",
    "emptyReturnTime": "2022-02-17T17:46:38.769"
}
Get Imports (Bulk)

Get import availability data for up to 100 containers.

Requests for import availability must include a valid bill of lading that is associated with the container.

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

Parameters

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

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

Returns

Status 200

A list of import availability response objects.

equipmentId
The container number from the request object.
referenceId
The bill of lading number from the request object.
data
The import availabilty object.
message
The reason why availability information was not populated.

POST /import-availability

curl -X POST https://subscriptions.portofvirginia.com/import-availability
-H "X-API-KEY: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '[ { "equipmentId": "GLDU1234567", "referenceId": "AAA123999" } ]'

RESPONSE

[
    {
        "equipmentId":  "GLDU1234567",
        "referenceId": "AAA123999",
        "data": {
            "container": "GLDU1234567",
            "billOfLading": "AAA123999",
            "category": "IMPRT",
            "freightKind": "LADEN",
            "iso": "22G0",
            "terminal": "NIT",
            "shipmentStatus": "Available",
            "shipmentAction": "UV",
            "carrierScac": "CMDU",
            "carrierName": "CMA",
            "yardBlock": null,
            "isHazardous": false,
            "isReefer": false,
            "holds": [],
            "freeTimeExpiration": null,
            "voyageLloyds": "9321263",
            "voyageCode": "COUR-1247",
            "voyageVesselName": "MOL COURAGE",
            "weight": "18750",
            "weightUnit": "K",
            "weightQualifier": "N",
            "chassis": "CHAZ123456",
            "outTime": "2022-02-15T18:16:13.973",
            "emptyReturnTime": "2022-02-17T17:46:38.769"
        },
        message: null
    }
]
Create Subscriptions

Subscribe to availability statuses. Each time the status changes, the import availability object will be POST-ed to the callback URL provided.

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

Parameters

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

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

Returns

Status 200

A list of import availability response objects.

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

POST /import-availability/subscriptions

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

RESPONSE

[
    {
        "equipmentId":  "GLDU1234567",
        "referenceId": "AAA123999",
        "data": {
            "subscriptionId": "0382b97e-0a51-4b10-883e-a5e822d18d3f",
            "callbackUrl": "https://www.portofvirginia.com/availability-events",
            "equipmentId": "GLDU1234567",
            "referenceId": "AAA123999",
            "terminal": "NIT"
        },
        "message": null
    }
]
Get Subscriptions

This endpoint returns import availability 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 /import-availability/subscriptions

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

RESPONSE

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

This endpoint removes an import availability subscription. Once the subscription is removed, you will no longer receive events at your endpoint for the specified 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 the container leaves the terminal.

Query Parameters

None

Returns

Status 200

DELETE /import-availability/subscriptions/{id}

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

RESPONSE

None
;