Skip to main content
GET
Get Case
Retrieve complete details of a specific case including its steps and schema.
embed_links gives one link per portal contact, to show their forms in an iframe on your website. See Iframe Embedding.
The status field contains the key of the status, not its label. Use status_label to display it directly, or the statuses array — returned with the case — to map every key to its label. Neither requires an extra call.Custom statuses return the label configured on the case template. Built-in statuses (draft, pending, in_progress, closed, cancelled) return an English label: translate them from the key if you need another language.
Where the case came from. Three read-only fields say how a case was created. actor_type says who decided: 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. channel says which surface the case came through: app, outlook, mcp, api, email, form, connection or system. creator is the workspace member who created the case, or null when no person did.You cannot write these fields. A value sent in a request body is ignored. They are null on cases created before this was recorded.

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

Response

200 - application/json

Successful response

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.