Discover and use company status choices through the API

Use a status definition ID to choose the exact company status in an API call. Names can change. The older status field stays available as a broad category.

Start with API authentication. These routes work with client account task boards. Overall internal projects and company status-list editing stay in the app.

Find status choices

Call GET /v1/status-definitions with your API key. The response has items and nextCursor. Each item has:

• id, name, color, and marker (DOT or TROPHY).
• needsAttention and requiresUpdateText.
• archived, position, revision, and legacyStatus.

The list starts with active choices. Add includeArchived=true to include archived ones. limit defaults to 50 and accepts 1–200. Follow nextCursor with the same archive choice. If the company list changes and the cursor expires, restart the list.

Post an account-board update

Use POST /v1/accounts/{accountId}/task-boards/{boardId}/status-updates. Send exactly one selector:

• statusDefinitionId: an ID from discovery, for an exact choice.
• status: one of ON_TRACK, AT_RISK, OFF_TRACK, ON_HOLD, COMPLETE, or DROPPED, for its original saved choice.

For an exact choice, this body also sends the revision returned by discovery:

{
  "statusDefinitionId": "REPLACE_WITH_DISCOVERED_ID",
  "statusDefinitionRevision": 1,
  "update": { "format": "html", "html": "<p>Waiting for the client's review.</p>" }
}

Replace both the ID and revision with the discovered values. The revision is optional. Send it to check for a choice that changed while you wrote the update. Custom choice availability follows the company settings.

An archived choice isn't available for a new post. If requiresUpdateText is true, send readable text in update; comingNext alone is insufficient. Refresh discovery and review the error before retrying. A new company rule can also make an older API call need text.

Each POST creates a new update. Check history after an uncertain response before retrying, to avoid posting it twice.

Read exact current details

Add include=statusDefinition to status-update list, detail, or create URLs. It adds statusDefinition with the current choice details, or null when those details are unavailable. Omit it to keep the existing response keys.

The six original choices keep their original status aliases after a rename. A custom choice returns AT_RISK when Needs attention is on and ON_TRACK otherwise. Use the definition ID for exact matching. Names and old categories can change or match more than one choice.

Opt into webhook status details

In an endpoint's settings, turn on Include board status details. The saved API option is includeStatusDefinition. It defaults to false.

For taskBoard.statusUpdate.created, opted-in deliveries can include:

{
  "status_definition": {
    "id": "EXAMPLE_STATUS_ID",
    "name": "Awaiting review",
    "color": "#D97706",
    "marker": "DOT",
    "isAttention": true
  }
}

These values show the choice when the update was posted. Later renames, color changes, or attention changes don't rewrite that event. Older events without saved details omit the field. Keep accepting deliveries without it. This differs from REST reads, which return current details.

Authored-text settings are separate. Status details don't enable message or update text. Existing webhook endpoints keep their saved choices. See webhook payloads and signatures.

Next step

• Read and post board status updates
• Manage status choices in the app