🔼 Upstream API

Early‑Access API

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

How you can help

1. Try it out in non‑production environments first.
2. 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": {                       // one per tradeflow
    "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",
      }}
  ],

  "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_is_actual": true,

    "port_of_discharge": "USLAX",
    "arrival_event_date": "2025‑06‑06T15:30:00‑07:00",
    "arrival_is_actual": false,

    "transshipment_ports": ["ESBCN"],
    "incoterms": "FOB",
    "cargo_opening_time": "2025‑05‑11T08:00:00+02:00",
    "vessel_name": "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",
      "actual": true,
      "container_reference": "ABCD1234567",
      "location_reference": "BEANR" }
  ]
}

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

---

3 · Location updates

LOCATION_UPDATE

{
  "id": "evt_loc_6ab1",
  "category": "LOCATION",
  "code": "POS",
  "event_date": "2025‑05‑10T11:03:00+02:00",
  "vessel_name": "MAERSK SOPHIE",
  "lat": 51.140,
  "lng": 4.300,
  "sog_knots": 13.2,
  "cog_deg": 223
}

These objects appear in the events array; they do not reference the locations list.

---

4 · Status code table

Code	Category	Description
GE	MILESTONE	Empty equipment dispatched
GN	MILESTONE	Gate in
AE	MILESTONE	Loaded on vessel
VD	SHIPMENT	Vessel departure
VA	SHIPMENT	Vessel arrival
UV	MILESTONE	Unloaded from vessel
GT	MILESTONE	Gate out
GR	MILESTONE	Empty equipment returned
POS	LOCATION	Position update (lat/lng, speed, course)

---

5 · 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.

---

6 · 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).

---

7 · 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.