Simple MBL

Simple MBL 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 Simple MBL, 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

Simple MBL 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

Simple MBL 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. The tables below list the possible milestones you may receive — not every shipment will generate every milestone listed, since that depends on what actually happens during that shipment's journey.

📘
These milestone events are built from document_type/transport_mode and event_type combinations. For the full reference list of the underlying DCSA codes, see DCSA Event Code Types.

SHIPMENT milestones

SHIPMENT events 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).

Milestone Event Names	Milestone Description
Carrier release	Carrier has issued the message releasing the shipment
Customs hold	Shipment has been placed on hold by customs
Customs hold released	Customs hold on the shipment has been released
Customs release	Shipment has been released by customs
Freight hold	Shipment has been placed on hold pending freight charges
Freight hold released	Freight hold on the shipment has been released

TRANSPORT milestones

TRANSPORT events are driven by occurrences in the general transport of a shipment, and include all customer-relevant events carried out by one or more modes of transport. The milestone names below reflect the actual description values seen in production Simple MBL payloads — the same underlying arrival/departure event is reported with different wording depending on where in the journey it happens (origin, destination, or a transshipment stop).

Milestone Event Names	Milestone Description
Vessel departed	Vessel has departed a place of operations (last mooring released)
Vessel departure from origin port	Vessel has departed the origin port
Vessel departure from transshipment port	Vessel has departed a transshipment port
Feeder departed	Feeder vessel has departed a place of operations
Vessel arrived	Vessel has arrived at port and is berthed for load/discharge operations
Vessel arrived at destination port	Vessel has arrived and berthed at the destination port
Vessel arrival at transshipment port	Vessel has arrived and berthed at a transshipment port
Vessel arrived at origin port	Vessel has arrived and berthed at the origin port
Vessel berthed in port	Vessel has berthed in port
Vessel berthed at transshipment port	Vessel has berthed at a transshipment port
Feeder arrived	Feeder vessel has arrived and berthed
Estimated arrival at destination	Estimated (not yet actualized) arrival at the destination
Cargo cutoff date	The cargo cutoff deadline for the vessel
Terminal earliest receiving date	The earliest date the terminal will receive cargo for the vessel
Rail departed	Rail transport has departed the platform or rail head
Rail departed from destination port	Rail transport has departed the destination port
Rail departed from origin port	Rail transport has departed the origin port
Rail arrived	Rail transport has arrived and is stationary at the platform or rail head
Rail arrived at origin port	Rail transport has arrived at the origin port
Rail arrived at destination	Rail transport has arrived at the destination
Rail arrived at inland destination	Rail transport has arrived at the inland destination
Rail arrival at interchange facility	Rail transport has arrived at an interchange facility
Truck departed	Truck has departed a place of operations
Truck departed from destination port	Truck has departed the destination port
Truck departure at transshipment port	Truck has departed a transshipment port
Truck arrived	Truck has arrived and is ready for load/discharge operations
Truck arrived at origin port	Truck has arrived at the origin port
Truck arrived at transshipment port	Truck has arrived at a transshipment port
Barge departed	Barge has departed a place of operations
Barge arrived	Barge has arrived at port and is ready for load/discharge operations
Barge arrived at destination	Barge has arrived at the destination

Subscribing to a Master Bill of Lading

To track a Master Bill of Lading using Simple MBL, 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

Simple MBL'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 Simple MBL

{
  "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 Simple MBL

Please click here to learn more about Simple MBL 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.