Skip to main content
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:
  1. Create an API token in the dashboard.
  2. POST a case to your workflow’s cases endpoint with its attributes.
  3. Fetch the case to read its current status and attributes.
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

  1. Go to Tokens in the dashboard.
  2. Click Create Token, choose the API scope, and click Create.
  3. 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"}}'
​
WORKFLOW_ID
integer
required
Path parameter. The numeric ID of a direct case workflow.
​
Authorization
string
required
Request header. Bearer <YOUR_API_TOKEN> — an API-scoped token from the Tokens page.
​
subject
string
Request body. A human-readable title for the case. If you omit it or leave it blank, Champ stamps a timestamped default like API - 2026-05-28 17:04:12 UTC.
​
attributes
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.
The body accepts only subject and attributes. 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",
    "attributes": { "amount": 42, "reason": "late delivery" },
    "created_at": "2026-05-28T17:04:12Z",
    "updated_at": "2026-05-28T17:04:12Z"
  }
}
FieldDescription
idUnique case ID. Use it to fetch the case.
workflow_idThe workflow this case belongs to.
subjectThe case title.
statusCase status. New cases start as Open; the workflow updates it as it runs.
attributesThe 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 evolve through the workflow’s own automation, not through external writes — there’s no update endpoint. To watch a case progress, poll this endpoint or set up a webhook subscription.

​
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’t set or change status with this API. Each workflow ships with three default statuses that are always present:
StatusMeaning
OpenThe case is live and the workflow is working it. Every case starts here.
ClosedThe case is resolved and done. The workflow has finished with it.
ErrorThe 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.
Status is driven entirely by the workflow’s automation. There’s no endpoint to set it, and a case can only ever be in a status its workflow has defined.

​
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

StatusWhen
401Missing or invalid Authorization header.
404Workflow or case not found, or it belongs to another organization.
422The workflow isn’t a direct case workflow, an unsupported body key was sent, attributes wasn’t an object, or attributes failed validation.
Errors return a JSON body with an error message.