Customs Clearance API

The Customs Clearance API is a tracking option that reports milestones based on the MBL (master bill of lading), rather than its individual containers.

This API seamlessly integrates with your existing systems and provides real-time access to critical customs data, allowing you to make informed decisions faster and optimize your workflow.

Use cases

Using the Custom Clearance API, you can accomplish the following:

Automate routine tasks, reducing manual data entry and errors.
Prioritize containers based on urgency and compliance requirements.
Expedite the customs clearance process and minimize delays.
Enhance visibility into the status of each Master Bill of Lading in real-time.

How it works

The customs clearance API checks for new information related to the bill of lading on a daily basis, ensuring you have the most accurate information for managing customs entries.

Since milestones are related to the master bill of lading (and not its constituent containers), payloads will only have TRANSPORT and SHIPMENT type journey events.

Supported milestones

The customs clearance API presents milestones at the level of the Master Bill of Lading, which means that you won't expect to see container-level events, such as a discharge. Instead, the milestones will be of either the DCSA journey type SHIPMENT or TRANSPORT, which are explained in more detail below.

SHIPMENT events

SHIPMENT events are events which are driven by occurrences in the customer-facing information flow tied to a shipment. A shipment can consist of FCL/LCL (plus carrier/merchant haulage). A SHIPMENT event consists of a document_type and an event_type, and its possible values are below:

List of SHIPMENT event document_types

document_type	Description
`BKG`	"Booking" is a reservation of space and/or equipment for a vessel/voyage and possibly inland transport with a specific origin/destination/equipment type and commodity.
`SHI`	"Shipping Instruction" is an enrichment to the original booking shared by the shipper to the carrier. The shipping instruction includes volume/weight, shipping dates, origin, destination, and other special instructions. The information given by the shipper through the shipping instructions is the information which is required to create the Bill of Lading.
`VGM`	"VGM" is a notification of reception of the declaration informing the carrier of the weight of the container, verified by an authorized person from the shipper or on behalf of said shipper. This includes cargo weight, bracing, dunnage and container tare weight.
`SRM`	"Shipment Release Message" is document sent to the consignee informing, that the shipment can now be released from its current location and transferred to the consignee on gate-out.
`TRD`	"Transportation Document" is a document that governs the terms of carriage between shipper and carrier for maritime transportation. 2 distinct types of transport documents exist: Original Bill of Lading and Sea Waybill
`ARN`	"Arrival Notice" is a notification to the notifying party (often the consignee and/or notify party) on the estimated arrival time of the shipment.
`CAS`	"Cargo Survey" is an activity identifier of the act of documenting details on the cargo on behalf of the carrier, customer, or authorities. This could be the measurement of an out of gauge shipment, packing of dangerous goods or any element which requires specific documentation of the physical condition of the cargo. It can have Requested or Completed status.
`CUS`	"Customs Inspection" is an activity identifier that is used to denote the status of a shipment and/ or container regarding inspection by the respective customs authorities. It can have a status of "On Hold" or "Released".
`DGD`	"Dangerous Good Desclaration" is a notification of reception of the Document issued by a shipper (consignor) in accordance with applicable conventions or regulations, describing hazardous goods or materials for transport purposes, and stating that the latter have been packed and labelled in accordance with the provisions of the relevant conventions or regulations.
`OOG`	"Out-of-Gauge" Is a notification of reception of the declaration for Cargo that has been loaded into special equipment, that exceed the dimensions of a standard 20', 40', or high cube container e.g., Out-of-gauge cargo is over length, over width, over height, or combinations thereof.

List of SHIPMENT event event_types

event_type	Description
`APPR`	Approved; indicates that a document has been approved by the counterpart.
`CANC`	Cancelled; a status indicator to be used when the booking is cancelled by the Shipper.
`CMPL`	Completed; a status indicator that can be used with a number of activity identifiers to denote that a certain activity, service or document has been completed.
`CONF`	Confirmed; indicates that the document is confirmed.
`DRFT`	Drafted; indicates that a document is in draft mode being updated by either the shipper or the carrier.
`HOLD`	On hold; a status indicator that can be used with a number of activity identifiers to denote that a container or shipment has been placed on hold i.e. can’t progress in the process.
`ISSU`	Issued; indicates that a document has been issued by the carrier.
`PENA`	Pending approval; indicates that a document has been submitted by the shipper or carrier and is now awaiting approval by the counterpart.
`PENU`	Pending update; indicates that the carrier requested an update from the shipper which is not received yet.
`RECE`	Received; indicates that a document is received by the carrier or shipper.
`REJE`	Rejected; indicates that a document has been rejected by the carrier.
`RELS`	Released; a status indicator that can be used with a number of activity identifiers to denote that a container or shipment has been released i.e. allowed to move from depot or terminal by authorities or service provider.
`REQS`	Requested; a status indicator that can be used with a number of identifiers to denote that a certain activity, service or document has been requested by the carrier, customer or authorities. This status remains constant until the requested activity is “Completed”.
`SUBM`	Submitted; indicates that a document has been submitted by the customer to the carrier.
`SURR`	Surrendered; indicates that a document has been surrendered by the customer to the carrier.
`VOID`	Void; cancellation of an original document.

TRANSPORT events

TRANSPORT events are events which are driven by occurrences in the general transport of a shipment. A Transport Journey includes all customer-relevant events carried out by one or more modes of transport. A TRANSPORT event consists of a transport_mode and an event_type, and its possible values are below:

List of TRANSPORT event transport_modes

transport_mode	Description
`VESSEL`	"Vessel" is a floating, sea going structure (mother vessels and feeder vessels) with either an internal or external mode of propulsion designed for the transport of cargo and/or passengers. Ocean vessels are uniquely identified by an IMO number consisting of 7 digits, or alternatively by their AIS signal with an MMSI number.
`RAIL`	"Rail" is a transport designed for the movement of goods or people. In the context of the event naming structure, this is limited to rail transport designed for containerized cargo.
`BARGE`	"Barge" is a flat-bottomed floating structure built mainly for transport of cargo/equipment at coastal areas, rivers, canals or on open sea. A barge may or may not be self-propelled.

List of TRANSPORT event event_types

event_type	Description
`ARRI`	The event which occurs, when a mode of transport reaches its final or intermediate destination, and the mode of transport is ready for load/discharge operations to begin at the specified location.
`DEPA`	The event which occurs when a mode of transport leaves a place of operations.

Subscribing to a Master Bill of Lading

To track a Master Bill of Lading using the customs clearance API, simply add the parameter simple_tracking, set to true, in your request body as shown below:

{
    "bill_of_lading": "USG0280709",
    "carrier_code": "CMDU",
    "simple_tracking": true,
    "callback_url": "{{callbackUrl}}"
}

Response structure

The customs clearance API's update schema is similar to that of container tracking, except the container_id and container_iso fields will always be null, as shown below:

Example update payload using the customs clearance API

{
  "id": "8f34dfbb-bd30-4346-897d-300ffd6bb71d",
  "payload": {
    "carrier_scac": "CMDU",
    "container_id": null,
    "container_iso": null,
    "bill_of_lading": "USG0280709",
    "booking_number": null,
    "inland_origin": {
      "name": "Shanghai",
      "city": "Shanghai",
      "state": "Shanghai",
      "country": "China",
      "unlocode": "CNSGH",
      "splc_cd": null,
      "firms_cd": null,
      "bic_cd": null,
      "smdg_cd": null,
      "facility": null,
      "geolocation": {
        "latitude": 31.23333,
        "longitude": 121.48333
      }
    },
    "origin_port": {
      "name": "Sipg Zhendong Container Terminal",
      "city": "Shanghai",
      "state": "Shanghai",
      "country": "China",
      "unlocode": "CNSGH",
      "splc_cd": null,
      "firms_cd": null,
      "bic_cd": null,
      "smdg_cd": "CNSGHWAIG",
      "facility": "WAIG",
      "geolocation": {
        "latitude": 31.375,
        "longitude": 121.57944
      }
    },
    "destination_port": {
      "name": "Fenix Marine Container Terminal (Fms)",
      "city": "San Pedro",
      "state": "California",
      "country": "United States",
      "unlocode": "USLAX",
      "splc_cd": null,
      "firms_cd": null,
      "bic_cd": "USLAXINBU",
      "smdg_cd": "USLAXEAGLE",
      "facility": "EAGLE",
      "geolocation": {
        "latitude": 33.73389,
        "longitude": -118.25306
      }
    },
    "inland_destination": {
      "name": null,
      "city": null,
      "state": null,
      "country": null,
      "unlocode": null,
      "splc_cd": null,
      "firms_cd": null,
      "bic_cd": null,
      "smdg_cd": null,
      "facility": null,
      "geolocation": {
        "latitude": null,
        "longitude": null
      }
    },
    "milestones": [
      {
        "timestamp": "2024-08-31T23:11:00.000+08:00",
        "location": {
          "name": "Sipg Zhendong Container Terminal",
          "city": "Shanghai",
          "state": "Shanghai",
          "country": "China",
          "unlocode": "CNSGH",
          "splc_cd": null,
          "firms_cd": null,
          "bic_cd": null,
          "smdg_cd": "CNSGHWAIG",
          "facility": "WAIG",
          "geolocation": {
            "latitude": 31.375,
            "longitude": 121.57944
          }
        },
        "description": "Vessel departure from origin port",
        "raw_description": "Vessel Departure",
        "journey_event": {
          "event_classifier": "ACT",
          "journey_type": "TRANSPORT",
          "transport_mode": "VESSEL",
          "facility_type": "POTE",
          "empty_indicator": null,
          "event_type": "DEPA"
        },
        "shipment_location": {
          "type_code": "POL"
        },
        "vessel": "PRESIDENT WILSON",
        "vessel_imo": "9218686",
        "vessel_mmsi": null,
        "voyage": "0DBJFE1PL",
        "planned": false,
        "mode": "Vessel",
        "transport_type": null,
        "source": "carrier"
      },
      {
        "timestamp": "2024-08-31T23:29:08.000+08:00",
        "location": {
          "name": "Sipg Zhendong Container Terminal",
          "city": "Shanghai",
          "state": "Shanghai",
          "country": "China",
          "unlocode": "CNSGH",
          "splc_cd": null,
          "firms_cd": null,
          "bic_cd": null,
          "smdg_cd": "CNSGHWAIG",
          "facility": null,
          "geolocation": {
            "latitude": 31.375,
            "longitude": 121.57944
          }
        },
        "description": "Vessel departure from origin port",
        "raw_description": "departure",
        "journey_event": {
          "journey_type": "TRANSPORT",
          "event_classifier": "ACT",
          "event_type": "DEPA",
          "transport_mode": "VESSEL",
          "facility_type": "POTE"
        },
        "shipment_location": {
          "type_code": "POL"
        },
        "vessel": "PRESIDENT WILSON",
        "vessel_imo": "9218686",
        "vessel_mmsi": null,
        "voyage": "0DBJGW1PL",
        "planned": false,
        "mode": "Vessel",
        "transport_type": null,
        "source": "ais"
      },
      {
        "timestamp": "2024-09-03T11:28:20.000+09:00",
        "location": {
          "name": "Busan New Container Terminal (Bnct)",
          "city": "Busan",
          "state": "Busan",
          "country": "South Korea",
          "unlocode": "KRPUS",
          "splc_cd": null,
          "firms_cd": null,
          "bic_cd": null,
          "smdg_cd": "KRPUSBNCT",
          "facility": null,
          "geolocation": {
            "latitude": 35.06778,
            "longitude": 128.81278
          }
        },
        "description": "Vessel arrived",
        "raw_description": "berth",
        "journey_event": {
          "journey_type": "TRANSPORT",
          "event_classifier": "ACT",
          "event_type": "ARRI",
          "transport_mode": "VESSEL",
          "facility_type": null
        },
        "shipment_location": {
          "type_code": null
        },
        "vessel": "PRESIDENT WILSON",
        "vessel_imo": "9218686",
        "vessel_mmsi": null,
        "voyage": "0DBJGW1PL",
        "planned": false,
        "mode": "Vessel",
        "transport_type": null,
        "source": "ais"
      },
      {
        "timestamp": "2024-09-04T12:14:07.000+09:00",
        "location": {
          "name": "Busan New Container Terminal (Bnct)",
          "city": "Busan",
          "state": "Busan",
          "country": "South Korea",
          "unlocode": "KRPUS",
          "splc_cd": null,
          "firms_cd": null,
          "bic_cd": null,
          "smdg_cd": "KRPUSBNCT",
          "facility": null,
          "geolocation": {
            "latitude": 35.06778,
            "longitude": 128.81278
          }
        },
        "description": "Vessel departed",
        "raw_description": "departure",
        "journey_event": {
          "journey_type": "TRANSPORT",
          "event_classifier": "ACT",
          "event_type": "DEPA",
          "transport_mode": "VESSEL",
          "facility_type": null
        },
        "shipment_location": {
          "type_code": null
        },
        "vessel": "PRESIDENT WILSON",
        "vessel_imo": "9218686",
        "vessel_mmsi": null,
        "voyage": "0DBJGW1PL",
        "planned": false,
        "mode": "Vessel",
        "transport_type": null,
        "source": "ais"
      },
      {
        "timestamp": "2024-09-19T05:59:10.000-07:00",
        "location": {
          "name": "Fenix Marine Container Terminal (Fms)",
          "city": "San Pedro",
          "state": "California",
          "country": "United States",
          "unlocode": "USLAX",
          "splc_cd": null,
          "firms_cd": null,
          "bic_cd": "USLAXINBU",
          "smdg_cd": "USLAXEAGLE",
          "facility": null,
          "geolocation": {
            "latitude": 33.73389,
            "longitude": -118.25306
          }
        },
        "description": "Vessel arrived at destination port",
        "raw_description": "berth",
        "journey_event": {
          "journey_type": "TRANSPORT",
          "event_classifier": "ACT",
          "event_type": "ARRI",
          "transport_mode": "VESSEL",
          "facility_type": "POTE"
        },
        "shipment_location": {
          "type_code": "POD"
        },
        "vessel": "PRESIDENT WILSON",
        "vessel_imo": "9218686",
        "vessel_mmsi": null,
        "voyage": "0DBJGW1PL",
        "planned": false,
        "mode": "Vessel",
        "transport_type": null,
        "source": "ais"
      },
      {
        "timestamp": "2024-09-19T06:05:00.000-07:00",
        "location": {
          "name": "Fenix Marine Container Terminal (Fms)",
          "city": "San Pedro",
          "state": "California",
          "country": "United States",
          "unlocode": "USLAX",
          "splc_cd": null,
          "firms_cd": null,
          "bic_cd": "USLAXINBU",
          "smdg_cd": "USLAXEAGLE",
          "facility": "EAGLE",
          "geolocation": {
            "latitude": 33.73389,
            "longitude": -118.25306
          }
        },
        "description": "Vessel arrived at destination port",
        "raw_description": "Vessel Arrival",
        "journey_event": {
          "event_classifier": "ACT",
          "journey_type": "TRANSPORT",
          "transport_mode": "VESSEL",
          "facility_type": "POTE",
          "empty_indicator": null,
          "event_type": "ARRI"
        },
        "shipment_location": {
          "type_code": "POD"
        },
        "vessel": "PRESIDENT WILSON",
        "vessel_imo": "9218686",
        "vessel_mmsi": null,
        "voyage": "0DBJGW1PL",
        "planned": false,
        "mode": "Vessel",
        "transport_type": null,
        "source": "carrier"
      },
      {
        "timestamp": "2024-09-20T01:52:00.000-07:00",
        "location": {
          "name": "Fenix Marine Container Terminal (Fms)",
          "city": "San Pedro",
          "state": "California",
          "country": "United States",
          "unlocode": "USLAX",
          "splc_cd": null,
          "firms_cd": null,
          "bic_cd": "USLAXINBU",
          "smdg_cd": "USLAXEAGLE",
          "facility": null,
          "geolocation": {
            "latitude": 33.73389,
            "longitude": -118.25306
          }
        },
        "description": "Vessel arrived at destination port",
        "raw_description": "{\"ActualArrivalMode\":\"VESSEL\"}",
        "journey_event": {
          "journey_type": "TRANSPORT",
          "event_classifier": "ACT",
          "event_type": "ARRI",
          "transport_mode": "VESSEL",
          "facility_type": "POTE"
        },
        "shipment_location": {
          "type_code": "POD"
        },
        "vessel": null,
        "vessel_imo": null,
        "vessel_mmsi": null,
        "voyage": null,
        "planned": false,
        "mode": "Vessel",
        "transport_type": null,
        "source": "terminal"
      }
    ],
    "reference_id": "d2e18bc6-752a-4a21-8292-4714cefdce0a"
  },
  "status": "data_received",
  "organization_id": "5c9f3d52-2743-4868-89d1-c88af9ca8396",
  "reference_id": "d2e18bc6-752a-4a21-8292-4714cefdce0a",
  "created_at": "2024-10-01T17:52:41.204Z",
  "parent_reference_id": null,
  "nonce": "852c92477a1941cc2d4ac84c0cfe2e18"
}

Enabling customs clearance

Please click here to learn more about the Custom Clearance API on the Vizion API website.

Additionally, our Sales team welcomes the opportunity to discuss how this API can specifically benefit your operations and provide a personalized demonstration. To schedule a personalized demo of the API in action, contact sales.

If you have any further questions, please contact support.