Skip to main content
GET
List Cases
Retrieve a paginated list of cases with optional filtering and sorting.
Cases are also referred to as workflows in the API. They represent structured processes with multiple steps and contacts.
Use the parent_status filter to quickly find cases in specific workflow stages, and combine with waiting_for to identify bottlenecks.
The status field contains the key of the status, not its label. Each case also carries status_label, the label of its current status, and a statuses array mapping every key to a human-readable label — so a list can be rendered without fetching the case templates. Built-in statuses (draft, pending, in_progress, closed, cancelled) are labelled in English.
Looking for a case by who it is about? Use contact[search] — one free-text query, matched against the contact’s name, email, phone, internal reference and company name at once:
Every word must match, in any order, anywhere in the contact, and accents are ignored in both directions — so Mélanie Hardy, hardy mel and melanie hardy all find the same person, and Jorgensen finds Jørgensen.The contact[given_name], contact[family_name] and contact[email] filters are exact match instead: contact[given_name]=Mélanie will not find a contact stored as MELANIE. Reach for them only when you have the precise stored value — otherwise use contact[search].
Where each case came from. Every case in the list carries actor_type (who decided: human, ai, automation, partner or system), channel (the surface it came through: app, outlook, mcp, api, email, form, connection or system) and creator (the workspace member who created it, or null when no person did). The three fields are read-only, and 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}

Query Parameters

template[id]
string<uuid>

Filter by template UUID

status
string

Filter by custom status

parent_status
enum<string>

Filter by parent status

Available options:
draft,
pending,
in_progress,
closed,
cancelled
archived
boolean
default:false

Filter by archived status

waiting_for
enum<string>

Filter by who the case is waiting for

Available options:
none,
owner,
contact
reference
string

Filter by custom reference number

owner[id]
string<uuid>

Filter by owner UUID

owner[email]
string<email>

Filter by owner email

workspace[id]
string<uuid>

Filter by workspace UUID

workspace[slug]
string

Filter by workspace slug

contact[given_name]
string

Filter by contact first name. Exact match, case-sensitive and accent-sensitive — use contact[search] for partial, case-insensitive or accent-insensitive matching.

contact[family_name]
string

Filter by contact last name. Exact match, case-sensitive and accent-sensitive — use contact[search] for partial, case-insensitive or accent-insensitive matching.

contact[email]
string<email>

Filter by contact email. Exact match — use contact[search] to match on a fragment of the address.

Free-text search over the case's contacts. Returns cases having at least one contact that matches.

The query is split on spaces and every word must match, anywhere in the contact and in any order — so Mélanie Hardy, hardy mel and Hardy Mélanie all find the same person. Matching is case-insensitive and accent-insensitive in both directions (Melanie finds Mélanie, Jorgensen finds Jørgensen).

Searched fields: first name, last name, email, phone number, internal reference and company name. A fragment is enough — 112233 matches the phone +32470112233.

% and _ are matched literally, not as wildcards.

Combine it with contact[given_name], contact[email], or any case-level filter: all conditions must hold.

An empty value applies no filter, so a cleared search box can keep sending the parameter.

Limits: at most 128 characters and at most 6 words. Exceeding either returns 422 Unprocessable Entity.

Maximum string length: 128
filter
string

Filter using advanced JSON syntax. If specified, will ignore all other filter parameters. See the Advanced Filters guide for more information.

page[number]
integer
default:1

Page number (starts at 1)

Required range: x >= 1
page[size]
integer
default:10

Number of items per page (max: 100)

Required range: 1 <= x <= 100
sort
string
default:-created_at

Sort field (prefix with - for descending)

Response

200 - application/json

Successful response

meta
object
data
object[]