This article discusses duplicate references, why they are allowed, and what you can do to handle or prevent duplicates
What is a duplicate?
When using the Vizion API to create a tracking reference, it's possible to create multiple references that are tracking the same container ID, bill of lading, or booking number. These are known as duplicates.
It's important to distinguish that each reference will have its own unique reference ID, but the details of that container will be the same values.
Here's an example of what creating duplicate references might look like:
[Example A]
Input:
{
"container_id":"CAXU9928302",
"carrier_code":"MSCU"
}
Output (truncated):
{
"message": "Reference created successfully.",
"reference": {
"id": "7c732b69-cb1c-43b6-8747-70a59d309492",
"container_id": "CAXU9928302",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
[Example B]
Input:
{
"container_id":"CAXU9928302",
"carrier_code":"MSCU"
}
Output (truncated):
{
"message": "Reference created successfully.",
"reference": {
"id": "9506c503-fd84-4da0-86ec-cbd9a1601ea9",
"container_id": "CAXU9928302",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
Notice that both input request bodies above are exactly the same, but the reference object in the output shows two unique ID numbers which are shown in bold.
This means that there are now two active references tracking container CAXU9928302 with MSCU.
Why is it possible to create a reference that duplicates a container?
The Vizion API allows for duplicates in order to provide flexibility in terms of integration. For a user that does not wish to create duplicates, there exists another user who requires the ability to create duplicates.
If multiple users using the same integration wish to separately track the same container, the API does not block this action.
It's also comparable to how a machine in a factory works. If the request to create something is made and there are no faults in the request itself (bad format, access denied, etc), the machine will function to the specifications of the request. If the machine is asked to track the same container ten times, it will create ten unique references in the system that are all tracking the same container.
How to prevent duplicates
In terms of simplicity, we have a free feature that can be enabled for your API keys to allow for automatic duplicate prevention. Just reach out to Support at support@vizionapi.com and one of our engineers will gladly enable this feature for you.
In order to currently manually prevent duplicates, it's best to compare your existing active references against the reference that you're attempting to create.
This can be accomplished by using the List Active References endpoint of the Vizion API.
Using the example request from above, a duplicate can be avoided.
[Input example]
{
"container_id":"CAXU9928302",
"carrier_code":"MSCU"
}
First, check to see if one of the active references is already tracking a container with the ID of CAXU9928302 with the carrier code of MSCU.
Input:
GET https://demo.vizionapi.com/references?include_metadata=true&page=1&limit=25
The output will look similar to this:
{
"data": [
{
"id": "9506c503-fd84-4da0-86ec-cbd9a1601ea9",
"container_id": "CAXU9928302",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "MSCU",
"callback_url": null,
"organization_id": "fa6ba8f0-52a6-42c3-9c1a-d92a58a31945",
"parent_reference_id": null,
},
{
"id": "11b7cd8c-d71e-47b3-8c6b-12749f6a74e9",
"container_id": "MRSU4167060",
"bill_of_lading": "MAEU228164213",
"booking_number": null,
"carrier_scac": "MAEU",
"callback_url": "https://webhook.site/53b5e97c-b6f2-449f-98fc-49fc404221e1",
"organization_id": "fa6ba8f0-52a6-42c3-9c1a-d92a58a31945",
"parent_reference_id": null,
},
{
"id": "49a50b4d-a418-41c6-a558-387f7077a055",
"container_id": "TCNU4256362",
"bill_of_lading": "ZIMUHCM80337764",
"booking_number": null,
"carrier_scac": "ZIMU",
"callback_url": "https://webhook.site/53b5e97c-b6f2-449f-98fc-49fc404221e1",
"organization_id": "fa6ba8f0-52a6-42c3-9c1a-d92a58a31945",
"parent_reference_id": null,
},
{
"id": "7c05cf47-cf4c-4f22-9336-494b34486286",
"container_id": "FCIU9708080",
"bill_of_lading": null,
"booking_number": null,
"carrier_scac": "OOCL",
"callback_url": "https://webhook.site/53b5e97c-b6f2-449f-98fc-49fc404221e1",
"organization_id": "fa6ba8f0-52a6-42c3-9c1a-d92a58a31945",
"parent_reference_id": null,
},
{
"id": "5109e282-8708-4009-90ce-70802f73b59e",
"container_id": "FCIU9708080",
"bill_of_lading": "OOLU2720664770",
"booking_number": null,
"carrier_scac": "OOCL",
"callback_url": "https://webhook.site/53b5e97c-b6f2-449f-98fc-49fc404221e1",
"organization_id": "fa6ba8f0-52a6-42c3-9c1a-d92a58a31945",
"parent_reference_id": null,
}
]
}
In the above, the very first reference in the list with the ID of 9506c503-fd84-4da0-86ec-cbd9a1601ea9 is already tracking the container with ID CAXU9928302 with the carrier code of MSCU.
To avoid manual inspection before every created reference, a possible recommendation would be to create a loop that looks through the `data` object and compares the entered values (i.e. container_id, carrier_code) against each item's container ID and carrier code.
If a match is found, do not create a new reference.
If a match is not found, proceed with creating the reference.
How to handle existing duplicates
If you have not been safeguarding against duplicates and find that your account has created many unwanted duplicates, using the List Active References endpoint of the Vizion API can help you locate any duplicates after performing an inspection.
Once you've identified a list of reference IDs, unsubscribe for each unwanted reference using the Unsubscribe Reference endpoint.
If you find that there are too many duplicates to manage alone, please reach out to Support at support@vizionapi.com and we can determine if we can assist with your issue.