This list is intended to help new and existing API developers ensure that they are using the API to its full capacity when designing a MVP for an integration
When integrating with the Vizion API, the best source of information lies in the API documentation.
However, it can also be useful to know which endpoints are expected to maximize the effectiveness of your integration, and when those endpoints should be call.
The simple process flow looks like this:
- Use the List Carriers endpoint to programmatically check for supported carriers and to retrieve their Vizion carrier codes. The result of this endpoint can be cached for a period of time to reduce requests.
- Create a reference using either Create Reference via Carrier Code endpoint, Create Reference via Bill of Lading endpoint, or the [Beta] Create Reference via Booking Number endpoint.
- Use the Create Reference via ACI endpoint as a backup or only in cases where you truly do not know the carrier code.
- Give the newly-created reference some time (~1 to 2 minutes) to process and complete.
- If created reference has an error such as extraction_failed when checking the Show Reference Details endpoint, try again later or contact Support.
- If created reference has the no_data error when checking the Show Reference Details endpoint, confirm that the container_id or bill_of_lading numbers are correct using Show Reference Details endpoint.
- If reference returns the webhook_failed error when checking the Show Reference Details endpoint, check that the entered callback_url is correct or that your webhook is open to receiving responses from our API. If it still does not work, contact Support.
- If created reference has no errors and returns data_received or duplicate_payload, the update has either been delivered to your webhook or you can pull all available updates from the API directly using the List Reference Updates endpoint.
- If on a Pro plan, you can access the [Beta] List Container Trace endpoint to retrieve vessel movements for a particular reference. We recommend only calling this endpoint either as requested or on an hourly basis.
- Once a reference is no longer desired either due to the container journey being complete (i.e. milestone array contains a "Gate in empty return" event at the destination port), use the Unsubscribe Reference endpoint to stop tracking for that reference.