Postman, a tool for developing and working with APIs, provides a helpful interface to explore Vizion’s Container Tracking API. This tutorial walks through how to set up the Vizion collection in Postman, make an API request to track your first container, and check your webhook endpoint for updates on the container’s location. Additionally, learn how to see the status of a reference and view all references associated with your API key.

Access the collection

You can import the Postman collection by clicking the ‘Run in Postman’ button located in the top right corner of the Vizion API documentation. This will open the Vizion collection in the Postman workspace of your choice.

Set the API key and callback URL

After importing the API collection into your workspace, navigate to the Environments tab and select Vizion Docs. From here, replace two variables: apiKey with your Vizion API key and callbackURL with the URL where you would like Vizion to send updates. The API key is the unique identifier that grants access to Vizion's API services, while the callback URL is the location where Vizion will send update payloads whenever a reference is updated.

The baseUrl variable should be set to either https://demo.vizionapi.com if you are working with your demo API key or https://prod.vizionapi.com if you are using your production API key. Be sure to update this baseUrl accordingly to avoid errors related to a mismatch of the API key and environment.

To test out the Vizion API first before pointing to a URL on your server, you can use Webhook.site to create a temporary endpoint. Go to webhook.site and a unique URL will be created for you to use as a webhook endpoint. Enter this as your callbackUrl variable. Save your changes in the ‘Environments’ tab and select Vizion docs as the environment in the top right corner.

Vizion Docs set as the Environment

Vizion Docs set as the Environment

Make an API request

Next, we will learn how to make an API request to track a container.

  1. To get started, choose the Create reference via Carrier Code endpoint in the Postman collection sidebar. This endpoint allows you to create a new reference by specifying the carrier code associated with a shipment.
  2. Next, click on the ‘Body’ tab. Here, you will be prompted to enter the container ID and carrier code for the shipment you want to create a reference for. Enter the container ID in the container_id field and the carrier code in the carrier_code field. This information will be used by our system to locate the container and generate a new reference for it.
  3. Click send to make your first API request! Postman will display the response, which should contain the message “Reference created successfully.”

JSON returned with successful POST request in Postman

JSON returned with successful POST request in Postman

View the update payload

Now that the reference is created, check webhook.site (or the endpoint on your server) for the update payload information from Vizion. This data, in JSON format, describes where the container you are tracking is in the world. You can expect to receive this first update within 30 seconds of making your API request. You will then receive further updates when new data is available.

At your webhook.site URL, select the top POST request in the list to the left. Scroll down to see the JSON delivered by Vizion containing event milestones relevant to the container you are tracking. You are successfully receiving updates for your first reference! For a full explanation of what this data means, we recommend the How do I read the JSON update payload? article.

Raw update payload JSON at webhook.site

Raw update payload JSON at webhook.site

Check the status of a reference

To check the status of a particular reference, you can use the Show Reference Details endpoint in Postman.

  1. First, copy the reference_id from the previous step within the JSON payload.
  2. Choose the Show Reference Details endpoint in Postman and replace :reference_id in the URL with the reference ID you have copied.