List Cases
Retrieve a paginated list of cases (workflows) with optional filtering and sorting.
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.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
API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}
Query Parameters
Filter by template UUID
Filter by custom status
Filter by parent status
draft, pending, in_progress, closed, cancelled Filter by archived status
Filter by who the case is waiting for
none, owner, contact Filter by custom reference number
Filter by owner UUID
Filter by owner email
Filter by workspace UUID
Filter by workspace slug
Filter by contact first name. Exact match, case-sensitive and accent-sensitive — use contact[search] for partial, case-insensitive or accent-insensitive matching.
Filter by contact last name. Exact match, case-sensitive and accent-sensitive — use contact[search] for partial, case-insensitive or accent-insensitive matching.
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.
128Filter using advanced JSON syntax. If specified, will ignore all other filter parameters. See the Advanced Filters guide for more information.
Page number (starts at 1)
x >= 1Number of items per page (max: 100)
1 <= x <= 100Sort field (prefix with - for descending)