💻 Web-widget API - ad-hoc requests

A newer version is available

New integrations can use the Trident (v3) Widget API, which authenticates with API Console keys and returns a link to the shipment in your portal. This v2 endpoint keeps working with your existing Web widget keys.

Introduction 🌐

The widget API answers one-off lookups: send a single reference and get back the shipment that best matches it, with its containers and their latest status. It is the same endpoint the embeddable widget uses.

Authentication 🔑

Requests are authenticated with a Web widget key:

In the Dockflow application, open Settings → Organisation and scroll to Web widget.
Click + to create a key. Copy it straight away: it is shown only once, Dockflow only stores a hash of it.

Send the key in the Authorization header. The Basic prefix is optional:

Authorization: Basic YOUR_WIDGET_KEY

note

Keys from the API Console are not accepted here, whatever their scope. Use a Web widget key.

A widget key only ever searches the shipments of the organisation that created it.

Request

GET https://api.dockflow.com/api/v2/widget-search?query=YOUR_REFERENCE

query can be a container number, a bill of lading, a booking number or one of your own references (order, PO, …). Use at least 6 characters.

A query shaped like a container number (4 letters followed by 6 or 7 digits) matches a container or a shipment.
Any other query matches shipments only.

Only the best match is returned, never a list.

Response 📋

Field	Description
`entities`	Your own references for the shipment, as `{ "reference": … }`
`carrier`	Carrier name
`booking_reference` / `bill_of_lading_reference`	Carrier references, `null` when unknown
`departure` / `arrival`	Port of loading / discharge: vessel, date, whether the date is `actual`, and the location including its coordinates (`point`)
`containers`	Each container with its type details and its `latest_actual_milestone`
`tracks`	Position readings along the route, one entry per tracking source

The status_code of a milestone is returned as a readable label for the main events:

Label	Event
`Gate out empty`	Empty container picked up
`Gate in full`	Full container delivered at the terminal
`Loaded on vessel`	Loaded on board
`Vessel departure`	Vessel left the port
`Vessel arrival`	Vessel arrived in the port
`Unloaded from vessel`	Discharged from the vessel
`Gate out full`	Full container picked up at the terminal
`Gate out to inland depot`	Moved to an inland depot
`Empty return`	Empty container returned

Other events are returned with their raw Dockflow status code.

Example

{
    "entities": [{ "reference": "PO-2026-0412" }],
    "carrier": "MSC",
    "booking_reference": "MEDUABC77599",
    "bill_of_lading_reference": null,
    "departure": {
        "vessel": { "name": "MSC AMERICA" },
        "event_date": "2026-08-22T15:30:00+00:00",
        "actual": true,
        "location": {
            "name": "CN Shanghai",
            "unlocode": "CNSHA",
            "timezone": "Asia/Shanghai",
            "country": { "name": "China", "iso_a2": "CN" },
            "point": { "lat": 31.23, "lon": 121.47 }
        }
    },
    "arrival": {
        "vessel": { "name": "MSC AMERICA" },
        "event_date": "2026-10-21T10:15:00+00:00",
        "actual": false,
        "location": {
            "name": "NL Rotterdam",
            "unlocode": "NLRTM",
            "timezone": "Europe/Amsterdam",
            "country": { "name": "Netherlands", "iso_a2": "NL" },
            "point": { "lat": 51.95, "lon": 4.14 }
        }
    },
    "containers": [
        {
            "reference": "TCNU1929808",
            "details": {
                "type_code": "45G1",
                "type_group": "45GP",
                "type_reefer": false,
                "length": 40
            },
            "latest_actual_milestone": {
                "vessel": { "name": "MSC AMERICA" },
                "location": {
                    "name": "SG Singapore",
                    "unlocode": "SGSIN",
                    "timezone": "Asia/Singapore",
                    "country": { "name": "Singapore", "iso_a2": "SG" }
                },
                "event_date": "2026-09-13T01:30:00+00:00",
                "actual": true,
                "status_code": "Vessel departure"
            }
        }
    ],
    "tracks": [
        {
            "device_reference": "MSC AMERICA (AIS)",
            "location_readings": [
                { "event_date": "2026-09-13T02:00:00+00:00", "lat": 1.21, "lng": 103.95 },
                { "event_date": "2026-09-20T02:00:00+00:00", "lat": -34.2, "lng": 25.6 }
            ]
        }
    ]
}

Nothing found

When no shipment matches, the API still answers HTTP 200, with every field empty:

{
    "entities": [],
    "carrier": null,
    "booking_reference": null,
    "bill_of_lading_reference": null,
    "departure": null,
    "arrival": null,
    "containers": [],
    "tracks": []
}

Errors

A missing, malformed or unknown key returns HTTP 401:

{ "error": "Unauthorized", "detail": "Token invalid." }

Feedback and Support 📧

Questions or issues? Reach out to our support team at [email protected].

Widget API​

Introduction 🌐​

Authentication 🔑​

Request​

Response 📋​

Example​

Nothing found​

Errors​

Feedback and Support 📧​

Widget API