Input options for tracking containers

When using the Vizion API, there are three ways to begin tracking containers: Create reference via Carrier Code, Create reference via Bill of Lading, or Create reference via ACI. By understanding the differences of each option and looking at the data you have available, you can select the one that most fits your needs.

Webhooks vs GET request

With all three options, you can provide a value for the callback URL parameter in the POST request body that indicates where Vizion should send Update Payloads. This means that Vizion will send you data in realtime via webhook rather than having to check an API endpoint for changes as specified intervals. If using a polling method better suits your use case, you can exclude the callback URL when subscribing to a container and use a List reference updates GET request to return a list of Update Payloads for the given reference ID.

Passing custom data to Vizion

To pass custom data, include a callback URL with your POST request and append query string parameters to end of the URL. Upon receiving an update for your shipment, you can reference the values included in the URL when the reference was created. For instance, if you are managing two users and need to distinguish between them when receiving tracking information from Vizion, you can set up callback URLs like: Customer 'A' callback URL: https://yourdomain.com/webhook?customer=a and Customer 'B' callback URL: https://yourdomain.com/webhook?customer=b. Though updates for both customers will be directed to the same location, additional logic can be applied to handle each update appropriately.

Carrier code

Create reference via Carrier Code requires a container ID and carrier code:

//Example request body
{
  "container_id": "MRKU0090522",
  "carrier_code": "MAEU",
  "callback_url": "https://yourdomain.com/webhook"
}

A request to the endpoint generates a single reference that provides the most recent trip associated with a container. The API will assign a reference ID (reference_id) to the container that can be used to access updates, check the status, and unsubscribe. As a container is reused, you will receive updates for a given container until you unsubscribe using the Unsubscribe Reference endpoint.

Bill of lading

Create reference via Bill of Lading requires a bill of lading number and carrier code:

📘

Container ID with bill of lading

It is possible to pass a container ID (container_id) as a parameter along with the bill of lading and carrier code. Please note that if a container ID is used, the API will generate only a single reference to the individual container. If the bill of lading provided is incorrect or unavailable, we will not be able to locate the child reference.

//Example request body
{
  "bill_of_lading": "MAEU255221188",
  "carrier_code": "MAEU",
  "callback_url": "https://yourdomain.com/webhook"
}

When tracking your shipment using the bill of lading and carrier code, Vizion will identify all of the containers associated with the master bill of lading and create references for each container. This option will generate a reference for the bill of lading that will serve as a parent reference to all containers associated with the shipment. All individual child references will have a parent_reference_id which is a property set to the parent reference's reference_id. The endpoint will only return updates for the journey associated with the bill of lading for each container.

Auto Carrier Identification (ACI)

Create reference via ACI requires only the container ID:

//Example request body
{
  "container_id": "MRKU0090522",
  "callback_url": "https://yourdomain.com/webhook"
}

If a carrier is identified based on the container ID provided, the carrier code will be added to the reference and tracking will begin. This option should be used as a last resort when the carrier code is unknown. Using it may result in a large number of tracking failures and we ultimately recommend that you provide the carrier code whenever possible.

Which input to use

To recap, to track each individual container, use Create reference via Carrier Code by passing in the container ID and carrier code. If you have the master bill of lading and are interested in tracking all of the containers that belong to a shipment, use Create reference via Bill of Lading. If you do not have the carrier code, Auto Carrier Identification may occasionally be used as a fallback.