🔼 Upstream API

Early‑Access API

🚧 Heads‑up! This is our next‑generation API and it's still under active development.

How you can help

Try it out in non‑production environments first.
Report issues or request features by mailing [email protected]

Thank you for partnering with us to shape the future of our platform!

Base URL: https://api.dockflow.com/v3 Scope token: upstream_* (production) or uat_upstream_* (sandbox)

1 · Delivery options

Mode	Workflow	Best for
Polling	`GET /upstream` → up to 1000 events, plus `cursor` for the next page.	Batch jobs, cron.
Webhooks	Dockflow POSTs events to your HTTPS URL within seconds (automatic retries).	Real‑time pipelines.

2 · Envelope format

{
  "version": "3.0.0",
  "tradeflow_reference": "PO4564268",

  "data_quality": {                       // information about the Blue Sails
    "freshness_min": 12,
    "anomalies": 0,
    "missed_milestones": 1,
    "has_live_data": true,
    "is_singular_shipment": false
  },

  "metadata": {
    "last_updated": "2025‑05‑10T12:22:48Z",
    "carrier_name": "Maersk",
    "carrier_scac": "MAEU"
  },

  "locations": [
    { "reference": "BEANR", "name": "Port of Antwerp", "type": "SEA_PORT",
      "timezone": "Europe/Brussels", "country": "Belgium",
      "lat": 51.263, "lng": 4.398 }
  ],

  "containers": [
    { "reference": "ABCD1234567", "iso_type": "45R1", "length_ft": 40,
      "is_reefer": true,
      "free_time": {                     // detention & demurrage window
        "demurrage_free_time_expires": "2025‑06‑08T23:59:00+02:00",
        "detention_free_time_expires": "2025‑06‑15T23:59:00+02:00",
      },
      "arrival_at_pod_event_date": "2025‑06‑06T15:30:00‑07:00",  // container ETA/ATA at final POD
      "arrival_at_pod_event_date_extended": {
        "event_date_zulu": "2025-06-06T22:30:00Z",
        "event_date_local": "2025-06-06T15:30:00-07:00",
        "timezone_geo": "America/Los_Angeles",
        "timezone_utc_offset_minutes": -420,
        "timezone_abbreviation": "PDT"
      },
      "arrival_at_pod_is_actual": false,                         // true if actual, false if estimated
      "latest_actual_milestone": {       // last confirmed milestone for this container
        "code": "GN",
        "event_date": "2025‑05‑09T10:34:00+02:00",
        "event_date_extended": {
          "event_date_zulu": "2025-05-09T08:34:00Z",
          "event_date_local": "2025-05-09T10:34:00+02:00",
          "timezone_geo": "Europe/Brussels",
          "timezone_utc_offset_minutes": 120,
          "timezone_abbreviation": "CEST"
        },
        "location_reference": "BEANR",
        "is_pol": false,                 // true if at port of loading
        "is_final_pod": false,           // true if at final port of discharge
        "is_transshipment": false,       // true if at a transshipment port
        "is_prepol": false,              // true if before port of loading
        "is_postpod": false              // true if after final port of discharge
      }}
  ],

  "vessels": [
    { "name": "MAERSK SOPHIE", "imo": "9721234", "mmsi": "219028000" }
  ],

  "shipment": {
    "split_shipment_number": 2,               // undefined if single leg
    "port_of_loading": "BEANR",
    "departure_event_date": "2025‑05‑14T10:00:00+02:00",
    "departure_event_date_extended": {
      "event_date_zulu": "2025-05-14T08:00:00Z",
      "event_date_local": "2025-05-14T10:00:00+02:00",
      "timezone_geo": "Europe/Brussels",
      "timezone_utc_offset_minutes": 120,
      "timezone_abbreviation": "CEST"
    },
    "departure_is_actual": true,

    "port_of_discharge": "USLAX",
    "arrival_event_date": "2025‑06‑06T15:30:00‑07:00",
    "arrival_event_date_extended": {
      "event_date_zulu": "2025-06-06T22:30:00Z",
      "event_date_local": "2025-06-06T15:30:00-07:00",
      "timezone_geo": "America/Los_Angeles",
      "timezone_utc_offset_minutes": -420,
      "timezone_abbreviation": "PDT"
    },
    "arrival_is_actual": false,

    "transshipment_ports": ["ESBCN"],
    "incoterms": "FOB",
    "cargo_opening_time": "2025‑05‑11T08:00:00+02:00",
    "shipment_legs": [
      {
        "sequence_number": 0,
        "departure": "BEANR",
        "arrival": "ESBCN",
        "vessel": "MAERSK SOPHIE"
      },
      {
        "sequence_number": 1,
        "departure": "ESBCN",
        "arrival": "USLAX",
        "vessel": "MAERSK SOPHIE"
      }
    ],

    // Carbon emission attributes
  },

  "events": [
    { "id": "evt_01", "category": "MILESTONE", "code": "GN",
      "message": "Gate in",
      "event_date": "2025‑05‑09T10:34:00+02:00",
      "event_date_extended": {
        "event_date_zulu": "2025-05-09T08:34:00Z",
        "event_date_local": "2025-05-09T10:34:00+02:00",
        "timezone_geo": "Europe/Brussels",
        "timezone_utc_offset_minutes": 120,
        "timezone_abbreviation": "CEST"
      },
      "actual": true,
      "container_reference": "ABCD1234567",
      "location_reference": "BEANR",
      "is_pol": false,
      "is_final_pod": false,
      "is_transshipment": false,
      "is_prepol": false,
      "is_postpod": false }
  ]
}

All date‑times (event_date, free‑time expiry, cargo opening) are expressed in the timezone of the location.

3 · Location type flags

Both the latest_actual_milestone object (in containers) and all events in the events array include boolean flags indicating the type of location where the milestone occurred:

is_pol: Port of Loading — where the container was loaded onto the first vessel
is_final_pod: Final Port of Discharge — where the container will be unloaded from the final vessel
is_transshipment: Transshipment Port — intermediate port where cargo transfers between vessels
is_prepol: Pre-POL Location — locations before the port of loading (e.g., depot, rail terminal)
is_postpod: Post-POD Location — locations after final discharge (e.g., inland destination, final delivery point)

Note: Multiple flags can be true simultaneously. For example, a milestone at a transshipment port that also serves as a POL for the next leg could have both is_transshipment and is_pol set to true.

Usage: These flags are particularly useful for vessel arrival/departure events (VA/VD) to determine whether the vessel is arriving at or departing from a POL, POD, or transshipment port.

4 · Extended date format

All date fields (event_date, arrival_at_pod_event_date, departure_event_date, arrival_event_date) include a corresponding *_extended object with full timezone context:

Field	Type	Description
`event_date_zulu`	string	UTC/Zulu time in ISO 8601 format
`event_date_local`	string	Local time at the location in ISO 8601 format
`timezone_geo`	string	IANA timezone identifier (e.g., `Europe/Brussels`)
`timezone_utc_offset_minutes`	integer	UTC offset in minutes (e.g., `120` for UTC+02:00)
`timezone_abbreviation`	string	Timezone abbreviation (e.g., `CEST`, `PDT`)

Example:

"event_date": "2025-05-09T10:34:00+02:00",
"event_date_extended": {
  "event_date_zulu": "2025-05-09T08:34:00Z",
  "event_date_local": "2025-05-09T10:34:00+02:00",
  "timezone_geo": "Europe/Brussels",
  "timezone_utc_offset_minutes": 120,
  "timezone_abbreviation": "CEST"
}

Note: If the location has no timezone configured, timezone_geo, timezone_utc_offset_minutes, and timezone_abbreviation will be null, and event_date_local will match the original event_date.

5 · Status code table

Code	Category	Description
GE	MILESTONE	Empty equipment dispatched
GN	MILESTONE	Gate in
AE	MILESTONE	Loaded on vessel
VD	MILESTONE	Vessel departure
VA	MILESTONE	Vessel arrival
UV	MILESTONE	Unloaded from vessel
GT	MILESTONE	Gate out
GR	MILESTONE	Empty equipment returned

6 · Attribute selection

Choose which blocks to receive with the fields parameter (polling and webhooks):

fields=events,locations,containers,shipment

Omit the parameter to get all blocks.

7 · Filters

Param	What it does
`since=ISO‑date`	Only events created after this timestamp (UTC).
`tradeflow=REF`	Filter by tradeflow reference.
`container=REF`	Filter by container reference.
`category=MILESTONE`	Event category.
`code=VD`	Specific status code.
`cursor`	Continue from previous batch.
`per_page=1‑1000`	Page size (default 500).

8 · Error handling

Status	Meaning	Suggested fix
400	Invalid parameter.	Check `fields`/filters spelling.
401	Wrong token scope.	Use an `upstream_*` token.
413	Webhook body too large.	Lower `per_page` or trim blocks via `fields`.
429	Rate limit hit.	Wait 60 s / reduce polling.
5xx	Dockflow outage.	Retry with back‑off.

Questions? Contact [email protected] — engineers respond within one business day.

How you can help​

1 · Delivery options​

2 · Envelope format​

3 · Location type flags​

4 · Extended date format​

5 · Status code table​

6 · Attribute selection​

7 · Filters​

8 · Error handling​