🚀 Getting started (Dockflow API v3)

Using Dockflow in the browser?

This section is for API integration. For how to use the web app (dashboard, automations, terminals), start with the product introduction.

Dockflow offers a single REST API.
Use it to push purchase orders and containers into the platform and to pull milestones, documents and analytics back into any system.

---

1 · Create an API token 🔑

1. Sign in to the API Console at console.dockflow.com and open API Keys.
2. Create a key, pick Production or UAT and the scopes it is for: downstream, upstream or widget.
3. Copy the key. It is shown only once.

Every request sends the key in the Authorization header, with or without a Bearer prefix. Key format, environments and error codes: Authorization.

Your first call (UAT, about 2 minutes)

Use a UAT key with both the downstream and upstream scopes, on uat.dockflow.com. Nothing you send there reaches your production account, and mock_tracking gives the tradeflow a predictable journey instead of real carrier data (see UAT environment).

export DOCKFLOW_KEY="uat_acme-logistics_Zk3n1c0Q2m9..."   # your UAT key from the API Console

1. Send a tradeflow.

curl -X POST https://uat.dockflow.com/v3/downstream/tradeflows \
     -H "Authorization: $DOCKFLOW_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "tradeflow_reference": "QUICKSTART-001",
           "port_of_loading": "BEANR",
           "port_of_discharge": "USLAX",
           "mock_tracking": { "scenario": "ocean_basic" }
         }'

The answer is 202 Accepted with {"status": "queued", ...}. Processing finishes a few seconds later.

2. Read it back. A tradeflow filter returns that tradeflow regardless of when it changed:

curl "https://uat.dockflow.com/v3/upstream?tradeflow=QUICKSTART-001" \
     -H "Authorization: $DOCKFLOW_KEY"

If data is still empty, processing has not finished yet: wait a few seconds and repeat the call. Once processed, the response holds one record in data, with the mock events (gate out empty, gate in full, loaded on vessel at Antwerp, predicted arrival at Los Angeles) and the transport plan.

3. Go to production. Create a prod_ key, switch the host to api.dockflow.com, drop mock_tracking, and send real references (container_reference, bill_of_lading_reference, booking_reference) as described in the Downstream guide. For a continuous feed, set up polling with a cursor or a webhook.

Building with an AI coding assistant?

Point it at docs.dockflow.com/llms-full.txt, the complete Dockflow API documentation as one text file. Every page is also available as markdown by adding .md to its URL, for example /api/downstream.md.

---

2 · Typical integration flow

1. Use Downstream API to create or update tradeflows and upload documents in Dockflow.
2. Upstream delivers real‑time status, ETA changes and analytics from Dockflow.
3. Widget & weblink endpoints add lightweight UI options.

---

3 · Pick the right endpoint

Direction	Path	Authentication
Downstream	/v3/downstream/tradeflows	API key (downstream)
Documents	/v3/downstream/documents	API key (downstream)
Upstream (polling)	GET /v3/upstream	API key (upstream)
Upstream (webhook)	Dockflow POSTs to your HTTPS endpoint	Headers you configure
Widget API	GET /v3/widget/search	API key (widget), see Widget API
Widget iframe	embed.dockflow.com/track (browser embed)	API key (widget), see Widget Embed
Weblink	/redirect (browser link)	none

The /v3 endpoints share one host: https://api.dockflow.com (or https://uat.dockflow.com for the sandbox). A widget-scope token is limited to the widget endpoints and cannot be combined with other scopes; the older /api/v2/widget-search endpoint takes a widget key instead.

---

4 · Documentation map

Topic	Go to
Send tradeflows & documents (Downstream)	Downstream guide
Receive milestones & alerts (Upstream)	Upstream guide
API keys, key format & auth errors	Authorization
UAT sandbox & mock tracking	UAT environment
On‑the‑spot JSON search (Widget API)	Widget API
Embed a Dockflow view (Widget iframe)	Widget iframe
Deep‑link users into Dockflow	Weblink

---

Need help? Email [email protected] – engineers reply within one business day.