Workflow States API

🚀 Why Use the Workflow States API?

Every location moves appointments through a workflow: the core states DataDocks ships with (booked, arrived, started, and so on) plus any custom states the warehouse adds, such as "Paperwork collected" between arrival and unloading. The Workflow States API is read-only: it returns the location's workflow so your integration knows which states exist, their order, and which timestamp field records each one.

Real Problems This API Solves

• Map states to your system: Translate the state returned on appointments, including custom states, into your own statuses
• Discover timestamp fields: Learn the <state>_at field to send or read for each custom state without hardcoding keys
• Follow the warehouse's order: Use position to show progress the same way DataDocks does

This endpoint does not create, update, or delete states. Please use the DataDocks software to manage your workflow.

5-Minute Quickstart

1. Obtain an API token and your location subdomain (see Authentication).
2. Call the listing endpoint.

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
  "https://YOUR_LOCATION.datadocks.com/api/v1/workflow_states"

Authentication

All requests must send your token in the Authorization header (same as other location APIs). See Authentication for details.

Authorization: Token YOUR_API_TOKEN

Listing Workflow States

Purpose

Return every state in the location's workflow, in workflow order. The list includes core states, custom states, and states the location has hidden. A location without a configured workflow returns the default core states.

HTTP Request

GET https://[location_subdomain].datadocks.com/api/v1/workflow_states

Query Parameters

None. The response is not paginated.

Response Format

The JSON root is an array of state objects, ordered by position.

Field	Type	Description
state	String	State key. This is the value returned in an appointment's state field
timestamp_key	String/null	Appointment field that records when the state was reached (e.g. approved_at, unloading_at); null when the state records no timestamp
name	String	Display name of the state
parent_state	String/null	For a custom state, the core state it belongs to; null for core states
position	Integer	Sort order within the workflow; later states have higher positions
hidden	Boolean	Whether the location hides this state in DataDocks

Core States

state	timestamp_key
needs_booking	null
pending	null
booked	approved_at
arrived	arrived_at
started	started_at
completed	completed_at
left	left_at
cancelled	cancelled_at

Custom States

A custom state always belongs to a core state (parent_state) and follows it in the workflow. Its timestamp_key is its own key plus _at, and that field appears on appointments once the state is reached. See Custom Workflow States for how to read and set these timestamps.

Custom state keys are generated from the state's name when it is created and stay the same if the state is renamed. Read keys from this endpoint rather than deriving them from names.

Code Examples

cURL

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
  "https://YOUR_LOCATION.datadocks.com/api/v1/workflow_states"

JavaScript

See JavaScript example

const getWorkflowStates = async () => {
  const response = await fetch(
    "https://YOUR_LOCATION.datadocks.com/api/v1/workflow_states",
    {
      method: "GET",
      headers: {
        Authorization: "Token YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
    }
  );

  if (!response.ok) {
    const errorData = await response.text();
    throw new Error(`Failed to fetch workflow states: ${errorData}`);
  }

  return response.json();
};

// Find the timestamp fields of custom states
getWorkflowStates().then((states) => {
  const customTimestampKeys = states
    .filter((state) => state.parent_state && state.timestamp_key)
    .map((state) => state.timestamp_key);

  console.log(customTimestampKeys); // e.g. ["paperwork_collected_at"]
});

Sample Response

See sample response

[
  {
    "state": "needs_booking",
    "timestamp_key": null,
    "name": "Needs Booking",
    "parent_state": null,
    "position": 0,
    "hidden": false
  },
  {
    "state": "pending",
    "timestamp_key": null,
    "name": "Pending",
    "parent_state": null,
    "position": 1,
    "hidden": false
  },
  {
    "state": "booked",
    "timestamp_key": "approved_at",
    "name": "Booked",
    "parent_state": null,
    "position": 2,
    "hidden": false
  },
  {
    "state": "arrived",
    "timestamp_key": "arrived_at",
    "name": "Arrived",
    "parent_state": null,
    "position": 3,
    "hidden": false
  },
  {
    "state": "paperwork_collected",
    "timestamp_key": "paperwork_collected_at",
    "name": "Paperwork collected",
    "parent_state": "arrived",
    "position": 4,
    "hidden": false
  },
  {
    "state": "started",
    "timestamp_key": "started_at",
    "name": "Started",
    "parent_state": null,
    "position": 5,
    "hidden": true
  },
  {
    "state": "completed",
    "timestamp_key": "completed_at",
    "name": "Completed",
    "parent_state": null,
    "position": 6,
    "hidden": false
  },
  {
    "state": "left",
    "timestamp_key": "left_at",
    "name": "Left",
    "parent_state": null,
    "position": 7,
    "hidden": false
  },
  {
    "state": "cancelled",
    "timestamp_key": "cancelled_at",
    "name": "Cancelled",
    "parent_state": null,
    "position": 8,
    "hidden": false
  }
]

Errors

Error Code	Description	Possible Cause
401	Unauthorized	Invalid or missing API token

Related Endpoints

• Appointments API - Read and set appointment state timestamps
• Webhooks - Get notified when appointments change state