Postman collection

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

Import the collection by following this link. 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.

Make an API request

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

1. To get started, choose Create reference via Carrier Code 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.”

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 reading more about understanding the update payload.

Check the status of a reference

To check the status of a particular reference, you can use the Get reference 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.
3. Finally, make the request and the JSON response will provide detailed information about the status of your reference, including the last update status (last_update_status property). For more information about what each status means, please refer to the check reference status troubleshooting article .

View all references you are tracking

Finally, to see all the references associated with your API key, you can use the List active references. Click on the endpoint in Postman and ‘Send’ to make the request. No additional parameters are required. The response will include an array of reference objects, allowing you to easily view all the active references currently associated with your account.

If you need to unsubscribe from any of these references, you can simply pass in the reference ID to the Unsubscribe a reference endpoint and it will be removed from your list of active references.

Next steps

For further practice in Postman, make a request to the List reference updates endpoint to retrieve all update payloads associated with a specific reference and use List Carriers to programmatically view our list of currently supported carriers.