Update Case

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "in_progress" }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "closed" }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "archived": true }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "archived": false }'

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Onboarding - Acme Corp",
  "status": "in_progress",
  "status_label": "In Progress",
  "parent_status": "in_progress",
  "archived_at": null
}

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Invalid status \"done\". Valid statuses for this case: draft, pending, in_progress, closed, cancelled"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Cannot update a template"
}

POST

cases

{id}

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "in_progress" }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "closed" }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "archived": true }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "archived": false }'

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Onboarding - Acme Corp",
  "status": "in_progress",
  "status_label": "In Progress",
  "parent_status": "in_progress",
  "archived_at": null
}

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Invalid status \"done\". Valid statuses for this case: draft, pending, in_progress, closed, cancelled"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Cannot update a template"
}

Update a case. Send status to move the case through its lifecycle, archived to archive or restore it, or both in the same call. At least one of the two is required.

Statuses

These five keys are always accepted:

Key	Meaning
`draft`	not started yet
`pending`	waiting on someone
`in_progress`	being worked on
`closed`	finished
`cancelled`	dropped

A case created from a case template also accepts that template’s custom status keys. Read the accepted keys from the statuses array of Get Case — you never have to hardcode them. There is no transition matrix: any accepted key can follow any other, reopening a closed case included. This is the same freedom a user has inside Penbox. parent_status is derived by Penbox from the status you set and cannot be written.

A status change made with an API token is written to the case timeline and attributed to your integration by name, so a user reading the case in Penbox can tell your change apart from a Penbox automation.

Changing a status does not run the case automations. Automations move the status, not the other way round — exactly as when a user changes the status by hand.

Case templates cannot be updated through this endpoint. Calling it on a template returns a 400.

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "in_progress" }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "closed" }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "archived": true }'

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "archived": false }'

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Onboarding - Acme Corp",
  "status": "in_progress",
  "status_label": "In Progress",
  "parent_status": "in_progress",
  "archived_at": null
}

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Invalid status \"done\". Valid statuses for this case: draft, pending, in_progress, closed, cancelled"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Cannot update a template"
}

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

string<uuid>

required

Case UUID

Body

application/json

status

string

The status key to move the case to. Always accepted: draft, pending, in_progress, closed, cancelled. A case created from a case template also accepts that template's custom status keys — read them from the statuses array of GET /cases/{id}. Any other key returns 422 with the list of accepted keys.

Example:

"in_progress"

archived

boolean

Set to true to archive the case, false to restore it.

Example:

true

Response

Case updated successfully

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

Show child attributes

description

string | null

Case description

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.

Show child attributes

archived_at

string<date-time> | null

Timestamp when archived

contacts

object[]

Array of contact objects

Show child attributes

template

string | null

Template reference

owner

object | null

Case owner information

Show child attributes

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.

Show child attributes

steps

object[]

Array of step objects representing the case workflow

Show child attributes

schema

object[]

Array of data fields with their current values

Show child attributes

API Reference

Workspaces

Cases

Tasks

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Statuses

Authorizations

Path Parameters

Body

Response

​Statuses

Authorizations

Path Parameters

Body

Response

Statuses