Start Case Step
Start (execute) a specific step in a case
- Sending email notifications to contacts or case owners
- Sending SMS notifications
- Creating and sending form requests
- Creating internal notes or tasks
- Triggering automations
Notes
- You cannot start steps in template cases (is_template: true)
- Starting a step may trigger automations configured for the case
- The step must be defined in the case’s step configuration
- Some steps may have execution conditions that prevent them from running if not met
Authorizations
API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}
Path Parameters
Case UUID
Step key identifier from the case's step configuration
Body
Optional data to pass to the step execution
Response
Step started successfully
Case UUID
Case title
Parent status
draft, pending, in_progress, closed, cancelled Creation timestamp
Last update timestamp
Workspace the case belongs to
Case description
Language/locale code
Custom reference number
Key of the current status
Human-readable label of the current status. Custom statuses return the label configured on the case template, in the language it was written in. Built-in statuses (draft, pending, in_progress, closed, cancelled) return an English label, as the API has no notion of the reader's language.
"Waiting for documents"
Who the case is waiting for
none, owner, contact Statuses available on this case, inherited from its case template. Use it to resolve the status key into a readable label. Null when no status is configured.
Timestamp when archived
Array of contact objects
Template reference
Case owner information
Who decided to create the case: human a person, ai a model, automation a rule configured on a case template, partner a partner integration, system Penbox itself or an API token. Read-only, and null on cases created before this was recorded.
human, ai, automation, partner, system The surface the case came through: the Penbox app, the Outlook add-in, an AI assistant, this API, an email, a completed form, a connection or Penbox itself. Read-only, and null on cases created before this was recorded.
app, outlook, mcp, api, email, form, connection, system The workspace member who created the case. Null when no person created it, and null on cases created before this was recorded. Read-only.
Array of step objects representing the case workflow
Array of data fields with their current values