🔽 Downstream - send to 🌐
Heads‑up! This API is being sunset.
What this means for you
- Existing integrations keep working but no new features will be added.
- Bug‑fixes and security patches are best‑effort only during the deprecation window.
- After the sunset date, requests will return HTTP 410 (Gone).
Recommended next steps
- Migrate to our new API: see the Trident API for a step‑by‑step walkthrough.
- Update client libraries and SDKs to their latest major version.
- Reach out on
[email protected]if you need help or an extension.
Thank you for building with us!
Your feedback has shaped the next generation of our platform, and we’re here to make the transition as smooth as possible.
Downstream API
The Downstream API is used to input data from your system to Dockflow.
Example request
Replace xxxxx with your API token for authorization.
curl -X POST \
-H "Authorization: xxxxx" \
-d '[{ "container_reference": "ABCD1234567", "tradeflow_reference": "PO1674684" }]' \
https://api.dockflow.com/downstream
For the reference requests below, the Authorization header placeholder will be omitted. However, make sure to include it.
Request payload
The request can contain one or multiple tradeflows, but should always be an array. A tradeflow contains a container reference and a tradeflow reference.
[
{
"tradeflow_reference": "PO4564268", // mandatory - the internal reference from your system
// At least one of these
// (
"container_reference": "ABCD1234567", // either container number
// AND/OR
"bill_of_lading_reference": "ANR00001010", // and/or B/L reference
// AND/OR
"booking_reference": "94512540", // and/or booking reference
// )
// Optional arguments
"active": true, // optional, default = true. Set to false to deactivate the tradeflow
"port_of_loading": "BEANR", // optional
"port_of_discharge": "NLRTM", // optional
"estimated_time_of_departure": "2021-08-24T15:00:25+00:00", // optional
"explicit_departure_confirmation": false, // optional
"estimated_time_of_arrival": "2021-08-24T15:00:25+00:00", // optional
"explicit_arrival_confirmation": false, // optional
"vessel": "Maersk SOPHIE", // optional
"customer_name": "Fruit Maker EXIM International", // optional
"customer_reference": "PO_12345_CUST", // optional - this customer's reference for the shipment
"partners": [ // optional - array of additional partner entities involved in the shipment
{
"name": "Best Forwarder BV", // required - partner entity name
"role": "forwarder", // optional - partner role (e.g., "forwarder", "shipper", "consignee")
"reference": "FWD_PO_789", // optional - this partner's internal reference for the shipment
"lead_contact": "[email protected]" // optional - email of lead contact at partner
}
],
"carrier_name": "Maersk", // optional
"lead_contact": "[email protected]", // optional
"incoterms": "FOB", // optional
"configuration": {
"enroll_insurance": true,
}, // optional configuration flags
"references": {
"house_bill_of_lading": "hbl_123456789", // optional house bill of lading reference
"delivery_location": "Factory yard 12345", // optional, string of the delivery location
"delivery_event_date": "2021-08-24T15:00:25+00:00" // optional, ISO-date of delivery
},
"events":[ // optional, array of events to import
{
"message": "container loaded on vessel", // mandatory, name of the event- preferably DSCA-compliant
"container_reference": "ABCD1234567", // optional, container number
"location_name": "BEANR" // optional, location of the vent
"event_date":"2021-08-24T15:00:25+00:00", // optional, ISO-date of the event
"actual": true // optional, whether the event is actual or estimated - default is false
}
]
},
{
// Example of correct minimum message
"container_reference": "MNOP7654321",
"tradeflow_reference": "XYZ12341223AB2"
},
{
// Other example of correct minimum message
"bill_of_lading_reference": "ANR00001010",
"tradeflow_reference": "XYZ12341223AB2"
}
]
- Tradeflow_reference refers to the internal name for this shipment, usually set to the client's PO-number, or B/L number. It can be any arbitrary string, by which containers are grouped for business sense. Tradeflow specific alerts will be grouped by tradeflow
- Two dumps can have the same tradeflow_reference. In this case the two containers will be grouped in the same tradeflow
Single tradeflow with multiple containers example
[
{
"container_reference": "ABCD1234567",
"tradeflow_reference": "PO1674684"
},
{
"container_reference": "XYZZ7654321",
"tradeflow_reference": "PO1674684"
}
]
Set the tradeflow_reference equal to the container_reference to have each container in a separate tradeflow or file
Partners
The partners array allows you to associate multiple partner entities with a tradeflow. The customer_name field is a shortcut for adding a single customer partner, while partners provides full control over multiple entities with different roles.
Fields:
name(required): Partner entity namerole(optional): Partner role (e.g., "forwarder", "shipper", "consignee")reference(optional): Partner's own reference for this shipment (defaults to roottradeflow_referenceif not provided)lead_contact(optional): Email address of lead contact at partner organization
Example:
[
{
"tradeflow_reference": "PO1674684",
"container_reference": "ABCD1234567",
"customer_name": "Acme Corp",
"customer_reference": "ACME_PO_123",
"partners": [
{
"name": "Global Forwarders Inc",
"role": "forwarder",
"reference": "FWD_REF_456",
"lead_contact": "[email protected]"
},
{
"name": "Ocean Shipping Lines",
"role": "carrier"
}
]
}
]
Success Response
Condition: Data provided is valid and User is Authenticated.
Code: 202 Accepted
Custom payloads
If you are importing a custom payload, please post to https://api.dockflow.com/downstream/scheme/xxxxx, replacing xxxxx with your integration scheme.