Update Case

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Litige bail commercial - Dupont",
    "description": "Commercial lease dispute, hearing on 12 March.",
    "agent": { "instructions": "Always answer the client in French." }
  }'

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 '{
    "title": "Litige bail commercial - Dupont",
    "description": "Commercial lease dispute, hearing on 12 March.",
    "agent": { "instructions": "Always answer the client in French." }
  }'

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 any of these fields, alone or together; at least one is required.

Field	Effect
`title`	renames the case (cannot be empty)
`description`	replaces its description; `null` clears it
`agent.instructions`	replaces the instructions the case agent follows; `null` clears them. The rest of the agent’s settings stay as they are.
`status`	moves the case through its lifecycle
`archived`	archives (`true`) or restores (`false`) the case

agent.instructions is returned by Get Case and by this endpoint.

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 '{
    "title": "Litige bail commercial - Dupont",
    "description": "Commercial lease dispute, hearing on 12 March.",
    "agent": { "instructions": "Always answer the client in French." }
  }'

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

title

string

The new title of the case. Cannot be empty.

Minimum string length: 1

Example:

"Litige bail commercial - Dupont"

description

string | null

The new description of the case. null or an empty string clears it.

Example:

"Commercial lease dispute, hearing on 12 March."

agent

object

The case agent. Only its instructions can be set through the API; the rest of its settings stay as they are.

Show child attributes

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

agent

object

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

Show child attributes

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

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

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

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

Show child attributes

embed_links

object[]

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.

Show child attributes

API Reference

Workspaces

Cases

Webhooks

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