Connect Vizion: track containers with milestones from a sales-issued API key

The Vizion API Key is issued by Vizion sales when your account is opened — there is no self-service signup. Paste the key as the single api_key field in Integration, test, map and activate, and container milestones then feed your drayage tracking.

The Vizion connector does one job: container tracking for drayage. You start tracking — a reference — with a container number, a bill of lading number or a booking number, and the connector brings back the milestone updates for that shipment: each milestone carries a planned time (an estimate, ETA) or an actual time (ATA), so you can see both what is expected and what has really happened. That is the whole scope: it does not pull orders, does not create shipments or dispatches, does not book terminal appointments, and does not write anything back to Vizion. One connection works with one Vizion API Key.

Prerequisites#

• A Vizion account opened with Vizion sales, with API access included. The API Key is issued by Vizion sales when the account is opened — there is no self-service signup page, so if you do not have a key yet, getting one from Vizion sales is step zero, before anything in this system.
• The API Key itself, as Vizion sales issued it to you. Keep the original message or document it arrived in — if the key is ever lost or refused, only Vizion sales can reissue it; it cannot be looked up or regenerated from a settings page.
• At least one container, bill of lading or booking number you actually want to track, so you can check the first milestones against a shipment you know. When you have the carrier code (SCAC) for it, keep that ready too — Vizion can identify the carrier automatically, but its own guidance is to provide the carrier code whenever you can.

Get your credentials#

1. Contact Vizion sales and open your Vizion account with API access, if you have not already. The API Key is issued by Vizion sales as part of opening the account.
2. Receive the API Key from Vizion sales. There is no self-service signup and no developer page where you could create one yourself — if a page or a person offers to "register" a Vizion key for you outside the account-opening process, that is not how this key is issued.
3. Copy the full key at once, exactly as issued — keys for this connection start with vizion_ — and keep it ready to paste. Do not shorten it and do not add any prefix to it.
4. There is only this one credential, and only one Vizion address to know: https://prod.vizionapi.com. There is no separate sandbox address to configure — the key you were issued is tested and run against that same address.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Vizion → New connection.
2. api_key — required, Vizion API Key: paste the full key Vizion sales issued to you, starting with vizion_. It is the only field on this connection. It is a password-type field and is stored as a secret. Paste the key only, exactly as issued — the system sends it as the X-API-Key header itself.
3. Save the connection, then run the test before you change anything else — with one field, a failing test is about that key or about whether the account behind it is active, not about finding which of many fields is wrong.

Test the connection#

Click Test connection. With your key filled in, the test sends one real, read-only request: GET https://prod.vizionapi.com/references?limit=1, with your key sent as the X-API-Key header, with a 12-second timeout. It only lists your active references, limited to one, so it changes nothing in Vizion. A passing answer comes back as "Vizion authentication passed". If the key is refused, the test reports HTTP_401. If api_key is empty, it stops with MISSING_CREDENTIALS. A request that cannot be completed reports CONNECTION_FAILED. Fix the cause named by the result, then test again.

Mapping / pick a template#

Pick the Vizion standard mapping. It takes each milestone update Vizion returns for a reference and lines it up with the container record you follow in drayage tracking here, keeping the distinction Vizion itself makes: a milestone marked as planned carries an estimated time (ETA), and one that is not planned carries the actual time (ATA). After the test passes, start tracking for one container, bill of lading or booking you know, and compare the first milestones — event, place, and whether each time is planned or actual — with what Vizion shows for the same shipment. If they match, the mapping is right and you can activate.

Activate#

After activation, you can start tracking from a container number, a bill of lading number or a booking number, and the connection keeps the milestone updates for those references coming into drayage tracking here. Two rules from Vizion apply when you start a reference: give the bill of lading or the booking number, never both together — a request carrying both is rejected — and add the carrier code (SCAC) whenever you have it, because automatic carrier identification is the fallback, not the preferred path. Updates for a reference can also arrive as pushed notifications in the same shape as the pulled updates, so what you see here stays consistent either way. Watch the first references in Runs / Logs and compare a few shipments with Vizion before leaving the connection unattended.

What this connection does not do: it does not pull orders or shipments from any other system, it does not create dispatches or loads, it does not book or change terminal appointments, and it does not send tracking data back to Vizion. It also only tracks references you start — it does not import a shipment history you built elsewhere.

FAQ#

Test fails with HTTP_401

Vizion refused the key you sent. The usual causes are a key that was trimmed while copying, a character changed from the issued original, or a key that Vizion has since replaced or not yet activated on your account. This connection sends the key as the X-API-Key header, exactly as the official documentation specifies, so the sending form is not the variable — the key value is.

Compare the pasted key character by character with the original Vizion sales issued to you, fix any difference, save and test again. If the pasted key matches the original exactly and the test still reports HTTP_401, contact Vizion sales and ask them to confirm the key is active on your account or to reissue it — only Vizion sales can do that, there is no page where you can reset it yourself.

Test stops with MISSING_CREDENTIALS

The api_key field is empty, so there is no key to send and the test cannot check anything. This connection has exactly one field, so there is nowhere else the credential could be hiding.

Paste the full key Vizion sales issued to you into api_key, save the connection, and test again. If you do not have a key yet, get it from Vizion sales first — there is no signup page to create one.

There is no signup page — where do I get a Vizion API Key?

That is by design on the Vizion side: the API Key is not self-service. Keys are issued by Vizion sales when a Vizion account is opened, so there is deliberately no public page that creates one, and this system cannot generate one for you either.

Contact Vizion sales, open the account with API access, and receive the key from them. Then come back to this connection, paste the key into api_key, save and test. If your company already has a Vizion account, ask the colleague who opened it where the issued key is recorded before opening a second account.

Starting tracking fails with INVALID_REQUEST — bill of lading and booking number both given

Vizion validates the two numbers as alternatives: a tracking request may carry a bill of lading or a booking number, but a request carrying both at once is rejected by that validation. It is a rule of the Vizion side, not a fault in either number — each one on its own is acceptable.

Start the tracking again with only one of the two numbers — keep the bill of lading or the booking number, and remove the other. A container number can be given as the identifier instead. Add the carrier code (SCAC) as well when you have it.

Starting tracking fails with INVALID_REQUEST — no identifier given

No identifier was given for the reference. Vizion starts tracking from one identifier — a container number (container_id), a bill of lading number or a booking number — and with none of the three there is nothing to open a reference for.

Start the tracking again with one of the three numbers for that shipment — and remember the pairing rule: if you use the bill of lading, do not add the booking number as well. Add the carrier code (SCAC) when you have it, so Vizion does not have to identify the carrier automatically.

Test fails with CONNECTION_FAILED, or times out after 12 seconds

The read-only request to prod.vizionapi.com could not be completed in time. That is a reachability problem on the way to the Vizion API, or a temporary Vizion slowdown — it is not proof that the key is wrong, because the key is only judged once the API actually answers.

Wait a short while and test again without changing the key. If it keeps failing, note the failing time from Runs / Logs when you ask for help, and tell Vizion support the request goes to https://prod.vizionapi.com with the key in the X-API-Key header, so they can check the same window on their side.

A milestone time looks wrong — it is in the future, or it moved

That milestone is most likely a planned one. In Vizion data, a milestone marked planned=true carries an estimated time (an ETA), which by nature sits in the future and is revised as the shipment moves; a milestone with planned=false carries the actual time (an ATA), which is fixed once it happens. The estimate changing is the data working as intended, not the tracking being wrong.

Read the milestone with its planned flag before acting on the time: plan around planned (ETA) times, and treat only actual (ATA) times as history. If a time marked actual disagrees with what the carrier or terminal shows for the same event, note the reference and the event when you ask Vizion support to check it.