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
created_at
string<date-time>

Creation timestamp

updated_at
string<date-time>

Last update timestamp

description
string | null

Case description

locale
string | null

Language/locale code

reference
string | null

Custom reference number

status
string | null

Custom status value

waiting_for
enum<string>

Who the case is waiting for

Available options:
none,
owner,
contact
archived_at
string<date-time> | null

Timestamp when archived

contacts
object[]

Array of contact objects

template
string | null

Template reference

owner
object | null

Case owner information

steps
object[]

Array of step objects representing the case workflow

schema
object[]

Array of data fields with their current values