Skip to main content
POST
/
cases
/
{id}
/
start
/
{stepKey}
Start Case Step
curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id}/start/{stepKey} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": {}
}'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "title": "<string>",
  "parent_status": "draft",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "locale": "<string>",
  "reference": "<string>",
  "status": "<string>",
  "waiting_for": "none",
  "archived_at": "2023-11-07T05:31:56Z",
  "contacts": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "key": "<string>",
      "name": "<string>",
      "email": "[email protected]",
      "given_name": "<string>",
      "family_name": "<string>",
      "phone": "<string>"
    }
  ],
  "template": "<string>",
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "[email protected]",
    "given_name": "<string>",
    "family_name": "<string>"
  },
  "steps": [
    {
      "id": "<string>",
      "title": "<string>",
      "status": "<string>",
      "data": {}
    }
  ],
  "schema": [
    {
      "key": "<string>",
      "type": "<string>",
      "value": "<unknown>",
      "name": "<string>"
    }
  ]
}
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

Case owner information

​
steps
object[]

Array of step objects representing the case workflow

​
schema
object[]

Array of data fields with their current values