🔽 Downstream - send to 🌐

Deprecation Notice

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

note

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
    "team_name": "Sales Team EMEA", // optional - assigns an existing team to the tradeflow
    "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 name
role (optional): Partner role (e.g., "forwarder", "shipper", "consignee")
reference (optional): Partner's own reference for this shipment (defaults to root tradeflow_reference if 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"
      }
    ]
  }
]

Teams

The team_name field allows you to assign an existing team to a tradeflow. Teams must be created in advance within an organization in the Dockflow platform.

Field:

team_name (optional): Name of an existing team (case-insensitive, minimum 3 characters)

Behavior:

First searches for a team in your organization
If not found, searches in partner organizations involved in the tradeflow
If a matching team is found, it will be assigned to the tradeflow
If no matching team is found in any involved organization, the field is silently ignored (no error)
Team lookup is case-insensitive (e.g., "Sales Team EMEA" matches "sales team emea")

Example:

[
  {
    "tradeflow_reference": "PO1674684",
    "container_reference": "ABCD1234567",
    "team_name": "Sales Team EMEA"
  }
]

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.

What this means for you​

Recommended next steps​

Downstream API​

Example request​

Request payload​

Partners​

Teams​

Success Response​

Custom payloads​