API documentation
API docs
FlowMint exposes one container-tracking contract across direct carrier integrations, browser-backed routes, terminal-specific lanes, vessel pages, and manual recovery paths. The API follows a source-aware routing and normalized truth model.
Authentication uses Authorization: Bearer <consumer-token>. Use the dashboard and onboarding flow to obtain a consumer token, then exercise the same contract through polling or signed webhooks.
Error codes
| Code | Message |
|---|
| 0 | No errors. |
| 1 | System error. |
| 2 | Carrier not responding. |
| 3 | Container or booking not found. |
| 4 | Carrier performing system maintenance. |
| 6 | Invalid container or booking number. |
| 7 | Carrier or source not supported. |
| 201 | API key or token is not set. |
| 202 | API key or token is incorrect. |
| 208 | API service is temporarily unavailable. |
| 409 | No eligible runtime slot ready for the requested browser lane. |
Tips and recommendations
- Prefer webhook delivery whenever you want continuous updates instead of repeated polling.
- Wait for the first response before sending repeated requests for the same container.
- If your system already knows the likely carrier, source, or port lane, include that hint to reduce probe noise.
- Use deterministic source hints in production once the route mix is validated in the dashboard.
Tracking request types
- HTTP Webhook Push API — Submit a tracking request together with your consumer token and webhook settings, then let FlowMint push normalized updates as the journey state changes.
- GET/POST polling API — Submit a tracking request, then read current status or timeline on demand whenever you need a synchronous operational view.
Code example
One request, one normalized contract. No carrier-specific parsing logic in your own systems.
curl -X POST https://flowmint.cargoflowplus.com/api/v1/containers/track \
-H "Authorization: Bearer YOUR_CONSUMER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"container_number":"MSDU7696924","port_code":"NLRTM"}'
Example response
{
"container_number": "MSDU7696924",
"carrier": "MSC",
"status": "in_transit",
"eta": "2026-05-03T00:00:00Z",
"origin_port": "NLRTM",
"destination_port": "GBFXT",
"source": "msc_api",
"error_code": 0,
"milestones": [
{ "event": "Gate out", "location": "Rotterdam, NL", "ts": "2026-04-20T08:14:00Z" },
{ "event": "Vessel departed","location": "Rotterdam, NL", "ts": "2026-04-21T02:00:00Z" }
]
}
Current status
GET /api/v1/containers/{number}
Returns the current shipment state, ETA basis, selected source, and the strongest normalized view for the tracking reference.
Timeline
GET /api/v1/containers/{number}/timeline
Returns milestone history in customer-facing order together with the summary block used for external delivery and internal review.
Webhook target
POST /api/v1/subscriptions/webhooks
Registers or updates the delivery target for signed webhook events such as container.updated and container.completed.
Interactive preview
GET /api/v1/containers/view/page
Opens the browser preview surface so teams can inspect live contract output before embedding FlowMint in other systems.
Authentication
Every API call must include a valid consumer token. Internal admin tokens and dashboard login credentials are not substitutes for the customer-facing API contract.
Authorization: Bearer YOUR_CONSUMER_TOKEN
Error handling
Do not immediately retry permanent failures such as not-found or unsupported-source conditions. Retry for transient outages, slot readiness issues, or temporary browser-route instability. Error codes distinguish permanent from transient failures.
Automatic line detection
By default FlowMint probes eligible routes automatically. If you already know the likely line, terminal, or source family, pass that hint to improve response time and reduce unnecessary probes. Hints bias the probe order — they do not lock the route.
Next step
Validate the live route mix, then move into delivery.
Use the docs for shape, the dashboard for real route behavior, and onboarding once the delivery model is agreed.