🔽 Downstream API - send to 🌐

Endpoints

Method	Path	Description
POST	`/downstream/tradeflows`	Create a tradeflow or update an existing one. Accepts a single object or an array.
DELETE	`/downstream/tradeflows/{tradeflow_reference}`	Deactivate a tradeflow. `?hard=true` → permanently delete.

1 · Create / update tradeflows `POST /downstream/tradeflows`

Payload format

A single JSON object or an array of objects.

{
  "tradeflow_reference": "PO4564268", // required

  // Tracking references — string OR array
  "container_reference": [
    {
      "reference": "ABCD1234567",
      "custom_properties": {
        "requires_inspection": true,
        "quality_check_date": "2025-05-01"
      }
    },
    {
      "reference": "EFGH7654321",
      "custom_properties": {
        "requires_inspection": true,
        "quality_check_date": "2025-05-01"
      }
    }
  ],
  "container_references_complete": true,

  "bill_of_lading_reference": "ANR00001010",
  "booking_reference": ["94512540", "94512888"],

  // Tradeflow status
  "active": true, // default = true

  // Carrier name
  "carrier_name": "Maersk", // optional
  "carrier_scac": "MAEU", // optional

  // Partner shortcuts
  "customer_name": "Fruit Maker EXIM International",
  "customer_reference": "PO_12345_CUST", // optional
  "partners": [
    {
      "name": "Best Forwarder BV",
      "role": "forwarder",
      "reference": "PO_4564268"
    }
  ],
  "partners_complete": false,

  // Team assignment
  "team_name": "Sales Team EMEA", // optional

  // Voyage metadata
  "port_of_loading": "BEANR",
  "port_of_discharge": "USLAX",

  "estimated_time_of_departure": "2025-05-14T12:00:00Z",
  // or - when vessel has already departed
  "actual_time_of_departure": "2025-05-14T12:00:00Z",

  "estimated_time_of_arrival": "2025-06-06T22:00:00Z",
  // or - when vessel has already arrived
  "actual_time_of_arrival": "2025-06-06T22:00:00Z",

  "vessel": "Maersk SOPHIE",
  "incoterms": "FOB",
  "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
  },

  // Optional self-defined events
  "events": [
    {
      "message": "delivery at client",
      "container_reference": "ABCD1234567",
      "location_name": "BEANR", // also accepts string-addresses
      "event_date": "2025-05-12T08:34:00Z",
      "actual": true // whether the event already happened – or is scheduled
    }
  ],

  // NEW · Arbitrary key-value pairs defined by you
  "custom_references": {
    "invoice_number": "INV-12345",
    "priority": 2,
    "quality_check_date": "2025-05-01",
    "requires_inspection": true
  }
}

`custom_references` — what & why

Field	Type	Description
`custom_references`	object	A free-form dictionary whose keys are fully user-defined. Each value may be a string, number, boolean, or ISO-8601 date. Use it for anything that doesn’t fit the prescribed schema (e.g. internal IDs, workflow flags, etc.).

Nested objects or arrays inside custom_references are not allowed (hard-fail).
Keys are case-sensitive UTF-8 strings (≤ 255 chars).
Duplicate keys in the object are rejected (409 Conflict).

Complete-list flags

Flag	Applies to	Effect when `true`
`container_references_complete`	`container_reference[]`	Containers not listed are removed.
`bill_of_lading_references_complete`	`bill_of_lading_reference[]`	Same logic.
`booking_references_complete`	`booking_reference[]`	Same logic.
`partners_complete`	`partners[]`	Partners not listed are removed.

If a _complete flag is omitted, the list is merged instead of replaced.

Partner input

customer_name — quick way to add one partner with role customer.
partners — full array that supports multiple roles and references. Both inputs may be combined.

Team assignment

team_name — assigns an existing team to the tradeflow.
- Must be an existing team (minimum 3 characters)
- First searches your organization, then partner organizations involved in the tradeflow
- Case-insensitive matching (e.g., "Sales Team EMEA" matches "sales team emea")
- If no matching team is found in any involved organization, the field is silently ignored

Response `202 Accepted`

Processing is asynchronous. The response lists queued items and any warnings:

{
  "status": "queued",
  "tradeflows": [
    {
      "tradeflow_reference": "PO4564268",
      "created": false,
      "warnings": [
        {
          "path": "[0].container_reference[1]",
          "message": "EFGH7654321 does not match ISO 6346 and was ignored"
        },
        {
          "path": "[0].custom_references.quality_check_date",
          "message": "Date must be ISO-8601; received \"20250501\""
        }
      ]
    }
  ]
}

Warnings indicate values that were ignored without blocking the request (soft-fail).

2 · Remove tradeflows `DELETE /downstream/tradeflows/{tradeflow_reference}`

Action	How
Deactivate (preferred)	`DELETE /downstream/tradeflows/PO4564268` — same effect as posting `"active": false`.
Permanent delete	`DELETE /downstream/tradeflows/PO4564268?hard=true`

Returns 204 No Content on success.

Bulk delete (UAT only)

Using * as the tradeflow_reference deletes all tradeflows in your UAT (User Acceptance Testing) environment. This wildcard is restricted to UAT environments to prevent accidental deletion of production data.

Example:

DELETE /downstream/tradeflows/*

This deactivates all tradeflows in your UAT environment. Add ?hard=true for permanent deletion.

Note: This endpoint returns 403 Forbidden when called from a production environment.

Validation rules

Hard-fail (request rejected — 400 Bad Request):

Payload must be JSON object or array.
tradeflow_reference missing or longer than 255 characters.
Date fields not ISO-8601 (YYYY-MM-DDTHH:MM:SSZ) or YYYYMMDD.
port_of_loading / port_of_discharge not a 2-letter ISO country code or 5-character UN/LOCODE.
custom_references:
- Contains nested array/object values.
- A value is not string/number/boolean/date.
- Total number of keys > 50.

Soft-fail (processed but returned as warnings):

container_reference not matching ^[A-Z]{4}[0-9]{7}$.
Empty strings or null values inside array fields.
Unknown top-level properties (outside custom_references).

Error codes

Status	Meaning
400 Bad Request	Validation failed (hard-fail rules).
401 Unauthorized	Missing or invalid `Authorization` token.
404 Not Found	Tradeflow not found on delete.
409 Conflict	Same `tradeflow_reference` appears twice in one payload. Duplicate key inside `custom_references`.
500 Internal Server Error	Unexpected error during processing.

Questions or feedback? Create an issue in the public repository or contact Dockflow support.

Endpoints​

1 · Create / update tradeflows POST /downstream/tradeflows​

Payload format​

custom_references — what & why​

Complete-list flags​

Partner input​

Team assignment​

Response 202 Accepted​

2 · Remove tradeflows DELETE /downstream/tradeflows/{tradeflow_reference}​

Bulk delete (UAT only)​

Validation rules​

Error codes​