Specification

The Export Booking API provides information on bookings.

In addition to retrieving booking data, users can receive a message when a booking changes by subscribing to it with a callback URL.

Endpoints

GET /export-booking
POST /export-booking
POST /export-booking/subscriptions
GET /export-booking/subscriptions
DELETE /export-booking/subscriptions/:id
Get Export

Query Parameters

referenceId
The booking number. Required.

Returns

Status 200

The booking object.

GET /export-booking

curl https://subscriptions.portofvirginia.com/export-booking?
referenceId=BOOKING_NUMBER&
key=YOUR_API_KEY

RESPONSE

{
    "bookingReference": "123999",
    "lineItems": [
        {
            "iso": "4300",
            "quantity": "20"
        }
    ],
    "shippingLine": "HYUNDAI",
    "shippingLineScac": "HDMU",
    "vesselName": "ULSAN EXPRESS",
    "outboundVoyageNumber": "038W",
    "beginReceiveDate": "2022-02-25T00:00:00",
    "vesselEtaDate": "2022-03-02T08:00:00",
    "vesselAtaDate": "2022-03-02T07:00:00",
    "vesselEtdDate": "2022-03-04T23:00:00",
    "vesselAtdDate": "2022-03-04T23:30:00",
    "canceledDate": null,
    "facility": "VIG",
    "containers": [
        {
            "equipmentId": "OOLU1234567",
            "iso": "22G1",
            "inTime": "2022-02-07T07:49:06.045",
            "vesselLoadTime": "2022-02-08T15:03:44.723"
        }
    ]
}
Get Exports (Bulk)

Get data for up to 100 bookings.

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

Parameters

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

referenceId
The booking number. Required.

Returns

Status 200

A list of booking response objects.

referenceId
The booking number from the request object.
data
The booking object.
message
The reason why booking data was not populated.

POST /export-booking

curl -X POST https://subscriptions.portofvirginia.com/export-booking
-H "X-API-KEY: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '[ { "referenceId": "123999" } ]'

RESPONSE

[
    {
        "referenceId": "123999",
        "data": {
            "bookingReference": "123999",
            "lineItems": [
                {
                    "iso": "4300",
                    "quantity": "20"
                }
            ],
            "shippingLine": "HYUNDAI",
            "shippingLineScac": "HDMU",
            "vesselName": "ULSAN EXPRESS",
            "outboundVoyageNumber": "038W",
            "beginRecieveDate": "2022-02-25T00:00:00",
            "vesselEtaDate": "2022-03-02T08:00:00",
            "vesselAtaDate": "2022-03-02T07:00:00",
            "vesselEtdDate": "2022-03-04T23:00:00",
            "vesselAtdDate": "2022-03-04T23:30:00",
            "canceledDate": null,
            "facility": "VIG",
            "containers": [
                {
                    "equipmentId": "OOLU1234567",
                    "iso": "22G1",
                    "inTime": "2022-02-07T07:49:06.045",
                    "vesselLoadTime": "2022-02-08T15:03:44.723"
                }
            ]
        },
        message: null
    }
]
Create Subscriptions

Subscribe to bookings. Each time the booking changes, the booking object will be POST-ed to the callback URL provided.

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

Query Parameters

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

referenceId
The booking number. Required.
callback
The url to receive events. Required.

Returns

Status 200

A list of booking response objects.

referenceId
The booking number from the request object.
data
The subscription object.
message
The reason why the subscription could not be created.

POST /export-booking/subscriptions

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

RESPONSE

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

This endpoint returns booking 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 /export-booking/subscriptions

curl https://subscriptions.portofvirginia.com/export-booking/subscriptions
page=0&
key=YOUR_API_KEY

RESPONSE

[
    {
        "id": "0382b97e-0a51-4b10-883e-a5e822d18d3f",
        "callbackUrl": "https://www.portofvirginia.com/booking-events",
        "referenceId": "123999",
        "terminal": "NIT"
    }
]
Remove Subscription

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

Query Parameters

None

Returns

Status 200

DELETE /export-booking/subscriptions/{id}

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

RESPONSE

None
;