This guide walks through the structure of the Reference object delivered by the Vizion API in JSON format.
The Vizion API's JSON output is designed to be easily interpreted by both machines and humans alike, making it versatile and convenient to use with any language or system. Once you understand the key components of the payload, the format is intuitive and straightforward to navigate.
This article walks through the structure of the JSON returned by the Show Reference Details endpoint, which defines the Reference object created by the Create Reference via Carrier Code endpoint, Create Reference via Bill of Lading endpoint, or [Beta] Create Reference via Booking Number endpoint.
Top-level Properties
The top-level properties of the JSON for a reference include a unique id to that reference, the container_id of the container being tracked, a bill_of_lading number or booking_number if one was provided when creating the reference, and the carrier_scac, or standard carrier alpha code, for that supported vessel operating common carrier.
Additionally, the callback_url will contain the URL, if provided, that the API will send tracking updates to when they are generated.
{
"id": "9305845f-1d54-4bae-8906-cd6f26c1234y",
"container_id": "WHSU1234567",
"bill_of_lading": "null",
"booking_number": null,
"carrier_scac": "WHLC",
"callback_url": "https://webhook.site/ae73ede4-ba8e-4c6f-91e9-f0e455aaeab6",
"parent_reference_id": null,
"active": true,
"auto_carrier": false,
"last_update_status": "duplicate_payload",
"created_at": "2023-10-18T15:31:47.348Z",
"updated_at": "2023-10-19T03:39:49.351Z",
"last_update_attempted_at": "2023-10-19T03:37:44.799Z",
"retry_count": 1,
}
To define the remaining properties:
- parent_reference_id - The ID of the parent reference that was used to create this reference when creating by bill of loading or booking number
- active - if the reference is actively tracking a container
- auto_carrier - true if the reference was creating using the Create Reference via ACI endpoint
- last_update_status - the status code returned when the reference last attempted to generate a new tracking update (see statuses here)
- created_at - the timestamp when the reference was created
- updated_at - the timestamp when the reference was last modified
- last_update_attempted_at - the timestamp when the reference last checked for new tracking data
- retry_count - the number of retries the reference has performed while the last_update_status is in an error state (i.e. extraction_failed)
Organization
The reference object contains the ID of the organization that created it as well as an organization object with additional information. The id will match the organization_id. The name will be the name entered into Vizion's system for that organization. The active property determines if the organization is in use. Lastly, the created_at date displays when the organization was created in the system, and the updated_at date displays the last time that the organization was modified.
"organization_id": "04855606-8e38-402c-9c7d-ffc6c733597a",
"organization": {
"id": "04855606-8e38-402c-9c7d-ffc6c733597a",
"name": "VIZION",
"active": true,
"created_at": "2022-12-14T16:01:16.888Z",
"updated_at": "2023-09-20T22:21:50.583Z"
},
Carrier
The reference object contains information about the carrier as well. The carrier_id, or id within the carrier object, is an internal identifying number for the carrier in the system. The name is the carrier's name. The code is the Vizion carrier code used when creating references to track containers with that carrier. Lastly, the enabled property is used to designate if the carrier is actively supported at that time.
"carrier_id": 133,
"carrier": {
"id": 133,
"name": "Wan Hai",
"code": "WHLC",
"enabled": true
},
Child Reference IDs
The child_reference_ids property is populated only when creating a reference using the Create Reference via Bill of Lading endpoint or the [Beta] Create Reference via Booking Number endpoint. It provides an array of all reference IDs used to track the containers associated with that bill of loading or booking number. When creating a reference using the Create Reference via Carrier Code endpoint, this array will be empty as shown below.
"child_reference_ids": []