🔼 Upstream - receive from 🌐

Upstream API

The Upstream API is used to retrieve data from Dockflow to your system.

Methods (pull vs push)

The upstream API is available both on pull-basis ("polling mechanism", making GET-requests periodically to Dockflow), as well as on push-basis (new data is sent to a webhook).

Polling method - example request (GET)

Replace xxxxx with your API token for authorization.

curl "https://api.dockflow.com/upstream" -H "Authorization: xxxxx"

note

For the reference requests below, the Authorization header placeholder will be omitted. However, make sure to include it.

Push method - example configuration

The webhook can be configured using an Automation. The automation should be configured using the web GUI, as follows:

alt text

note

Make sure to also ENABLE the automation in the upper-right corner after configuration.

Response

The response will contain the 500 most recent datapoints available from the last 24 hours. Content will be a JSON array of APIMessage, with following scheme:

APIMessage {
    hash: string; // Unique has of this APIMessage
    message_generated_event_date: string; // ISO Date-string of when the message was generated
    type: string; // Type of APIMessage
    tradeflow_reference: string; // Tradeflow reference as known for this client (e.g. PO)
    payload: (...) // Payload of the APIMessage, depending on the type - see below
}

The updates are marked into 3 categories:

SHIPMENT_CHANGE: Updates for a shipment. Can be related to a planned shipment or booking, or a group of containers on the same journey. Examples are: Vessel Departure, Vessel Arrival, Transshipment,...
CONTAINER_MILESTONE: Updates for a specific container and its movements. Examples are: Empty Returned, Loaded on Vessel, Gate Out, Discharge, Vessel Arrival,...
LOCATION_UPDATE: Periodic coordinates updates for a Vessel or Truck Examples are: Vessel MSC Sophie is now at (51.000145 lat, 4.584368 lng) - updated every x minutes.
BASIC_STATUS: The most low-level update. Anything that happens in a tradeflow will be recorded as a BASIC_STATUS, can be related to shipment, administration or container. Data is unfiltered and data quality is not guaranteed. Examples are: Tradeflow creation and deactivation, new predicted arrival, loaded on vessel,...

note

Requests can be modified to filter for specific messages, please see below for Filtering the request

info

If you are unsure which reponse type you'll need, please contact support at [email protected]

warning

BASIC_STATUS messages are returned from the API, but are not actively supported as an integration type.

SHIPMENT_CHANGE

info

Download a populated example JSON file at shipment-change.json

An APIMessage with type SHIPMENT_CHANGE will contain a payload in following scheme:

APIMessage {
  // Some generic attributes - see above
  // (...)
  // Specific payload:
  payload: {
          type: string; // "SHIPMENT_CHANGE"
          // Change: the actual change in the shipment data
          change: {
              actual: boolean; // Is the change actual (true) or predicted (false)
              is_pol: boolean; // Is this change for the Port Of Loading?
              booking_reference: string | null; // Booking reference
              bill_of_lading_reference: string | null; // Bill of lading reference
              vessel: Vessel; // Vessel data - see generic scheme below
              carrier: Entity; // Carrier data - see generic scheme below
              reading: string; // ISO Date-string reading for this change
              location: Location; // Location of this change - see generic scheme below
              move_type: string; // "arrival" or "departure"
              containers: Container[]; // Array of containers involved - see generic scheme below
              is_final_pod: boolean; // Is this change for the final Port Of Discharge?
              predicted_at: string; // ISO Date-string reading for when this change was received
              is_transshipment_location: boolean; // Is this change about a T/S location?
          };
          // + the full shipment data after the change above has been processed - see generic scheme below
          shipment: Shipment;
      };
    }
}

CONTAINER_MILESTONES

info

Download a populated example JSON file at container-milestone-example.json

An APIMessage with type CONTAINER_MILESTONES will contain a payload in following scheme:

APIMessage {
  // Some generic attributes - see above
  // (...)
  // Specific payload:
  payload: {
        type: string; // "CONTAINER_MILESTONES"
        actual: boolean;  // Is the milestone actual (true) or predicted (false)
        // A history of predicted dates for this milestone
        history: Array<{
            actual: boolean; // Is the milestone actual (true) or predicted (false)
            source: string; // Free-text source of this predicted date
            event_date: string; // ISO Date-string for the milestone event
            predicted_at: string; // ISO Date-string reading for when this change was received
        }>;
        // A details of the container
        container_details: {
            reference: string; // The container reference
            container_type: string; // iso-type of the container
            container_length: number; // Length in ft of the container
            container_is_reefer: boolean; // Is the container a reefer or not (boolean)
        };
        message: string; // Free-text message as received for this milestone
        status_code: string; // Standardized status code for this milestone
        location: Location; // Location of this milestone - see generic scheme below
        event_date: string; // ISO Date-string for the milestone event
        predicted_at: string | null; // ISO Date-string reading for when this change was received
        transport_unit_reference: string; // container reference (e.g. ABCD1234567)
        booking_reference: string | null; // Booking reference
        bill_of_lading_reference: string | null; // Bill of lading reference

        // + the full shipment data after this milestone was processed - see generic scheme below
        shipment: Shipment;

        // +  the dwell details
        dwell_details: {
          demurrage_free_time_expires: string; // calculated ISO DateTime-string after which free time on quay has expired (demurrage fees start)
          detention_free_time_expires: string; // calculated ISO DateTime-string after which free time after pick-up has expired (detention fees start)
        }
      };
    }
}

LOCATION_UPDATE

Location updates will contain following payload:

{
  "lat": 26.017188333333,
  "lng": 56.997915,
  "type": "LOCATION_UPDATE",
  "event_date": "2022-04-20 09:55:08.000000",
  "vessel_name": "NORTHERN PRACTISE"
}

Shipment types

With some APIMessage-types, the full shipment details will be included.:

interface Shipment {
      containers: Container[];
      transport_plan_legs: TransportPlanLeg[];
  }

     interface TransportPlanLeg {
      carrier: Carrier;
      booking_number?: any;
      sequence_number: number;
      sea_shipment_legs: SeaShipmentLeg[];
      bill_of_lading_number?: any;
  }

interface SeaShipmentLeg {
      arrival: Arrival;
      carrier: Carrier;
      departure: Departure;
      carrier_transport_unit: Vessel;
  }


  interface ReadingLog {
      actual: boolean;
      reading: string;
      is_latest: boolean;
      event_date: string;
      is_provisional: boolean;
      is_latest_provisional: boolean;
  }

  interface Arrival {
      type: string;
      actual: boolean;
      is_pol: boolean;
      carrier: Carrier;
      location: Location;
      containers: Container[];
      reading_log: ReadingLog[];
      is_final_pod: boolean;
      latest_reading: string;
      first_known_reading: string;
      carrier_transport_unit: Vessel;
      first_confirmed_reading: string;
      latest_confirmed_reading: Date;
      is_transshipment_location: boolean;
      latest_provisional_reading: Date;
  }


  interface Departure {
      type: string;
      actual: boolean;
      is_pol: boolean;
      carrier?: any;
      location: Location;
      containers: Container[];
      reading_log: ReadingLog[];
      is_final_pod: boolean;
      latest_reading: string;
      first_known_reading: string;
      carrier_transport_unit: Vessel;
      first_confirmed_reading: string;
      latest_confirmed_reading: string;
      is_transshipment_location: boolean;
      latest_provisional_reading: string;
  }

     interface Location {
      name: string;
      country: Country;
      timezone: string;
      unlocode: string;
      coordinates: Coordinates;
  }

  interface Country {
      name: string;
      iso_a2: string;
  }

  interface Carrier {
      name: string;
  }

  interface Coordinates {
      lat: number;
      lng: number;
  }

  interface Container {
      reference: string;
      container_type:string;
      container_length: number;
      container_is_reefer: boolean;
  }

  interface Entity {
      name: string;
  }

  interface Vessel {
      name: string;
      imo_number: string;
      mmsi_number: string;
  }

Status codes

Following status codes can be returned:

Code	Description
GE	empty equipment dispatched
GN	gate in
AE	loaded on vessel
VD	vessel departure
VA	vessel arrival
UV	unloaded from vessel
GT	gate out
GR	empty equipment returned

Filtering the request

Filter the request using a request parameter. These filters can be combined.

Filter for updates created since date

Use this to filter your request for recently created updates. curl "https://api.dockflow.com/upstream?since=2022-04-15T00:48:36+00:00"

Filter for a specific tradeflow

Use this to filter your request for a specific tradeflow curl "https://api.dockflow.com/upstream?tradeflow=PO12134567"

Filter for a specific container

Use this to filter your request for a specific tradeflow curl "https://api.dockflow.com/upstream?container=ABCD1234567"

warning

Filtering for a container will never return SHIPMENT_CHANGE messages.

Filter for a type of update

Use this to filter your request for a specific update type curl "https://api.dockflow.com/upstream?type=SHIPMENT_CHANGE"

Filter for only the latest update

Use this to filter for only the latest status / updates curl "https://api.dockflow.com/upstream?latest=true"

Exclude data from return

You might want to exclude the full shipment details from the data, as follows: curl "https://api.dockflow.com/upstream?excludes=shipment"

Pagination

Append per_page=x with x a positive integer between 1 and 500 to do paginated calls. curl "https://api.dockflow.com/upstream?per_page=500"

The resulting response will be an object with 3 keys:

{
  'next_cursor':string;
  'data': [...]
}

To query for the next set of results, use the cursor string as follows: curl "https://api.dockflow.com/upstream?per_page=500&cursor=[next_cursor string from response]"

Upstream API​

Methods (pull vs push)​

Polling method - example request (GET)​

Push method - example configuration​

Response​

SHIPMENT_CHANGE​

CONTAINER_MILESTONES​

LOCATION_UPDATE​

Shipment types​

Status codes​

Filtering the request​

Filter for updates created since date​

Filter for a specific tradeflow​

Filter for a specific container​

Filter for a type of update​

Filter for only the latest update​

Exclude data from return​

Pagination​

Upstream API

Methods (pull vs push)

Polling method - example request (GET)

Push method - example configuration

Response

SHIPMENT_CHANGE

CONTAINER_MILESTONES

LOCATION_UPDATE

Shipment types

Status codes

Filtering the request

Filter for updates created since date

Filter for a specific tradeflow

Filter for a specific container

Filter for a type of update

Filter for only the latest update

Exclude data from return

Pagination