---
updatedAt: 2026-10-22T16:47:51.000Z
agentTools:
  projectIndex: https://docs.vizionapi.com/llms.txt
---

# Quick start

Use cURL to get started with Vizion's Container Tracking API

This tutorial will walk through how to use the Container Tracking API to subscribe to a container and receive location updates. You will make use of the command line and [cURL](https://curl.se/) to access the API, which is a language option in [Vizion API reference](https://docs.vizionapi.com/reference/reference_create).

![Programming language selection in API reference](https://files.readme.io/e0a89e9-getting-started-curl.png)

## Getting started

You will need a few items before getting started:

* Your **Vizion API key**
* The **container ID** and **carrier code** of a shipment you want to track
* Access to the [command line](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Command_line) on your computer

## Create a <Glossary>callback URL</Glossary>

The Container Tracking API is designed to provide realtime data updates to you through webhooks, eliminating the need to manually check for changes at regular intervals. Vizion will send these updates directly to the <Glossary>callback URL</Glossary> you provide.

> 📘 Polling method
>
> If your use case is better suited for a polling method, you have the option to exclude the <Glossary>callback URL</Glossary> when subscribing to a container. Instead, you can utilize a GET request for [List Reference Updates](https://docs.vizionapi.com/reference/reference_updates_list), which will retrieve a list of Update Payloads specific to the provided reference ID.

To demonstrate the functionality of the Vizion API first before pointing to a URL on your server, you can use [Webhook.site](https://webhook.site/) to create a temporary endpoint to use as your <Glossary>callback URL</Glossary>. Go to webhook.site and copy the unique URL generated for you.

![\[Webhook.site\](http://Webhook.site) unique URL](https://files.readme.io/a5dd5d0-Screen_Shot_2023-11-27_at_5.10.03_PM.png)

## Make an API request to create a reference

For this tutorial, [Create reference via Carrier Code](https://docs.vizionapi.com/reference/reference_create) will be used. You can explore other input options by referring to the [Input options for tracking containers](https://docs.vizionapi.com/docs/input-options) guide.

1. Using the cURL request below, replace `callback_url` with your [webhook.site](http://webhook.site) URL and `YOUR_API_KEY_HERE` with your Vizion API key.

<Terminal>
  {`$ curl --location 'https://prod.vizionapi.com/references' \\
      --header 'X-API-Key: YOUR_API_KEY_HERE' \\
      --header 'Content-Type: application/json' \\
      --data '{
        "container_id": "MEDU8381210",
        "carrier_code": "MSCU",
        "callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d"
      }'
      `}
</Terminal>

2. Replace the `container_id` and `carrier_code` values with your own shipment information or use the example data above.
3. Open your terminal, paste the complete cURL request, and press Enter.
4. You will see a response indicating that the request was successful with information about the reference created.

```json
// Successful reference creation response in the terminal
{
    "message": "Reference created successfully.",
    "reference": {
        "id": "ef37bc21-e65e-46cc-8f2b-ef66a32e5a76",
        "container_id": "MEDU8381210",
        "bill_of_lading": null,
        "booking_number": null,
        "carrier_scac": "MSCU",
        "callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d",
        "organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
        "parent_reference_id": null,
        "latest_update_id": null,
        "carrier_id": 6,
        "active": true,
        "auto_carrier": false,
        "last_update_status": null,
        "created_at": "2023-11-28T01:53:03.669Z",
        "updated_at": "2023-11-28T01:53:03.669Z",
        "last_update_attempted_at": null,
        "next_scheduled_update_attempt_at": null,
        "process_frequency_minutes": null,
        "retry_count": 0,
        "simple_tracking": false,
        "shipment_completed": false,
        "auto_unsubscribed": false
    }
}
```

## Check <Glossary>callback URL</Glossary> for update

Now that the reference is created, check your [webhook.site](http://webhook.site) URL for the update payload information. 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 have successfully created your first reference! For a full explanation of what this data means, we recommend reading more about [understanding the update payload](https://docs.vizionapi.com/docs/understand-update-payload).

![Update payload at \[webhook.site\](http://webhook.site) <\<glossary:callback URL>>
](https://files.readme.io/5632813-Screen_Shot_2023-11-27_at_5.59.14_PM.png)

🎉 Now that you are successfully subscribed to this reference, you will continue to receive updates as the container moves along its journey until it is [auto-unsubscribed](https://docs.vizionapi.com/docs/auto-unsubscribe) or you unsubscribe using the [Unsubscribe reference](https://docs.vizionapi.com/reference/reference_deactivate) endpoint.

## Retrieve reference status

If you ever encounter a situation where you haven't received data for a specific reference and would like to investigate further, you can utilize the [Get reference endpoint](https://docs.vizionapi.com/reference/reference_get). This endpoint allows you to [check the status](https://docs.vizionapi.com/docs/reference-status) and gather more information about the reference in question.

1. First, copy the `reference_id` from the previous step within the JSON payload.
   <Terminal>
     {`$ curl --location 'https://prod.vizionapi.com/references/REFERENCE_ID' \\
     --header 'X-API-Key: YOUR_API_KEY_HERE'
     `}
   </Terminal>
2. Below, replace `REFERENCE_ID` in the URL with the reference ID you have copied and `YOUR_API_KEY_HERE` with your API key.
3. Copy the request into your terminal and press Enter. The JSON response provides detailed information about the status of your reference, including the last update status (`last_update_status`). For more information about what each status means, please refer to the [check reference status troubleshooting article](https://docs.vizionapi.com/docs/reference-status).

```json
{
    "id": "ef37bc21-e65e-46cc-8f2b-ef66a32e5a76",
    "container_id": "MEDU8381210",
    "bill_of_lading": null,
    "booking_number": null,
    "carrier_scac": "MSCU",
    "callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d",
    "organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
    "parent_reference_id": null,
    "organization": {
        "id": "777ccf97-c75b-4051-893b-a47a367bf185",
        "name": "Organization",
        "active": true,
        "created_at": "2023-01-25T18:46:49.676Z",
        "updated_at": "2023-10-10T01:01:35.560Z"
    },
    "carrier_id": 6,
    "carrier": {
        "id": 6,
        "name": "MSC",
        "code": "MSCU",
        "enabled": true
    },
    "active": true,
    "auto_carrier": false,
    // Last update status is data received indicating the data was delivered to the <<glossary:callback URL>> successfully
    "last_update_status": "data_received",
    "created_at": "2023-11-28T01:53:03.669Z",
    "updated_at": "2023-11-28T01:53:06.114Z",
    "last_update_attempted_at": "2023-11-28T01:53:03.935Z",
    "retry_count": 0,
    "child_reference_ids": []
}
```

## View all references you are currently tracking

To see all the references associated with your API key, you can use the [List active references endpoint](https://docs.vizionapi.com/reference/reference_list). The response will include an array of reference objects, allowing you to easily view all the active references currently associated with your account.

1. Copy the cURL request below and replace `YOUR_API_KEY_HERE` with your API key.
2. The JSON response returned will contain an array of all reference objects you are currently tracking.
   <Terminal>
     {`$ curl --location 'https://prod.vizionapi.com/references' \\
     --header 'X-API-Key: YOUR_API_KEY_HERE'
     `}
   </Terminal>

```json
 {
    "id": "ef37bc21-e65e-46cc-8f2b-ef66a32e5a76",
    "container_id": "MEDU8381210",
    "bill_of_lading": null,
    "booking_number": null,
    "carrier_scac": "MSCU",
    "callback_url": "https://webhook.site/8c650d00-aa31-4a4b-a483-1fcc88e4337d",
    "organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
    "parent_reference_id": null,
    "organization": {
        "id": "777ccf97-c75b-4051-893b-a47a367bf185",
        "name": "Organization",
        "active": true,
        "created_at": "2023-01-25T18:46:49.676Z",
        "updated_at": "2023-10-10T01:01:35.560Z"
    },
    "carrier_id": 6,
    "carrier": {
        "id": 6,
        "name": "MSC",
        "code": "MSCU",
        "enabled": true
    },
    "active": true,
    "auto_carrier": false,
    "last_update_status": "data_received",
    "created_at": "2023-11-28T01:53:03.669Z",
    "updated_at": "2023-11-28T01:53:06.114Z",
    "last_update_attempted_at": "2023-11-28T01:53:03.935Z",
    "retry_count": 0,
    "child_reference_ids": []
},
{
    "id": "1f95ae71-5cbd-4c77-9c90-2c856e17eb03",
    "container_id": "MEDU8381210",
    "bill_of_lading": null,
    "booking_number": null,
    "carrier_scac": "MSCU",
    "callback_url": "https://webhook.site/#!/92cc0ca9-37d7-417e-8afd-baa6b2bb0d23",
    "organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
    "parent_reference_id": null,
    "organization": {
        "id": "777ccf97-c75b-4051-893b-a47a367bf185",
        "name": "Organization",
        "active": true,
        "created_at": "2023-01-25T18:46:49.676Z",
        "updated_at": "2023-10-10T01:01:35.560Z"
    },
    "carrier_id": 6,
    "carrier": {
        "id": 6,
        "name": "MSC",
        "code": "MSCU",
        "enabled": true
    },
    "active": true,
    "auto_carrier": false,
    "last_update_status": null,
    "created_at": "2023-11-28T01:52:09.400Z",
    "updated_at": "2023-11-28T01:52:09.400Z",
    "last_update_attempted_at": null,
    "retry_count": 0,
    "child_reference_ids": []
},
{
    "id": "1d9e7094-25b2-47f7-8c3f-c0f786cded1d",
    "container_id": "MEDU8381210",
    "bill_of_lading": null,
    "booking_number": null,
    "carrier_scac": "MSCU",
    "callback_url": "https://webhook.site/92cc0ca9-37d7-417e-8afd-baa6b2bb0d23",
    "organization_id": "777ccf97-c75b-4051-893b-a47a367bf185",
    "parent_reference_id": null,
    "organization": {
        "id": "777ccf97-c75b-4051-893b-a47a367bf185",
        "name": "Organization",
        "active": true,
        "created_at": "2023-01-25T18:46:49.676Z",
        "updated_at": "2023-10-10T01:01:35.560Z"
    },
    "carrier_id": 6,
    "carrier": {
        "id": 6,
        "name": "MSC",
        "code": "MSCU",
        "enabled": true
    },
    "active": true,
    "auto_carrier": false,
    "last_update_status": null,
    "created_at": "2023-11-28T01:51:02.211Z",
    "updated_at": "2023-11-28T01:51:02.211Z",
    "last_update_attempted_at": null,
    "retry_count": 0,
    "child_reference_ids": []
},
...
```

## Next steps

In this tutorial, you learned how to use the Container Tracking API to subscribe to a container. By utilizing the command line and cURL, you accessed the API and created a <Glossary>callback URL</Glossary> to receive realtime data updates through webhooks. With these steps, you can effectively track containers and receive updates throughout their journey. Check out our [Input options for tracking containers](https://docs.vizionapi.com/docs/input-options) and [Use the Vizion Postman collection](https://docs.vizionapi.com/docs/use-the-vizion-postman-collection) for more introductory material.