Skip to main content

🔎 Widget API

Widget API​

The widget API answers one-off lookups: send a single reference and get back the shipment that best matches it, with its containers, their latest status, the vessel's track and a link to the shipment in your Dockflow portal. It is the endpoint the Widget Embed uses. Call it yourself to show the same data in your own interface.

Using the v2 widget API?

GET /api/v2/widget-search with a Web widget key from Settings → Organisation keeps working. It is documented under API v2 › Web-widget API. This page describes the Trident (v3) endpoint, which takes an API Console key with the Widget scope.

Authentication 🔑​

Create a key with only the Widget scope in the API Console (see Authorization). Send it in the Authorization header. The bare key and the Bearer scheme are both accepted:

Authorization: Bearer prod_acme-logistics_Zk3n1c0Q2m9...

A widget key only ever searches the shipments of your own organisation, and only on this endpoint. Downstream and upstream keys are refused here, and a widget key is refused on every other Trident endpoint.

Request​

GET https://api.dockflow.com/v3/widget/search?q=YOUR_REFERENCE

Use https://uat.dockflow.com/v3/widget/search with a uat_… key.

ParameterDescription
q(mandatory) A container number, booking or bill of lading reference, 4 to 64 characters.

Only the best match is returned, never a list.

Response 📋​

FieldDescription
referencesYour own references for the shipment (order, PO, …)
carrierCarrier name, null when unknown
booking_reference / bill_of_lading_referenceCarrier references, null when unknown
departure / arrivalPort of loading and of discharge: vessel_name, event_date, whether that date is actual, and the location
containersEach container with its type_code, type_group, length and its latest_actual_milestone
tracksPosition readings along the route (event_date, lat, lng), one entry per tracking source
details_urlThe shipment in your Dockflow portal, null when nothing matches

A location has a name, unlocode, timezone, country (name, iso_a2) and a point (lat, lng). point is null when the coordinates are unknown. Dates are ISO 8601. Show them in the location's timezone, not in UTC, or an event can land on the wrong day.

A milestone's status is a readable label for the main events:

LabelEvent
Gate out emptyEmpty container picked up
Gate in fullFull container delivered at the terminal
Loaded on vesselLoaded on board
Vessel departureVessel left the port
Vessel arrivalVessel arrived in the port
Unloaded from vesselDischarged from the vessel
Gate out fullFull container picked up at the terminal
Gate out to inland depotMoved to an inland depot
Empty returnEmpty container returned

Other events are returned with their raw Dockflow status code.

details_url points to your organisation's own portal domain when you have one (for example https://yourcompany.dockflow.com/tradeflow/view/…), and to app.dockflow.com otherwise. Opening it requires a Dockflow account with access to the shipment.

Example​

{
    "references": ["PO-2026-0418"],
    "carrier": "MSC",
    "booking_reference": "EBKG04821937",
    "bill_of_lading_reference": "MEDUAN482193",
    "departure": {
        "vessel_name": "MSC DEMO",
        "event_date": "2026-09-25T11:00:00+00:00",
        "actual": true,
        "location": {
            "name": "Antwerpen",
            "unlocode": "BEANR",
            "timezone": "Europe/Brussels",
            "country": { "name": "Belgium", "iso_a2": "BE" },
            "point": { "lat": 51.2637, "lng": 4.3987 }
        }
    },
    "arrival": {
        "vessel_name": "MSC DEMO",
        "event_date": "2026-10-05T09:00:00+00:00",
        "actual": false,
        "location": {
            "name": "Istanbul",
            "unlocode": "TRIST",
            "timezone": "Europe/Istanbul",
            "country": { "name": "Türkiye", "iso_a2": "TR" },
            "point": { "lat": 40.9667, "lng": 28.8 }
        }
    },
    "containers": [
        {
            "reference": "DEMU1234565",
            "type_code": "45G1",
            "type_group": "GP",
            "length": "40",
            "latest_actual_milestone": {
                "status": "Vessel departure",
                "event_date": "2026-09-25T11:00:00+00:00",
                "vessel_name": "MSC DEMO",
                "location": {
                    "name": "Antwerpen",
                    "unlocode": "BEANR",
                    "timezone": "Europe/Brussels",
                    "country": { "name": "Belgium", "iso_a2": "BE" },
                    "point": { "lat": 51.2637, "lng": 4.3987 }
                }
            }
        }
    ],
    "tracks": [
        {
            "device_reference": "AIS MSC DEMO",
            "readings": [
                { "event_date": "2026-09-25T12:00:00+00:00", "lat": 51.33, "lng": 4.25 },
                { "event_date": "2026-09-25T18:00:00+00:00", "lat": 51.45, "lng": 3.1 }
            ]
        }
    ],
    "details_url": "https://yourcompany.dockflow.com/tradeflow/view/482193"
}

Nothing found​

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

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

Errors​

Error bodies have the shape {"error": "<message>", "status": <code>}. The key errors are listed under Authorization › Authentication errors. Two more are specific to this endpoint:

StatusMessageCause
403Token lacks the "widget" scope.A downstream or upstream key was used. Create a separate key with only the Widget scope.
422{"message": …, "errors": {"q": [ … ]}}q is missing, or shorter than 4 or longer than 64 characters.

Feedback and Support 📧​

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