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 endpoints, 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.

Carrier code

The Create Reference via Carrier Code endpoint requires a container ID and carrier code:

Examples: FSCU5722094, CMAU5447085, GAOU6570655 | | carrier_code | Code of the carrier transporting the container (these codes should match those in our https://vizionapi.notion.site/afa65e3d79fb4a33bc5ce5c331576668)

Examples: MAEU, CMDU, EGLV |

{
  "container_id": "MRKU0090522",
  "carrier_code": "MAEU",
  "callback_url": "<https://yourdomain.com/webhook>"
}

A request to this endpoint generates a single reference that provides information on the most recent trip of 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

The Create Reference via Bill of Lading endpoint requires a bill of lading number and carrier code:

Examples: CMDUCNMD251217, MAEU225616225 | | carrier_code | Code of the carrier transporting the container (these codes should match those in our https://vizionapi.notion.site/afa65e3d79fb4a33bc5ce5c331576668)

Examples: MAEU, CMDU, EGLV |

<aside> 💡 It is possible to pass a container ID (container_id) as an optional parameter with the bill of lading and carrier code. Note that if a container ID is used, the API will generate only a single reference to the individual container. The bill of lading provided will be passed through to the reference’s bill_of_lading attribute.

</aside>

{
  "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 endpoint 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 ****property set to the parent reference's reference_id. This endpoint will only return updates for the journey associated with the bill of lading for each container.

Auto Carrier Identification

The Create Reference via ACI endpoint requires only the container ID:

Examples: FSCU5722094, CMAU5447085, GAOU6570655 |

{
  "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.