Manage cases via REST API

A direct case workflow can have cases created from outside Champ with a single HTTP request — from your own backend, a form handler, or another tool. Each case you create kicks off the workflow’s automation against the data you submit. The flow is:

Create an API token in the dashboard.
POST a case to your workflow’s cases endpoint with its attributes.
Fetch the case to read its current status and attributes.
Optionally, update the case’s status — for example to close it from your own system.

This endpoint only works for workflows whose case source is direct. Ticketing and email workflows take in cases through their own channels and can’t be written to with this API.

Create an API token

Go to Tokens in the dashboard.
Click Create Token, choose the API scope, and click Create.
Copy the token immediately — it’s shown once and cannot be retrieved again. API tokens look like api_xxxxxxxx….

The token is scoped to your organization. Treat it as a secret: store it in an environment variable or secrets manager, and delete it from the Tokens page if it’s ever exposed.

Find your workflow ID

Open the direct case workflow in the dashboard. The numeric ID is the last segment of its URL (https://dash.champ.ai/app/workflows/<WORKFLOW_ID>). You’ll use it in the request path below.

Create a case

Send a POST request to the workflow’s cases endpoint:

curl -X POST https://api.champ.ai/api/external/v1/workflows/{WORKFLOW_ID}/cases \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Refund request", "attributes": {"amount": 42, "reason": "late delivery"}}'

integer

required

Path parameter. The numeric ID of a direct case workflow.

string

required

Request header. Bearer <YOUR_API_TOKEN> — an API-scoped token from the Tokens page.

string

Request body. A human-readable title for the case. If you omit it or leave it blank, Champ stamps a timestamped default like Refund Intake via API - 2026-05-28 17:04:12 UTC.

object

Request body. The case’s field values, validated against the workflow’s attribute schema. Any attribute that is required in the workflow must be supplied here. Omit it (or pass {}) for workflows with no required attributes.

string

default:"live"

Request body. "live" (default) or "test". Test cases run the workflow end to end but don’t count as real work — they’re excluded from webhooks, billing, metrics, and digests, and their runs execute in test mode. Point your staging environment here.

The body accepts only subject, attributes, and mode. Any other top-level key is rejected with a 422 before the case is created.

The case is created immediately and the workflow’s automation starts asynchronously. The response is the new case:

{
  "case": {
    "id": 987,
    "workflow_id": 123,
    "subject": "Refund request",
    "status": "Open",
    "outcome": null,
    "mode": "live",
    "attributes": { "amount": 42, "reason": "late delivery" },
    "created_at": "2026-05-28T17:04:12Z",
    "updated_at": "2026-05-28T17:04:12Z"
  }
}

Field	Description
`id`	Unique case ID. Use it to fetch the case.
`workflow_id`	The workflow this case belongs to.
`subject`	The case title.
`status`	Case status. New cases start as `Open`; the workflow updates it as it runs.
`outcome`	Disposition of a `Closed` case (e.g. `Resolved`); `null` otherwise.
`mode`	`"live"` or `"test"`. See Test cases.
`attributes`	The case’s current field values.

Fetch a case

Read a case’s current status and attributes by ID:

curl https://api.champ.ai/api/external/v1/workflows/{WORKFLOW_ID}/cases/{CASE_ID} \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

The response is the same case shape as above. As the workflow runs, the status and attributes reflect the latest state.

Cases normally evolve through the workflow’s own automation. To watch a case progress, poll this endpoint or set up a webhook subscription.

Update a case’s status

Move a case to a new status yourself — for example to close it when it’s resolved on your side, or to reopen it:

curl -X PATCH https://api.champ.ai/api/external/v1/workflows/{WORKFLOW_ID}/cases/{CASE_ID} \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"status": "Closed"}'

string

required

Request body. The status to move the case to. Must be one of the statuses declared on the workflow (see Case statuses). Error is engine-managed and can’t be set through the API.

This is more than writing a field: the update is recorded on the case’s timeline and starts the workflow run attached to the new status, which counts toward your usage like any other run. Use it when you intend the case to actually move, not to sync statuses.

The response is the updated case in the same shape as above.

The body accepts only status. Any other top-level key is rejected with a 422.

Test cases

Create a case with "mode": "test" to exercise a workflow without creating real work:

curl -X POST https://api.champ.ai/api/external/v1/workflows/{WORKFLOW_ID}/cases \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Staging smoke test", "attributes": {"amount": 1}, "mode": "test"}'

Test cases behave like live ones — the workflow runs end to end, statuses transition, attributes update — but they are excluded from webhooks, billing, metrics, and reporting digests, and their runs are marked test mode. This makes them safe to fire from a staging environment or CI check.

Test cases still execute the workflow’s real steps. If your workflow calls external systems or sends messages, design it to branch on the case’s mode where those actions shouldn’t run for test traffic.

Case statuses

Every case carries a status. A new case always starts as Open, and the workflow’s automation moves it through the rest as it runs. You can also move it yourself with the update endpoint. Each workflow ships with three default statuses that are always present:

Status	Meaning
`Open`	The case is live and the workflow is working it. Every case starts here.
`Closed`	The case is resolved and done. The workflow has finished with it.
`Error`	The workflow hit a problem it couldn’t resolve and parked the case.

A workflow can also define custom statuses on top of these defaults (for example Awaiting customer or Pending review) to model the intermediate stages of its own process. A case’s status is always one of the statuses declared on its workflow, so the exact set you’ll see depends on how that workflow is configured — open the workflow in the dashboard to view its full status list.

A case can only ever be in a status its workflow has defined. Error is set by the engine when a run fails and can’t be set through the API — recover an errored case by moving it to another status.

Validation errors

If attributes doesn’t match the workflow’s schema — a missing required field, a wrong type — the request returns 422 with a validation_errors array. Each entry points to the offending field with a JSON Pointer:

{
  "error": "attributes_validation_failed",
  "validation_errors": [
    { "path": "/amount", "error": "value at `/amount` is not a number" }
  ]
}

Errors

Status	When
`401`	Missing or invalid `Authorization` header.
`404`	Workflow or case not found, or it belongs to another organization.
`422`	The workflow isn’t a direct case workflow, an unsupported body key was sent, `attributes` wasn’t an object, `attributes` failed validation, or a status update sent a status the workflow doesn’t define.

Errors return a JSON body with an error message.

Get started

Integrations

Browser Profiles

Webhooks

Manage cases via REST API

Create an API token

Find your workflow ID

Create a case

Fetch a case

Update a case’s status

Test cases

Case statuses

Validation errors

Errors

​Create an API token

​Find your workflow ID

​Create a case

​Fetch a case

​Update a case’s status

​Test cases

​Case statuses

​Validation errors

​Errors

Create an API token

Find your workflow ID

Create a case

Fetch a case

Update a case’s status

Test cases

Case statuses

Validation errors

Errors