Skip to main content
POST
Start Case Step
This endpoint triggers the execution of a specific step within a case. When a step is started, it performs its configured actions such as:
  • 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

Authorization
string
header
required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Path Parameters

id
string<uuid>
required

Case UUID

stepKey
string
required

Step key identifier from the case's step configuration

Body

application/json
data
object

Optional data to pass to the step execution

Response

Step started successfully

id
string<uuid>
required

Case UUID

title
string
required

Case title

parent_status
enum<string>
required

Parent status

Available options:
draft,
pending,
in_progress,
closed,
cancelled
created_at
string<date-time>

Creation timestamp

updated_at
string<date-time>

Last update timestamp

workspace
object

Workspace the case belongs to

description
string | null

Case description

agent
object

The case agent, as far as the API exposes it.

locale
string | null

Language/locale code

reference
string | null

Custom reference number

status
string | null

Key of the current status

status_label
string | null

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.

Example:

"Waiting for documents"

waiting_for
enum<string>

Who the case is waiting for

Available options:
none,
owner,
contact
statuses
object[] | null

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.

archived_at
string<date-time> | null

Timestamp when archived

silent
boolean

True for a Silent case: created from a connected mailbox, not picked up by anyone yet, and kept out of the team's case views. It is picked up, for good, at the first action a person takes on it.

contacts
object[]

Array of contact objects

template
string | null

Template reference

owner
object | null

Case owner information

actor_type
enum<string> | null
read-only

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.

Available options:
human,
ai,
automation,
partner,
system
channel
enum<string> | null
read-only

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.

Available options:
app,
outlook,
mcp,
api,
email,
form,
connection,
system
creator
object | null
read-only

The workspace member who created the case. Null when no person created it, and null on cases created before this was recorded. Read-only.

steps
object[]

Array of step objects representing the case workflow

schema
object

The data of the case: its declared fields with their current values, and the values written without a declared field.

One embed link per contact who has the customer portal on this case. Empty when the case runs no portal, when the contact's role has no portal, or when the case requires a verification code.