# What is Penbox Agent
Source: https://docs.penbox.io/agent/introduction
The AI assistant built into Penbox
Penbox Agent is the AI assistant built into Penbox. You describe what you want, and it applies the change.
Penbox Agent builds your Form Templates, Case Templates, and Document Intelligence Templates. It also works on your live cases, all from the same chat panel, with capabilities that adapt to the page you have open.
Every outbound message Penbox Agent creates is a draft. Nothing leaves your
workspace until you approve it.
## A builder and a runner
Penbox Agent does two distinct things.
### The builder
In the Form Template, Case Template, and Document Intelligence Template editors, Penbox Agent is a builder. You describe what to build or change, and Penbox Agent does it.
This is where Penbox Agent handles complex Penbox logic for you:
* **Conditional logic.** "Show the Vehicle step only when the user picks Car on step 1 and when the estimated damage amount is greater than 1000." Penbox Agent writes the visibility expression.
* **Flow variables.** "Compute the full name from given name and family name." Penbox Agent defines and wires the variable.
* **Multilingual content.** Penbox Agent translates every visible string and updates the form's languages list.
* **AI extraction.** Penbox Agent lists data points to extract from an uploaded document and binds them to form fields.
* **Building from a document.** Drop a paper form or claim report. Penbox Agent reproduces it end to end.
Typical workflow: open the template, describe what you want, watch each change land live, iterate.
Penbox Agent, thinks with you, and builds for you. He handles all the technical complexity.
Give Penbox Agent a business brief, for example:
It designs the form, computes the pricing variables, wires the conditional logic, and confirms what it built:
The quote step uses PenScript expressions to handle the math. Your contact sees a polished, branded breakdown:
What Penbox Agent handles for you
→
What your contact sees
### The runner
On a running case, Penbox Agent is your operator's assistant: it reads the timeline and the data, answers questions, drafts the next message, and moves the case forward.
This is where Penbox Agent answers operational questions:
* **What's the state?** "Summarize this case." "What did the contact say last?" "What's the IBAN we received?"
* **What's next?** "Draft a reminder to the main contact about the missing photos."
* **Move the case.** "Move to 'In review'." "We're waiting for the contact now."
Typical workflow: open the case, ask what you need to know, get a draft for the next move, review and send.
## Setup
How you open the chat depends on the surface:
* **In a case or a Case Template.** Click **Ask Penbox** in the top right. The button turns blue and the chat opens on the right.
* **In the Form Template editor.** Use the **Assistant / Preview** toggle in the top right. Assistant opens the chat; Preview hides it and shows the form as a contact would see it.
* **In a Document Intelligence Template.** The chat is always open.
Penbox Agent does not edit Email Templates or SMS Templates. Those stay manual.
Build forms: steps, fields, conditional logic, translations, signatures, automations.
Design recurring case workflows: data schema, contacts, steps, statuses,
automations.
Configure extraction fields for documents.
Answer questions, set values, draft the next step, move the case forward.
## Essentials
### Reverting changes
Penbox Agent records each change it makes as a separate entry in the chat. A simple request produces one entry. A complex request, like building a form from scratch, produces many. Penbox Agent breaks the work into smaller steps and each step gets its own entry.
The entry header names the surface and how many attributes the step touched. The label format depends on the surface:
* Form Template editor: **Adapted form ...**
* Case Template editor: **Adapted template ...**
* Live case: **Updated case ...**
The count after the label reflects the number of attributes touched. A step may touch a single attribute (`1 change`) or many (`7 changes`).
Hover an entry to reveal the revert arrow. Click it to undo, click again to reapply.
Expand an entry to see its individual changes, each marked with a green checkmark once applied. Hover an individual change to:
* Highlight the matching element in the editor (purple outline).
* Reveal a revert arrow for that single change. Click to undo just that one.
To wipe everything Penbox Agent built in one go, ask it in plain language: "clear
the form", "empty the case template". Faster than clicking revert on every
entry.
In a Document Intelligence Template, the revert arrow does not appear in the
chat. Ask Penbox Agent in plain language ("undo that last change") and it will
revert.
### Chat history
Penbox Agent keeps every conversation you start. Open the chat panel and you see your previous conversations on this artifact, each with an auto-generated title summarizing the first message.
* History is per artifact. A Form Template, a Case Template, a Document Intelligence Template, and a Case each have their own conversation list.
* History is private. Your colleagues have their own conversation lists, even on the same artifact.
* Open a previous conversation to resume it. Penbox Agent picks up where you left off.
* Delete a conversation when you no longer need it.
### Working with files
Drop or attach a PDF/image into the chat. Penbox Agent reads it and builds the matching artifact.
* Drop a paper form into the Form Template editor. Penbox Agent reproduces it as a Penbox form with every field, every section, and the right types.
* Drop a claim report or intake form into the Case Template editor. Penbox Agent generates a Case Template with the matching data schema, contacts, and workflow steps.
Send the file with no message and Penbox Agent treats it as a request to build the artifact from scratch. It announces a short plan, then executes.
Files only exist on the turn you send them. Penbox Agent has no memory of a file
from an earlier message. Reference an older document and it will ask you to
re-upload.
### Languages
Penbox Agent answers in the language you write in, or in the locale of the template or case you have open. Multilingual Form Templates work end to end: Penbox Agent translates form content into French, Dutch, English, German, and other languages.
## What Penbox Agent does not do
* Does not send messages. On live cases, every email, SMS, or form is a draft.
* Does not trigger automations directly. Automations run on their own conditions.
* Does not edit artifacts other than the one you have open.
* Does not guess. Ambiguous requests get a clarifying question.
***
## Next Steps
Build templates with Penbox Agent
Work on running cases with Penbox Agent
Build forms with Penbox Agent
Design case workflows with Penbox Agent
# Penbox Agent on Live Cases
Source: https://docs.penbox.io/agent/live-cases
Understand a case, edit its data, draft the next step
Penbox Agent works on the case you have open: it reads the timeline and the current data, answers questions, applies changes, and drafts the next message.
Penbox Agent does not send messages and it does not modify the Case Template behind the case.
Penbox Agent on a live case operates on the case only. Changes here do not affect
the Case Template or other cases created from it.
## What you can do
**Read and explain**
* Summarize the case end to end or focus on a specific moment.
* Recap a conversation: who said what, what was promised, what is pending.
* Find a value: "What's the IBAN we received?", "When did the contact reply?", "What was decided on the deductible?"
* Pull a value out of an email already received in the case.
**Edit case data**
* Set or clear values on fields in the case schema. Each update lands in the timeline and may trigger automations.
* Group related updates ("set the IBAN to X and the account holder to Y") into a single batch.
**Edit the case structure (this case only)**
* Add a new field to the case schema.
* Add a section.
* Add a contact role.
These changes affect only the open case. The Case Template stays untouched.
**Draft the next step**
* Create a draft email, SMS, or form step.
* The draft uses real case data: names, references, values. No placeholders.
* Review the draft in the timeline. Send it manually.
**Move the case forward**
* Change the case status (picking from statuses defined on the Case Template).
* Set the waiting-for indicator: `owner` (the team), `contact` (an external party), or `none`.
**Manage reminders on form steps**
* Add or edit reminders on a form step that has not been sent yet.
* Schedule an additional reminder on a form step already sent.
## Drafts vs sending
Penbox Agent never sends an email, SMS, or form. Every outbound message is a draft.
1. You ask Penbox Agent to draft a message: "draft a reminder to Marie about the missing photos."
2. Penbox Agent creates the step on the case using the real names, references, and values.
3. You open the draft in the timeline, adjust if needed, and click send.
Even if you say "send the reminder", Penbox Agent creates the draft and stops.
Sending is a human click away.
## Example prompts
> "Summarize this case in five lines."
> "What did the contact say in their last email?"
> "Set the contract amount to 12 500 €."
> "Add a 'broker' contact role to this case."
> "Draft a reminder email to the main contact asking for the missing photos of the damage."
> "Move this case to 'In review'."
> "We're waiting for the contact now."
> "Add a reminder in three days on the document request form."
## What Penbox Agent does not do here
* Does not send messages. Outbound is always a draft.
* Does not trigger automations. Automations run on their own conditions.
* Does not create internal form steps or signature steps. Those step types stay manual.
* Does not edit the Case Template behind the case. Open the Case Template in Studio for that.
* Does not invent data. If a value is not in the case, Penbox Agent says so.
***
## Next Steps
Cases in Penbox
Design the templates behind your cases
Penbox Agent inside Form Templates
What Penbox Agent does across Penbox
# Penbox Agent for Case Templates
Source: https://docs.penbox.io/agent/templates/case-templates
Design recurring case workflows with Penbox Agent
A Case Template is the blueprint for a recurring case type: data schema, contacts, workflow steps, statuses, automations. Penbox Agent designs every part of it.
## What you can do
**Data schema**
* Add, rename, remove, or reorder fields.
* Set the field type (`text`, `number`, `date`, `file`, `choices`, `checkbox`).
* Set visibility (`always-visible`, `hide-when-empty`, `always-hide`).
* Configure type-specific options (placeholder, hint, min/max, accepted file types, choice list).
**Sections**
* Group related fields into named sections.
* Reorder or remove sections. Toggle section visibility.
**Contact roles**
* Add secondary contacts with custom roles: broker, expert, billing contact, witness.
* Rename or remove secondary contacts. The main contact is required and cannot be removed.
**Workflow steps**
Penbox Agent adds and edits three step types: email, SMS, and form. Internal form steps and signature steps stay manual for now.
* **Email.** A one-way email to a contact: confirmation, status update, internal notification.
* **SMS.** A short text message to a contact.
* **Form.** A request sent to a contact to collect data. Built inline on the step, or attached from an existing Form Template.
For each step, Penbox Agent configures the title, the recipient, the subject and body (static HTML or an AI-generated body that adapts to the case data at send time), attachments, and conditional execution.
**Custom statuses**
Define the statuses your case moves through (Pending, In Review, Awaiting Documents, Closed) and configure automatic transitions: move from one status to another when a condition is met.
**Automations**
Configure webhooks and email automations triggered by step completion, status changes, or data updates.
**AI extraction**
Configure AI extraction on file fields. Two mechanisms:
* **Inline extraction.** Defined directly on the file field. Best for ad-hoc extraction.
* **Existing Document Intelligence Template.** Penbox Agent attaches a reusable template from your workspace and maps its fields to the case schema.
## Inline forms vs reusable Form Templates
Two options when you add a form step.
* **Inline form.** Penbox Agent defines the form fields directly on the step. Best when the form is specific to this Case Template.
* **Attach an existing Form Template.** Penbox Agent searches your workspace by name, asks you to confirm, and attaches the right one. Best when several Case Templates reuse the same form.
Describe what the form should ask for ("add a step that requests proof of
identity and a recent utility bill") and Penbox Agent builds an inline form. Ask
explicitly to "use the KYC form" or "attach our onboarding form" to reuse an
existing Form Template.
## Auto-syncing form data into the schema
When Penbox Agent adds a form step, it proposes to add the form's fields to the case schema too. The schema stays in sync with the data the case will collect: other steps can pre-fill from those fields, automations can react to them, and your team sees what data is expected before the form comes back.
Accept the suggestion, modify it, or skip it.
## Example prompts
> "Add a billing contact called Contact facturation."
> "Add an email step that confirms the case opening to the main contact."
> "Add a form step that requests an ID card and a proof of residence. Configure AI extraction on the ID card."
> "Create a status 'Awaiting documents' and transition to it automatically when the document field is empty after the form was sent."
> "Add an automation that posts the case to our CRM when the status becomes Closed."
> "Build a Case Template from this document."
## What Penbox Agent does not do here
* Does not create internal form steps or signature steps. Those step types stay manual in the Case Template editor.
* Does not edit permissions or sender integrations (email sender, signature provider). Those stay in the workspace settings.
* Does not edit a Form Template attached to a step. Open the Form Template and use Penbox Agent there.
* Does not edit settings outside the data schema, contacts, workflow steps, statuses, and automations of the Case Template.
***
## Next Steps
Case Templates in Penbox
Penbox Agent inside Form Templates
Configure extraction templates
Penbox Agent on running cases
# Penbox Agent for Document Intelligence Templates
Source: https://docs.penbox.io/agent/templates/document-intelligence
Define what to extract from documents
A Document Intelligence Template tells Penbox what to extract from a document: a list of fields, each with a type and an optional hint. Penbox Agent builds and refines these templates.
## What you can do
**Extraction fields**
* Add, rename, remove, or reorder fields.
* Set the field type: `text`, `number`, `date`, or `list` (a repeatable group of sub-fields, like line items on an invoice).
* Add a hint. A short instruction that disambiguates the extraction ("use the issue date, not the expiry date" or "the number printed at the bottom of the card").
* For list fields, define the sub-fields the extraction produces for each item.
**Keys**
Penbox Agent generates a snake\_case `key` for each field when you do not provide one. The key is the identifier you reference elsewhere in Penbox, for example from a Case Template that uses this Document Intelligence Template on a file field.
## Example prompts
> "Add the fields needed to extract data from an ID card."
> "Add a list field `line_items` with description, quantity, unit price, and total."
> "Add a hint to the issue date field so it picks the issuance date, not the expiry date."
> "Rename `invoice_number` to `ref_number`."
## Where these templates are used
Once a Document Intelligence Template exists in your workspace, attach it to a file field inside a Case Template. Penbox Agent recognizes "use the workspace template" or "use the invoices template" and wires it up. See [Penbox Agent for Case Templates](/agent/templates/case-templates#ai-extraction).
## What Penbox Agent does not do here
* Does not run the extraction on a document for you. Testing happens in the Document Intelligence Template's test interface.
* Does not invent fields you did not ask for. When the document type is ambiguous, Penbox Agent asks which fields you want.
***
## Next Steps
Use a Document Intelligence Template inside a Case Template
Configure inline AI extraction on a form file field
What Penbox Agent does across Penbox
Penbox Agent on running cases
# Penbox Agent for Form Templates
Source: https://docs.penbox.io/agent/templates/form-templates
Build and edit forms by describing what you want
Penbox Agent edits the Form Template you have open. You describe a change, and it applies it.
## What you can do
**Form structure**
* Add, remove, rename, or reorder steps.
* Add, remove, or edit elements inside a step.
* Set conditional visibility on a step, a section, or a field.
* Mark fields required. Set placeholders, hints, and validation (min/max, length, format).
**Field types**
Penbox Agent knows every Penbox field type: text, number, date, choices (single or multiple), file upload, signature, phone, country, currency, IBAN, checkbox, toggle, autocomplete, rating, and display elements (paragraph, card, image, download).
**Welcome and ending pages**
Configure the welcome screen (title, intro message, custom image, privacy policy, help button) and the ending screen (confirmation message, image, redirect URL).
**Flow variables**
Define reusable computed values once and reference them anywhere in the form. Useful for derived values (`{full_name} = {user.given_name} {user.family_name}`) or shared labels.
**Sender-filled Options**
Configure the secondary form the sender fills in when launching the main form (case type, reference, logo). Values entered in Options become available across the main form and in conditional logic.
**Signatures**
Add signature elements with the right method: handwritten, SMS code, email code, ID-card reader, Itsme. Configure additional signers, legal notices, and signature placement on documents.
**AI extraction on file fields**
List the data points the contact's document should yield (last name, first name, ID number, expiry date). Penbox Agent wires the extraction to the matching form fields.
**Invitations and reminders**
Configure form delivery and follow-up reminder cadence.
**Automations on the form**
Trigger an email or HTTP call on form lifecycle events: opened, updated, submitted, declined, or expired.
## Translations
Ask Penbox Agent to translate the open form into French, Dutch, German, English, or any combination, and the entire form is multilingual in under a minute. Every visible string the contact sees gets translated: step titles, field labels, hints, placeholders, choice options, validation messages, welcome and ending pages. The form's available languages list is updated in the same pass.
Done manually, this means filling every element's translation slot by hand, hours of work for each language. With Penbox Agent, it is a one-line prompt.
Add a language later by asking. Penbox Agent translates what is missing without touching strings already translated.
## Example prompts
> "Add a step that asks for the IBAN and the account holder's name."
> "Make the email field required and add a placeholder."
> "Show the Vehicle step only when the user picks Car on step 1."
> "Translate this form to French and Dutch."
> "Add a signature step using Itsme."
> "On the ID card field, extract last name, first name, date of birth, ID number, and expiry date."
> "Build a form from this document."
## Smart suggestions
Click the lightbulb icon in the chat to turn smart suggestions on. With suggestions enabled, Penbox Agent ends each reply with one improvement to consider, like AI extraction on a file field that does not have it, or an obvious required field not marked required. Reply "yes" and Penbox Agent applies it.
Suggestions are grounded in the form you have open, never generic advice.
## What Penbox Agent does not do here
* Does not edit forms other than the one you have open.
* Does not send the form. You publish and share it from the form's invitation settings.
* Does not invent unsupported syntax. If something cannot be done in PenScript, Penbox Agent says so.
***
## Next Steps
Form Templates in Penbox
Penbox Agent inside Case Templates
Configure AI extraction templates
Penbox Agent on running cases
# Penbox Agent for Templates
Source: https://docs.penbox.io/agent/templates/introduction
Build the templates that power your workspace
Templates are the reusable artifacts that drive your operations. Penbox Agent edits three of them: Form Templates, Case Templates, and Document Intelligence Templates.
Penbox also supports Email Templates and SMS Templates. Penbox Agent does not
edit those. They need to be manually edited.
## The three template types
The form your contacts fill in: steps, fields, pages, translations, signatures, AI extraction, invitations.
The blueprint for a recurring workflow: data schema, contacts, workflow steps,
statuses, automations.
The extraction definition for documents.
## How template editing works
Create or open a template, open Penbox Agent, and describe what you want.
1. You describe a change, or attach a PDF or image.
2. Penbox Agent announces a short plan.
3. Penbox Agent applies the change incrementally. You see each change appear live in the editor.
4. Penbox Agent confirms what changed. In the Form Template editor, it can add one actionable suggestion to improve the form if you click on the lightbulb icon.
> "Add a step that asks for the IBAN and the account holder's name."
> "Translate this form to French and Dutch."
## Building from a document
Drop a document. Penbox Agent reads it and scaffolds the template.
* Drop a paper form into the Form Template editor. Penbox Agent reproduces it as a Penbox form.
* Drop a claim report, intake form, or contract into the Case Template editor. Penbox Agent generates the matching data schema, contacts, and workflow steps.
Send the file with no message and Penbox Agent builds end to end, announcing a short plan before executing.
Use a clean, representative example. Penbox Agent infers field types,
conditional sections, and required information from what it sees.
## What carries across all three
* Penbox Agent reads the live template before every change. Edits made in the UI outside the chat are picked up automatically.
* Penbox Agent asks a short clarifying question instead of guessing.
* Large requests are split into many small calls. You see each change land and you can stop the agent at any point.
* Every change is reversible. See [Reverting changes](/agent/introduction#reverting-changes) for the per-surface details.
***
## Next Steps
What Penbox Agent does inside a Form Template
What Penbox Agent does inside a Case Template
Configure extraction fields with Penbox Agent
Penbox Agent on running cases
# Penbox for AI agents
Source: https://docs.penbox.io/agents/introduction
Drive Penbox from Claude Code, Claude, Codex or any MCP client.
Penbox exposes an MCP server. An AI agent connected to it can open cases, follow them, build case templates and form templates, read form responses, and reach the rest of the public API. It works from Claude Code, claude.ai, Claude Desktop, Codex and any MCP client.
Two commands for Claude Code. One URL for claude.ai. A zip for Codex.
## What you get
### The MCP server
The server lives at `https://connect.penbox.io/mcp`. It speaks business vocabulary: case, case template, form, form template. Every tool runs as the signed-in user, with that user's rights and nothing more.
| Area | Tools |
| - | - |
| Workspace | `list_workspaces` |
| Cases | `list_cases`, `get_case`, `create_case`, `assign_contact`, `update_case`, `update_case_status`, `update_case_data`, `update_case_waiting_for`, `update_draft`, `add_step_reminder`, `start_case_step` |
| Tasks | `list_tasks`, `create_task`, `update_task` |
| Case templates | `list_case_templates`, `get_case_template`, `create_case_template`, `update_case_template` |
| Form templates | `list_form_templates`, `get_form_template`, `create_form_template`, `update_form_template` |
| Forms | `list_forms`, `get_form`, `get_form_response` |
| Knowledge | `get_skill`: the reference guides an agent loads before building a template |
| Public API | `penbox_api_search`, `penbox_api_details`, `penbox_api_call`: the rest of the [API](/api-reference/introduction) |
`start_case_step` is the only tool that sends something for real: an email, an SMS or a form goes out to the contact. Every other write stays inside Penbox.
### The skills
A plugin adds five skills on top of the server. A skill is a short playbook the agent loads when the task matches. It teaches the order of operations, not the tools. See [Skills](/agents/skills).
## Two ways to sign in
* **As a user.** The default. The agent opens your browser once. You sign in to Penbox and approve. The agent then acts as you. What you cannot do in Penbox, it cannot do either.
* **With a workspace API token.** For a server-side agent with no human at the keyboard. Create the token in your [workspace settings](/workspace/settings/api) and use it as the bearer on `https://connect.penbox.io/mcp`. The agent is then scoped to that workspace.
## Where it runs
| Surface | Path |
| - | - |
| Claude Code | Plugin: server and skills |
| claude.ai, Claude Desktop | Custom connector: server only |
| Claude organization | Plugin synced to every member by an admin |
| Codex | Plugin from the zip: server and skills |
| Any MCP client | Server only |
## Next
Every install path, and prompts to start with.
What each skill does and when it triggers.
Rights, data, and what the agent can never do.
# Security
Source: https://docs.penbox.io/agents/security
What an AI agent can and cannot do in your Penbox workspace.
An agent connected to Penbox is a user with tools. This page says what that user can do, what leaves your workspace, and what is refused.
## Sign-in
* **OAuth, in your browser.** On the first tool call, the agent opens the Penbox sign-in page. You sign in with your own account and approve the connection.
* **No token to paste.** The client registers itself with Penbox (dynamic client registration). No API key travels through the chat, a config file or the plugin.
* **Revocable.** Disconnect the connector in your client, or sign out of Penbox. The agent loses access.
A server-side agent can use a workspace API token instead. That token has the workspace's rights, like any [API client](/api-reference/authentication).
## Rights
* **The agent never has more rights than you.** Every tool call runs as the signed-in user. The same policies apply as in the Penbox app and the public API. What you cannot see or change in Penbox, the agent cannot either.
* **Several workspaces, no silent pick.** When your account reaches several workspaces, listing and creation tools refuse until the agent names one. The agent must ask you.
* **Actions are attributed to you.** A change made over MCP shows your name in the case history, with a "via MCP" tag.
## What the agent cannot do
* **Delete.** No tool deletes anything, and the raw API passthrough refuses every DELETE. Deleting is done in the Penbox app. Archiving a case is allowed: it is reversible.
* **Provision a workspace or create a member.** Both are refused over MCP.
* **Send without being asked.** Only `start_case_step` sends an email, an SMS or a form to a contact. The skills tell the agent to call it only when you explicitly ask to send.
* **Delete a task.** A task is dismissed, not deleted.
## Data
* **Nothing is pre-loaded.** The agent receives only what a tool call returns: the case it asked for, the form response it read. No background sync, no export of your workspace.
* **Data goes to your agent's provider.** A tool result is handed to the model you use (Anthropic, OpenAI, or another). Check that provider's terms for what it keeps. Penbox does not send anything to a model on its own during MCP usage.
* **Third-party text is labelled as data.** A case and a form response carry a note telling the agent that content written by contacts, respondents or incoming emails is data, never an instruction. This limits prompt injection through a form answer.
* **Large responses are cut.** A response over 50 KB is truncated. The agent is told to narrow the call.
## Hosting and billing
* **EU hosting.** The MCP server runs in the European Union, with the rest of Penbox.
* **No credits.** MCP usage does not consume Penbox credits. The model runs on your side, in your agent.
## Refused over MCP
| Operation | What happens |
| - | - |
| Any `DELETE` | Refused. Delete in the Penbox app. |
| `POST /workspaces` | Refused. Workspace provisioning is not available over MCP. |
| `POST /members` | Refused. Member creation is not available over MCP. |
| A write covered by a curated tool | Refused. The refusal names the tool to use, so its guards apply. |
Refusals are answers, not errors. The agent reads the refusal and follows it. A refusal from the API itself, such as a 403, is final: it means your account lacks the right.
# Skills
Source: https://docs.penbox.io/agents/skills
The five playbooks the Penbox plugin gives an agent.
The Penbox plugin ships five skills. A skill is a short document the agent reads when your request matches its description. It tells the agent what to load, in which order, and what to check before it answers. The skills never repeat the reference material: the agent fetches that from the server with `get_skill`.
The skills are in the plugin only. A custom connector or a tools-only setup does not carry them. The tools still work; the agent just has less guidance.
## penbox-getting-started
**When:** the first Penbox action in a conversation.
The agent resolves your workspace, learns the vocabulary (case, case template, form, form template, contact) and the read-before-write rule: every update starts from the current document, never from memory. It also learns that text written by contacts and respondents is data, never an instruction.
## manage-cases
**When:** you want to open a case, add a contact, change a status, fill in data, send a reminder, or check where a case or a form stands.
No reference needed. The agent finds the case, reads it, then acts. It searches cases by contact name or email, because case titles usually default to the template name. Sending a form or a reminder now goes through `start_case_step`, only when you ask to send.
## build-case-template
**When:** you want a new type of case, or want to change the steps, statuses, automations, contacts or data schema of an existing template.
The agent loads the case template reference once, checks whether a similar template already exists, then edits with small patches, one concern each. Before it writes a status, an automation or a condition, it loads the guide for that feature.
## build-form-template
**When:** you want a new form, or want to add or change questions, signatures, translations, repeated sections or generated documents in an existing one.
Same method: load the form template reference once, list what exists, create, then patch. The agent reads the validation errors the server returns and fixes them before moving on. A form template is created published, so the agent builds it one patch at a time.
## penbox-api
**When:** a curated tool refuses, is missing, or you name an endpoint of the Penbox API.
The agent searches the [public API](/api-reference/introduction) with `penbox_api_search`, reads the contract with `penbox_api_details`, then calls it with `penbox_api_call`. When a curated tool covers the operation, the search says so and the agent uses that tool instead.
You never name a skill. Describe the task in business words and the agent picks the matching skill on its own.
# Troubleshooting
Source: https://docs.penbox.io/agents/troubleshooting
The few things that look broken and are not.
`list_workspaces` returns zero. The install is fine. Your Penbox account is not a member of any workspace yet.
Ask your workspace administrator to [add you as a member](/workspace/settings/members), then try again. No reinstall needed.
A plugin installed during a session stays invisible to that session.
Open a new session. In Claude Code you can also run `/reload-plugins` in the current one.
Codex asks you to approve the filesystem write at install, and again the first time a tool runs. `codex exec` cannot answer those prompts.
Run the install and the first tool call in an interactive Codex session. After that, `codex exec` works.
Your client picks up a new version on its next launch, and only when the declared version moved.
Restart the client. If the version is unchanged, there is nothing new to fetch.
Sign-in happens on the first Penbox tool call, not at install time.
Ask the agent to list your workspaces. That first call triggers the OAuth flow.
Write to [support@penbox.io](mailto:support@penbox.io) with the tool name and the exact refusal message.
# Advanced Filters
Source: https://docs.penbox.io/api-reference/advanced-filters
Comprehensive guide to filtering API resources with query parameters and JSON filters
The Penbox API provides two powerful filtering methods to query and retrieve exactly the data you need. Both methods are available on `GET` (list) and `GET /count` endpoints.
## Two Filtering Methods
### Method 1: Direct Query Parameters
The simplest way to filter is by adding query parameters directly to the URL:
```bash theme={null}
GET /v1/cases?workspace[id]=abc-123&owner[email]=john@acme.com&status=pending
```
**Benefits:**
* Simple and readable
* Easy to construct manually
* Good for basic filtering needs
**Example:**
```javascript theme={null}
// Filter cases by workspace and owner
const params = new URLSearchParams({
'workspace[id]': workspaceId,
'owner[email]': 'sales@acme.com',
'archived': 'false'
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
```
### Method 2: Advanced JSON Filter
For complex queries, use the `filter` parameter with a JSON object containing operators:
```bash theme={null}
GET /v1/cases?filter={"attributes":{"created_at":{"$gt":"2024-01-01"}}}
```
**Benefits:**
* Powerful operator-based filtering
* Support for complex conditions
* Filter on attributes and relationships
* Combine multiple criteria with operators
**Example:**
```javascript theme={null}
const filter = {
attributes: {
created_at: { $gt: '2024-01-01T00:00:00Z' },
status: { $ne: 'draft' }
},
relationships: {
owner: {
attributes: {
email: { $eq: 'sales@acme.com' }
}
}
}
};
const response = await fetch(
`https://connect.penbox.io/v1/cases?filter=${encodeURIComponent(JSON.stringify(filter))}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
```
## Filter Operators
When using the JSON filter method, you can use the following operators:
| Operator | Description | Example |
| - | - | - |
| `$eq` | Equals | `{ status: { $eq: 'pending' } }` |
| `$ne` | Not equals | `{ status: { $ne: 'draft' } }` |
| `$gt` | Greater than | `{ created_at: { $gt: '2024-01-01' } }` |
| `$lt` | Less than | `{ created_at: { $lt: '2024-12-31' } }` |
| `$ge` | Greater than or equal to | `{ created_at: { $ge: '2024-01-01' } }` |
| `$le` | Less than or equal to | `{ created_at: { $le: '2024-12-31' } }` |
| `$like` | Pattern matching | `{ title: { $like: '%onboarding%' } }` |
| `$ilike` | Case-insensitive pattern matching | `{ title: { $ilike: '%Customer%' } }` |
The `$like` and `$ilike` operators support SQL-style wildcards: `%` matches any characters
Comparison operators (`$gt`, `$lt`, `$ge`, `$le`) can be used for numbers and dates.
## Filter Structure
The JSON filter object has two main sections:
### Attributes
Filter on the resource's direct attributes:
```json theme={null}
{
"attributes": {
"status": { "$eq": "pending" },
"archived_at": { "$eq": null },
"created_at": { "$gt": "2024-01-01T00:00:00Z" }
}
}
```
### Relationships
Filter on related resources:
```json theme={null}
{
"relationships": {
"owner": {
"id": { "$eq": "abc-123" }
},
"company": {
"attributes": {
"slug": { "$eq": "acme-corp" }
}
}
}
}
```
## Examples by Resource
### Filtering Cases
**Direct Parameters:**
```bash theme={null}
# Filter by template, workspace, and status
GET /v1/cases?template[id]=template-123&workspace[slug]=acme&parent_status=in_progress
```
**JSON Filter:**
```javascript theme={null}
// Cases created after a date with pending status
const filter = {
attributes: {
created_at: { $gt: '2024-01-01T00:00:00Z' },
parent_status: { $eq: 'pending' },
archived_at: { $eq: null }
},
relationships: {
workspace: {
attributes: {
slug: { $eq: 'acme-corp' }
}
}
}
};
```
### Filtering Case Templates
**Direct Parameters:**
```bash theme={null}
# Search by title and filter by workspace
GET /v1/case_templates?title=onboarding&workspace[slug]=acme&archived=false
```
**JSON Filter:**
```javascript theme={null}
// Templates with specific title pattern
const filter = {
attributes: {
is_template: { $eq: true },
title: { $ilike: '%customer%' },
archived_at: { $eq: null }
}
};
```
### Filtering Forms
**Direct Parameters:**
```bash theme={null}
# Filter by flow, user, and completion status
GET /v1/forms?flow[slug]=kyc&user[email]=john@example.com&completed=true
```
**JSON Filter:**
```javascript theme={null}
// Active forms with specific owner
const filter = {
attributes: {
active: { $eq: true },
completed: { $eq: false }
},
relationships: {
owner: {
attributes: {
email: { $eq: 'sales@acme.com' }
}
}
}
};
```
## Common Filtering Patterns
### Time-Based Filtering
```javascript theme={null}
// Cases created in the last 7 days
const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
const filter = {
attributes: {
created_at: { $gt: sevenDaysAgo }
}
};
```
### Status Filtering
```javascript theme={null}
// Active, non-archived cases in progress
const filter = {
attributes: {
parent_status: { $eq: 'in_progress' },
archived_at: { $eq: null }
}
};
```
### Text Search
```javascript theme={null}
// Case templates with "customer" in the title
const filter = {
attributes: {
title: { $ilike: '%customer%' }
}
};
```
### Multiple Criteria
```javascript theme={null}
// Complex filter combining multiple conditions
const filter = {
attributes: {
created_at: { $gt: '2024-01-01T00:00:00Z' },
parent_status: { $ne: 'draft' },
archived_at: { $eq: null }
},
relationships: {
workspace: {
attributes: {
slug: { $eq: 'acme-corp' }
}
},
owner: {
attributes: {
email: { $eq: 'sales@acme.com' }
}
}
}
};
```
## Available Filters by Endpoint
### Cases (`/v1/cases`)
**Direct Parameters:**
* `template[id]` - Filter by template UUID
* `status` - Custom status value
* `parent_status` - Parent status (draft, pending, in\_progress, closed)
* `archived` - Boolean (true/false)
* `waiting_for` - Who the case is waiting for (none, owner, contact)
* `reference` - Custom reference number
* `owner[id]` - Owner UUID
* `owner[email]` - Owner email
* `workspace[id]` - Workspace UUID
* `workspace[slug]` - Workspace slug
* `contact[given_name]` - Contact first name (exact match)
* `contact[family_name]` - Contact last name (exact match)
* `contact[email]` - Contact email (exact match)
* `contact[search]` - Free-text search over the contact — partial and accent-insensitive; see [List Cases](/api-reference/cases/list-cases)
### Case Templates (`/v1/case_templates`)
**Direct Parameters:**
* `title` - Search by title (partial match)
* `reference` - Custom reference
* `archived` - Boolean (true/false)
* `owner[id]` - Owner UUID
* `owner[email]` - Owner email
* `workspace[id]` - Workspace UUID
* `workspace[slug]` - Workspace slug
### Forms (`/v1/forms`)
**Direct Parameters:**
* `workspace[slug]` - Workspace slug
* `flow[slug]` - Form template slug (single value or array)
* `flow[customization]` - Template customization UUID
* `owner[email]` - Owner email
* `user[given_name]` - User first name
* `user[family_name]` - User last name
* `user[email]` - User email
* `user[phone]` - User phone
* `archived` - Boolean (true/false)
* `active` - Boolean (true/false)
* `completed` - Boolean (true/false)
* `processed` - Boolean (true/false)
## Best Practices
For basic filtering needs (workspace, status, owner), use direct query parameters. They're easier to read and debug.
When you need operators, date comparisons, or pattern matching, use the JSON filter method.
When passing JSON in the filter parameter, always use `encodeURIComponent()` to properly encode special characters.
Always use pagination when expecting many results to avoid timeouts and improve performance.
To check for null values, use `{ $eq: null }` or `{ $ne: null }` in your filter.
```javascript theme={null}
// Non-archived resources
{ archived_at: { $eq: null } }
```
When searching text fields, use `$ilike` instead of `$like` for case-insensitive matching.
## Real-World Examples
### Dashboard: Active Cases by Team Member
```javascript theme={null}
async function getActiveCases(ownerEmail) {
const filter = {
attributes: {
parent_status: { $eq: 'in_progress' },
archived_at: { $eq: null }
},
relationships: {
owner: {
attributes: {
email: { $eq: ownerEmail }
}
}
}
};
const response = await fetch(
`https://connect.penbox.io/v1/cases?filter=${encodeURIComponent(JSON.stringify(filter))}&sort=-created_at`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return await response.json();
}
```
### Search Case Templates
```javascript theme={null}
async function searchTemplates(searchTerm) {
// Using direct parameter for simplicity
const params = new URLSearchParams({
title: searchTerm,
archived: 'false'
});
const response = await fetch(
`https://connect.penbox.io/v1/case_templates?${params}&sort=title`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return await response.json();
}
```
### Multi-Workspace Reporting
```javascript theme={null}
async function getCompletedCases(workspaceSlug, startDate, endDate) {
const filter = {
attributes: {
parent_status: { $eq: 'closed' },
created_at: { $gt: startDate, $lt: endDate }
},
relationships: {
workspace: {
attributes: {
slug: { $eq: workspaceSlug }
}
}
}
};
const response = await fetch(
`https://connect.penbox.io/v1/cases?filter=${encodeURIComponent(JSON.stringify(filter))}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return await response.json();
}
```
## Error Handling
Invalid filters return a `400 Bad Request` error:
```json theme={null}
{
"errors": [
{
"status": "400",
"title": "Invalid Filter",
"detail": "Invalid filter parameter format"
}
]
}
```
**Common Issues:**
* Invalid JSON format in filter parameter
* Unrecognized filter fields
* Type mismatches (e.g., string instead of boolean)
* Invalid operator usage
**Solution:**
```javascript theme={null}
try {
const response = await fetch(url, { headers });
if (!response.ok) {
const error = await response.json();
console.error('Filter error:', error);
return { data: [], meta: { total_count: 0 } };
}
return await response.json();
} catch (error) {
console.error('Request failed:', error);
return { data: [], meta: { total_count: 0 } };
}
```
## Next Steps
Control result size and order
Complete API specification with all available filters
Apply filters to the Cases endpoint
Filter forms with advanced queries
Search and filter case templates
# All API Endpoints
Source: https://docs.penbox.io/api-reference/all-endpoints
Complete reference of all API endpoints
## Quick Reference
This page provides a complete overview of all available API endpoints.
## Forms
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/forms` | [List forms with filtering and pagination](/api-reference/requests/list-requests) |
| `GET` | `/v1/forms/count` | [Count forms with optional grouping](/api-reference/requests/count-requests) |
| `POST` | `/v1/forms` | [Create a new form](/api-reference/requests/create-request) |
| `GET` | `/v1/forms/{id}` | [Get form details and responses](/api-reference/requests/get-request) |
| `PATCH` | `/v1/forms/{id}` | [Update form status or properties](/api-reference/requests/update-request) |
## Responses
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/responses/{id}` | [Get response details with attachments](/api-reference/responses/get-response) |
## Form Templates
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/form_templates` | [List available form templates](/api-reference/flows/list-flows) |
| `GET` | `/v1/form_templates/{slug}/options` | [Get template configuration options](/api-reference/flows/get-flow-options) |
| `GET` | `/v1/form_templates/{slug}/steps` | [Get template structure and fields](/api-reference/flows/get-flow-steps) |
## Cases
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/cases` | [List cases with filtering and pagination](/api-reference/cases/list-cases) |
| `GET` | `/v1/cases/count` | [Count cases](/api-reference/cases/count-cases) |
| `POST` | `/v1/cases` | [Create a new case](/api-reference/cases/create-case) |
| `GET` | `/v1/cases/{id}` | [Get case details with steps](/api-reference/cases/get-case) |
| `POST` | `/v1/cases/{id}/data` | [Update case data fields](/api-reference/cases/update-case-data) |
| `POST` | `/v1/cases/{id}/contacts` | [Update case contacts](/api-reference/cases/update-case-contacts) |
| `POST` | `/v1/cases/{id}` | [Change the status, archive or restore a case](/api-reference/cases/archive-case) |
| `POST` | `/v1/cases/{id}/start/{stepKey}` | [Start a case step](/api-reference/cases/start-case-step) |
## Tasks
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/cases/{id}/tasks` | [List the follow-up tasks of a case](/api-reference/tasks/list-case-tasks) |
| `POST` | `/v1/cases/{id}/tasks` | [Add a follow-up task to a case](/api-reference/tasks/create-case-task) |
| `PATCH` | `/v1/cases/{id}/tasks/{taskId}` | [Close, reopen or reassign a task](/api-reference/tasks/update-case-task) |
## Case Templates
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/case_templates` | [List case templates with filtering](/api-reference/case-templates/list-case-templates) |
| `GET` | `/v1/case_templates/{id}` | [Get case template details with steps](/api-reference/case-templates/get-case-template) |
## Attachments
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/attachments/{id}` | [Download single attachment](/api-reference/attachments/get-attachment) |
| `GET` | `/v1/attachments` | [Download multiple attachments as PDF](/api-reference/attachments/get-attachments-multiple) |
| `POST` | `/v1/attachments` | [Upload files (JSON or multipart)](/api-reference/attachments/upload-attachments) |
## Document Intelligence
| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/v1/document_intelligence` | [Create document extraction job](/api-reference/document-intelligence/create-document-intelligence) |
| `GET` | `/v1/document_intelligence/{id}` | [Get extraction results](/api-reference/document-intelligence/get-document-intelligence) |
## Signatures
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/signatures/{id}` | [Get signature metadata or download file](/api-reference/signatures/get-signature) |
## Workspaces
| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/workspaces` | [List accessible workspaces](/api-reference/workspaces/list-workspaces) |
| `POST` | `/v1/workspaces` | [Provision a workspace for a client (partners only)](/api-reference/workspaces/provision-workspace) |
## Members
| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/v1/members` | [Register a team member on a workspace](/api-reference/members/create-member) |
## Response Formats
Most endpoints return JSON responses by default. Some endpoints support multiple response formats:
### JSON Responses
* Default for most endpoints
* Set `Accept: application/json` header
### Binary Responses
* Attachments and signatures support `Accept: application/octet-stream`
* Returns file content for download
### PDF Responses
* Responses support `Accept: application/pdf`
* Returns rendered PDF of form response
## Authentication Requirements
All endpoints require authentication via Bearer token:
```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```
## Common Query Parameters
Most list endpoints support these query parameters:
* **`page[number]`** - Page number (starts at 1)
* **`page[size]`** - Items per page (default: 10, max: 100)
* **`filter`** - JSON string with filter criteria
* **`sort`** - Sort field (prefix with `-` for descending)
* **`group-by`** - Group counts by field (count endpoints only)
See [Pagination & Sorting](/api-reference/pagination-and-sorting) and [Advanced Filters](/api-reference/advanced-filters) for detailed documentation.
## HTTP Methods
| Method | Usage |
| - | - |
| `GET` | Retrieve data (list, read, count) |
| `POST` | Create new resources or perform actions |
| `PATCH` | Update existing resources |
## Base URL
All endpoints are relative to:
```text theme={null}
https://connect.penbox.io/v1
```
## Related Resources
Detailed guide to API capabilities
OAuth2 authentication guide
Filter with operators and JSON queries
Control result size and order
# Get File
Source: https://docs.penbox.io/api-reference/attachments/get-attachment
GET /attachments/{id}
Download or retrieve metadata for a specific attachment.
Download or retrieve metadata for a specific file (API: `attachment`).
In the API, uploaded files are referred to as **attachments**. This is the technical term used in all endpoints and parameters.
```javascript Download File (JS) theme={null}
const fileId = '670e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://connect.penbox.io/v1/attachments/${fileId}`,
{
headers: {
'Authorization': `Bearer ${accessToken}`,
'Accept': 'application/octet-stream'
}
}
);
const blob = await response.blob();
// Save or process the file
```
```javascript Get Metadata (JS) theme={null}
const fileId = '770e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://connect.penbox.io/v1/attachments/${fileId}`,
{
headers: {
'Authorization': `Bearer ${accessToken}`,
'Accept': 'application/json'
}
}
);
const metadata = await response.json();
console.log('Filename:', metadata.name);
console.log('Size:', metadata.metadata.size);
console.log('Type:', metadata.type);
```
```bash Download File (cURL) theme={null}
curl -X GET 'https://connect.penbox.io/v1/attachments/670e8400-e29b-41d4-a716-446655440000' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/octet-stream' \
--output downloaded-file.pdf
```
```bash Get Metadata (cURL) theme={null}
curl -X GET 'https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/json'
```
## Response Formats
The endpoint supports two response formats controlled by the `Accept` header:
| Format | Accept Header | Use Case |
| - | - | - |
| **Binary** | `application/octet-stream` | Download the actual file |
| **JSON** | `application/json` | Get metadata and Base64 data (for files \< 50MB) |
### JSON Response
When using `Accept: application/json`, you'll receive:
```json theme={null}
{
"id": "770e8400-e29b-41d4-a716-446655440000",
"name": "passport.pdf",
"type": "application/pdf",
"metadata": {
"size": 245678,
"width": null,
"height": null
},
"uri": "https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000",
"data": "JVBERi0xLjQKJeLjz9MKJSVJU0lTIEREREVfUGRmLVY3LjEg..."
}
```
| Field | Type | Description |
| - | - | - |
| `id` | string | File UUID |
| `name` | string | Original filename |
| `type` | string | MIME type (e.g., `application/pdf`, `image/jpeg`) |
| `metadata.size` | number | File size in bytes |
| `metadata.width` | number | Image width in pixels (null for non-images) |
| `metadata.height` | number | Image height in pixels (null for non-images) |
| `uri` | string | Direct download URL |
| `data` | string | Base64-encoded file data (only for files \< 50MB) |
Files larger than 50MB cannot be retrieved as JSON. Use `Accept: application/octet-stream` to download large files.
## Bulk Download
Download multiple files as a single ZIP archive:
```bash theme={null}
curl -X GET 'https://connect.penbox.io/v1/attachments?ids=id1,id2,id3&filename=documents' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/octet-stream' \
--output documents.zip
```
### Query Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `ids` | string | Yes | Comma-separated list of file UUIDs |
| `filename` | string | No | Custom filename for the downloaded archive |
Multiple files are packaged as a ZIP archive for download.
## Finding File IDs
File IDs are included when you retrieve a form response:
```javascript theme={null}
// Get response with files
const { data, included } = await fetch(
`https://connect.penbox.io/v1/responses/${responseId}`,
{
headers: { 'Authorization': `Bearer ${accessToken}` }
}
).then(r => r.json());
// Extract file IDs from included resources
const files = included.filter(item => item.type === 'attachments');
for (const file of files) {
console.log('File ID:', file.id);
console.log('Filename:', file.attributes.name);
console.log('Size:', file.attributes.metadata.size);
// Download the file
await downloadFile(file.id, accessToken);
}
```
## Supported File Types
Penbox supports various file types:
| Category | MIME Types |
| - | - |
| **Documents** | `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| **Images** | `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml` |
| **Spreadsheets** | `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/csv` |
| **Archives** | `application/zip`, `application/x-rar-compressed`, `application/x-7z-compressed` |
| **Other** | `text/plain`, `application/json`, `application/xml` |
## Response Codes
| Code | Description |
| - | - |
| `200` | Success - File downloaded or metadata retrieved |
| `400` | Bad Request - Missing `ids` parameter (for bulk download) |
| `401` | Unauthorized - Invalid access token |
| `403` | Forbidden - No access to this file |
| `404` | Not Found - File doesn't exist |
| `413` | Payload Too Large - File too big for JSON response (use octet-stream) |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
Files are permanently stored and remain accessible even after the form is archived.
For large files (> 50MB), always use `Accept: application/octet-stream`. The JSON endpoint will return a 413 error for files exceeding this limit.
Downloaded files should be scanned for viruses before processing, especially in production environments.
# Get Multiple Attachments
Source: https://docs.penbox.io/api-reference/attachments/get-attachments-multiple
GET /attachments
Download multiple attachments as a single PDF file.
Download multiple attachments as a single PDF file.
## Query Parameters
Comma-separated list of attachment UUIDs
Custom filename for the downloaded PDF (without extension)
## Response
Returns a PDF file containing all requested attachments merged together.
**Content-Type:** `application/pdf`
## Response Codes
| Code | Description |
| - | - |
| `200` | Success - PDF generated |
| `400` | Bad Request - Missing or invalid ids parameter |
| `401` | Unauthorized - Invalid access token |
| `404` | Not Found - One or more attachments not found |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
This endpoint automatically merges multiple attachments into a single PDF document, which is useful for batch downloads or generating combined reports.
# Upload Attachment
Source: https://docs.penbox.io/api-reference/attachments/upload-attachments
POST /attachments
Upload one or more attachments. Supports both JSON (base64) and multipart/form-data formats.
Upload a single attachment to Penbox. Supports both JSON (base64) and multipart/form-data formats.
**Size limits.** Multipart uploads accept up to 10GB per file. JSON uploads accept a body of
20MB. That limit applies to the transmitted, base64-inflated payload, so roughly 15MB of file.
Downloads are limited to 50MB.
To store an uploaded document on a case field, follow
[Add a Document to a Case](/guides/upload-document-to-case) for the full sequence.
## Query Parameters
Workspace UUID. Optional for a token scoped to a single workspace. A token scoped to several
workspaces should name the target one — the first workspace of the token is used otherwise.
Note the bracket syntax: `?workspace[id]=`.
## Request Body (JSON)
For JSON uploads, send base64-encoded file data:
File name
Base64-encoded file content
MIME type (e.g., "application/pdf", "image/jpeg"). Optional - will be detected if not provided.
Not applied. Every upload is created with the same access rules: the workspace API token and
workspace admins can download the attachment. Use a step attachment if a contact or another member
needs access to the file.
## Request Body (Multipart)
For multipart uploads, use `multipart/form-data` with a file field.
## Response Structure
Returns a single attachment object:
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "document.pdf",
"type": "application/pdf",
"uri": "https://connect.penbox.io/v1/attachments/550e8400-e29b-41d4-a716-446655440000",
"metadata": {
"size": 1024
}
}
```
## Response Codes
| Code | Description |
| - | - |
| `201` | Created - File uploaded successfully |
| `400` | Bad Request - Invalid file data |
| `401` | Unauthorized - Invalid access token |
| `403` | Forbidden - No company scope in token |
| `413` | Payload Too Large - JSON body over 20MB, or multipart file over 10GB |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
Use multipart/form-data for large files. It is the only form that goes past 20MB, and it is
faster because nothing is base64-encoded. Keep the JSON form for small files.
# Authentication
Source: https://docs.penbox.io/api-reference/authentication
Authenticate API requests using Bearer tokens
The API uses **Bearer token authentication** for all requests. This simple and secure method requires you to include your API token in the `Authorization` header of every request.
## Getting Your API Token
### Step 1: Access API Settings
Navigate to your Penbox API settings page:
```text theme={null}
https://app.penbox.io/workspace/settings/api
```
### Step 2: Create a New Token
1. Click the **"Create API Token"** button
2. Give your token a descriptive name (e.g., "Production Integration", "Development", "Analytics Tool")
3. Select the workspace you want to authorize
4. Copy the generated token immediately
**Important:** Your API token will only be displayed once. Copy it immediately and store it securely. If you lose it, you'll need to generate a new token.
### Token Format
Your API token will look like this:
```text theme={null}
pnbx_1234567890abcdef1234567890abcdef1234567890abcdef
```
Tokens always start with the `pnbx_` prefix.
Building an integration that several Penbox workspaces authorize themselves? An [OAuth 2.0 flow](/api-reference/authentication-oauth2) with a client ID and client secret is available as an Enterprise feature. It is not the recommended method: a personal API token is simpler for most integrations.
## Using Your API Token
Include your API token in the `Authorization` header of every API request using the Bearer scheme:
```bash theme={null}
Authorization: Bearer pnbx_1234567890abcdef1234567890abcdef1234567890abcdef
```
### Example Requests
```bash cURL theme={null}
curl -X GET 'https://connect.penbox.io/v1/workspaces' \
-H 'Authorization: Bearer pnbx_1234567890abcdef1234567890abcdef1234567890abcdef'
```
```javascript JavaScript theme={null}
const response = await fetch('https://connect.penbox.io/v1/cases', {
headers: {
'Authorization': `Bearer ${apiToken}`
}
});
const forms = await response.json();
```
```python Python theme={null}
import requests
headers = {
'Authorization': f'Bearer {api_token}'
}
response = requests.get(
'https://connect.penbox.io/v1/forms',
headers=headers
)
forms = response.json()
```
```php PHP theme={null}
### Making Authenticated Requests
Every API endpoint requires authentication. Here's an example creating a form request:
```javascript theme={null}
const apiToken = 'pnbx_1234567890abcdef1234567890abcdef1234567890abcdef';
const response = await fetch('https://connect.penbox.io/v1/forms', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
flow: { slug: 'client-onboarding' },
user: {
email: 'client@example.com',
given_name: 'John',
family_name: 'Doe'
}
})
});
const form = await response.json();
console.log('Form created:', form.id);
```
## Token Scopes and Permissions
Each API token is associated with a specific workspace. The token will have access to:
* All forms in the workspace
* All cases in the workspace
* All form templates enabled for the workspace
* All files and attachments in the workspace
* Document intelligence features for the workspace
Tokens are workspace-specific. If you need to access multiple workspaces, create a separate token for each one.
## Token Security
### Best Practices
* Never commit tokens to version control (Git, SVN, etc.)
* Store tokens in environment variables or secure credential management systems
* Use secrets management services (AWS Secrets Manager, HashiCorp Vault, etc.)
* Never expose tokens in client-side code or browser JavaScript
Store your API token in environment variables:
```bash .env theme={null}
PENBOX_API_TOKEN=pnbx_1234567890abcdef1234567890abcdef1234567890abcdef
```
Then load it in your application:
```javascript theme={null}
const apiToken = process.env.PENBOX_API_TOKEN;
```
* Rotate tokens periodically for enhanced security
* Create a new token before revoking the old one to avoid downtime
* Update all applications using the old token
* Revoke the old token once migration is complete
Give your tokens meaningful names to track usage:
* ✅ "Production API - CRM Integration"
* ✅ "Development Environment"
* ✅ "Analytics Dashboard"
* ❌ "Token 1", "Test", "My Token"
* Track which applications use which tokens
* Monitor for unexpected API usage patterns
* Set up alerts for unusual activity
* Revoke tokens immediately if compromised
### What NOT to Do
**Never:**
* Commit tokens to Git repositories
* Share tokens via email, chat, or screenshots
* Store tokens in plain text files
* Use the same token across multiple environments
* Hardcode tokens in your source code
* Post tokens in public forums or documentation
## Managing Tokens
### Viewing Active Tokens
Visit [app.penbox.io/workspace/settings/api](https://app.penbox.io/workspace/settings/api) to see all your active API tokens:
* Token name
* Creation date
* Last used date
* Associated workspace
### Revoking Tokens
To revoke a token:
1. Go to [app.penbox.io/workspace/settings/api](https://app.penbox.io/workspace/settings/api)
2. Find the token you want to revoke
3. Click the **"Revoke"** button
4. Confirm the action
Once revoked, a token is immediately invalidated. All API requests using that token will fail with a `401 Unauthorized` error.
### Token Lifecycle
```mermaid theme={null}
graph LR
A[Create Token] --> B[Use Token]
B --> C{Still Needed?}
C -->|Yes| B
C -->|No| D[Revoke Token]
C -->|Rotate| E[Create New Token]
E --> F[Update Applications]
F --> D
```
## Authentication Errors
### Common Error Responses
#### 401 Unauthorized - Missing Token
```json theme={null}
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Missing authorization header"
}
```
**Cause:** The `Authorization` header is missing from your request.
**Solution:** Add the `Authorization` header with your Bearer token.
#### 401 Unauthorized - Invalid Token
```json theme={null}
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid token"
}
```
**Cause:** The token is invalid, expired, or has been revoked.
**Solution:** Check your token is correct, or create a new token if it was revoked.
#### 403 Forbidden - No Access
```json theme={null}
{
"statusCode": 403,
"error": "Forbidden",
"message": "No access to this resource"
}
```
**Cause:** Your token doesn't have access to the requested resource (e.g., wrong workspace).
**Solution:** Verify you're using the correct token for the workspace you're trying to access.
### Debugging Authentication Issues
If you're experiencing authentication issues:
1. **Verify the token format**
* Token should start with `pnbx_`
* No extra spaces or newlines
* Complete token copied
2. **Check the Authorization header**
```bash theme={null}
Authorization: Bearer pnbx_your_token_here
```
* Includes "Bearer " prefix with a space
* Token immediately after the space
3. **Verify token is active**
* Check [app.penbox.io/workspace/settings/api](https://app.penbox.io/workspace/settings/api)
* Ensure token hasn't been revoked
* Confirm token exists in the list
4. **Test with cURL**
```bash theme={null}
curl -v -X GET 'https://connect.penbox.io/v1/workspaces' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
The `-v` flag shows detailed request/response information.
## Rate Limiting
API tokens are subject to rate limiting to ensure fair usage and system stability.
### Rate Limit Exceeded
If you exceed the rate limit, you'll receive a `429 Too Many Requests` response:
```json theme={null}
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please try again later.",
"retryAfter": 60
}
```
### Best Practices for Rate Limiting
* Cache responses when possible
* Implement exponential backoff on errors
* Monitor your usage patterns
* Spread requests over time instead of bursting
* Use webhooks instead of polling when possible
## Testing Your Authentication
### Quick Test
Test your token with a simple request to list workspaces:
```bash theme={null}
curl -X GET 'https://connect.penbox.io/v1/workspaces' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Expected response (success):**
```json theme={null}
{
"data": [
{
"id": "...",
"slug": "my-workspace",
"name": "My Workspace"
}
]
}
```
**Error response (invalid token):**
```json theme={null}
{
"statusCode": 401,
"error": "Unauthorized"
}
```
### Integration Checklist
Before deploying to production:
* [ ] Token stored securely (environment variable or secrets manager)
* [ ] Authorization header correctly formatted
* [ ] Error handling implemented for 401/403 responses
* [ ] Rate limiting handled with backoff strategy
* [ ] Token name clearly identifies the integration
* [ ] Monitoring/logging in place for API usage
* [ ] Token rotation plan documented
## Multiple Environments
For different environments, create separate tokens:
### Development
```bash theme={null}
PENBOX_API_TOKEN_DEV=pnbx_dev_token_here
```
### Staging
```bash theme={null}
PENBOX_API_TOKEN_STAGING=pnbx_staging_token_here
```
### Production
```bash theme={null}
PENBOX_API_TOKEN_PROD=pnbx_production_token_here
```
Then load the appropriate token based on your environment:
```javascript theme={null}
const apiToken = process.env.NODE_ENV === 'production'
? process.env.PENBOX_API_TOKEN_PROD
: process.env.PENBOX_API_TOKEN_DEV;
```
## Next Steps
Learn how to create forms
Retrieve your authorized workspaces
Complete API capabilities guide
Browse all available endpoints
## Support
If you encounter issues with authentication:
1. Check this documentation for troubleshooting steps
2. Verify your token at [app.penbox.io/workspace/settings/api](https://app.penbox.io/workspace/settings/api)
3. Test with the cURL examples above
4. Contact support at [support@penbox.io](mailto:support@penbox.io) with:
* Token name (never send the actual token)
* Error messages received
* API endpoint being called
* Request timestamp
# OAuth 2.0
Source: https://docs.penbox.io/api-reference/authentication-oauth2
Authenticate on behalf of Penbox workspaces with OAuth 2.0, using a client ID and client secret
**This is not the recommended way to authenticate.** For most integrations, use a [personal API token](/api-reference/authentication): it is simpler and needs no setup on our side. Choose OAuth 2.0 only if you need each workspace to authorize your application itself.
**Enterprise feature.** OAuth 2.0 is available on the Enterprise plan. Contact your Penbox account manager to enable it.
Use OAuth 2.0 when you build an **integration used by several Penbox workspaces** (a partner platform, a marketplace app). Each workspace admin authorizes your application once, and you receive a Bearer token for that workspace, without ever handling a personal API token.
OAuth 2.0 clients are provisioned by Penbox. There is no self-service screen to create one yet. Contact [support@penbox.io](mailto:support@penbox.io) with your application name, logo, website and the HTTPS redirect URI(s) you will use. You receive a `client_id` and a `client_secret` in return.
## How it works
Penbox supports the **Authorization Code** flow, with refresh tokens.
```mermaid theme={null}
sequenceDiagram
participant U as Workspace admin
participant A as Your application
participant P as Penbox (connect.penbox.io)
A->>U: Redirect to /authorize
U->>P: Sign in and pick a workspace
P->>A: Redirect to your redirect_uri with ?code=...
A->>P: POST /token (code + client_id + client_secret)
P->>A: access_token + refresh_token
A->>P: API calls with Authorization: Bearer access_token
```
The `client_secret` must stay on your server. Never ship it in a browser app or a mobile app.
## Endpoints
| Environment | Base URL |
| - | - |
| Production | `https://connect.penbox.io` |
| Staging | `https://connect.aiboov.com` |
The authorization and token endpoints live at the root of the host, not under `/v1`. The server metadata is published at `/.well-known/openid-configuration`.
## Step 1: Send the user to Penbox
Redirect the user's browser to `/authorize`:
```text theme={null}
https://connect.penbox.io/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fpenbox%2Fcallback
&response_type=code
&state=RANDOM_VALUE
```
| Parameter | Required | Description |
| - | - | - |
| `client_id` | Yes | The client ID Penbox gave you. |
| `redirect_uri` | Yes | Must use `https://` and match one of the URIs registered for your client. It cannot contain `code`, `state`, `error` or `error_description` query parameters. |
| `response_type` | Yes | Use `code`. |
| `state` | Recommended | An opaque value returned unchanged to your redirect URI. Use it to prevent CSRF. |
| `scope` | No | Defaults to `offline_access`, which returns a refresh token. |
The user signs in, selects the workspace to authorize, and approves your application.
## Step 2: Receive the authorization code
Penbox redirects the user back to your `redirect_uri`:
```text theme={null}
https://app.example.com/penbox/callback?code=AUTHORIZATION_CODE&state=RANDOM_VALUE
```
Check that `state` matches what you sent. If something went wrong, the redirect carries `error` and `error_description` instead of `code`.
## Step 3: Exchange the code for tokens
Call `POST /token` from your server with your credentials:
```bash cURL theme={null}
curl -X POST 'https://connect.penbox.io/token' \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "authorization_code",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "https://app.example.com/penbox/callback",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://connect.penbox.io/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code,
redirect_uri: 'https://app.example.com/penbox/callback',
client_id: process.env.PENBOX_CLIENT_ID,
client_secret: process.env.PENBOX_CLIENT_SECRET
})
});
const tokens = await response.json();
```
The body can be JSON or `application/x-www-form-urlencoded`. Instead of the body, you can also send the credentials with HTTP Basic authentication (`Authorization: Basic base64(client_id:client_secret)`).
If you sent a `redirect_uri` in step 1, send the same value here.
**Response:**
```json theme={null}
{
"access_token": "eyJhbGciOi...",
"id_token": "eyJhbGciOi...",
"refresh_token": "d41f...",
"token_type": "Bearer",
"expiresIn": 86400
}
```
| Field | Description |
| - | - |
| `access_token` | The Bearer token for API calls. Valid for 24 hours (`expiresIn`, in seconds). It is scoped to the workspace the user selected. |
| `refresh_token` | Returned when the `offline_access` scope was granted (the default). Use it to get a new access token. |
| `id_token` | Basic profile of the user who authorized (name, email, locale). |
## Step 4: Call the API
Use the access token exactly like a personal API token:
```bash theme={null}
curl -X GET 'https://connect.penbox.io/v1/cases' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
## Refreshing the access token
Before the access token expires, request a new one:
```bash theme={null}
curl -X POST 'https://connect.penbox.io/token' \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "refresh_token",
"refresh_token": "REFRESH_TOKEN",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}'
```
The response contains a new `access_token`. The refresh token stays the same, so keep storing it.
If the refresh token is rejected (`400`), send the workspace admin through the authorization flow again.
## Errors
| Status | Cause |
| - | - |
| `401` | Missing or invalid `client_id` / `client_secret`, unknown or invalid `code`, `redirect_uri` that differs from the one used in step 1, or unsupported `grant_type`. |
| `400` | Malformed request, or invalidated refresh token. |
At the `/authorize` step, errors are sent back to your `redirect_uri` as `error` and `error_description`. If the `redirect_uri` itself is invalid, the error is shown to the user instead of redirecting.
## Security checklist
* Store `client_secret` and refresh tokens in a secrets manager, never in source control or client-side code.
* Always send and verify `state`.
* Register exact HTTPS redirect URIs.
* Keep one access token and one refresh token per authorized workspace.
* Ask Penbox to rotate your `client_secret` if it may have leaked.
## Next steps
Use a personal API token for your own workspace
HTTP status codes returned by the API
# Get Case Template
Source: https://docs.penbox.io/api-reference/case-templates/get-case-template
GET /case_templates/{id}
Retrieve complete details of a specific case template including its steps and schema.
Retrieve complete details of a specific case template including its steps and schema.
This endpoint returns the full template structure including all configured steps and data schema fields. Use this to understand what a template workflow looks like before creating cases from it.
## Response Details
The response includes:
* **Basic template information**: title, description, reference, etc.
* **Steps**: The complete workflow steps configuration
* **Schema**: Data fields and their types that cases created from this template will have
* **Contacts**: Contact roles configured in the template
* **Statuses**: The custom statuses configured in the template, each with its `key`, human-readable `label` and `parent_status`
Cases created from this template inherit these statuses and return them in their own `statuses` array, so resolving a case status key into a label does not require fetching the template.
# List Case Templates
Source: https://docs.penbox.io/api-reference/case-templates/list-case-templates
GET /case_templates
Retrieve a paginated list of case templates (template workflows) with optional filtering and sorting. Case templates are reusable workflow blueprints.
Retrieve a paginated list of case templates with optional filtering and sorting.
Case templates are reusable workflow blueprints that can be instantiated into actual cases.
Use the `title` filter to search for templates by name with case-insensitive partial matching. This makes it easy to find the right template quickly.
## Common Use Cases
* List all available case templates in a workspace
* Search for templates by title
* Filter templates by owner or workspace
* Find archived vs active templates
* Review the statuses configured on each template through the `statuses` array
# Apply Case Input
Source: https://docs.penbox.io/api-reference/cases/apply-case-input
POST /cases/{id}/inputs/{input_id}/apply
Review a `suggest` input: accept some rows, optionally with an edited value, and reject the rest. Deterministic, no AI call, applied from the stored record.
- An accepted row is written whatever the fill setting says: a human validated it.
- A row whose field changed on the case since the proposal comes back `skipped` with `reason: value_changed`, so an old proposal never overwrites a newer value.
- Idempotent: rows already applied or rejected are returned unchanged. An unknown row id is a 400.
- `reject_others` (default `true`) rejects every row you did not list. Pass `false` to keep them proposed for a later call.
- A `document` row is filed at apply time. Pass `key` to file an `unclassified` document, or to send a classified one to another field. Document Intelligence runs after this response, so re-read the case a moment later when a row comes back with `"intelligence": "pending"`.
Review an input created in `suggest` mode: accept some rows, optionally with an edited value, and reject the rest.
A `document` row is filed at apply time. Pass `key` on the row to choose the file field. Use it
to file a document that came back `unclassified`, or to send a classified one to another field.
The key must be a file field of the case, else the call is a 400.
```json Filing a document on apply theme={null}
{
"changes": [
{ "id": "c1" },
{ "id": "c7", "key": "photos" }
]
}
```
Document Intelligence runs after this response, and only when the target field has a Document
Intelligence template on the case. A row that comes back with `"intelligence": "pending"` means
values read from the file will land on the case shortly: re-read `GET /cases/{id}` a moment
later. Document Intelligence is billed per page.
# Update Case
Source: https://docs.penbox.io/api-reference/cases/archive-case
POST /cases/{id}
Move a case to another status, archive it, or restore it
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](/api-reference/cases/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`.
```bash Move the case forward theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "status": "in_progress" }'
```
```bash Close the case theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "status": "closed" }'
```
```bash Archive theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "archived": true }'
```
```bash Unarchive theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "archived": false }'
```
```json 200 theme={null}
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Onboarding - Acme Corp",
"status": "in_progress",
"status_label": "In Progress",
"parent_status": "in_progress",
"archived_at": null
}
```
```json 422 theme={null}
{
"statusCode": 422,
"error": "Unprocessable Entity",
"message": "Invalid status \"done\". Valid statuses for this case: draft, pending, in_progress, closed, cancelled"
}
```
```json 400 theme={null}
{
"statusCode": 400,
"error": "Bad Request",
"message": "Cannot update a template"
}
```
# Count Cases
Source: https://docs.penbox.io/api-reference/cases/count-cases
GET /cases/count
Get the total count of cases matching your filter criteria.
Get the total count of cases matching your filter criteria.
This endpoint accepts the same filters as [List Cases](/api-reference/cases/list-cases), including the
free-text `contact[search]`, so a count always matches the list it belongs to:
```
GET /v1/cases/count?contact[search]=M%C3%A9lanie%20Hardy
```
# Create Case
Source: https://docs.penbox.io/api-reference/cases/create-case
POST /cases
Create a new case (workflow) with contacts and data schema.
Create a new case (workflow) with contacts and data schema.
Contacts are automatically created or linked if they already exist in the system based on their email address.
For an API token, `workspace.id` is **required** — it is never inferred from the token.
A case created through this endpoint is stamped `channel: "api"` and `actor_type: "system"`, with a null `creator`. These three fields are read-only: a value sent in the body is ignored.
```bash From a template theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"title": "Dupont vs. Acme",
"workspace": { "id": "" },
"template": { "id": "" },
"owner": { "email": "amina@firm.example" },
"contacts": [{ "key": "main", "email": "j.dupont@mail.example" }]
}'
```
# Create Case Input
Source: https://docs.penbox.io/api-reference/cases/create-case-input
POST /cases/{id}/inputs
Push raw material on a case (a call transcript, CRM notes, a chat thread, a parsed email as JSON) and let Penbox turn it into case data, the way an inbound email is read.
This is the front door for writing to a case. `data` covers `POST /cases/{id}/data`, `contacts` covers `POST /cases/{id}/contacts`, and `content` is what neither can take. Use the atomic routes when you already know exactly which key to write; use this route when you hold material Penbox should read, or when you want to know what was written **and what was refused**.
At least one of `content`, `data`, `contacts`, `documents` is required. A call carrying only `data` / `contacts` / `documents` with an explicit `key` runs no AI.
- `auto` mode (the default, configurable per case template) writes the values right away, within the case's Email Intelligence *fill* setting: by default an input fills empty fields and never overwrites a value the case already holds.
- `suggest` mode keeps every row as a proposal. Review it with `POST /cases/{id}/inputs/{input_id}/apply`.
Explicit values always win over what the AI reads. Values land on the case in a single write, so automations and Document Intelligence fire as they do for `POST /cases/{id}/data`; Document Intelligence runs after the response, so re-read the case a moment later if a file field with a template was written.
**Documents.** Send up to 5 files in `documents`. A file is either an attachment you already uploaded with `POST /attachments` (`{ "id": "…" }`), or an inline base64 file (`{ "name", "type", "data" }`). The whole request body must stay under 50 MB. Upload a big file with `POST /attachments` first and send its id: that route takes files up to 10 GB with multipart/form-data. Penbox classifies each file and files it on the right file field of the case. Classification is synchronous: the response tells you where every document went. Add `"key": ""` to a document to file it on that field yourself, without classification. `options.classify_documents: false` switches the classifier off: a document without a `key` comes back `unclassified` and stays unfiled on the workspace.
**Document Intelligence.** Filing a document can trigger Document Intelligence. It runs only when the target file field has a Document Intelligence template configured on the case, and it runs after the response. A document row with `"intelligence": "pending"` means values read from the file will land on the case shortly: re-read `GET /cases/{id}` a moment later. In `suggest` mode the file is uploaded but not filed, so Document Intelligence runs at apply time. Document Intelligence is billed per page. Classification is not billed separately.
Push raw material on a case and let Penbox read it into case data, the way an inbound email is read.
Use this route when you hold something Penbox should read: a call transcript, CRM notes, a chat thread, a parsed email. Use `POST /cases/{id}/data` when you already know exactly which key to write.
The response is the input resource: what Penbox proposed or wrote, row by row, and what it refused and why. The refreshed case is embedded under `case`.
Contacts sent in `contacts` are the caller's own word: the role is created when the
case does not declare it, an already-bound role is replaced, and the identity fields
you send override the ones on an existing contact. A contact the AI read is more
conservative: it fills a declared role, and only when that role is empty.
## New fields
The AI may add new fields to the case for information that matches no existing field. This is
controlled by `options.create_fields`. It defaults to the case setting, then `true`. Send
`false` to keep that information in `unmapped` instead.
This is how you fill a case created without a template. Post one input per message and the case
builds up as the conversation goes.
## Documents
Send files in `documents`, 5 at most per call. Each file is either an attachment you already
uploaded, or an inline base64 file.
```json Two ways to send a file theme={null}
"documents": [
{ "id": "6f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d" },
{ "name": "quote.pdf", "type": "application/pdf", "data": "JVBERi0xLjQK…" }
]
```
The whole request body must stay under 50 MB. For a big file, upload it first with
`POST /attachments`, then send its id here. That route takes files up to 10 GB.
Penbox reads each file and files it on the right file field of the case. This classification
happens during the request. The response tells you where every document went.
Add a `key` to a document to file it on that field yourself. The classifier is then skipped
for that file. The key must be a file field of the case, else the call is a 400 with the code
`not_file_field`.
```json Filed on an explicit field theme={null}
{ "name": "photo.jpg", "type": "image/jpeg", "data": "/9j/4AAQ…", "key": "photos" }
```
Set `options.classify_documents` to `false` to switch the classifier off. Documents without a
`key` then come back with the status `unclassified`. The file is uploaded and kept on the
workspace, but it is not filed on the case. You can file it later with
`POST /cases/{id}/inputs/{input_id}/apply`.
`intelligence.documents` says how the classification went: `succeeded`, `partial` (at least one
file could not be classified), `failed` (none could) or `skipped` (no file needed the
classifier). A file that fails classification comes back `unclassified`. The upload is never
lost.
A file the case already holds is not classified twice. Penbox matches on the attachment id, or
on name + size + type. When both sides carry a checksum and the checksums differ, it is not a
duplicate. The match runs against every file field of the case, not only the one the classifier
would have picked: a document already filed elsewhere must not land under a second field.
The row comes back `skipped`, with `reason: duplicate` and the `key` of the field that already
holds the file. A document sent with an explicit `key` skips this check: it is filed as you
asked.
```json A document row theme={null}
{
"id": "c5",
"kind": "document",
"key": "quote",
"label": "Quote",
"attachment": {
"id": "6f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
"name": "quote.pdf",
"size": 128413,
"type": "application/pdf"
},
"origin": "ai",
"status": "applied",
"intelligence": "pending"
}
```
## Document Intelligence
Filing a document can trigger Document Intelligence. It runs only when the target file field
has a Document Intelligence template configured on the case. It runs after the response, not
during the request.
A document row with `"intelligence": "pending"` means values read from the file will land on
the case shortly. Re-read `GET /cases/{id}` a moment later to see them. The change list of the
input never carries them.
In `suggest` mode the file is uploaded but not filed. Document Intelligence therefore runs
after the apply call, not after this one.
Document Intelligence is billed per page, exactly as it is on `POST /document_intelligence`.
Classification is not billed separately.
# Get Case
Source: https://docs.penbox.io/api-reference/cases/get-case
GET /cases/{id}
Retrieve complete details of a specific case including its steps and schema.
Retrieve complete details of a specific case including its steps and schema.
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.
# Get Case Input
Source: https://docs.penbox.io/api-reference/cases/get-case-input
GET /cases/{id}/inputs/{input_id}
One input, with its raw `content` and the current case. This is the "see the input" read.
One input, with the raw material it was created from.
A `document` row keeps the file it filed under `attachment`. A row still marked `unclassified`
has an uploaded file waiting for a field: file it with
`POST /cases/{id}/inputs/{input_id}/apply` and a `key`.
# List Case Inputs
Source: https://docs.penbox.io/api-reference/cases/list-case-inputs
GET /cases/{id}/inputs
The inputs of a case, newest first. The list drops `changes`, `unmapped` and `content`, and carries `changes_count` / `applied_count` instead.
The inputs of a case, newest first.
The list drops the change rows, so it does not tell you where a document was filed. Read one
input to see that.
# List Cases
Source: https://docs.penbox.io/api-reference/cases/list-cases
GET /cases
Retrieve a paginated list of cases (workflows) with optional filtering and sorting.
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:
```
GET /v1/cases?contact[search]=M%C3%A9lanie%20Hardy
```
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.
# Start Case Step
Source: https://docs.penbox.io/api-reference/cases/start-case-step
POST /cases/{id}/start/{stepKey}
Start (execute) a specific step in a case
This endpoint triggers the execution of a specific step within a case. When a step is started, it performs its configured actions such as:
* Sending email notifications to contacts or case owners
* Sending SMS notifications
* Creating and sending form requests
* Creating internal notes or tasks
* Triggering automations
## Notes
* You cannot start steps in template cases (is\_template: true)
* Starting a step may trigger automations configured for the case
* The step must be defined in the case's step configuration
* Some steps may have execution conditions that prevent them from running if not met
# Update Case Contacts
Source: https://docs.penbox.io/api-reference/cases/update-case-contacts
POST /cases/{id}/contacts
Replace the contacts for a specific case. This will replace all existing contacts with the provided contacts.
Add or modify contacts in a case.
# Update Case Data
Source: https://docs.penbox.io/api-reference/cases/update-case-data
POST /cases/{id}/data
Update multiple data fields in a case using a bulk operation.
Update multiple data fields in a case using a bulk operation.
To set a file field, upload the document first and save the reference it returns — see
[Add a Document to a Case](/guides/upload-document-to-case).
# Create Document Intelligence
Source: https://docs.penbox.io/api-reference/document-intelligence/create-document-intelligence
POST /document_intelligence
Extract structured data from documents using AI-powered document intelligence.
Extract structured data from documents using AI-powered document intelligence.
To use this feature, activation is required on your workspace. Please contact us for more
information.
## Request Body
Company reference (will use first workspace from token if ommited)
Company UUID
Array of attachments to process (minimum 1 attachment). Each attachment must use **either** the `id` field (reference existing) **OR** the `data` field (upload new).
Base64-encoded file content
File name (required when using `data`)
MIME type (required when using `data`, e.g., "application/pdf", "image/jpeg")
Existing attachment UUID
File name (optional when using `id`)
MIME type (optional when using `id`)
Exactly one of `fields` or `template` must be provided — not both.
Array of fields to extract from the documents. Mutually exclusive with `template`.
Field name to extract
Optional key for the field
Hint to help the AI extract the field (optional).
Can be used to specify the format of the field, for example: "DD/MM/YYYY" for a date field.
Field type: `text`, `number`, `date`, or `list`. Use `list` for repeating items; when `list`, provide a nested `fields` array defining the structure of each item.
Sub-field name to extract
Key for the sub-field (required for list items)
Hint to help the AI extract the sub-field
Sub-field type: `text`, `number`, or `date`
Reference to a document intelligence template. Mutually exclusive with `fields`.
Document intelligence template UUID
Optional language hint for document processing
Extraction quality level: `fast` or `advanced`. It sets both the model used and the credit cost per
page — `fast` costs 3 credits per page, `advanced` costs 6. Defaults to `advanced`.
Only valid together with `fields`. When you use a `template`, the level configured on that template
applies instead, and sending `level` alongside `template` is rejected.
The document intelligence processing may take a few seconds. The response includes the extracted
results in the `results` field once processing is complete.
Use the `hint` field to help the AI extract the field. For example, if the field is a date, you
can use the `hint` field to specify the format of the date. For example: "DD/MM/YYYY".
You can reference existing attachments by their UUID instead of uploading new ones, which is more
efficient if the documents are already in the system.
# Get Document Intelligence
Source: https://docs.penbox.io/api-reference/document-intelligence/get-document-intelligence
GET /document_intelligence/{id}
Retrieve the results of a document intelligence extraction job.
Retrieve the results of a document intelligence extraction job.
The `results` object contains the extracted field values with the same keys you specified when creating the job. Values are automatically typed based on the field type (text, number, or date).
# Error Codes
Source: https://docs.penbox.io/api-reference/error-codes
Complete reference of the HTTP status codes returned by the Penbox API and how to handle them
The Penbox API uses conventional HTTP status codes to indicate the success or
failure of a request. The same set of codes applies consistently across **all
endpoints** — creating a Case behaves the same way as any other call.
## Success codes
| Code | Name | Description |
| - | - | - |
| **200** | `OK` | The request succeeded. Returned for reads, updates, **and for creating a Case** (`POST /cases`). |
| **201** | `Created` | A resource was created successfully (e.g. attachment upload, document intelligence). |
| **202** | `Accepted` | The request was accepted and will be processed asynchronously (e.g. webhooks / events). |
## Client error codes (4xx)
| Code | Name | Description |
| - | - | - |
| **400** | `Bad Request` | The request is invalid: a required field is missing, the JSON is malformed, a UUID or email is invalid, a schema value is incorrect, or a referenced template/owner could not be found. |
| **401** | `Unauthorized` | Authentication failed: the `Authorization` header is missing, or the token/JWT is invalid or expired. |
| **403** | `Forbidden` | Authenticated but not allowed: the token does not have access to the requested workspace or resource. |
| **404** | `Not Found` | The resource does not exist (unknown id for a case, template, workspace, form…) or the endpoint does not exist. |
| **409** | `Conflict` | The request conflicts with the current state of the resource (e.g. a step already started, a duplicate). |
| **413** | `Payload Too Large` | The request body is too large (e.g. a file upload exceeding the size limit). |
| **422** | `Unprocessable Entity` | The request is well-formed but fails a business validation rule. |
## Server error codes (5xx)
| Code | Name | Description |
| - | - | - |
| **500** | `Internal Server Error` | An unexpected error occurred on our side. |
| **502** | `Bad Gateway` | A backend service is unreachable or returned an error. |
| **503** | `Service Unavailable` | The service is temporarily unavailable (infrastructure level). |
| **504** | `Gateway Timeout` | The request took too long to complete (timeout ≈ 30 s). |
**`429 Too Many Requests`** is not produced by the application itself, but may be returned by the
network / gateway layer if rate limiting is in effect.
## Error response body
All error responses share the same JSON structure:
```json theme={null}
{
"statusCode": 400,
"error": "Bad Request",
"message": "A human-readable description of the error",
"errors": [
{
"message": "validation detail",
"path": ["field"],
"type": "..."
}
]
}
```
| Field | Description |
| - | - |
| `statusCode` | The HTTP status code, repeated in the body for convenience. |
| `error` | The official HTTP status name (e.g. `Bad Request`). |
| `message` | A human-readable description of what went wrong. |
| `errors` | Present only for validation errors (`400`). An array detailing each invalid field. |
When handling errors programmatically, branch on the HTTP `statusCode` rather than parsing the
`message`, which is meant for humans and may change.
# Get Form Template Options
Source: https://docs.penbox.io/api-reference/flows/get-flow-options
GET /form_templates/{slug}/options
Retrieve the configuration options for a specific form template.
Retrieve the configuration options for a specific form template.
The exact structure of the options object depends on the form template configuration. Different form templates may have different available options.
# Get Form Template Steps
Source: https://docs.penbox.io/api-reference/flows/get-flow-steps
GET /form_templates/{slug}/steps
Retrieve the form steps/structure for a specific form template.
Retrieve the form steps/structure for a specific form template.
Use this endpoint to understand the structure of a form template before creating forms, or to build a custom form UI.
# List Form Templates
Source: https://docs.penbox.io/api-reference/flows/list-flows
GET /form_templates
Retrieve a paginated list of form templates available in the authorized workspaces.
Retrieve all active form templates available in the authorized workspaces.
Only **enabled** and **published** templates are returned by this endpoint. Archived or disabled templates require the `?archived=true` query parameter.
Cache template information to improve performance. Template configurations don't change frequently, so you can refresh this data periodically (e.g., hourly or daily).
Template slugs can be reused across different workspaces. Always combine the template slug with the workspace slug when storing or referencing templates in your system.
# Introduction
Source: https://docs.penbox.io/api-reference/introduction
Get started with the Penbox API
Welcome to the Penbox API documentation. Build powerful integrations for form management, workflow automation, and document processing.
## Quick Start
Login to [app.penbox.io/workspace/settings/api](https://app.penbox.io/workspace/settings/api) and create a new API token.
[Learn about Authentication →](/api-reference/authentication)
Use your token to authenticate API requests:
```bash theme={null}
curl https://connect.penbox.io/v1/workspaces \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
Browse available endpoints and try them in the interactive documentation.
## API Essentials
**Base URL:** `https://connect.penbox.io/v1`
**Authentication:** All requests require a Bearer token in the `Authorization` header.
**Rate Limits:**
* 100 requests per minute per token
* 1,000 requests per hour per client
## Available Resources
List authorized workspaces
Create and manage workflow cases with steps
Reusable workflow blueprints for creating cases
Create and manage forms, responses, and templates
Upload and download attachments
Extract structured data from documents using AI
Download and manage digital signatures
## Developer Guides
Complete guide to API capabilities and best practices
Quick reference of all available endpoints
OAuth2 authentication and token management
Powerful filtering with operators and JSON queries
Control result size and order
## Need Help?
* **Documentation**: Browse the detailed guides above
* **Support**: [support@penbox.io](mailto:support@penbox.io)
* **Status**: status.penbox.io
# Create Member
Source: https://docs.penbox.io/api-reference/members/create-member
POST /members
Register a member of your client's team on a workspace
Register a member of your client's team on a workspace. Cases then resolve that person as an owner or an assignee, instead of mistaking the team for contacts.
Members created through the API are always **silent**: Penbox never emails them, and the flag cannot be overridden from the payload. A partner can never create a member Penbox would contact.
## Idempotency
The call is idempotent on the pair (`workspace.id`, `email`): re-posting a member who already exists returns that member with a `200` instead of failing on the uniqueness constraint. A `201` means the member was created.
Emails are lowercased and trimmed before the lookup, so `Jane@Acme.com` and `jane@acme.com` are the same member.
## Roles
| Field | Default | Meaning |
| - | - | - |
| `is_handler` | `true` | Can be set as the owner or an assignee of a case |
| `is_admin` | `false` | Can administer the workspace and its settings |
`workspace.id` is always explicit — it is never inferred from the token. A token that does not cover the workspace returns a `404`.
# Pagination and Sorting
Source: https://docs.penbox.io/api-reference/pagination-and-sorting
Control result size and order with pagination and sorting parameters
The Penbox API provides pagination and sorting capabilities on all list endpoints to help you manage large datasets and control the order of results.
## Pagination
All list endpoints support pagination to manage large result sets efficiently.
### Basic Usage
```javascript theme={null}
// Method 1: Direct parameters
const params = new URLSearchParams({
'page[number]': '1',
'page[size]': '50',
'workspace[slug]': 'acme-corp'
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
// Method 2: With JSON filter
const params = new URLSearchParams({
'filter': JSON.stringify({
attributes: { status: { $eq: 'pending' } }
}),
'page[number]': '1',
'page[size]': '50'
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
```
### Pagination Parameters
| Parameter | Type | Default | Max | Description |
| - | - | - | - | - |
| `page[number]` | integer | 1 | - | Page number (starts at 1) |
| `page[size]` | integer | 10 | 100 | Number of results per page |
The maximum `page[size]` is **100**. If you need to retrieve more results, use multiple paginated requests.
### Response Format
All paginated endpoints return results in the same format:
```json theme={null}
{
"meta": {
"total_count": 150,
"total_pages": 15,
"page_size": 10,
"current_page": 1
},
"data": [
{ "id": "abc-123", "title": "Case 1", "created_at": "2024-01-15T10:00:00Z" },
{ "id": "def-456", "title": "Case 2", "created_at": "2024-01-14T09:30:00Z" }
]
}
```
**Response Fields:**
| Field | Type | Description |
| - | - | - |
| `meta.total_count` | integer | Total number of results matching your filters |
| `meta.total_pages` | integer | Total number of pages available |
| `meta.page_size` | integer | Number of results per page |
| `meta.current_page` | integer | Current page number |
| `data` | array | Array of resource objects |
### Pagination Examples
#### Iterating Through Pages
```javascript theme={null}
async function getAllCases(workspaceSlug) {
const allCases = [];
let currentPage = 1;
let hasMorePages = true;
while (hasMorePages) {
const params = new URLSearchParams({
'workspace[slug]': workspaceSlug,
'page[number]': currentPage.toString(),
'page[size]': '100' // Max page size for efficiency
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const result = await response.json();
allCases.push(...result.data);
// Check if there are more pages
hasMorePages = currentPage < result.meta.total_pages;
currentPage++;
}
return allCases;
}
```
#### Loading a Specific Page
```javascript theme={null}
async function getCasesPage(pageNumber, pageSize = 25) {
const params = new URLSearchParams({
'page[number]': pageNumber.toString(),
'page[size]': pageSize.toString(),
'archived': 'false'
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return await response.json();
}
```
#### Pagination with Filters
```javascript theme={null}
async function getPendingCasesPaginated(page = 1) {
const filter = {
attributes: {
parent_status: { $eq: 'pending' },
archived_at: { $eq: null }
}
};
const params = new URLSearchParams({
'filter': JSON.stringify(filter),
'page[number]': page.toString(),
'page[size]': '50'
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return await response.json();
}
```
## Sorting
Control the order of results with the `sort` parameter. Sorting works with both direct parameters and JSON filters.
### Basic Usage
```bash theme={null}
# Sort by creation date (descending - newest first)
GET /v1/cases?sort=-created_at
# Sort by title (ascending - A to Z)
GET /v1/case_templates?sort=title
# Combine with filters
GET /v1/cases?workspace[slug]=acme&sort=-updated_at
# Sort with pagination
GET /v1/forms?sort=-created_at&page[size]=50
```
### Sort Format
| Format | Description | Example |
| - | - | - |
| `sort=field_name` | Ascending order (A-Z, oldest-newest, low-high) | `sort=title` |
| `sort=-field_name` | Descending order (Z-A, newest-oldest, high-low) | `sort=-created_at` |
Prefix the field name with a minus sign (`-`) for descending order.
### Common Sort Fields by Endpoint
#### Cases (`/v1/cases`)
* `created_at` - Creation timestamp
* `updated_at` - Last update timestamp
* `title` - Case title
* `status` - Custom status value
* `parent_status` - Parent status
* `waiting_for` - Who the case is waiting for
* `reference` - Custom reference number
* `archived_at` - Archive timestamp
#### Case Templates (`/v1/case_templates`)
* `created_at` - Creation timestamp
* `updated_at` - Last update timestamp
* `title` - Template title
* `reference` - Custom reference
* `archived_at` - Archive timestamp
#### Forms (`/v1/forms`)
* `created_at` - Creation timestamp
* `updated_at` - Last update timestamp
* Various custom fields based on form template
#### Form Templates (`/v1/form_templates`)
* `created_at` - Creation timestamp
* `updated_at` - Last update timestamp
### Sorting Examples
#### Sort by Date
```javascript theme={null}
// Get newest cases first
const params = new URLSearchParams({
'sort': '-created_at',
'page[size]': '25'
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
```
#### Sort by Title
```javascript theme={null}
// Get case templates alphabetically
const params = new URLSearchParams({
'sort': 'title',
'archived': 'false'
});
const response = await fetch(
`https://connect.penbox.io/v1/case_templates?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
```
#### Sort with JSON Filter
```javascript theme={null}
// Get active cases sorted by last update
const filter = {
attributes: {
parent_status: { $eq: 'in_progress' },
archived_at: { $eq: null }
}
};
const params = new URLSearchParams({
'filter': JSON.stringify(filter),
'sort': '-updated_at'
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
```
#### Dynamic Sorting
```javascript theme={null}
function getCases(sortField, sortDirection = 'asc') {
const sortParam = sortDirection === 'desc'
? `-${sortField}`
: sortField;
const params = new URLSearchParams({
'sort': sortParam,
'page[size]': '50'
});
return fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
).then(r => r.json());
}
// Usage
const newestFirst = await getCases('created_at', 'desc');
const alphabetical = await getCases('title', 'asc');
```
## Combining Pagination and Sorting
Pagination and sorting work together seamlessly:
```javascript theme={null}
async function getCasesPaginatedAndSorted(options = {}) {
const {
page = 1,
pageSize = 25,
sortBy = 'created_at',
sortDirection = 'desc',
workspaceSlug = null
} = options;
const params = new URLSearchParams({
'page[number]': page.toString(),
'page[size]': pageSize.toString(),
'sort': sortDirection === 'desc' ? `-${sortBy}` : sortBy
});
if (workspaceSlug) {
params.set('workspace[slug]', workspaceSlug);
}
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return await response.json();
}
// Usage examples
const firstPage = await getCasesPaginatedAndSorted({
page: 1,
pageSize: 50,
sortBy: 'title',
sortDirection: 'asc'
});
const recentUpdates = await getCasesPaginatedAndSorted({
page: 1,
sortBy: 'updated_at',
sortDirection: 'desc',
workspaceSlug: 'acme-corp'
});
```
## Best Practices
* Use larger page sizes (50-100) for batch processing
* Use smaller page sizes (10-25) for UI display
* Consider network latency and processing time
Never assume a dataset is small. Always implement pagination to avoid:
* API timeouts
* Memory issues
* Poor user experience
Sorting by `created_at` or `updated_at` is typically faster than custom fields. Use these when possible for better performance.
If sorting by the same field repeatedly, consider caching the results to reduce API calls.
Always check if the `data` array is empty:
```javascript theme={null}
const result = await response.json();
if (result.data.length === 0) {
console.log('No results found');
}
```
Show users how many total results exist:
```javascript theme={null}
const { meta, data } = await response.json();
console.log(`Showing ${data.length} of ${meta.total_count} results`);
```
## Complete Example: Data Table
Here's a complete example of implementing a paginated, sortable data table:
```javascript theme={null}
class CasesTable {
constructor(token, workspaceSlug) {
this.token = token;
this.workspaceSlug = workspaceSlug;
this.currentPage = 1;
this.pageSize = 25;
this.sortBy = 'created_at';
this.sortDirection = 'desc';
}
async fetchCases() {
const params = new URLSearchParams({
'workspace[slug]': this.workspaceSlug,
'page[number]': this.currentPage.toString(),
'page[size]': this.pageSize.toString(),
'sort': this.sortDirection === 'desc'
? `-${this.sortBy}`
: this.sortBy
});
const response = await fetch(
`https://connect.penbox.io/v1/cases?${params}`,
{ headers: { 'Authorization': `Bearer ${this.token}` } }
);
return await response.json();
}
async goToPage(pageNumber) {
this.currentPage = pageNumber;
return await this.fetchCases();
}
async nextPage() {
this.currentPage++;
return await this.fetchCases();
}
async previousPage() {
if (this.currentPage > 1) {
this.currentPage--;
}
return await this.fetchCases();
}
async sortBy(field, direction = 'asc') {
this.sortBy = field;
this.sortDirection = direction;
this.currentPage = 1; // Reset to first page when sorting
return await this.fetchCases();
}
async changePageSize(size) {
this.pageSize = Math.min(size, 100); // Enforce max
this.currentPage = 1; // Reset to first page
return await this.fetchCases();
}
}
// Usage
const table = new CasesTable(accessToken, 'acme-corp');
// Initial load
const firstPage = await table.fetchCases();
console.log(`Showing ${firstPage.data.length} of ${firstPage.meta.total_count} cases`);
// Navigate
await table.nextPage();
await table.goToPage(5);
// Sort
await table.sortBy('title', 'asc');
await table.sortBy('updated_at', 'desc');
// Change page size
await table.changePageSize(50);
```
## Next Steps
Learn how to filter results with operators
Apply pagination to the Cases endpoint
Paginate and sort forms
See all available sort fields
# API Overview
Source: https://docs.penbox.io/api-reference/pen-connect-overview
Complete guide to the Penbox API endpoints and capabilities
The Penbox API provides programmatic access to Penbox's form management, case management, and document processing capabilities. This comprehensive guide covers all API capabilities, response formats, and best practices.
Start with the Quick Start guide to make your first API call
## API Categories
### Cases
Manage multi-step workflows with contacts and structured data.
**Key Endpoints:**
* `GET /cases` - List cases with filtering
* `POST /cases` - Create a new case
* `GET /cases/{id}` - Get case details with steps
* `POST /cases/{id}/data` - Update case data fields
* `POST /cases/{id}` - Archive or unarchive a case
* `GET /cases/count` - Count cases
**Common Use Cases:**
* Create structured workflows for customer onboarding, support tickets, etc.
* Track case progress through multiple steps
* Manage contacts associated with cases
* Update case data programmatically
### Forms
Manage forms and responses.
**Key Endpoints:**
* `GET /forms` - List forms with filtering and pagination
* `POST /forms` - Create a new form
* `GET /forms/{id}` - Get form details including responses
* `PATCH /forms/{id}` - Update form status or properties
* `GET /forms/count` - Count forms with optional grouping
* `GET /responses/{id}` - Get response details
**Common Use Cases:**
* Send forms to customers or partners
* Track form completion status
* Archive or process completed forms
* Retrieve form responses with attachments
### Form Templates
Access and configure form templates and their customizations.
**Key Endpoints:**
* `GET /form_templates` - List available form templates
* `GET /form_templates/{slug}/options` - Get template configuration options
* `GET /form_templates/{slug}/steps` - Get template structure and fields
**Common Use Cases:**
* Discover available form templates
* Understand form structure before creating forms
* Access template-specific settings
### Attachments
Upload, download, and manage file attachments.
**Key Endpoints:**
* `POST /attachments` - Upload files (JSON or multipart)
* `GET /attachments/{id}` - Download single attachment
* `GET /attachments?ids=...` - Download multiple attachments as PDF
**Common Use Cases:**
* Upload documents for processing
* Download form response attachments
* Merge multiple documents into a single PDF
### Document Intelligence
Extract structured data from documents using AI.
**Key Endpoints:**
* `POST /document-intelligence` - Create extraction job
* `GET /document-intelligence/{id}` - Get extraction results
**Common Use Cases:**
* Extract invoice data (number, date, amount)
* Parse ID documents
* Process contracts and forms automatically
### Signatures
Access digital signatures created through form responses.
**Key Endpoints:**
* `GET /signatures/{id}` - Get signature metadata or download file
**Common Use Cases:**
* Download signed documents
* Track signature status
* Verify signature completion
### Workspaces
List available workspaces accessible with your token.
**Key Endpoints:**
* `GET /workspaces` - List accessible workspaces
## Rate Limiting
* **100 requests per minute** per access token
* **1,000 requests per hour** per client
If you exceed the rate limit, you'll receive a `429 Too Many Requests` response. Implement exponential backoff in your integration.
## Response Format
All responses use JSON format with consistent structure:
### Single Resource Response
```json theme={null}
{
"id": "uuid",
"created_at": "2024-01-15T10:30:00Z",
"status": "completed",
"archived": false,
...
}
```
### Paginated Collection Response
```json theme={null}
{
"meta": {
"total_count": 150,
"total_pages": 8,
"page_size": 20,
"current_page": 1
},
"data": [
{ "id": "uuid-1", ... },
{ "id": "uuid-2", ... }
]
}
```
### Error Response
```json theme={null}
{
"error": "Error message",
"statusCode": 400,
"message": "Detailed error description"
}
```
## Pagination and Filtering
The API provides powerful pagination, sorting, and filtering capabilities on all list endpoints.
Control result size and order with `page[number]`, `page[size]`, and `sort` parameters
Filter results with operators like `$eq`, `$ne`, `$gt`, `$like`, and `$extends`
## Common Headers
### Request Headers
* `Authorization: Bearer {token}` - Required for authentication
* `Content-Type: application/json` - For JSON request bodies
* `Accept: application/json` - Default response format (optional)
### Response Headers
* `Content-Type: application/json` - JSON responses
* `Content-Type: application/octet-stream` - Binary file downloads
## HTTP Status Codes
| Code | Description |
| - | - |
| `200` | Success |
| `201` | Created |
| `202` | Accepted (async processing) |
| `400` | Bad Request - Invalid input |
| `401` | Unauthorized - Invalid or missing token |
| `403` | Forbidden - No access to resource |
| `404` | Not Found - Resource doesn't exist |
| `413` | Payload Too Large |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Internal Server Error |
## Webhooks
When creating forms, you can specify webhook URLs to receive real-time notifications about events:
```json theme={null}
{
"webhooks": {
"https://your-server.com/webhook": [
"responses:completed",
"forms:updated"
]
}
}
```
Available webhook events:
* `forms:created`, `forms:updated`, `forms:deleted`
* `forms:archived`, `forms:unarchived`
* `responses:created`, `responses:updated`, `responses:deleted`
* `responses:completed`
## Best Practices
### 1. Use Filtering Wisely
Apply filters to reduce data transfer and improve response times.
### 2. Implement Error Handling
Always handle potential error responses and implement retry logic with exponential backoff.
### 3. Store IDs, Not Full Objects
Store resource IDs and fetch fresh data when needed to avoid stale data.
### 4. Use Webhooks for Real-Time Updates
Instead of polling, use webhooks to receive notifications when forms are completed.
### 5. Batch Operations
When possible, use batch endpoints like `POST /cases/{id}/data` to update multiple fields at once.
### 6. Respect Rate Limits
Implement proper rate limiting in your application to avoid `429` errors.
## Support
For questions or issues with the API:
* Check the detailed endpoint documentation
* Review the [Advanced Filters](/api-reference/advanced-filters) guide
* Contact support at [support@penbox.io](mailto:support@penbox.io)
## Version History
**Current Version:** v1
The API follows semantic versioning principles. Breaking changes will be introduced in new major versions.
# Count Requests
Source: https://docs.penbox.io/api-reference/previous-api-version/count-requests
Previous version of Count Forms. Count requests matching filter criteria.
Previous API version. Use [`GET /forms/count`](/api-reference/requests/count-requests) for new integrations. This route still works but is deprecated.
Get the total count of requests matching your filter criteria, with optional grouping by field values.
```text theme={null}
GET https://connect.penbox.io/v1/requests/count
```
## Query Parameters
| Parameter | Type | Description |
| - | - | - |
| `filter` | string | JSON-encoded filter object (same keys as `GET /requests`) |
| `group-by` | string | Group counts by `status`, `user.{field}`, or `data.{field}` |
## Response
### Without grouping
```json theme={null}
{ "count": 42 }
```
### With grouping
```json theme={null}
{
"count": 42,
"by": {
"status": { "pending": 15, "completed": 20, "draft": 7 }
}
}
```
## Example
```bash cURL theme={null}
curl 'https://connect.penbox.io/v1/requests/count?group-by=status' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
## Response Codes
| Code | Description |
| - | - |
| `200` | Success |
| `400` | Bad Request — invalid filter or group-by |
| `401` | Unauthorized |
| `403` | Forbidden |
| `429` | Too Many Requests |
| `500` | Server Error |
# Create Request
Source: https://docs.penbox.io/api-reference/previous-api-version/create-request
Previous version of Create Form. Create a new request from a flow.
Previous API version. Use [`POST /forms`](/api-reference/requests/create-request) for new integrations. This route still works but is deprecated.
Create a new request (now called a form) from a flow (form template).
```text theme={null}
POST https://connect.penbox.io/v1/requests
```
## Request Body
### Required
| Field | Type | Description |
| - | - | - |
| `flow.slug` | string | Flow (form template) identifier |
### Optional
| Field | Type | Description |
| - | - | - |
| `company.slug` | string | Workspace identifier (if multiple authorized) |
| `user.email` | string | Contact email address |
| `user.phone` | string | Contact phone number |
| `user.given_name` | string | Contact first name |
| `user.family_name` | string | Contact last name |
| `user.locale` | string | Contact language (e.g. `en`, `fr`) |
| `data` | object | Pre-filled data (keys must match field keys) |
| `options` | object | Request-specific options |
| `external_args` | object | Your custom metadata |
| `redirect_url` | string | HTTPS URL to redirect after completion |
| `draft` | boolean | Create as draft (default: `false`) |
| `active_from` | string | ISO 8601 date when the request becomes active |
| `active_until` | string | ISO 8601 date when the request expires |
| `owner.email` | string | Request owner email (or `null`) |
| `branding.slug` | string | Branding profile slug |
| `webhooks` | object | Map of HTTPS URL → array of subscribed events |
Supported webhook events: `requests:created`, `requests:updated`, `requests:deleted`, `requests:archived`, `requests:unarchived`, `responses:created`, `responses:updated`, `responses:deleted`, `responses:completed`.
## Example
```bash cURL theme={null}
curl -X POST 'https://connect.penbox.io/v1/requests' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"flow": { "slug": "client-onboarding" },
"user": { "email": "client@example.com", "given_name": "John", "family_name": "Doe" },
"data": { "company_name": "Acme Corporation" },
"external_args": { "crm_id": "12345" }
}'
```
## Response
Returns the created request object (same shape as [Get Request](/api-reference/previous-api-version/get-request)).
## Response Codes
| Code | Description |
| - | - |
| `201` | Created |
| `400` | Bad Request — invalid parameters |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found — flow not enabled for the user |
| `409` | Conflict — more than one flow matches |
| `422` | Unprocessable — validation failed |
| `429` | Too Many Requests |
| `500` | Server Error |
# Get Flow Options
Source: https://docs.penbox.io/api-reference/previous-api-version/get-flow-options
Previous version of Get Form Template Options.
Previous API version. Use [`GET /form_templates/{slug}/options`](/api-reference/flows/get-flow-options) for new integrations. This route still works but is deprecated.
Retrieve the configuration options for a specific flow (now called a form template).
```text theme={null}
GET https://connect.penbox.io/v1/flows/{slug}/options
```
## Path Parameters
| Parameter | Type | Description |
| - | - | - |
| `slug` | string | Flow identifier |
The exact structure of the options object depends on the flow configuration. Different flows may expose different options.
## Example
```bash cURL theme={null}
curl 'https://connect.penbox.io/v1/flows/client-onboarding/options' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
## Response Codes
| Code | Description |
| - | - |
| `200` | Success |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found — flow not found or not enabled |
| `429` | Too Many Requests |
| `500` | Server Error |
# Get Flow Steps
Source: https://docs.penbox.io/api-reference/previous-api-version/get-flow-steps
Previous version of Get Form Template Steps.
Previous API version. Use [`GET /form_templates/{slug}/steps`](/api-reference/flows/get-flow-steps) for new integrations. This route still works but is deprecated.
Retrieve the steps/structure of a specific flow (now called a form template).
```text theme={null}
GET https://connect.penbox.io/v1/flows/{slug}/steps
```
## Path Parameters
| Parameter | Type | Description |
| - | - | - |
| `slug` | string | Flow identifier |
Use this endpoint to understand the structure of a flow before creating requests, or to build a custom form UI.
## Example
```bash cURL theme={null}
curl 'https://connect.penbox.io/v1/flows/client-onboarding/steps' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
## Response Codes
| Code | Description |
| - | - |
| `200` | Success |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found — flow not found or not enabled |
| `429` | Too Many Requests |
| `500` | Server Error |
# Get Request
Source: https://docs.penbox.io/api-reference/previous-api-version/get-request
Previous version of Get Form. Retrieve a single request with responses and notifications.
Previous API version. Use [`GET /forms/{id}`](/api-reference/requests/get-request) for new integrations. This route still works but is deprecated.
Retrieve complete details of a specific request (now called a form), including responses, attachments, and notifications.
```text theme={null}
GET https://connect.penbox.io/v1/requests/{id}
```
## Path Parameters
| Parameter | Type | Description |
| - | - | - |
| `id` | string (uuid) | Request identifier |
## Response
Returns a single request object:
```json theme={null}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"created_at": "2024-01-15T10:30:00Z",
"status": "completed",
"archived": false,
"user": { "email": "client@example.com", "given_name": "John", "family_name": "Doe" },
"external_args": { "crm_id": "12345" },
"flow": { "slug": "client-onboarding" },
"owner": null,
"active_from": "2024-01-15T10:30:00Z",
"active_until": null,
"archived_at": null,
"processed_at": null,
"workspace": { "id": "...", "slug": "acme-corp" },
"links": { "fill": "https://...", "app": "https://..." },
"responses": [
{ "id": "...", "completed_at": "2024-01-16T09:00:00Z", "user": {}, "attachments": [] }
],
"notifications": []
}
```
The `responses` and `notifications` arrays carry the same fields as the current [Get Form](/api-reference/requests/get-request) endpoint.
## Response Codes
| Code | Description |
| - | - |
| `200` | Success |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found — request doesn't exist |
| `429` | Too Many Requests |
| `500` | Server Error |
# List Companies
Source: https://docs.penbox.io/api-reference/previous-api-version/list-companies
Previous version of List Workspaces. Retrieve authorized companies.
Previous API version. Use [`GET /workspaces`](/api-reference/workspaces/list-workspaces) for new integrations. This route still works but is deprecated.
Retrieve all companies (now called workspaces) that the authenticated user has authorized your application to access.
```text theme={null}
GET https://connect.penbox.io/v1/companies
```
## Response
Unlike the current `GET /workspaces` endpoint, this route returns a **bare JSON array** with no pagination `meta` envelope.
```json theme={null}
[
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"created_at": "2024-01-15T10:30:00Z",
"slug": "acme-corp",
"name": "Acme Corp"
}
]
```
The `slug` is a URL-safe, unique identifier used in API calls to specify which workspace you want to interact with.
## Example
```bash cURL theme={null}
curl 'https://connect.penbox.io/v1/companies' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
## Response Codes
| Code | Description |
| - | - |
| `200` | Success — returns array of companies |
| `401` | Unauthorized |
| `403` | Forbidden |
| `429` | Too Many Requests |
| `500` | Server Error |
# List Flows
Source: https://docs.penbox.io/api-reference/previous-api-version/list-flows
Previous version of List Form Templates. Retrieve available flows.
Previous API version. Use [`GET /form_templates`](/api-reference/flows/list-flows) for new integrations. This route still works but is deprecated.
Retrieve all active flows (now called form templates) available in the authorized workspaces.
```text theme={null}
GET https://connect.penbox.io/v1/flows
```
## Query Parameters
| Parameter | Type | Description |
| - | - | - |
| `archived` | boolean | When `true`, returns archived flows instead of active ones |
## Response
Unlike the current `GET /form_templates` endpoint, this route returns a **bare JSON array** with no pagination `meta` envelope.
```json theme={null}
[
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"created_at": "2024-01-15T10:30:00Z",
"slug": "client-onboarding",
"name": "Client Onboarding",
"archived_at": null,
"enabled": true,
"workspace": { "id": "...", "slug": "acme-corp" }
}
]
```
Flow slugs can be reused across different workspaces. Always combine the flow slug with the workspace slug when storing or referencing them in your system.
## Example
```bash cURL theme={null}
curl 'https://connect.penbox.io/v1/flows' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
## Response Codes
| Code | Description |
| - | - |
| `200` | Success — returns array of flows |
| `401` | Unauthorized |
| `403` | Forbidden |
| `429` | Too Many Requests |
| `500` | Server Error |
# List Requests
Source: https://docs.penbox.io/api-reference/previous-api-version/list-requests
Previous version of List Forms. Retrieve a list of requests with filtering.
Previous API version. Use [`GET /forms`](/api-reference/requests/list-requests) for new integrations. This route still works but is deprecated.
Retrieve a list of requests (now called forms) matching specific criteria.
```text theme={null}
GET https://connect.penbox.io/v1/requests
```
## Query Parameters
| Parameter | Type | Description |
| - | - | - |
| `filter` | string | JSON-encoded filter object (workspace, flow, user, owner, status, external args) |
| `page[number]` | number | Page number (starts at 1) |
| `page[size]` | number | Results per page (default: 10, max: 100) |
The `filter` object accepts the same keys as the current endpoint: `company.slug`, `flow.slug`, `user`, `owner.email`, `active`, `archived`, `completed`, `processed`, and `external_args`. See the [Advanced Filters guide](/api-reference/advanced-filters).
## Response
Unlike the current `GET /forms` endpoint, this route returns a **bare JSON array** with no pagination `meta` envelope.
```json theme={null}
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"created_at": "2024-01-15T10:30:00Z",
"status": "pending",
"archived": false,
"user": {
"email": "client@example.com",
"given_name": "John",
"family_name": "Doe"
},
"external_args": { "crm_id": "12345" },
"flow": { "slug": "client-onboarding" },
"owner": null,
"active_from": "2024-01-15T10:30:00Z",
"active_until": null,
"archived_at": null,
"processed_at": null,
"workspace": { "id": "...", "slug": "acme-corp" },
"links": { "fill": "https://...", "app": "https://..." },
"responses": []
}
]
```
## Example
```bash cURL theme={null}
curl 'https://connect.penbox.io/v1/requests' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
## Response Codes
| Code | Description |
| - | - |
| `200` | Success — returns array of requests |
| `400` | Bad Request — invalid filter parameters |
| `401` | Unauthorized — invalid or expired access token |
| `403` | Forbidden — token lacks required permissions |
| `429` | Too Many Requests — rate limit exceeded |
| `500` | Server Error |
# Overview
Source: https://docs.penbox.io/api-reference/previous-api-version/overview
Previous-generation Connect API routes (requests, flows, companies) that remain available for backward compatibility.
Before the current Forms API, the Connect API exposed an earlier generation of routes built around `requests`, `flows`, and `companies`. These routes are **still served** for backward compatibility but are no longer part of the main API list above.
These endpoints are deprecated. They are maintained so existing integrations keep working, but they receive no new features and may be removed in a future major version. **New integrations should use the current endpoints** ([Forms](/api-reference/requests/list-requests), [Form Templates](/api-reference/flows/list-flows), [Workspaces](/api-reference/workspaces/list-workspaces)).
They use the same base URL and the same Bearer-token authentication as the current API:
```text theme={null}
https://connect.penbox.io/v1
```
```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```
## Endpoint mapping
Each previous-version route has a direct equivalent in the current API. Request bodies, query filters, and per-item response shapes are identical — see the current endpoint for the full schema and the interactive "Try It" tool.
### Forms (previously `requests`)
| Previous route | Current equivalent |
| - | - |
| `GET /requests` | [`GET /forms`](/api-reference/requests/list-requests) |
| `GET /requests/count` | [`GET /forms/count`](/api-reference/requests/count-requests) |
| `POST /requests` | [`POST /forms`](/api-reference/requests/create-request) |
| `GET /requests/{id}` | [`GET /forms/{id}`](/api-reference/requests/get-request) |
| `PATCH /requests/{id}` | [`PATCH /forms/{id}`](/api-reference/requests/update-request) |
### Form Templates (previously `flows`)
| Previous route | Current equivalent |
| - | - |
| `GET /flows` | [`GET /form_templates`](/api-reference/flows/list-flows) |
| `GET /flows/{slug}/options` | [`GET /form_templates/{slug}/options`](/api-reference/flows/get-flow-options) |
| `GET /flows/{slug}/steps` | [`GET /form_templates/{slug}/steps`](/api-reference/flows/get-flow-steps) |
### Workspaces (previously `companies`)
| Previous route | Current equivalent |
| - | - |
| `GET /companies` | [`GET /workspaces`](/api-reference/workspaces/list-workspaces) |
## Key differences
Apart from the path, the only behavioral change is in the **list** endpoints.
* **List responses are not paginated.** The previous list routes (`GET /requests`, `GET /flows`, `GET /companies`) return a **bare JSON array**. The current routes wrap results in a pagination envelope (`{ "meta": { ... }, "data": [ ... ] }`).
* **Resource naming.** The previous routes use the older resource names — `requests` (now forms), `flows` (now form templates), and `companies` (now workspaces). The shape of each item is otherwise unchanged.
Unchanged, current-generation routes such as [`GET /responses/{id}`](/api-reference/responses/get-response), [`GET /attachments/{id}`](/api-reference/attachments/get-attachment), and [`GET /signatures/{id}`](/api-reference/signatures/get-signature) are documented in their own sections above and are **not** part of the previous API version.
# Update Request
Source: https://docs.penbox.io/api-reference/previous-api-version/update-request
Previous version of Update Form. Update a request's status or expiration.
Previous API version. Use [`PATCH /forms/{id}`](/api-reference/requests/update-request) for new integrations. This route still works but is deprecated.
Update a request's (now form's) status or expiration date.
```text theme={null}
PATCH https://connect.penbox.io/v1/requests/{id}
```
## Path Parameters
| Parameter | Type | Description |
| - | - | - |
| `id` | string (uuid) | Request identifier |
## Request Body
At least one field must be provided.
| Field | Type | Description |
| - | - | - |
| `archived` | boolean | Archive or unarchive the request |
| `draft` | boolean | Set draft status (`true` = draft, `false` = activate) |
| `processed` | boolean | Mark as processed or unprocessed |
| `active_until` | string | Update expiration date (ISO 8601) |
## Example
```bash cURL theme={null}
curl -X PATCH 'https://connect.penbox.io/v1/requests/REQUEST_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "archived": true }'
```
## Response
Returns the updated request object (same shape as [Get Request](/api-reference/previous-api-version/get-request)).
## Response Codes
| Code | Description |
| - | - |
| `200` | Success |
| `400` | Bad Request — no valid field provided |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found — request doesn't exist |
| `422` | Unprocessable — validation failed |
| `429` | Too Many Requests |
| `500` | Server Error |
# Count Forms
Source: https://docs.penbox.io/api-reference/requests/count-requests
GET /forms/count
Get the total count of forms matching filter criteria, with optional grouping.
Get the total count of forms matching your filter criteria, with optional grouping by field values.
## Query Parameters
Group counts by a specific field. Supported values:
* `status` - Group by form status
* `user.{field}` - Group by user field (e.g., `user.email`)
* `data.{field}` - Group by data field (e.g., `data.property_type`)
## Response Structure
### Without Grouping
```json theme={null}
{
"count": 42
}
```
### With Grouping
```json theme={null}
{
"count": 42,
"by": {
"status": {
"pending": 15,
"completed": 20,
"draft": 7
}
}
}
```
Use the `group-by` parameter to get distribution statistics for your forms, which is useful for dashboards and analytics.
# Create Form
Source: https://docs.penbox.io/api-reference/requests/create-request
POST /forms
Create a new form to send to a contact.
## Request Parameters
### Required Fields
| Field | Type | Description |
| - | - | - |
| `flow.slug` | string | Form template identifier |
### Optional Fields
| Field | Type | Description |
| - | - | - |
| `company.slug` | string | Workspace identifier (if multiple authorized) |
| `user.email` | string | Contact email address |
| `user.phone` | string | Contact phone number |
| `user.given_name` | string | Contact first name |
| `user.family_name` | string | Contact last name |
| `user.locale` | string | Contact language (e.g., `en`, `fr`) |
| `data` | object | Pre-filled form data (keys must match form field keys) |
| `external_args` | object | Your custom metadata |
| `redirect_url` | string | HTTPS URL to redirect after completion |
| `draft` | boolean | Create as draft (default: `false`) |
| `active_from` | string | ISO 8601 date when form becomes active |
| `active_until` | string | ISO 8601 date when form expires |
| `owner.email` | string | Form owner email address |
| `branding.slug` | string | Branding profile slug (see [Branding](#branding) below) |
## Form Statuses
| Status | Description |
| - | - |
| `draft` | Form created but not yet sent |
| `pending` | Form sent, waiting for completion |
| `completed` | Contact submitted the form |
| `declined` | Contact declined to fill the form |
| `processed` | Response has been reviewed/processed |
## Pre-filling Form Data
The `data` parameter allows you to pre-fill form fields with values. This is useful for importing data from your system or providing a better user experience by reducing the amount of information the contact needs to enter.
### How It Works
The keys in the `data` object **must exactly match the field keys** defined in your form template. When a contact opens the form, these fields will already contain the provided values.
**Example:**
If your form template has fields with keys:
* `company_name`
* `address_zip`
* `annual_revenue`
You can pre-fill them like this:
```json theme={null}
{
"data": {
"company_name": "Acme Corp",
"address_zip": "10001",
"annual_revenue": "500000"
}
}
```
### Finding Field Keys
Field keys are defined in your form template configuration in Penbox. Common examples:
| Field Type | Example Keys |
| - | - |
| **Company Info** | `company_name`, `company_vat`, `company_registration` |
| **Address** | `address_street`, `address_city`, `address_zip`, `address_country` |
| **Contact** | `contact_name`, `contact_email`, `contact_phone` |
| **Financial** | `annual_revenue`, `number_employees`, `bank_account` |
| **Custom** | Any custom field keys you've defined in your template |
Field keys are case-sensitive and must match exactly. Use the Penbox app or contact your administrator to find the correct field keys for your form template.
### Complete Example
```javascript theme={null}
const response = await fetch('https://connect.penbox.io/v1/forms', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
flow: { slug: 'client-onboarding' },
user: {
email: 'client@example.com',
given_name: 'John',
family_name: 'Doe'
},
// Pre-fill form fields
data: {
company_name: 'Acme Corporation',
company_vat: 'BE0123456789',
address_street: '123 Main Street',
address_city: 'New York',
address_zip: '10001',
address_country: 'US',
annual_revenue: '1500000',
number_employees: '25'
},
external_args: {
crm_id: '12345'
},
branding: {
slug: 'partner-brand'
}
})
});
```
```bash cURL theme={null}
curl -X POST 'https://connect.penbox.io/v1/forms' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"flow": { "slug": "client-onboarding" },
"user": {
"email": "client@example.com",
"given_name": "John",
"family_name": "Doe"
},
"data": {
"company_name": "Acme Corporation",
"company_vat": "BE0123456789",
"address_street": "123 Main Street",
"address_city": "New York",
"address_zip": "10001",
"address_country": "US",
"annual_revenue": "1500000",
"number_employees": "25"
},
"external_args": {
"crm_id": "12345"
},
"branding": {
"slug": "partner-brand"
}
}'
```
### Use Cases
**Import from CRM:**
```javascript theme={null}
// Pull data from your CRM and pre-fill the form
const crmContact = await getCRMContact(contactId);
const formData = {
company_name: crmContact.companyName,
address_zip: crmContact.zipCode,
annual_revenue: crmContact.revenue,
contact_phone: crmContact.phone
};
await createForm({
flow: { slug: 'onboarding' },
user: { email: crmContact.email },
data: formData
});
```
**Progressive Forms:**
```javascript theme={null}
// Pre-fill with data collected in previous steps
const formData = {
company_name: step1Data.company,
address_zip: step2Data.zip,
business_type: step3Data.type
};
```
**Reduce Friction:**
```javascript theme={null}
// Pre-fill known information to make the form faster
const formData = {
company_name: user.organization,
contact_email: user.email,
contact_phone: user.phone
};
```
Pre-filling data improves form completion rates and reduces errors. Always pre-fill what you know while allowing contacts to modify values if needed.
If you provide a field key that doesn't exist in the form template, it will be silently ignored. Make sure your field keys match your template configuration.
## Branding
Use the `branding` parameter to apply a specific visual identity to a form — logo, colors, favicon, and related styling in the form experience and email notifications.
### Default behavior
When `branding` is omitted, the form uses your workspace's default branding — the profile configured under **Settings → Branding** in Penbox.
### How it works
Pass the slug of an existing branding profile in your workspace:
```json theme={null}
{
"flow": { "slug": "client-onboarding" },
"user": { "email": "client@example.com" },
"branding": {
"slug": "partner-brand"
}
}
```
The slug must match a branding profile that already exists in the workspace. If the slug is invalid or not found, the API returns `404`.
To use the workspace default branding, omit the `branding` field entirely. The slug `default` is only a UI label for the primary workspace profile — it is not a valid API value.
### Finding the branding slug
1. Open **Settings → Branding** in Penbox.
2. If your workspace has multiple branding profiles, select the profile you want and note its slug — it is displayed next to the profile selector (for example, `slug: partner-brand`).
See [Branding](/workspace/settings/branding) for how to create and manage branding profiles.
### Use cases
**White-label partner forms:**
```javascript theme={null}
await createForm({
flow: { slug: 'onboarding' },
user: { email: partner.contactEmail },
branding: { slug: 'partner-acme' }
});
```
**Different brands per client segment:**
```javascript theme={null}
const brandingSlug = client.segment === 'enterprise'
? 'enterprise-brand'
: 'self-serve-brand';
await createForm({
flow: { slug: 'signup' },
user: { email: client.email },
branding: { slug: brandingSlug }
});
```
Branding is set at form creation and applies to the form link and related emails for that form. Create separate branding profiles in Penbox when you need distinct visual identities for different clients or product lines.
## External Args
Use `external_args` to store your own metadata with forms for easy tracking:
```json theme={null}
{
"external_args": {
"crm_id": "12345",
"order_id": "ORD-789",
"source": "website",
"campaign": "summer-2024"
}
}
```
You can filter by external\_args when listing forms:
```json theme={null}
{
"filter": {
"external_args": {
"order_id": "ORD-789"
}
}
}
```
## Response Codes
| Code | Description |
| - | - |
| `201` | Created - New form created successfully |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid access token |
| `403` | Forbidden - No access to this resource |
| `409` | Conflict - Multiple form templates match criteria |
| `422` | Unprocessable - Validation failed |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
Created forms are immediately active unless `draft: true` is specified. Draft forms must be activated by setting `draft: false` via PATCH.
Use `external_args` to link Penbox forms back to your system's entities (orders, customers, tickets, etc.). This makes it easy to track and manage forms in your system.
The `active_from` and `active_until` dates control when the form link is accessible. Set `active_until` to create expiring forms.
# Get Form
Source: https://docs.penbox.io/api-reference/requests/get-request
GET /forms/{id}
Retrieve details of a specific form by ID.
Retrieve complete details of a specific form including responses and attachments.
## Response Structure
The response includes complete form details with all nested data:
### Form Fields
* **id**: Form UUID
* **created\_at**: Form creation timestamp
* **status**: Current form status (draft, pending, completed, declined, processed)
* **archived**: Boolean indicating if archived
* **archived\_at**: Timestamp when archived (if applicable)
* **processed\_at**: Timestamp when marked as processed (if applicable)
* **active\_from**: When the form becomes active (if set)
* **active\_until**: When the form expires (if set)
* **links.fill**: Public form link for the contact
* **links.app**: Internal app link to view the form
* **user**: Contact information (email, name, phone, anonymous flag)
* **owner**: Form owner information (id, email) if applicable
* **flow**: Form template info with slug
* **data**: Pre-filled form data object
* **external\_args**: Your custom metadata object
* **options**: Form-specific options
* **responses**: Array of response objects with attachments and signatures
* **notifications**: Array of notification objects
### Notification Fields
Each notification object contains:
* **id**: Unique identifier for the notification (UUID)
* **status**: Current status of the notification (`pending`, `sent`, `failed`, `skipped`)
* **method**: Delivery method (`sms` or `email`)
* **at**: Timestamp when the notification was sent (ISO 8601 format)
* **to**: Recipient address (email address or phone number), can be null
* **from**: Sender address (email or system identifier), can be null
* **cc**: Carbon copy recipient(s), can be null
* **bcc**: Blind carbon copy recipient(s), can be null
* **system**: Boolean indicating if this is a system notification
* **locale**: Language/locale code (e.g., 'fr', 'en')
* **template**: Template name used for the notification (e.g., 'raw', 'request\_completed')
* **variables**: Object containing template variables used in the message, can be null
* **active**: Boolean indicating if the notification is active
* **error**: Error message if notification failed, can be null
* **message\_id**: External message identifier from the delivery provider, can be null
* **attachments**: Attached files, can be null
* **deleted\_at**: Timestamp when the notification was deleted, can be null
## Response Codes
| Code | Description |
| - | - |
| `200` | Success - Form details retrieved |
| `401` | Unauthorized - Invalid access token |
| `403` | Forbidden - No access to this resource |
| `404` | Not Found - Form doesn't exist |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
The response includes all related data nested within the form object (responses, notifications, etc.), so you don't need additional API calls to access related resources.
# List Forms
Source: https://docs.penbox.io/api-reference/requests/list-requests
GET /forms
Retrieve a paginated list of forms with optional filtering and sorting. By default, only non-archived forms are returned.
Retrieve a list of forms matching specific criteria. Use filters to narrow down results.
## Query Parameters
| Parameter | Type | Description |
| - | - | - |
| `filter` | string | JSON-encoded filter object |
| `page[number]` | number | Page number (starts at 1) |
| `page[size]` | number | Results per page (default: 10, max: 100) |
## Filter Options
You can filter forms using a JSON-encoded filter object. The Connect API supports filtering by workspace, template, user, status, and custom metadata.
**Quick Example:**
```json theme={null}
{
"flow": { "slug": "client-onboarding" },
"active": true,
"completed": false
}
```
**Available Filters:**
* **Workspace** (workspace slug)
* **Form Template** (form template slug)
* **User** (email, name, phone, internal\_ref, company\_name)
* **Owner** (email)
* **Status** (active, archived, completed, processed)
* **External args** (your custom metadata)
See the complete filtering documentation with examples and use cases
## Response Codes
| Code | Description |
| - | - |
| `200` | Success - Returns list of forms |
| `400` | Bad Request - Invalid filter parameters |
| `401` | Unauthorized - Invalid or expired access token |
| `403` | Forbidden - Token doesn't have required permissions |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
Use `page[number]` and `page[size]` for pagination when working with large datasets. The maximum page size is 100 forms per request.
# Update Form
Source: https://docs.penbox.io/api-reference/requests/update-request
PATCH /forms/{id}
Update a form's status or properties.
Update a form's status or properties.
## Updatable Fields
| Field | Type | Description |
| - | - | - |
| `archived` | boolean | Archive or unarchive the form |
| `draft` | boolean | Set draft status (true = draft, false = activate) |
| `processed` | boolean | Mark as processed or unprocessed |
| `active_until` | string | Update expiration date (ISO 8601) |
## Common Use Cases
### Archive a Form
Archive completed or cancelled forms to keep your list organized:
```javascript theme={null}
await fetch(`https://connect.penbox.io/v1/forms/${formId}`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ archived: true })
});
```
### Mark as Processed
Track which forms you've reviewed in your system:
```javascript theme={null}
await fetch(`https://connect.penbox.io/v1/forms/${formId}`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ processed: true })
});
```
### Activate a Draft
Activate a draft form to send it to the contact:
```javascript theme={null}
await fetch(`https://connect.penbox.io/v1/forms/${formId}`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ draft: false })
});
```
## Response Codes
| Code | Description |
| - | - |
| `200` | Success - Form updated successfully |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid access token |
| `403` | Forbidden - No access to this resource |
| `404` | Not Found - Form doesn't exist |
| `422` | Unprocessable - Validation failed |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
You can only update certain fields. To modify form data or user information, you'll need to create a new form.
# Get Form Response
Source: https://docs.penbox.io/api-reference/responses/get-response
GET /responses/{id}
Retrieve complete response data including form answers and attachments.
Retrieve complete form response data including answers and attachments.
Form responses are called **responses** in the API. Each form (request) can have one or more responses as contacts fill them out.
## Response Formats
The endpoint supports two response formats controlled by the `Accept` header:
| Format | Accept Header | Description |
| - | - | - |
| **JSON** | `application/json` | Structured data including all form fields and file references |
| **PDF** | `application/pdf` | Generated PDF of the complete form response |
## Response Fields
### Response Attributes
| Field | Type | Description |
| - | - | - |
| `$created_at` | string | ISO 8601 timestamp when response was created |
| `$updated_at` | string | ISO 8601 timestamp of last update |
| `completed_at` | string/null | ISO 8601 timestamp when completed (null if pending) |
| `declined_at` | string/null | ISO 8601 timestamp when declined (null if not declined) |
| `user` | object | Contact information who filled the form |
| `data` | object | Form field values keyed by field name |
| `rating` | string | Optional rating provided by the contact |
### User Object
| Field | Type | Description |
| - | - | - |
| `email` | string | Contact email address |
| `given_name` | string | Contact first name |
| `family_name` | string | Contact last name |
| `phone` | string | Contact phone number |
| `locale` | string | Language used to fill the form (e.g., `en`, `fr`) |
## Completion Status
| Status | Description | Indicators |
| - | - | - |
| **Pending** | Form started but not submitted | `completed_at: null`, `declined_at: null` |
| **Completed** | Form successfully submitted | `completed_at` timestamp present, `declined_at: null` |
| **Declined** | Contact declined to fill the form | `completed_at: null`, `declined_at` timestamp present |
## Finding Response IDs
Response IDs are included when you retrieve a form. Use the relationships to find responses:
```javascript theme={null}
// Get a form with its responses
const requestResponse = await fetch(
`https://connect.penbox.io/v1/requests/${requestId}`,
{
headers: { 'Authorization': `Bearer ${accessToken}` }
}
);
const { data, included } = await requestResponse.json();
// Extract response IDs from relationships
const responseIds = data.relationships.responses.data.map(r => r.id);
// Fetch each response
for (const responseId of responseIds) {
const res = await fetch(
`https://connect.penbox.io/v1/responses/${responseId}`,
{
headers: { 'Authorization': `Bearer ${accessToken}` }
}
);
const responseData = await res.json();
console.log('Response data:', responseData.data.attributes.data);
}
```
## Accessing Form Data
The `data` attribute contains all form field values:
```javascript theme={null}
const { data } = await fetch(
`https://connect.penbox.io/v1/responses/${responseId}`,
{ headers: { 'Authorization': `Bearer ${accessToken}` } }
).then(r => r.json());
const formData = data.attributes.data;
// Access specific fields
console.log('Company name:', formData.company_name);
console.log('Registration number:', formData.registration_number);
// Check completion status
const isCompleted = data.attributes.completed_at !== null;
const isDeclined = data.attributes.declined_at !== null;
```
## Working with Uploaded Files
Responses include references to uploaded files in the `included` array:
```javascript theme={null}
const { data, included } = await fetch(
`https://connect.penbox.io/v1/responses/${responseId}`,
{ headers: { 'Authorization': `Bearer ${accessToken}` } }
).then(r => r.json());
// Find files in the included array
const files = included.filter(item => item.type === 'attachments');
for (const file of files) {
console.log('File:', file.attributes.name);
console.log('Type:', file.attributes.type);
console.log('Size:', file.attributes.metadata.size);
// Download the file using the Files endpoint
const fileUrl = `https://connect.penbox.io/v1/attachments/${file.id}`;
}
```
See [Get File](/api-reference/attachments/get-attachment) for download details.
## Response Codes
| Code | Description |
| - | - |
| `200` | Success - Response data retrieved |
| `401` | Unauthorized - Invalid access token |
| `403` | Forbidden - No access to this response |
| `404` | Not Found - Response doesn't exist |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
Responses are automatically created when a contact starts filling out a form. Initially, they contain partial data and no completion timestamp.
Once a response is completed (`completed_at` is set), it becomes immutable. You cannot modify the data or user information.
# Get Signature
Source: https://docs.penbox.io/api-reference/signatures/get-signature
GET /signatures/{id}
Retrieve signature information or download the signature file.
Retrieve signature information or download the signature file.
## Path Parameters
Signature UUID
## Headers
Response format:
* `application/json` - Get signature metadata (default)
* `application/octet-stream` - Download signature file
## Response Structure (JSON)
When `Accept: application/json` is used:
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:35:00Z",
"name": "Contract Signature",
"key": "customer_signature",
"status": "completed",
"items": 3,
"method": "electronic",
"merge": true,
"cost": 2.50,
"locale": "en"
}
```
## Response Fields (JSON)
Signature UUID
Creation timestamp
Last update timestamp
Signature name
Signature identifier key
Signature status (e.g., "pending", "completed", "declined")
Number of items/pages to be signed
Signature method (e.g., "electronic", "qualified")
Whether to merge signatures into a single document
Signature cost (if applicable)
Language/locale code
## Response (Binary)
When `Accept: application/octet-stream` is used, returns the signature file (typically PDF format).
## Response Codes
| Code | Description |
| - | - |
| `200` | Success - Signature retrieved |
| `401` | Unauthorized - Invalid access token |
| `404` | Not Found - Signature doesn't exist |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
Signatures are typically generated when a form response includes signature fields. The signature file contains the legally binding signed documents.
# Create Case Task
Source: https://docs.penbox.io/api-reference/tasks/create-case-task
POST /cases/{id}/tasks
Add a follow-up task to a case
Add a task to a case. Use it to put your own follow-ups next to the ones Penbox
creates, so the team sees a single to-do list.
The task lands on the **team side**: assign it to a workspace member by email, or
leave it unassigned. Assign by email and Penbox resolves the member for you —
including members you registered through
[Create Member](/api-reference/members/create-member), who never receive
Penbox emails.
You cannot create a task on the **client** side, nor move one there later. Those
are created by Penbox when it sends a form, and they close when the client submits
it — a client-side task you created would have no way to ever be closed.
The case and the assignee must both belong to a workspace your key covers.
Referencing either from another workspace returns `403`.
`type` is set to `manual` for every task you create. It is not a field you send:
Penbox reserves its own keys (`fill_form`, `review`, `follow_up`) for the tasks it
manages itself, and closes those automatically as the case moves.
```bash Assigned theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id}/tasks \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"title": "Call the client back",
"description": "The client asked for a callback before Friday.",
"due_at": "2026-09-04T00:00:00.000Z",
"assignee": { "email": "amina@firm.example" }
}'
```
```bash Unassigned theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id}/tasks \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "title": "Check the policy number" }'
```
```json 201 theme={null}
{
"id": "2c7e2ddd-ece1-4c38-9c2d-47aaaf50be97",
"created_at": "2026-08-31T10:12:04.100Z",
"case": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
"type": "manual",
"title": "Call the client back",
"description": "The client asked for a callback before Friday.",
"status": "open",
"due_at": "2026-09-04T00:00:00.000Z",
"completed_at": null,
"step_key": null,
"assignee": {
"kind": "member",
"id": "5f7e2c17-e9be-47c9-8049-0b35d8eb0ada",
"email": "amina@firm.example",
"given_name": "Amina",
"family_name": "Berger"
}
}
```
```json 400 theme={null}
{
"statusCode": 400,
"error": "Bad Request",
"message": "Assignee with email \"nobody@firm.example\" not found in workspace"
}
```
# List Case Tasks
Source: https://docs.penbox.io/api-reference/tasks/list-case-tasks
GET /cases/{id}/tasks
List the follow-up tasks of a case
List the tasks of a case, oldest due date first.
A task is a follow-up: something one person has to do before the case can move on.
Every task belongs to exactly one **side**, told by `assignee.kind`:
| `assignee.kind` | Whose job it is | Closed by |
| - | - | - |
| `member` | someone on the team | the team, or your integration |
| `contact` | the client | submitting the form Penbox sent them |
| `null` (unassigned) | nobody yet | anyone on the team |
This list includes the tasks **Penbox creates by itself** when a form step moves —
"Complete the form" for the client, "Review the answers" for the team — so you can
mirror the real state of the case in your own product.
Tasks are scoped to the workspaces your token covers. A case in another workspace
returns an empty list rather than an error.
The response is not paginated and returns at most **100** tasks, oldest due date
first. A case is not expected to carry more.
```bash cURL theme={null}
curl --request GET \
--url https://connect.penbox.io/v1/cases/{id}/tasks \
--header 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"id": "9b1c4b2e-1f3a-4f8c-9c2d-47aaaf50be97",
"created_at": "2026-08-31T09:54:39.963Z",
"case": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
"type": "fill_form",
"title": null,
"description": null,
"status": "in_progress",
"due_at": "2026-09-07T00:00:00.000Z",
"completed_at": null,
"step_key": "ask_documents",
"assignee": {
"kind": "contact",
"id": "d322ce86-fb0a-4fc9-b45a-28758840108c",
"email": "client@example.com",
"given_name": "Judd",
"family_name": "Haley"
}
},
{
"id": "2c7e2ddd-ece1-4c38-9c2d-47aaaf50be97",
"created_at": "2026-08-31T10:12:04.100Z",
"case": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
"type": "manual",
"title": "Call the client back",
"description": "The client asked for a callback before Friday.",
"status": "open",
"due_at": "2026-09-04T00:00:00.000Z",
"completed_at": null,
"step_key": null,
"assignee": {
"kind": "member",
"id": "5f7e2c17-e9be-47c9-8049-0b35d8eb0ada",
"email": "amina@firm.example",
"given_name": "Amina",
"family_name": "Berger"
}
}
]
}
```
# Update Case Task
Source: https://docs.penbox.io/api-reference/tasks/update-case-task
PATCH /cases/{id}/tasks/{taskId}
Close, reopen, or reassign a follow-up task
Update a task of a case. Send `status` to close or reopen it, `due_at` to move its
deadline, `assignee` to hand it to someone else. At least one field is required.
## Statuses
| Key | Meaning |
| - | - |
| `open` | not started |
| `in_progress` | being worked on |
| `done` | finished |
| `dismissed` | closed without doing it |
`done` and `dismissed` both close the task and stamp `completed_at`. Setting `open`
or `in_progress` on a closed task reopens it and clears `completed_at`.
This works on any **team-side** task of the case, including the ones Penbox created
itself — so your integration can close a Penbox follow-up once your side has done
the work.
Tasks assigned to a **contact** are read-only through the API: they close when the
contact submits the form Penbox sent them. Updating one returns `403`, and so does
moving a team-side task onto a contact.
There is no delete. Removing a task stays a manual action inside Penbox. Use
`dismissed` for "this no longer needs doing".
The task must belong to the case in the path. A task id from another case returns
a `404`.
```bash Close it theme={null}
curl --request PATCH \
--url https://connect.penbox.io/v1/cases/{id}/tasks/{taskId} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "status": "done" }'
```
```bash Reassign theme={null}
curl --request PATCH \
--url https://connect.penbox.io/v1/cases/{id}/tasks/{taskId} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "assignee": { "email": "karel@firm.example" } }'
```
```bash Unassign theme={null}
curl --request PATCH \
--url https://connect.penbox.io/v1/cases/{id}/tasks/{taskId} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "assignee": null }'
```
```json 200 theme={null}
{
"id": "2c7e2ddd-ece1-4c38-9c2d-47aaaf50be97",
"created_at": "2026-08-31T10:12:04.100Z",
"case": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
"type": "manual",
"title": "Call the client back",
"description": "The client asked for a callback before Friday.",
"status": "done",
"due_at": "2026-09-04T00:00:00.000Z",
"completed_at": "2026-09-02T14:31:00.000Z",
"step_key": null,
"assignee": {
"kind": "member",
"id": "5f7e2c17-e9be-47c9-8049-0b35d8eb0ada",
"email": "amina@firm.example",
"given_name": "Amina",
"family_name": "Berger"
}
}
```
```json 404 theme={null}
{
"statusCode": 404,
"error": "Not Found",
"message": "Task with ID \"2c7e2ddd-ece1-4c38-9c2d-47aaaf50be97\" not found on this case"
}
```
# List Workspaces
Source: https://docs.penbox.io/api-reference/workspaces/list-workspaces
GET /workspaces
Retrieve all Penbox workspaces that the authenticated user has authorized your application to access.
Retrieve all Penbox workspaces that the authenticated user has authorized your application to access.
## Workspace Slug
The `slug` is a URL-safe, unique identifier for the workspace. It's used in API calls to specify which workspace you want to interact with.
**Slug format:**
* Lowercase letters, numbers, and hyphens
* No spaces or special characters
* Unique across all Penbox workspaces
**Examples:**
* `acme-corp`
* `my-company-123`
* `law-firm-llp`
## Multi-Workspace Support
If a user has authorized your application for multiple workspaces, this endpoint returns all of them. The access token grants access to all authorized workspaces.
# Provision Workspace
Source: https://docs.penbox.io/api-reference/workspaces/provision-workspace
POST /workspaces
Create a fully configured workspace for a client and receive an API token scoped to it
Create a fully configured Penbox workspace for one of your clients, seed it with case templates, register its admins, and receive an API token scoped to that workspace — in a single call. For the end-to-end flow, see [Onboard a Client](/guides/headless-onboard-client).
Workspace provisioning must be enabled on your account — talk to Penbox. A token without it is rejected with a `401`.
**Two silent admins are created.** The `admin` in the payload is your client's. Penbox also adds
your own support account, read from the `support_email` configured once on your partner
workspace — it is never sent here. Without one, the call still succeeds and says so in
`warnings`.
**The token is returned exactly once**, in the `201` response that creates the workspace. Penbox stores nothing but its hash — persist it before you do anything else.
## Idempotency
The call is idempotent on `integration.legalops.source_workspace_id`: one Penbox workspace per workspace on your side. Use the status code to tell a creation from a replay:
| Status | Meaning | `token` |
| - | - | - |
| `201` | The workspace was created | Present, once |
| `200` | The workspace already existed | Absent |
Provisioning never fails halfway: an optional step that did not complete is reported in the `warnings` array, not as an error.
# AI Generated Fields
Source: https://docs.penbox.io/cases/ai-generated-fields
Let AI keep case data up to date for you
AI generated fields are a way for Penbox to keep your case data up to date automatically. Instead of a team member re-reading a form response or a document to fill in a field by hand, the AI does it: it reads everything already on the case and writes a structured value into the field you configured.
AI generated fields live on top of the regular [data schema](/cases/data_schema) — a generated field is a normal field with an AI job attached to it. It can be referenced in steps, automations, and penscript exactly like any other field.
## How it works
For each AI generated field, you configure three things:
* **The field.** Which data point the AI should maintain, and its type (text, number, choices, etc.).
* **The instructions.** A plain-language description of what the field should contain — a summary, a classification, a derived score.
* **The trigger.** The event that makes the AI run: for example, an intake form being completed, a document being uploaded, or a status change.
When the trigger fires, Penbox gathers everything already on the case — forms, contacts, documents, and existing data — and writes a structured value into the field.
**Common uses:**
* Summarize a claim as soon as the intake form is completed.
* Classify a new case into a category and route it to the matching case template.
* Derive a risk level or priority from the answers a client submitted.
## Generated values are always labeled
Every value written by the AI carries an **AI badge** in the case data panel, so anyone working on the case can tell which values were generated and which were entered by a person.
Editing a generated field replaces the AI value with yours. From that point on, the field is treated as manual: the AI will not overwrite it again, even if the trigger fires again.
Use AI generated fields for data you want kept current without babysitting it, and let manual edits take over whenever a human needs to correct or refine the value.
## Configuring AI generated fields
AI generated fields are configured on [case templates](/cases/case_templates), through the [case template assistant](/agent/templates/case-templates). Describe the job in plain language and it sets up the trigger, the target field, and the instructions for you — for example:
> "Summarize the claim into `claim_summary` as soon as the intake form is completed."
> "Classify the case into `case_category` based on the intake form answers, and route it to the matching case template."
You can also set up the same behavior manually from the [case automations builder](/cases/automations#fill-data-with-ai): add an automation with the **Fill data with AI** action, pick the fields to fill, and describe what the AI should write into each.
AI generated fields are configured per case template. Cases created from a template inherit its AI generated fields, the same way they inherit the rest of the data schema.
## Availability
AI generated fields are available today in all workspaces.
***
## Next Steps
Fields, sections, and visibility
Other ways cases update without manual intervention
Reusable blueprints for recurring case types
Configure AI generated fields with Penbox Agent
# Automations
Source: https://docs.penbox.io/cases/automations
The rules that make cases work without manual intervention
Automations are the rules that make cases work without manual intervention. They enable intelligent workflows by automatically executing actions when specific conditions are met — moving cases forward, revealing next steps, and integrating with external systems.
Four automation types power case workflows: status transitions (automatically move from one status to another), step visibility rules (show or hide steps based on case evolution), automatic step execution (trigger steps when conditions are met), and post-automations (send data to external systems via API or n8n when conditions are met).
## Status Transitions
Status transitions automatically move a case from one status to another when conditions are met, eliminating manual status updates and ensuring consistent workflow progression.
**How status transitions work:**
* Monitor case data for changes
* Evaluate conditions when relevant data updates
* Automatically update case status when condition is true
* Log the transition in case timeline
* Can trigger additional automations
**Common status transition patterns:**
**Move to "Ready for Review" when all documents uploaded:**
* Watch: Document upload fields
* Condition: All required documents have values
* Action: Change status to "Ready for Review"
**Move to "Awaiting Payment" when quote approved:**
* Watch: Quote approval field
* Condition: Approval equals "approved"
* Action: Change status to "Awaiting Payment"
**Move to "Closed - Completed" when final signature received:**
* Watch: Signature field
* Condition: Signature is defined
* Action: Change status to "Closed - Completed"
Status transitions eliminate the need for team members to manually update status, ensuring cases progress consistently and nothing falls through the cracks.
[Learn more about Statuses →](/cases/statuses_lifecycle)
## Step Visibility Rules
Step visibility rules hide or reveal steps based on case evolution, showing team members only the actions that are relevant to the current case state.
**How step visibility works:**
* Steps can be hidden by default
* Conditions determine when steps become visible
* Based on case data, status, or other factors
* Steps appear in the case when conditions are met
**Common visibility patterns:**
**Show "Request Additional Documents" only when initial review incomplete:**
* Condition: Review status equals "incomplete"
* Effect: Step appears for case manager to request more documents
**Show "Premium Service Options" only for high-value customers:**
* Condition: Annual revenue greater than threshold
* Effect: Step appears to offer premium services
**Show "Compliance Review" only for regulated industries:**
* Condition: Industry in regulated list
* Effect: Step appears for compliance workflow
**Show "Multi-Signature Workflow" only when multiple signers needed:**
* Condition: Number of signers greater than 1
* Effect: Multi-signature step appears
Step visibility rules keep case workflows clean by showing only relevant actions, reducing confusion and ensuring team members focus on what matters.
## Automatic Step Execution
Automatic step execution triggers a step when specific conditions are met, enabling fully automated workflows that respond to case data changes.
**How automatic execution works:**
* Monitor case data for changes
* Evaluate conditions when data updates
* Automatically execute the step (send email, SMS, form) when condition is true
* Step appears in timeline as executed
* Contact receives communication automatically
**Common automatic execution patterns:**
**Send reminder email if no response after 3 days:**
* Watch: Form sent date, form response status
* Condition: 3 days elapsed and no response received
* Action: Execute "Reminder Email" step
**Send approval request when all documents collected:**
* Watch: Document fields
* Condition: All required documents uploaded
* Action: Execute "Send Approval Form" step
**Send welcome email when case status changes to "Active":**
* Watch: Case status
* Condition: Status equals "Active"
* Action: Execute "Welcome Email" step
**Trigger compliance check when high-risk flag set:**
* Watch: Risk assessment field
* Condition: Risk level equals "high"
* Action: Execute "Compliance Review Form" step
Automatic step execution sends communications to contacts automatically. Test conditions thoroughly to ensure emails, SMS, and forms are sent at the right time.
## Post-Automations
Post-automations send data to external systems via API or n8n when conditions are met, enabling seamless integration between Penbox and back-office systems.
**How post-automations work:**
* Monitor case data for changes
* Evaluate conditions when data updates
* Send HTTP request to external system when condition is true
* Log request and response in timeline
* Can retry on failure
**Common post-automation patterns:**
**Send to CRM when case status changes to "Closed":**
* Watch: Case status
* Condition: Status equals "Closed"
* Action: POST to CRM API with case data
* Payload: Case ID, customer data, outcome
**Trigger n8n workflow when signature collected:**
* Watch: Signature field
* Condition: Signature defined
* Action: POST to n8n webhook
* Payload: Signed document, case details
**Update accounting system when invoice approved:**
* Watch: Invoice approval field
* Condition: Approval equals "approved"
* Action: POST to accounting API
* Payload: Invoice details, amounts, dates
**Send to document management system when case closed:**
* Watch: Case status
* Condition: Status equals "Closed"
* Action: POST documents to DMS
* Payload: All case documents and metadata
Post-automations enable Penbox to act as the intelligent interaction layer while seamlessly integrating with existing back-office systems via API.
## AI-Specific Automations
Penbox Intelligence enables AI-powered automations for email drafting and data extraction.
### Email Drafting Prompts
Configure an email drafting prompt so Intelligence prepares draft responses to incoming emails automatically.
**How it works:**
* Define a prompt that tells Intelligence how to draft responses
* When emails arrive, Intelligence analyzes the content
* Draft response is prepared based on your prompt
* Draft appears in case timeline for review before sending
**Example prompts:**
**Customer support:**
```text theme={null}
Draft a professional response acknowledging the customer's inquiry,
confirming we've received their message, and explaining the next steps
in our process. Maintain a friendly, helpful tone.
```
**Claims processing:**
```text theme={null}
Draft a response confirming we've received the claim, listing what
documents we still need, and providing an estimated timeline for review.
Be empathetic and professional.
```
**Best practices for prompts:**
* Be specific about tone and style
* Define what information should be included
* Specify any compliance requirements
* Mention if certain phrases should be avoided
[Learn more about Intelligence →](/intelligence/introduction)
### Fill Data with AI
The **Fill data with AI** action uses Penbox Intelligence to write values into existing case-data fields when the automation runs. It is the manual, visual counterpart to [AI generated fields](/cases/ai-generated-fields): instead of describing the job to the case template assistant, you configure the action directly in the automations builder.
**How it works:**
* Add an automation and choose the **Fill data with AI** action.
* (Optional) Add **custom instructions** — case-wide context for the AI, such as tone, language, or case type.
* Add one or more **output fields**: pick an existing case-data field and describe, in plain language, what the AI should write into it.
* When the automation's trigger fires (a watched field changes or a condition is met), Penbox reads everything already on the case and writes a structured value into each output field.
**Example — compare two fields:**
* Watch: `data.data_1`, `data.data_2`
* Custom instructions: "Compare the two data fields."
* Output field `match`: "Return true if `data_1` equals `data_2`, otherwise false."
Values written by this action carry the same **AI badge** as other AI generated fields, and a manual edit takes the field over from then on.
Use **Fill data with AI** when you want to configure an AI fill yourself in the automations builder. For a guided setup, describe the job to the [case template assistant](/agent/templates/case-templates) instead.
## Automation Execution
**When automations run:**
* Automations evaluate whenever case data changes
* Watched fields (if specified) trigger evaluation when they change
* Conditions are evaluated against current case data
* Actions execute when condition evaluates to true
**Execution tracking:**
* All automation executions appear in case timeline
* Shows automation name, timestamp, and outcome
* Success or failure status displayed
* Full execution details available on click
* Can retry failed automations
**Performance considerations:**
* Watch specific fields to reduce unnecessary evaluations
* Use execute\_once for one-time transitions
* Test conditions before deploying to production
## Common Patterns
### Sequential Workflow
Combine status transitions and step execution to create sequential workflows:
1. Form completed → Status: "Under Review"
2. Status "Under Review" → Execute "Request Documents" step
3. Documents uploaded → Status: "Ready for Approval"
4. Status "Ready for Approval" → Execute "Send Approval Form" step
5. Approval received → Status: "Closed - Approved"
### Conditional Branching
Use step visibility and execution for different paths:
**If customer type is "Enterprise":**
* Show "Enterprise Onboarding" steps
* Execute "Assign Account Manager" step
* Send to enterprise CRM endpoint
**If customer type is "Standard":**
* Show "Standard Onboarding" steps
* Execute "Send Welcome Email" step
* Send to standard CRM endpoint
### Integration Workflow
Combine multiple automation types for complete integration:
1. Data collected → Post to validation API
2. Validation passes → Status: "Validated"
3. Status "Validated" → Execute "Send Contract" step
4. Contract signed → Post to accounting system
5. Accounting updated → Status: "Closed - Complete"
***
## Next Steps
Configure automations in templates
Understand status transitions
Learn about automatic step execution
Define data for automation conditions
# Case Creation
Source: https://docs.penbox.io/cases/case_creation
The four ways cases come into existence
Cases can be created in four different ways, depending on your workflow. Each method serves different use cases and provides different defaults and configuration options.
## Manually in Penbox
Create a case directly from the Penbox app. This is the most common method for internal processes.
**What's required:**
* At least one main contact (can be added during creation or immediately after)
* Optionally select a case template
**What happens:**
* Case appears immediately in your case list
* If a template is selected, the case inherits the template's structure (fields, sections, contacts, steps, automations)
* If no template is selected, case starts blank and you build the structure as needed
* Main contact can be selected from existing contacts or created as new
* Case owner defaults to the creating user but can be changed
**Defaults applied:**
* Status: Draft
* Owner: Creating user
* Waiting For: None
* Reference: Auto-generated 6-character code
**Best for:**
* Customer onboarding
* Project kickoffs
* Internal workflows
* Processes that require manual oversight
Cases don't require a template. You can create a blank case and add fields, sections, and contacts as you go. For recurring workflows, templates save time by pre-configuring the structure.
## From an Incoming Email
Automatically create a case when an email arrives in a connected mailbox. Works with Email Intelligence or rule-based email routing.
### With Email Intelligence
When Email Intelligence labels an incoming email with the "In Penbox" trigger, a case is automatically created with the email content and sender as context.
**What's required:**
* Connected mailbox (Gmail or Outlook)
* Email Intelligence enabled
* "In Penbox" label configured
**What happens:**
* Email sender automatically becomes the main contact
* Email body and subject are captured in the case
* Any attachments are added to the case
* Case title can be auto-generated by AI based on email content
* Email appears in the case timeline
**Defaults applied:**
* Status: Pending
* Owner: Assigned based on workspace rules or unassigned
* Waiting For: Owner
* Reference: Auto-generated
### With Rule-Based Routing
Without Intelligence, cases can be created from emails sent to a dedicated mailbox (e.g., [support@yourcompany.com](mailto:support@yourcompany.com)).
**What's required:**
* Dedicated mailbox configured
* Email routing rule set up
**What happens:**
* Every email to the address creates a case
* Email sender becomes the main contact
* Email content captured in timeline
**Best for:**
* Support tickets
* Customer inquiries
* Claims submissions via email
* High-volume intake workflows
## From a Completed Form
When a form linked to case creation is completed, a case is automatically generated with the collected data.
**What's required:**
* Form template configured with "Create case on completion" setting
* Form must be sent and completed by a contact
**What happens:**
* Case is created immediately when form is marked complete
* Form respondent automatically becomes the main contact
* All form data is mapped to case fields (based on configuration)
* Form appears in the case timeline as the first event
* If configured, automations can trigger based on form data
**Defaults applied:**
* Status: Configurable (typically Pending or In Progress)
* Owner: Assigned based on form configuration or workspace rules
* Waiting For: Configurable
* Reference: Auto-generated
**Configuration options:**
* Which case template to use (or blank case)
* Default status for new cases
* Default owner assignment
* Field mapping (form elements to case fields)
* Initial automations to trigger
**Best for:**
* Customer intake forms
* Claims reporting
* Support request forms
* Application submissions
* Lead generation forms
Form-to-case creation is one of the most powerful features in Penbox, enabling external contacts to initiate cases directly through public forms.
## Via API
Create cases programmatically from external systems, enabling Penbox to serve as the intelligent interaction layer for back-office workflows.
**What's required:**
* API key with case creation permissions
* Minimum: main contact information (email or phone)
* Optionally: case template reference, initial data, owner assignment
**What happens:**
* Case is created via HTTP POST request to `/cases` endpoint
* Full control over all case properties
* Can pre-populate any case data
* Can assign owner, status, and contacts programmatically
* Returns case reference and ID for tracking
**Request parameters:**
* `template_id` - Optional case template to use
* `main_contact` - Contact information (email, phone, name)
* `data` - Initial case data (key-value pairs)
* `status` - Initial status (defaults to Draft)
* `owner_id` - Assign to specific team member
* `secondary_contacts` - Additional contacts with roles
**Best for:**
* Integration with CRM systems
* Automated case creation from webhooks
* Bulk case imports
* Connecting legacy systems to Penbox
* Building custom intake portals
**Example use cases:**
* E-commerce platform creates case when order requires follow-up
* CRM system creates case when lead reaches certain stage
* Payment processor creates case when dispute is filed
* HR system creates case for onboarding new employees
API creation enables Penbox to act as the intelligent interaction layer between your contacts and back-office systems, handling all communication while integrating seamlessly with existing tools.
[View API Documentation →](/api-reference/cases/create-case)
***
## Next Steps
Learn about cases and their structure
Design reusable templates
Understand workflow steps
API documentation
# Case Templates
Source: https://docs.penbox.io/cases/case_templates
Reusable blueprints for recurring case types
A case template is a reusable blueprint for recurring case types. Templates pre-configure the steps, contacts, data schema, automations, and statuses that a new case will start with. When you create a case from a template, the entire structure is applied instantly.
A case does not require a template — templates exist to save time on repeating workflows. You can create a blank case and build it as you go, or use templates to ensure consistency across similar cases.
Templates are the design-time artifact (the reusable pattern), while cases are the runtime instances (the actual work items).
## What Templates Define
Templates pre-configure every aspect of a case:
**Data schema:**
* Fields and their types (text, number, date, file, etc.)
* Sections organizing related fields
* Visibility settings for each field
* AI descriptions for Intelligence extraction
* Default values
**Contacts:**
* Main contact requirements
* Secondary contact roles (broker, expert, partner, etc.)
* Contact keys for referencing in steps
**Steps:**
* Predefined emails, SMS, and forms
* Step sequence and dependencies
* Conditional visibility rules
* Templates for email content
**Statuses:**
* Custom statuses for your workflow
* Status hierarchy and parent statuses
* Automatic transition conditions
**Automations:**
* Status transitions based on conditions
* Step visibility rules
* Automatic step execution
* Post-automations to external systems
When you create a case from a template, all this structure is applied instantly. Individual cases can then be customized without affecting the template.
## Creating Case Templates
Case templates are created using the same interface as regular cases. Templates are themselves cases with a special flag (`is_template: true`), which means:
* You use the same interface to design templates as you do to work with cases
* Templates can be tested like real cases
* What you see when designing is what users see when working
**Basic template information:**
* **Title** - Name shown when selecting template
* **Description** - What this template is for and when to use it
* **Locale** - Default language for the case
For compliance-heavy workflows, use the description to document regulatory requirements, guiding team members on what the case type must meet.
## Naming and Managing Templates
**Creating templates:**
1. Create a new case and mark it as template
2. Design the data schema, contacts, steps, and automations
3. Test the template by creating test cases
4. Publish for team use
**Duplicating templates:**
* Clone existing templates to create variations
* Useful for similar workflows with minor differences
* Maintains original template while creating new version
**Managing templates:**
* Templates can be updated at any time
* Changes don't affect existing cases created from the template
* Future cases use the updated template structure
Changes to templates only affect new cases created after the change. Existing cases maintain their original structure.
## Template Structure Examples
### Customer Onboarding Template
**Data schema sections:**
* Company Information (name, registration, industry)
* Contact Details (email, phone, address)
* Financial Data (revenue, IBAN, tax ID)
* Documents (registration, ID, proof of address)
**Contacts:**
* Main Contact (customer representative)
* Billing Contact (for invoicing)
**Steps:**
1. Welcome Email - Introduce process
2. KYC Form - Collect customer information
3. Document Request - Request required documents
4. Compliance Review - Internal approval form
5. Welcome Package - Send final confirmation
**Statuses:**
* Pending → In Progress → Compliance Review → Approved → Closed
**Automations:**
* Move to "Compliance Review" when all documents uploaded
* Send reminder if no response after 3 days
* Post to CRM when status changes to "Closed"
### Claims Processing Template
**Data schema sections:**
* Claim Information (date, type, description)
* Claimant Details (name, policy number, contact)
* Incident Details (location, witnesses, police report)
* Financial (claim amount, deductible)
* Documents (photos, reports, receipts)
**Contacts:**
* Main Contact (claimant)
* Witness (optional secondary contact)
**Steps:**
1. Claim Acknowledgment - Confirm receipt
2. Claim Declaration Form - Detailed claim info
3. Supporting Documents Form - Upload evidence
4. Assessment Request - Internal review
5. Decision Email - Communicate outcome
**Statuses:**
* Submitted → Under Review → Investigation → Decision → Closed
**Automations:**
* Move to "Investigation" when claim amount > threshold
* Assign to specialist when claim type is complex
* Send to payment system when approved
## Templates and Individual Cases
**When creating a case from a template:**
* Case inherits all template structure
* Data schema, contacts, steps, statuses copied
* Case can be customized independently
* Changes to case don't affect template
**Customizing individual cases:**
* Add fields specific to this case
* Modify sections for unique needs
* Add or remove contacts as required
* Adjust steps for special circumstances
This approach combines the efficiency of templates with the flexibility to handle exceptions and special situations.
Use templates for standardized processes to ensure consistency. Use individual modifications for unique situations that need customization.
## Best Practices
**Design for your actual process:**
* Map your workflow before creating the template
* Define statuses that match real stages
* Include all data you need to collect
* Plan for edge cases and exceptions
**Keep templates maintainable:**
* Use clear, descriptive names for fields and steps
* Document why each field exists
* Add help text for complex fields
* Use AI descriptions for Intelligence features
**Test before deploying:**
* Create test cases from the template
* Execute all steps to verify they work
* Test automations with sample data
* Validate forms and emails render correctly
**Plan for compliance:**
* Document regulatory requirements in description
* Include audit trail requirements
* Define mandatory fields for compliance
* Set appropriate visibility settings
**Optimize for users:**
* Group related fields in sections
* Use "hidden if empty" for optional fields
* Provide clear step instructions
* Set helpful default values
***
## Next Steps
Learn about cases
Design case data structures
Configure workflow steps
Set up automations
# Contacts
Source: https://docs.penbox.io/cases/contacts
The people involved in a case
Contacts are the people involved in a case. Every case has a **Main Contact** — the primary individual the case is about. Cases can also have **Secondary Contacts** — additional stakeholders like brokers, experts, partners, or opposing parties.
Each contact is identified with a unique key when defining the case, which allows the system to reference them in steps, notifications, and data throughout the platform.
## Main Contact
The main contact is the primary individual a case is about and the primary recipient for all external communications.
**Every case requires a main contact.** The main contact:
* Receives forms sent from the case
* Receives email communications and notifications
* Is the primary point of contact for the matter
* Can be an individual person or organization representative
* Must have at least an email address or phone number to receive communications
A case without a main contact cannot send forms or communications to external parties. Always add a main contact to enable full case functionality.
**Main contact information:**
* **Name** - Full name of the individual
* **Email** - Primary email address (required for email communications)
* **Phone** - Phone number (required for SMS communications)
* **Language** - Preferred communication language
* **Organization** - Optional company or organization name
* **Additional fields** - Custom fields based on your workspace configuration
When a case is created from a form submission or incoming email, the sender's information is automatically added as the main contact.
## Secondary Contacts
Secondary contacts are additional stakeholders involved in the case beyond the main contact. These can include:
**Common secondary contact roles:**
* **Brokers** - Insurance brokers, real estate agents, financial advisors
* **Experts** - Technical experts, appraisers, medical professionals
* **Partners** - Business partners, co-applicants, joint account holders
* **Legal representatives** - Lawyers, guardians, trustees
* **Billing contacts** - Separate contact for invoicing and payments
* **Technical contacts** - IT contacts, system administrators
* **Opposing parties** - In legal or dispute cases
Each secondary contact can have a specific role that defines their involvement in the case.
**Secondary contact configuration:**
* **Role** - Defines the contact's relationship to the case
* **Key** - Unique identifier for referencing in steps and automations
* **Contact information** - Same fields as main contact
* **Permissions** - What they can see or do (if applicable)
Use secondary contacts to involve multiple stakeholders in a case while maintaining clear roles and responsibilities.
## Contact Keys
Each contact (main and secondary) is identified with a unique key when defining the case. This key system allows the platform to reference contacts in various contexts:
**Where contact keys are used:**
* **Steps** - Reference which contact receives an email or form
* **Notifications** - Specify who gets notified about case events
* **Data fields** - Reference contact information in case data
* **Email templates** - Insert contact details dynamically
* **Automations** - Trigger actions based on contact responses
**Key naming:**
* Main contact typically uses the key `main`
* Secondary contacts use descriptive keys like `broker`, `expert`, `partner`, `billing`
* Keys must be unique within a case
* Keys are defined in case templates or when adding contacts to individual cases
Contact keys are explained conceptually here. For the technical notation and variable syntax, see the penscript documentation.
## Assigning Contacts
Contacts can be assigned to a case in several ways:
### Select Existing Contact
Choose from contacts already in your workspace:
* Search by name, email, or organization
* View contact history and previous cases
* Ensures data consistency across cases
* Maintains single source of truth for contact information
### Create New Contact
Add a new contact directly when creating or updating a case:
* Enter contact information manually
* Contact is added to workspace contact database
* Available for future cases
* Can be updated centrally
### Automatic Assignment
Contacts are automatically assigned in certain scenarios:
* **From form submission** - Form respondent becomes main contact
* **From incoming email** - Email sender becomes main contact
* **Via API** - Contact information provided in API request
### Bulk Import
For campaigns or large case imports:
* Upload CSV file with contact information
* Map columns to contact fields
* Create multiple cases with pre-assigned contacts
* Useful for annual updates or mass communications
## Language Preferences
Each contact can have a preferred communication language. This affects:
**Form language:**
* Forms sent to the contact appear in their preferred language
* Form templates must have translations available
* Automatic language selection based on contact preference
**Email language:**
* Email templates can have multiple language versions
* System selects appropriate version based on contact language
* Ensures professional communication in contact's language
**Supported languages depend on your workspace configuration.**
Set contact language preferences early to ensure all communications are sent in the correct language from the start.
## How Contact Information Flows
Contact information flows through the platform in several ways:
### In Steps
When sending forms or emails:
* Select which contact receives the communication
* Contact's email or phone is automatically used
* No need to re-enter contact information
* Changes to contact details automatically reflect in future communications
### In Data Fields
Case data can reference contact information:
* Pull contact name into document templates
* Use contact email for automated notifications
* Reference contact organization in reports
* Maintain consistency across all case materials
### In Notifications
Automations can notify specific contacts:
* Send confirmation emails to secondary contacts
* Notify brokers when status changes
* Alert partners when documents are signed
* Configure per contact role
### In Reports
Contact information appears in case reports:
* Filter cases by contact
* View all cases for a specific contact
* Track contact interactions across cases
* Analyze contact engagement
## Managing Contacts
**Updating contact information:**
* Changes to workspace contacts affect all future communications
* Existing case timeline preserves original contact info (audit trail)
* Update in one place, applies to new interactions
**Removing contacts:**
* Secondary contacts can be removed from cases
* Main contact cannot be removed (case requirement)
* Removed contacts remain in timeline history
**Contact privacy:**
* Contact information is stored securely
* Access controlled by workspace permissions
* Complies with data protection requirements
* Can be anonymized or deleted per retention policies
***
## Next Steps
Learn about cases and main contacts
Send communications to contacts
Reference contact information in data
Define contact roles in templates
# Data Schema Overview
Source: https://docs.penbox.io/cases/data_schema
The structured data a case collects
A data schema defines what information the case tracks — organized into sections containing individual data points. Each data point has a type (Text, Number, Currency, Date, File, Multiple Choice, etc.) and visibility settings.
Cases created from templates inherit the template's data schema. Cases created from scratch start with a blank schema. You can modify a case's data schema at any time by adding, modifying, or removing fields and sections. Structure changes apply only to that individual case and do not affect the template.
Each data point has a unique key that can be referenced throughout the
platform. Keys are explained conceptually here — for the technical notation
and variable syntax, see the penscript documentation.
## Field Types
Cases support 10 field types, each with specific configuration options and use cases. Click any field type below to see detailed configuration, examples, and best practices.
Single or multi-line text input for names, descriptions, and IDs
Numeric values for quantities, scores, and measurements
Monetary values with currency formatting for financial amounts
Date picker for birth dates, deadlines, and timestamps
Single yes/no option for agreements and consent flags
Multiple selections for services, features, and categories
Single selection for country, priority, and status
File upload for documents, images, and contracts
Digital signatures with authentication for legally binding agreements
External API data fetch for credit checks and verification
## Field Properties
Each field in a case has several properties:
| Property | Description | Example |
| - | - | - |
| **Key** | Unique identifier | `company_name`, `birth_date` |
| **Type** | Field data type | `text`, `number`, `date` |
| **Name** | Display label | "Company Name", "Date of Birth" |
| **Description** | Help text | "Legal name of your company" |
| **Value** | Current data | "Acme Corp", "1990-01-15" |
| **Visibility** | Display setting | Always, hide when empty, always hide |
| **Section** | Grouping | "Company Information" section |
## Visibility Settings
Fields can have different visibility settings to control when they appear:
**Always visible** - Field always appears in the case view, whether it has a value or not. Use for essential fields, required information, and key data points.
**Hidden if empty** - Field only shows when it has a value. Empty fields are hidden. Use for optional fields, conditional data, and supplementary information. This keeps case views clean and focused on relevant information.
**Always hidden** - Field is hidden from view but data is still stored. Use for technical fields, IDs, system data, and calculated values used in automations.
Use "hidden if empty" for optional fields to keep the case view uncluttered
while maintaining complete data storage for compliance.
## Sections
Sections organize related fields together, making cases easier to navigate and understand. Sections are groups of fields with a common purpose or theme.
**Example case structure:**
```
📁 Company Information
- Company Name (text)
- Registration Number (text)
- Industry (choices)
- Website (text)
📁 Financial Data
- Annual Revenue (number)
- IBAN (text)
- Tax ID (text)
📁 Documents
- Company Registration (file)
- ID Document (file)
- Proof of Address (file)
```
**Benefits of sections:**
* **Organization** - Group related fields logically
* **Navigation** - Easier to find specific information
* **Clarity** - Clear separation of different data types
* **Presentation** - Better visual organization
* **Workflow** - Align sections with process steps
Sections are defined in the case template. You cannot add or remove sections
from existing cases, but you can add or remove fields within sections.
## Data Updates
Case data can be updated through multiple channels:
### Manual Updates
Team members can update case fields directly:
* Edit fields in the case view
* Change values as needed
* Updates are tracked in timeline
* Changes can trigger automations
### Form Responses
When contacts submit forms, data flows into the case:
* Form fields map to case fields (based on configuration)
* Responses automatically update case data
* Files are attached to case
* Timeline shows form submission
### Automations
Automated workflows can update fields:
* Calculated values based on other fields
* Status updates based on conditions
* Data transformations
* External API responses
### API Call Fields
API Call fields fetch data from external sources:
* Credit checks from financial services
* Company data from business registries
* Verification services
* Real-time data lookups
## Data Validation
Field values are validated based on their type:
| Field Type | Validation |
| - | - |
| **Text** | Length limits, pattern matching |
| **Number** | Numeric values, min/max ranges |
| **Date** | Valid dates, date ranges |
| **Checkbox** | Boolean (true/false) |
| **Choices** | Must be from defined options |
| **File** | File type, size limits |
Validation rules are defined in the case template and cannot be changed for
individual cases.
## Keys and References
Each data point has a unique key that identifies it throughout the platform. These keys allow you to:
* Reference data in steps and automations
* Map form responses to case fields
* Use data in email and document templates
* Create calculated fields based on other data
* Trigger automations based on data changes
Keys are typically lowercase with underscores (e.g., `company_name`, `annual_revenue`, `birth_date`) and must be unique within the case template.
Keys are described conceptually here. For the full technical syntax including
dot notation and variable references, see the penscript documentation.
***
## Next Steps
Design data schemas in templates
Learn about case contacts
Automate based on data changes
Collect data through forms
# API Call Field
Source: https://docs.penbox.io/cases/data_schema/api_call
Call an external API from a case and write the response into case fields
The API Call field (`type: "http"`) calls an external API and stores the response on the case. With the optional `mapping`, parts of the response are written into other case fields — credit scores, company data verification, address lookups, vehicle registrations, or any external data source with an HTTPS API.
A team member runs the call from the case view (the **Run** button on the field); the response and its status are stored on the field itself, and mapped values land in the target fields immediately.
## When to Use
**Use API Call fields for:**
* Credit score checks
* Company data verification (registration, VAT validation)
* Address validation and geocoding
* Bank account verification (IBAN validation)
* Vehicle registration lookups
* API-based enrichment services
**Consider alternatives:**
* Use **Text**, **Number**, or other fields for manual data entry
* Use **case automations** (`http` action) to call an API automatically when case data changes — the API Call field itself only runs on demand
* Use webhooks for pushing data to external systems
## Configuration
A field entry in the case schema:
| Option | Description | Type | Default |
| - | - | - | - |
| `key` | Unique identifier | String | Required |
| `name` | Display label | String | Required |
| `description` | Help text | String | Optional |
| `type` | Must be `"http"` | String | Required |
| `options` | The API call configuration (below) | Object | Required to run |
| `visibility` | `always-visible`, `hide-when-empty`, `always-hide` | String | `always-visible` |
| `section` | Section this field belongs to | String | Optional |
### `options`
| Property | Description | Type |
| - | - | - |
| `url` | HTTPS endpoint (required to run). Supports expressions | String |
| `method` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | String (default `GET`) |
| `headers` | Request headers | Object |
| `body` | Request body, for `POST`/`PUT`/`PATCH` | Any |
| `params` | Query-string parameters | Object |
| `bearer` | Bearer token (sets the `Authorization` header) | String |
| `basic` | Basic-auth credentials | String |
| `accept` | `Accept` header override | String |
| `ct` | `Content-Type` header override | String |
| `responseMode` | `full_ok` (default): a non-2xx marks the field in error. `full`: any status is stored as a normal response | String |
| `payloadType` | How the response body is read: `parsed` (default), `text`, `json`, `data-uri`, `blob` | String |
| `mapping` | Writes response values into other case fields (below) | Object |
| `loadingText` | Label shown while the call runs | String |
Every option value may contain expressions resolved against the case at run time: `{data.vat_number}`, `{contacts.main.email}`, and company secrets via `{$secrets.my_api_key}` (never hardcode credentials).
**Unknown option keys are rejected.** Adding an option Penbox does not know — `response_mapping`, `api_config`, `trigger` — fails with a validation error naming the key and pointing at it. The check fires only on keys you *add*: a configuration that already carries a legacy key stays savable, so an unrelated edit never bricks an existing case. A few legacy aliases (`uri`, `json`, `responseType`) are also still accepted for configurations that use them.
An earlier version of this page documented `api_config`, `trigger`, `retry`, `cache_duration`, `auth` and `response_mapping`. Those options never existed and are now rejected at save time. Use the flat `options` object above, and `mapping` instead of `response_mapping`.
## Response Mapping
Without a `mapping`, the response is only stored on the API Call field itself. With one, parts of the response are also written into other case fields — visible in the case immediately, recorded in the case history, and able to trigger automations like any other field update.
Inside mapping values, the parsed response body is available as `@payload`:
```json theme={null}
{
"key": "vat_check",
"type": "http",
"name": "VAT validation",
"options": {
"url": "https://ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number",
"method": "POST",
"body": { "vatNumber": "{data.vat_number}", "countryCode": "{data.country}" },
"mapping": {
"data": {
"company_name": "{@payload.traderName}",
"company_address": { "value": "{@payload.traderAddress}", "replace": false }
}
}
}
}
```
Rules:
* **Targets must be existing field keys** in the case schema. The mapping writes values; it never creates fields. Unwritable targets are skipped (`mapping_skipped`), while valid targets are still written.
* **Two equivalent shapes**: nested `{ "data": { "field": … } }` or flat `{ "data.field": … }`.
* **Values are expressions** — they can read `@payload` but also any case data (`{data.other_field}`).
* **`{ "value": …, "replace": false }`** skips the write when the target already holds a non-empty value. This is the same vocabulary as the form API element's `mapping`.
* A mapping value pointing at a missing response path writes nothing and is reported as unresolved (`mapping_unresolved`) — a mistyped `@payload` path is the most common cause of "the API call worked but the case stayed empty".
After a run, the field itself says how many entries were ignored, whatever the cause. The dot stays green when the call succeeded and at least one entry was written, and turns amber when nothing was written at all. Click the field to see which entries and why.
### Mapping error responses
APIs often return useful bodies on failure (e.g. validation errors with a `400`). The response body is stored even when the call fails, so `@payload` works on the error path too. If you want non-2xx statuses treated as normal responses instead of errors, set `"responseMode": "full"`.
### Per-field error messages
When an API rejects one of the values you sent, it answers with a message about that value. The `errors` root puts that message under the field it is about, instead of leaving it inside the stored response:
```json theme={null}
"mapping": {
"data": { "company_name": "{@payload.traderName}" },
"errors": { "chassisnummer": "{@payload.errors.vin}" }
}
```
The `chassisnummer` row then shows the message in red underneath it, and the field's status reads `1 rejected`.
Rules:
* **Same target rules as `data`**: the key must already exist in the case schema, and it cannot be the API Call field's own key. Bad targets are reported in `mapping_skipped` under the name you wrote (`errors.not_a_field`).
* **`errors` must be an object** to mean the error root. `"errors": "{@payload.x}"` still means "write into a case field literally keyed `errors`" — existing configurations are unaffected.
* **Values are expressions**, and each must resolve to a string or to a list of strings (joined with `, `).
* **A path that resolves to nothing produces no message.** This is the normal case: the same mapping serves the run where the API rejects the field and the run where it accepts it. Unlike a value entry, an unresolved error entry is *not* counted as unresolved and does not affect the field's status.
* **No `{ "value": …, "replace": false }` wrapper** here — an error message is always the last word on the field.
Error messages are **not case data**. They are stored on the API Call field under `field_errors`, so they never appear in the case history, never trigger automations, and are never served by the public API as if they were data about the dossier. The next run replaces them wholesale, and a run that rejects nothing clears them. A message also disappears as soon as a team member edits the row it sits under, because it describes the value that was just replaced.
## Stored value
After a run, the field holds:
```json theme={null}
{
"config": { "…": "the options used for this run" },
"response": { "…": "the parsed response body" },
"status_code": 200,
"status_message": "OK",
"error": null,
"executed_at": "2026-08-13T15:00:00.000Z",
"mapping_written": ["company_name"],
"mapping_skipped": ["data.not_a_field"],
"mapping_unresolved": ["data.company_address"],
"field_errors": { "chassisnummer": "VIN checksum invalid" }
}
```
`error` carries the HTTP error name on failure. The mapping keys only appear when there is something to report: `mapping_written` names the fields that were filled, `mapping_skipped` the targets that do not exist, `mapping_unresolved` the entries whose value expression resolved to nothing, and `mapping_error` a mapping that could not be evaluated at all. Click the field's status in the case view to inspect this payload.
`field_errors` is the odd one out: it is not a diagnostic about your configuration but the messages the API returned about the case's data, written by the [`errors` mapping root](#per-field-error-messages). It is keyed by field, and it is the only place those messages exist.
## Editing in the app
In the case view, the field's menu offers **Edit API Call**: method, URL, headers, body, and the response mapping as JSON. Options managed outside the modal (e.g. `responseMode`, `params`) are preserved when saving.
## Examples
### Vehicle registration push
Send case data to a registration service and capture returned errors on the case:
```json theme={null}
{
"key": "register_vehicle",
"type": "http",
"name": "Register vehicle",
"options": {
"url": "https://api.example-insurer.com/RegisterVehicle",
"method": "POST",
"headers": { "X-API-Key": "{$secrets.insurer_api_key}" },
"body": { "vehicle_vin": "{data.vehicle_vin}" },
"mapping": { "data": { "registration_errors": "{@payload.errors}" } }
}
}
```
### Company data enrichment
```json theme={null}
{
"key": "company_data",
"type": "http",
"name": "Company data",
"options": {
"url": "https://api.companyreg.com/v2/companies/{data.company_id}",
"method": "GET",
"bearer": "{$secrets.company_api_token}",
"mapping": {
"data": {
"legal_name": "{@payload.name}",
"registration_date": "{@payload.incorporationDate}"
}
}
}
}
```
## Best Practices
* **Declare the target fields first** — the mapping only writes into fields that already exist in the case schema.
* **Use `{$secrets.…}` for credentials** — never paste API keys into the configuration.
* **Use `replace: false`** for fields a team member may have filled manually and that the API should not overwrite.
* **Read the ignored count on the field** when a target stays empty — it names the entries that could not be written and why, so a mistyped `@payload` path is visible instead of silent.
# Checkbox Field
Source: https://docs.penbox.io/cases/data_schema/checkbox
Single yes/no option for agreements, consent, and binary choices
The Checkbox field captures a single yes/no or true/false value. Checkboxes are ideal for agreements, consent flags, feature toggles, and any binary decision where the user confirms or denies something.
Use Checkbox fields when you need a simple on/off value. Unlike Multiple Choice fields (which allow selecting multiple options from a list), Checkbox fields represent a single boolean decision.
## When to Use
**Use Checkbox fields for:**
* Terms and conditions agreements
* Consent flags (marketing, data processing)
* Feature toggles (enable/disable)
* Confirmation checkboxes ("I confirm this information is accurate")
* Binary status indicators (active/inactive, enabled/disabled)
* Opt-in/opt-out preferences
* Acknowledgments
**Consider alternatives:**
* Use **Choices** for yes/no/maybe or multiple options
* Use **Multiple Choice** for selecting multiple items from a list
* Use **Text** or **Number** for non-binary data
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `terms_agreed` |
| `name` | Display label | String | Required | "I agree to terms and conditions" |
| `description` | Help text for users | String | Optional | "Required to proceed" |
| `required` | Must be checked to proceed | Boolean | `false` | `true` |
| `default` | Default checked state | Boolean | `false` | `false` |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Examples
### Terms Agreement
Require agreement to terms:
```json theme={null}
{
"key": "terms_agreed",
"type": "checkbox",
"name": "I agree to the terms and conditions",
"required": true,
"description": "You must agree to proceed"
}
```
### Marketing Consent
Opt-in for marketing communications:
```json theme={null}
{
"key": "marketing_consent",
"type": "checkbox",
"name": "I agree to receive marketing communications",
"default": false,
"description": "Optional - we respect your privacy"
}
```
### Data Accuracy Confirmation
Confirm data is correct:
```json theme={null}
{
"key": "data_confirmed",
"type": "checkbox",
"name": "I confirm the information provided is accurate and complete",
"required": true
}
```
### Feature Toggle
Enable optional feature:
```json theme={null}
{
"key": "enable_premium_features",
"type": "checkbox",
"name": "Enable premium features",
"default": false,
"description": "Additional features available with premium plan",
"visibility": "hide-when-empty"
}
```
## Validation
Checkbox fields have simple validation:
### Required Validation
* If `required: true`, checkbox must be checked to proceed
* Useful for mandatory agreements (terms, privacy policy)
* Prevents form submission when unchecked
### Boolean Value
* Checked = `true`
* Unchecked = `false`
* Stored as boolean in case data
Checkboxes that are not required can remain unchecked, storing `false` as the
value.
## Checkbox in Automations
Checkbox fields enable powerful conditional logic:
**Status transitions:**
* Move to "Ready for Approval" when all confirmations checked
* Trigger compliance review when specific consent given
* Prevent progress until required checkboxes checked
**Conditional steps:**
* Show additional form when premium features enabled
* Send different email based on consent preferences
* Trigger workflows based on toggle state
**Notifications:**
* Alert team when critical checkbox checked
* Send confirmation when consent given
* Notify compliance when data processing agreed
**Example automation:**
```json theme={null}
{
"watch": ["data.terms_agreed", "data.data_processing_consent"],
"condition": {
":and": ["{data.terms_agreed}", "{data.data_processing_consent}"]
},
"action": {
"type": "status_transition",
"status": "ready_to_proceed"
}
}
```
[Learn more about Automations →](/cases/automations)
## Best Practices
**Use clear, affirmative language:**
* "I agree to receive..." (clear what checking means)
* Avoid double negatives ("I don't want to not receive...")
* State the action being confirmed
**Don't overuse checkboxes:**
* Too many checkboxes overwhelm users
* Group related agreements when possible
* Consider single confirmation with linked terms
**Mark required appropriately:**
* Only mark required if absolutely necessary
* Explain why it's required in description
* Legal requirements should be clearly stated
**Default unchecked for consent:**
* Marketing consent should default to `false`
* Optional features should default to `false`
* Never pre-check consent checkboxes (regulatory compliance)
**Use for regulatory compliance:**
* GDPR consent requires explicit checkbox
* Terms agreements need clear checkbox
* Maintain audit trail of when checkbox was checked
**Visibility settings:**
* Keep consent checkboxes always visible
* Use "hide when empty" for optional toggles
* Never hide required checkboxes
***
## Related Field Types
Use for selecting multiple items from a list
Use for yes/no/maybe or multiple options
Use for free-form agreement text or detailed consent
Back to Data Schema overview
# Choices Field
Source: https://docs.penbox.io/cases/data_schema/choices
Single selection from predefined options
The Choices field allows users to select a single option from a predefined list. This field type displays as radio buttons or a dropdown menu, ensuring users choose exactly one option from the available choices.
Use Choices fields when you need to collect a single selection from a fixed set of possibilities — country, priority, status, category, or any scenario where only one option should be selected.
## When to Use
**Use Choices fields for:**
* Country or region selection
* Priority levels (low, medium, high)
* Categories or types
* Status indicators
* Gender or salutation
* Yes/No questions with additional options
* Industry or sector
* Payment methods
* Communication preferences
* Urgency levels
**Consider alternatives:**
* Use **Multiple Choice** for selecting multiple items
* Use **Checkbox** for simple yes/no only
* Use **Text** for free-form input
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `country` |
| `name` | Display label | String | Required | "Country" |
| `description` | Help text for users | String | Optional | "Select your country" |
| `options` | Array of available options | Array | Required | See below |
| `required` | Must select an option | Boolean | `false` | `true` |
| `default` | Default selected value | String | None | `belgium` |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
### Options Configuration
Each option in the `options` array:
| Property | Description | Type | Required | Example |
| - | - | - | - | - |
| `value` | Internal value stored | String | Yes | `belgium` |
| `label` | Display text shown to user | String | Yes | "Belgium" |
## Examples
### Country Selection
Select a single country:
```json theme={null}
{
"key": "country",
"type": "choices",
"name": "Country",
"description": "Select your country of residence",
"required": true,
"options": [
{ "value": "belgium", "label": "Belgium" },
{ "value": "france", "label": "France" },
{ "value": "germany", "label": "Germany" },
{ "value": "netherlands", "label": "Netherlands" },
{ "value": "luxembourg", "label": "Luxembourg" },
{ "value": "other", "label": "Other" }
]
}
```
### Priority Level
Set case priority:
```json theme={null}
{
"key": "priority",
"type": "choices",
"name": "Priority",
"description": "How urgent is this request?",
"default": "medium",
"options": [
{ "value": "low", "label": "Low - Routine" },
{ "value": "medium", "label": "Medium - Normal" },
{ "value": "high", "label": "High - Urgent" },
{ "value": "critical", "label": "Critical - Immediate" }
]
}
```
### Industry Sector
Select industry:
```json theme={null}
{
"key": "industry",
"type": "choices",
"name": "Industry Sector",
"description": "Primary business sector",
"required": true,
"options": [
{ "value": "finance", "label": "Financial Services" },
{ "value": "healthcare", "label": "Healthcare" },
{ "value": "technology", "label": "Technology" },
{ "value": "manufacturing", "label": "Manufacturing" },
{ "value": "retail", "label": "Retail" },
{ "value": "real_estate", "label": "Real Estate" },
{ "value": "other", "label": "Other" }
]
}
```
### Yes/No/Maybe
Three-option choice:
```json theme={null}
{
"key": "renewal_intention",
"type": "choices",
"name": "Do you intend to renew?",
"description": "Let us know your renewal plans",
"options": [
{ "value": "yes", "label": "Yes, I will renew" },
{ "value": "no", "label": "No, I will not renew" },
{ "value": "undecided", "label": "Not sure yet" }
]
}
```
## Validation
Choices fields enforce single-selection validation:
### Required Validation
* If `required: true`, user must select an option
* Empty selection not allowed
* Useful for essential categorization
### Option Validation
* User can only select from predefined options
* No free-form input
* Ensures data consistency and enables automation logic
## Stored Values
Choices fields store a single string value:
**Example stored data:**
```json theme={null}
{
"country": "belgium"
}
```
**Empty state:**
```json theme={null}
{
"country": null
}
```
The stored value is the `value` from the selected option, not the `label`.
## Choices in Automations
Choices fields enable powerful conditional workflows:
**Check for specific value:**
```json theme={null}
{
"condition": {":eq": "{data.country}", "belgium"}
}
```
**Check if value in set:**
```json theme={null}
{
"condition": {":in": "{data.priority}", ["high", "critical"]}
}
```
**Route based on selection:**
* Assign to country-specific team based on country
* Escalate high-priority cases automatically
* Show industry-specific steps based on industry
* Apply different pricing based on category
**Status transitions:**
* Move to "Urgent Queue" when priority is high
* Route to specialist when specific industry selected
* Apply different SLAs based on priority
[Learn more about Automations →](/cases/automations)
## Best Practices
**Keep option lists manageable:**
* 3-12 options is ideal
* More than 20 options: consider search functionality or text input
* Group logically (alphabetically or by frequency)
**Use clear, distinct labels:**
* Each option should be clearly different
* Avoid similar or overlapping choices
* Use consistent terminology
**Always include "Other" when appropriate:**
* Provides escape hatch for unlisted options
* Prevents forcing users into wrong category
* Can trigger follow-up for details
**Value vs Label clarity:**
* Values: short, technical, consistent (e.g., `belgium`)
* Labels: friendly, readable (e.g., "Belgium")
* Values don't change, labels can be updated
**Order options logically:**
* Alphabetical for countries and names
* Most common first for frequency-based
* Logical progression for priority/urgency
* Group related options together
**Set defaults carefully:**
* Only set default if there's a clear common choice
* Don't default to first option (users may not notice)
* Leave blank when user should actively choose
**Required vs Optional:**
* Mark required when choice is essential
* Leave optional when "prefer not to say" is valid
* Consider if "no selection" is a valid state
***
## Related Field Types
Use for selecting multiple options
Use for simple yes/no only
Use when predefined options aren't suitable
Back to Data Schema overview
# Currency Field
Source: https://docs.penbox.io/cases/data_schema/currency
Monetary values with currency formatting for financial amounts
The Currency field captures monetary values — amounts with two decimal places and optional prefix/suffix for currency symbols. Currency fields are purpose-built for financial data, ensuring consistent formatting and validation for prices, costs, revenues, and claims.
Use Currency fields whenever you need to store monetary amounts. They enforce two-decimal precision and support min/max validation, making them ideal for any financial data point.
## When to Use
**Use Currency fields for:**
* Prices and costs
* Revenue and income
* Claim amounts
* Loan amounts
* Insurance premiums
* Fees and charges
* Any monetary value
**Consider alternatives:**
* Use **Number** for non-monetary numeric values (quantities, scores, measurements)
* Use **Text** for formatted financial references (invoice numbers, account IDs)
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `claim_amount` |
| `name` | Display label | String | Required | "Claim Amount" |
| `description` | Help text for users | String | Optional | "Total claim value in euros" |
| `min` | Minimum allowed value | Number | None | `0` |
| `max` | Maximum allowed value | Number | None | `1000000` |
| `prefix` | Text displayed before the value | String | None | `EUR` |
| `suffix` | Text displayed after the value | String | None | `EUR` |
| `clearable` | Allow clearing the field | Boolean | `true` | `false` |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Examples
### Basic Currency Amount
Collect a monetary value:
```json theme={null}
{
"key": "claim_amount",
"type": "currency",
"name": "Claim Amount",
"description": "Total claim value in euros",
"suffix": "EUR",
"min": 0,
"max": 1000000
}
```
### Annual Revenue
Collect revenue with prefix:
```json theme={null}
{
"key": "annual_revenue",
"type": "currency",
"name": "Annual Revenue",
"description": "Company revenue for last fiscal year",
"prefix": "EUR",
"min": 0
}
```
### Insurance Premium
Collect premium amount:
```json theme={null}
{
"key": "gross_premium",
"type": "currency",
"name": "Gross Premium",
"description": "Total gross premium amount",
"suffix": "EUR",
"min": 0
}
```
## Validation
Currency fields enforce monetary validation automatically:
### Type Validation
* Only numeric values accepted
* Maximum two decimal places (cents precision)
* Non-numeric input rejected
### Range Validation
* `min` - Minimum allowed value (inclusive)
* `max` - Maximum allowed value (inclusive)
* User cannot enter values outside range
Currency fields always enforce a maximum of 2 decimal places, ensuring
consistent monetary precision.
## Best Practices
**Always use Currency for monetary data:**
* Don't use Number for financial amounts
* Currency enforces two-decimal precision automatically
* Ensures consistent formatting across the platform
**Use prefix or suffix for currency indication:**
* Add `prefix: "EUR"` or `suffix: "EUR"` to indicate the currency
* Helps users understand the expected currency
* Be consistent across all currency fields in a case
**Set appropriate min/max:**
* Use `min: 0` to prevent negative amounts (when appropriate)
* Set realistic max values based on business context
* Catches data entry errors early
**Be explicit in field names:**
* Include currency in the name when relevant: "Amount (EUR)"
* Distinguish between gross and net amounts
* Clarify the time period: "Annual Revenue" vs "Monthly Revenue"
***
## Related Field Types
Use for non-monetary numeric values
Use for financial reference numbers and IDs
Back to Data Schema overview
# Date Field
Source: https://docs.penbox.io/cases/data_schema/date
Date picker for birth dates, deadlines, and timestamps
The Date field provides a date picker interface for capturing date values. Date fields enable date-based comparisons, calculations, and automations, making them essential for deadlines, birth dates, start dates, and any time-sensitive data.
Use Date fields whenever you need to track when something happened or when something is due. Date fields provide built-in validation, consistent formatting, and enable powerful date-based automations and filtering.
## When to Use
**Use Date fields for:**
* Birth dates and ages
* Deadlines and due dates
* Start and end dates
* Incident or claim dates
* Contract dates (signature, expiration)
* Submission dates
* Approval dates
* Any date that drives workflow logic
**Consider alternatives:**
* Use **Text** for date ranges or free-form date descriptions
* Use **Number** for year-only values that don't represent actual dates
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `birth_date` |
| `name` | Display label | String | Required | "Date of Birth" |
| `description` | Help text for users | String | Optional | "Your date of birth" |
| `min` | Earliest allowed date | Date string | None | `1900-01-01` |
| `max` | Latest allowed date | Date string | None | `2026-12-31` |
| `format` | Display format | String | `YYYY-MM-DD` | `DD/MM/YYYY` |
| `default` | Default value | Date string | None | `today`, `2026-01-01` |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Examples
### Birth Date
Collect date of birth with reasonable validation:
```json theme={null}
{
"key": "birth_date",
"type": "date",
"name": "Date of Birth",
"description": "Your date of birth",
"min": "1900-01-01",
"max": "today"
}
```
### Deadline Date
Set a future deadline:
```json theme={null}
{
"key": "submission_deadline",
"type": "date",
"name": "Submission Deadline",
"description": "Documents must be submitted by this date",
"min": "today",
"default": "+30days"
}
```
### Incident Date
Collect when an event occurred:
```json theme={null}
{
"key": "incident_date",
"type": "date",
"name": "Incident Date",
"description": "When did the incident occur?",
"max": "today"
}
```
### Contract Expiration
Track contract end date:
```json theme={null}
{
"key": "contract_expiration",
"type": "date",
"name": "Contract Expiration Date",
"description": "When this contract expires",
"min": "today"
}
```
## Validation
Date fields provide automatic validation:
### Format Validation
* Only valid dates accepted
* Prevents impossible dates (February 30, month 13, etc.)
* Handles leap years correctly
* Consistent date format across platform
### Range Validation
* `min` - Earliest allowed date
* `max` - Latest allowed date
* Use `today` as dynamic value for current date
* Use relative values like `+30days`, `-1year`
### Special Values
* `today` - Current date
* `+Ndays` - N days from today (e.g., `+30days`)
* `-Ndays` - N days before today (e.g., `-7days`)
* `+Nmonths` - N months from today
* `+Nyears` - N years from today
## Date-Based Automations
Date fields enable powerful date-based automations:
**Deadline reminders:**
* Send reminder 7 days before deadline
* Escalate when deadline passes
* Update status based on deadline proximity
**Age calculations:**
* Calculate age from birth date
* Determine eligibility based on age
* Trigger different workflows for age groups
**Time-based transitions:**
* Move to "Overdue" if response not received by deadline
* Archive cases after 90 days from closure date
* Trigger renewal workflow 30 days before expiration
**Date comparisons:**
* Ensure start date is before end date
* Check if incident date is within policy coverage period
* Validate dates fall within reasonable ranges
[Learn more about Automations →](/cases/automations)
## Best Practices
**Use Date fields for all date values:**
* Don't store dates as text (prevents date-based logic)
* Enables date calculations and comparisons
* Provides consistent date formatting
**Set reasonable min/max:**
* Prevents clearly invalid dates
* Use `today` for dynamic validation
* Consider use case (birth dates should be in past)
**Default values:**
* Use `today` for current date fields
* Use `+30days` for typical deadlines
* Leave blank when user must actively choose
**Consider timezone:**
* Dates are stored in ISO 8601 format
* Display format respects user locale
* Specify timezone requirements in description if critical
***
## Related Field Types
Use for year-only values that aren't specific dates
Use for date ranges or free-form date descriptions
Create date-based workflow automations
Back to Data Schema overview
# File Field
Source: https://docs.penbox.io/cases/data_schema/file
File upload and storage for documents, images, and attachments
The File field enables file uploads and storage within cases. Users can upload documents, images, PDFs, contracts, and other files directly into the case. File fields integrate with Document Intelligence for automatic data extraction from uploaded documents.
Use File fields whenever you need to collect documents as part of the case workflow — identity documents, contracts, invoices, receipts, images, or any file-based information.
## When to Use
**Use File fields for:**
* Identity documents (ID cards, passports, driver's licenses)
* Contracts and agreements
* Invoices and receipts
* Proof documents (address, income, employment)
* Images and photos (damage, products, signatures)
* Medical documents
* Tax documents
* Certificates and licenses
* Supporting documentation
* Signed documents
**Consider alternatives:**
* Use **Text** for URLs to external documents
* Use **API Call** to fetch documents from external systems
* Use document generation for creating documents (not collecting them)
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `identity_document` |
| `name` | Display label | String | Required | "Identity Document" |
| `description` | Help text for users | String | Optional | "Upload ID card or passport" |
| `accept` | Allowed file types (MIME types) | Array | All files | `["application/pdf", "image/*"]` |
| `max_size` | Maximum file size (bytes) | Number | `10485760` | `5242880` (5MB) |
| `max_files` | Maximum number of files | Number | `1` | `5` |
| `required` | Must upload at least one file | Boolean | `false` | `true` |
| `enable_intelligence` | Enable Document Intelligence | Boolean | `false` | `true` |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Examples
### Identity Document
Collect government ID:
```json theme={null}
{
"key": "identity_document",
"type": "file",
"name": "Identity Document",
"description": "Upload your ID card, passport, or driver's license",
"required": true,
"accept": ["image/*", "application/pdf"],
"max_size": 5242880,
"max_files": 2,
"enable_intelligence": true
}
```
### Invoice Upload
Collect invoices:
```json theme={null}
{
"key": "invoices",
"type": "file",
"name": "Invoices",
"description": "Upload relevant invoices (PDF format preferred)",
"accept": ["application/pdf", "image/*"],
"max_files": 10,
"enable_intelligence": true
}
```
### Damage Photos
Collect images of damage:
```json theme={null}
{
"key": "damage_photos",
"type": "file",
"name": "Damage Photos",
"description": "Upload clear photos showing the damage",
"required": true,
"accept": ["image/jpeg", "image/png", "image/heic"],
"max_size": 10485760,
"max_files": 20
}
```
### Contract Document
Collect signed contract:
```json theme={null}
{
"key": "signed_contract",
"type": "file",
"name": "Signed Contract",
"description": "Upload the signed contract document",
"required": true,
"accept": ["application/pdf"],
"max_files": 1,
"enable_intelligence": true
}
```
## File Type Restrictions
Use the `accept` option to restrict file types:
### Common MIME Types
| Type | MIME Type | Example |
| - | - | - |
| PDF | `application/pdf` | Contracts, forms |
| Images (all) | `image/*` | Photos, scans |
| JPEG | `image/jpeg` | Photos |
| PNG | `image/png` | Screenshots, graphics |
| Word | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | .docx files |
| Excel | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | .xlsx files |
| All files | `*/*` | No restriction |
**Examples:**
Only PDFs:
```json theme={null}
{ "accept": ["application/pdf"] }
```
PDFs and images:
```json theme={null}
{ "accept": ["application/pdf", "image/*"] }
```
Images only:
```json theme={null}
{ "accept": ["image/*"] }
```
File type restrictions are enforced client-side for user experience but should
not be relied upon for security. Always validate file types server-side.
## File Size Limits
Control maximum file size with `max_size` (in bytes):
| Limit | Bytes | Configuration |
| - | - | - |
| 1 MB | 1,048,576 | `"max_size": 1048576` |
| 5 MB | 5,242,880 | `"max_size": 5242880` |
| 10 MB | 10,485,760 | `"max_size": 10485760` |
| 20 MB | 20,971,520 | `"max_size": 20971520` |
**Default:** 10 MB (10,485,760 bytes)
Set appropriate file size limits based on expected document types. ID scans:
5MB is sufficient. High-res photos: 10-20MB may be needed.
## Multiple Files
Allow multiple file uploads with `max_files`:
**Single file only:**
```json theme={null}
{ "max_files": 1 }
```
**Up to 5 files:**
```json theme={null}
{ "max_files": 5 }
```
**Unlimited files:**
```json theme={null}
{ "max_files": null }
```
Use multiple files for:
* Multiple pages of same document
* Several related documents
* Multiple photos of damage
* Various supporting documents
## Document Intelligence Integration
Enable automatic data extraction with `enable_intelligence: true`:
When enabled, Document Intelligence:
* Automatically extracts data from uploaded documents
* Populates other fields in the case based on extracted data
* Validates extracted data against case schema
* Flags inconsistencies or missing information
**What Intelligence extracts:**
* Text content from PDFs
* Structured data (names, dates, amounts, addresses)
* Information from scanned documents and images
* Data from forms and tables
* Key-value pairs from documents
[Learn more about Document Intelligence →](/intelligence/document-intelligence)
## File Storage
Uploaded files are:
* Stored securely within the case
* Accessible to case members
* Included in case exports
* Retained according to workspace retention policies
* Visible in the case timeline when uploaded
**File metadata stored:**
* Original filename
* File size
* Upload timestamp
* Uploaded by (member)
* File type (MIME)
## Validation
File fields enforce upload validation:
### Required Validation
* If `required: true`, at least one file must be uploaded
* User cannot proceed without uploading
### File Type Validation
* Only specified MIME types accepted
* Rejected files show error message
### Size Validation
* Files exceeding `max_size` rejected
* Clear error message shown
### Count Validation
* Cannot exceed `max_files`
* Disable upload when limit reached
## Best Practices
**Set appropriate file types:**
* Be specific when possible (PDFs only for contracts)
* Allow both PDF and images for flexibility (scans, photos)
* Don't be overly restrictive (users may have various formats)
**Configure realistic size limits:**
* Consider document type (ID scans: 5MB, photos: 10-20MB)
* Too restrictive: frustrates users with valid files
* Too generous: allows unnecessarily large uploads
**Use clear descriptions:**
* Specify accepted formats in description
* Mention size limits if restrictive
* Explain what to upload ("front and back of ID")
**Enable Intelligence strategically:**
* Enable for documents with extractable data
* Not necessary for photos without text
* Reduces manual data entry significantly
**Multiple files configuration:**
* Single file: official documents, contracts
* Multiple files: supporting docs, damage photos
* Consider workflow: easier to upload multiple at once
**Organize with sections:**
* Group related file fields in sections
* "Identity Documents", "Financial Documents", "Photos"
* Makes case data easier to navigate
**Name fields descriptively:**
* "Identity Document" not just "Document"
* "Damage Photos" not just "Photos"
* Helps users and case managers understand purpose
***
## Related Field Types
Use for URLs to external documents
Use to fetch documents from external systems
Learn about automatic data extraction
Back to Data Schema overview
# Multiple Choice Field
Source: https://docs.penbox.io/cases/data_schema/multiple_choice
Multiple selections from predefined options
The Multiple Choice field allows users to select multiple items from a predefined list of options. This field type displays as a checkbox group where users can check any combination of the available options.
Use Multiple Choice fields when you need to collect multiple selections from a fixed set of possibilities — services required, features selected, categories, interests, or any scenario where "select all that apply" is appropriate.
## When to Use
**Use Multiple Choice fields for:**
* Services or products selected
* Features or options enabled
* Categories or tags
* Interests or preferences
* Coverage types or insurance products
* Document types required
* Affected areas or departments
* Applicable regulations or requirements
**Consider alternatives:**
* Use **Choices** for single selection only
* Use **Checkbox** for a single yes/no option
* Use **Text** for free-form input
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `services_required` |
| `name` | Display label | String | Required | "Services Required" |
| `description` | Help text for users | String | Optional | "Select all services you need" |
| `options` | Array of available options | Array | Required | See below |
| `min_selections` | Minimum selections required | Number | `0` | `1` |
| `max_selections` | Maximum selections allowed | Number | None | `3` |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
### Options Configuration
Each option in the `options` array:
| Property | Description | Type | Required | Example |
| - | - | - | - | - |
| `value` | Internal value stored | String | Yes | `health_insurance` |
| `label` | Display text shown to user | String | Yes | "Health Insurance" |
## Examples
### Services Selection
Allow multiple service selections:
```json theme={null}
{
"key": "services_required",
"type": "multiple_choice",
"name": "Services Required",
"description": "Select all services you need",
"min_selections": 1,
"options": [
{ "value": "life_insurance", "label": "Life Insurance" },
{ "value": "health_insurance", "label": "Health Insurance" },
{ "value": "property_insurance", "label": "Property Insurance" },
{ "value": "liability_insurance", "label": "Liability Insurance" },
{ "value": "pension_planning", "label": "Pension Planning" }
]
}
```
### Document Types
Select required documents:
```json theme={null}
{
"key": "required_documents",
"type": "multiple_choice",
"name": "Required Documents",
"description": "Select all documents you need to submit",
"options": [
{ "value": "id_card", "label": "ID Card or Passport" },
{ "value": "proof_of_address", "label": "Proof of Address" },
{ "value": "bank_statement", "label": "Bank Statement" },
{ "value": "tax_return", "label": "Tax Return" },
{ "value": "employment_contract", "label": "Employment Contract" }
]
}
```
### Coverage Areas
Select applicable coverage:
```json theme={null}
{
"key": "coverage_areas",
"type": "multiple_choice",
"name": "Coverage Areas",
"description": "Select all areas where coverage is needed",
"max_selections": 3,
"options": [
{ "value": "europe", "label": "Europe" },
{ "value": "north_america", "label": "North America" },
{ "value": "asia", "label": "Asia" },
{ "value": "africa", "label": "Africa" },
{ "value": "south_america", "label": "South America" },
{ "value": "oceania", "label": "Oceania" }
]
}
```
## Validation
Multiple Choice fields enforce selection validation:
### Selection Count
* `min_selections` - Minimum required selections
* `max_selections` - Maximum allowed selections
* User must select within range to proceed
### Option Validation
* User can only select from predefined options
* No free-form input
* Ensures data consistency
**Common configurations:**
| Configuration | Use Case |
| - | - |
| `min: 1` | "Select at least one" |
| `min: 1, max: 3` | "Select 1-3 options" |
| `min: 0` | Optional selections (default) |
| `max: 5` | Limit selections |
## Stored Values
Multiple Choice fields store an array of selected values:
**Example stored data:**
```json theme={null}
{
"services_required": [
"life_insurance",
"health_insurance",
"pension_planning"
]
}
```
**Empty state:**
```json theme={null}
{
"services_required": []
}
```
This format enables easy checking in automations and data processing.
## Multiple Choice in Automations
Multiple Choice fields enable conditional logic based on selections:
**Check if specific option selected:**
```json theme={null}
{
"condition": {":in": "life_insurance", "{data.services_required}"}
}
```
**Check if any selection made:**
```json theme={null}
{
"condition": {":gt": {":len": "{data.services_required}"}, "0"}
}
```
**Check if multiple selections:**
```json theme={null}
{
"condition": {":gte": {":len": "{data.services_required}"}, "2"}
}
```
**Trigger based on selection:**
* Show additional steps for specific services
* Route to specialist based on selections
* Calculate pricing based on options selected
* Send targeted information based on interests
[Learn more about Automations →](/cases/automations)
## Best Practices
**Keep option lists focused:**
* 3-8 options is ideal
* More than 12 options becomes overwhelming
* Group related options logically
* Order by frequency of use or alphabetically
**Use clear labels:**
* Labels should be self-explanatory
* Avoid jargon or abbreviations
* Be consistent with terminology
**Consider min/max:**
* Use `min: 1` when at least one selection required
* Use `max` to prevent over-selection
* Most use cases don't need max limit
**Name the field as a question:**
* "Services Required" → clear what to select
* "Select Your Preferences" → action-oriented
* Avoid vague labels like "Options"
**Value vs Label:**
* Use short, technical values (`life_insurance`)
* Use friendly, readable labels ("Life Insurance")
* Values are used in code, labels shown to users
**Default selections:**
* Usually best to have no defaults
* Let users make explicit choices
* Pre-selecting can create unwanted selections
***
## Related Field Types
Use for single selection from options
Use for single yes/no option
Use for free-form input without predefined options
Back to Data Schema overview
# Number Field
Source: https://docs.penbox.io/cases/data_schema/number
Numeric values with formatting for amounts, quantities, and calculations
The Number field captures numeric values — integers or decimals — with optional formatting and validation. Number fields enable calculations, comparisons, and numeric operations within automations and data processing.
Use Number fields whenever you need to perform mathematical operations, apply min/max validation, or format values with prefix/suffix. Number fields are essential for quantities, ages, scores, and any data that requires numeric processing.
## When to Use
**Use Number fields for:**
* Quantities (items, count, volume)
* Ages and years
* Scores and ratings
* Percentages and ratios
* Measurements (weight, height, distance)
* Identifiers that are purely numeric (account numbers, IDs)
* Calculated values
**Consider alternatives:**
* Use **Currency** for monetary amounts (prices, costs, revenues, claims)
* Use **Text** for alphanumeric IDs (contain letters)
* Use **Choices** for predefined numeric ranges (age groups, price tiers)
* Use **Date** for years that represent dates
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `number_of_employees` |
| `name` | Display label | String | Required | "Number of Employees" |
| `description` | Help text for users | String | Optional | "Total full-time employees" |
| `min` | Minimum allowed value | Number | None | `0` |
| `max` | Maximum allowed value | Number | None | `1000000` |
| `decimals` | Number of decimal places | Number | None | `2` |
| `prefix` | Text displayed before the value | String | None | `$` |
| `suffix` | Text displayed after the value | String | None | `kg` |
| `placeholder` | Hint text shown in empty field | String | None | "Enter a number" |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Examples
### Basic Integer
Collect a simple count:
```json theme={null}
{
"key": "number_of_employees",
"type": "number",
"name": "Number of Employees",
"description": "Total full-time employees",
"min": 1
}
```
### Decimal Value
Collect precise measurements:
```json theme={null}
{
"key": "weight_kg",
"type": "number",
"name": "Weight (kg)",
"description": "Weight in kilograms",
"decimals": 2,
"suffix": "kg",
"min": 0
}
```
### Percentage with Prefix/Suffix
Collect a percentage value:
```json theme={null}
{
"key": "completion_percentage",
"type": "number",
"name": "Completion Percentage",
"description": "Project completion percentage",
"suffix": "%",
"min": 0,
"max": 100,
"decimals": 1
}
```
## Validation
Number fields enforce numeric validation automatically:
### Type Validation
* Only numeric values accepted
* Decimals allowed based on `decimals` configuration
* Non-numeric input rejected
### Range Validation
* `min` - Minimum allowed value (inclusive)
* `max` - Maximum allowed value (inclusive)
* User cannot enter values outside range
### Decimal Validation
* `decimals` defines maximum decimal places allowed
* For integers: omit `decimals` or set to `0`
* For precise values: set `decimals` to the required precision (e.g., `2`)
Validation happens when users fill the field. Existing data or API imports are
not automatically validated.
## Best Practices
**Always use Number for numeric data:**
* Don't store numbers as text (prevents calculations)
* Use Number even if you don't need calculations now (future-proofs)
* Enables numeric comparisons in automations
**Set appropriate min/max:**
* Prevents invalid or unrealistic values
* Catches data entry errors
* Useful for regulated fields with limits
**Configure decimals based on needs:**
* Omit `decimals` for counts and quantities
* Use `2` for precise measurements
* Use appropriate precision for your domain
**Use prefix/suffix for display context:**
* Add `suffix: "kg"` for weight fields
* Add `suffix: "%"` for percentage fields
* Helps users understand expected format
**Use Currency for monetary values:**
* Don't use Number with a currency prefix for financial amounts
* The **Currency** field type is purpose-built for monetary values
**Validate reasonably:**
* Don't set overly restrictive min/max
* Consider edge cases (zero values, large amounts)
* Test with realistic data ranges
***
## Related Field Types
Use for monetary amounts with currency formatting
Use for alphanumeric IDs and formatted numbers
Use for predefined numeric ranges or tiers
Back to Data Schema overview
# Signature Field
Source: https://docs.penbox.io/cases/data_schema/signature
Digital signature capture for legally binding electronic signatures
The Signature field enables digital signature collection directly within cases. This field type captures legally binding electronic signatures with multiple authentication methods, creating a complete audit trail for compliance and verification.
Use Signature fields when you need to collect formal agreements, approvals, or legally binding signatures as part of your case workflow — contracts, consent forms, acknowledgments, or any document requiring a verified signature.
## When to Use
**Use Signature fields for:**
* Contract signatures
* Agreement and consent forms
* Document approvals
* Legal acknowledgments
* Financial authorizations
* Medical consent
* Terms and conditions acceptance (when signature required)
* Compliance acknowledgments
* Verification of identity
* Multi-party agreements
**Consider alternatives:**
* Use **Checkbox** for simple agreement checkboxes (non-signature)
* Use **File** for uploading pre-signed documents
* Use document generation with signatures for template-based signing
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `contract_signature` |
| `name` | Display label | String | Required | "Contract Signature" |
| `description` | Help text for signers | String | Optional | "Sign to accept the contract terms" |
| `required` | Must be signed to proceed | Boolean | `false` | `true` |
| `signer_role` | Who signs this field | String | `main_contact` | `secondary_contact`, `case_manager` |
| `authentication` | Authentication method | String | `handwritten` | `sms_otp`, `email_otp`, `itsme`, `swisscom` |
| `document` | Document to sign | String | None | Document UUID or variable |
| `signature_type` | Type of signature | String | `standard` | `qualified`, `advanced` |
| `sequence` | Signing order (for multiple signatures) | Number | `1` | `2`, `3` |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Authentication Methods
Signature fields support multiple authentication methods for different legal and security requirements:
| Method | Description | Use Case | Legal Level |
| - | - | - | - |
| `handwritten` | Draw signature with mouse/touch | Simple agreements, internal approvals | Basic |
| `email_otp` | One-time code via email | Remote signing, email verification | Standard |
| `sms_otp` | One-time code via SMS | Strong verification, phone validation | Standard |
| `itsme` | Belgian eID authentication | Belgian residents, strong identity verification | Advanced/Qualified |
| `swisscom` | Swiss qualified signature | Swiss residents, legally binding in Switzerland | Qualified |
**Legal signature levels:**
* **Basic**: Simple electronic signature (handwritten)
* **Standard**: Verified email/phone with OTP
* **Advanced**: Identity-verified signature (Itsme)
* **Qualified**: Highest legal level, equivalent to handwritten (Itsme, Swisscom)
## Examples
### Simple Contract Signature
Basic signature for contract acceptance:
```json theme={null}
{
"key": "contract_signature",
"type": "signature",
"name": "Contract Signature",
"description": "Sign below to accept the contract terms",
"required": true,
"signer_role": "main_contact",
"authentication": "handwritten",
"document": "{document.contract_generated}"
}
```
### SMS-Verified Signature
Signature with SMS one-time code authentication:
```json theme={null}
{
"key": "authorization_signature",
"type": "signature",
"name": "Authorization Signature",
"description": "Sign to authorize this transaction. You will receive a code via SMS.",
"required": true,
"signer_role": "main_contact",
"authentication": "sms_otp",
"signature_type": "advanced"
}
```
### Multi-Party Signing Sequence
Multiple signatures in specific order:
```json theme={null}
{
"key": "client_signature",
"type": "signature",
"name": "Client Signature",
"description": "Client signature on agreement",
"required": true,
"signer_role": "main_contact",
"authentication": "email_otp",
"sequence": 1,
"document": "{document.agreement}"
}
```
```json theme={null}
{
"key": "manager_signature",
"type": "signature",
"name": "Manager Approval",
"description": "Manager approval signature",
"required": true,
"signer_role": "case_manager",
"authentication": "handwritten",
"sequence": 2,
"document": "{document.agreement}"
}
```
### Qualified Electronic Signature (Itsme)
Legally binding qualified signature for Belgian residents:
```json theme={null}
{
"key": "qualified_signature",
"type": "signature",
"name": "Qualified Electronic Signature",
"description": "Sign using your Itsme account for legally binding signature",
"required": true,
"signer_role": "main_contact",
"authentication": "itsme",
"signature_type": "qualified",
"document": "{document.legal_agreement}"
}
```
## Signer Roles
Control who signs each signature field:
| Role | Who Signs | Use Case |
| - | - | - |
| `main_contact` | Primary case contact | Client signatures, customer agreements |
| `secondary_contact` | Additional contact | Co-signers, witnesses, secondary parties |
| `case_manager` | Case owner/manager | Internal approvals, manager authorization |
| `custom` | Specified via variable | Dynamic signer assignment |
**Multiple signers:**
* Use `sequence` to control signing order
* Each signer must complete before next can sign
* Useful for approval chains and multi-party agreements
## Signature Workflow
### Signature Request Process
1. **Request sent**: Signer receives notification (email/SMS)
2. **Authentication**: Signer verifies identity (method depends on configuration)
3. **Review**: Signer reviews document (if attached)
4. **Sign**: Signer provides signature (draw, type, or authenticated)
5. **Confirmation**: Signature captured and stored
6. **Complete**: All parties notified, document finalized
### Signature Metadata Stored
Each signature captures:
* Signer name and contact information
* Timestamp (date and time signed)
* IP address (for audit trail)
* Authentication method used
* Device information
* Signature image (if handwritten)
* Certificate information (if qualified)
### Document Attachment
Signatures can be attached to documents:
* Generated documents from templates
* Pre-uploaded documents
* Documents from other steps
* Multiple signatures on same document
## Validation
Signature fields enforce signing validation:
### Required Validation
* If `required: true`, signature must be completed
* Case cannot progress until signed
* Useful for mandatory agreements
### Authentication Validation
* OTP codes must match (email/SMS)
* Identity must be verified (Itsme, Swisscom)
* Prevents unauthorized signatures
### Sequence Validation
* Earlier sequence signatures must complete first
* Order enforced automatically
* Prevents out-of-order signing
## Compliance and Legal
### Audit Trail
Complete audit trail for each signature:
* Who signed (name, email, phone)
* When signed (timestamp with timezone)
* Where signed (IP address, location)
* How authenticated (method used)
* What was signed (document version)
### Legal Validity
Signature validity depends on authentication method:
* **Handwritten**: Valid for low-risk agreements
* **Email/SMS OTP**: Valid for verified identity
* **Itsme/Swisscom**: Legally equivalent to handwritten signature in EU
### GDPR Compliance
Signature data is:
* Stored securely and encrypted
* Retained according to legal requirements
* Included in data export requests
* Deleted when case deleted (with retention rules)
### eIDAS Regulation
Qualified signatures (Itsme, Swisscom) comply with:
* eIDAS Regulation (EU 910/2014)
* Legally binding across EU member states
* Equivalent to handwritten signatures
* Admissible as legal evidence
## Best Practices
**Choose appropriate authentication:**
* Handwritten: Simple agreements, internal documents
* Email OTP: Remote signing, email verification needed
* SMS OTP: Higher security, phone verification
* Itsme/Swisscom: Legal requirements, high-value agreements
**Set realistic requirements:**
* Only mark required if signature truly mandatory
* Consider fallback if authentication fails
* Provide clear instructions for signers
**Sequence multiple signatures logically:**
* Client signs first, then internal approval
* Primary signer before secondary signers
* Lower authority before higher authority
**Attach the right documents:**
* Attach document being signed
* Ensure document is finalized before signing
* Use generated documents for consistency
**Provide clear descriptions:**
* Explain what signer is agreeing to
* Mention authentication method required
* Indicate estimated time to complete
**Test authentication methods:**
* Test OTP delivery (email/SMS)
* Verify Itsme/Swisscom integration
* Check user experience on mobile devices
**Consider user experience:**
* Mobile-friendly signature methods
* Clear error messages for failed authentication
* Allow signature retry on failure
* Send reminders for pending signatures
**Maintain compliance:**
* Store audit trail for legal minimum period
* Document authentication methods used
* Regularly review signature processes
* Ensure GDPR compliance for signature data
***
## Related Field Types
Use for simple agreement checkboxes
Use for uploading pre-signed documents
Learn about generating documents for signing
Back to Data Schema overview
# Text Field
Source: https://docs.penbox.io/cases/data_schema/text
Single or multi-line text input for names, descriptions, and IDs
The Text field is the most versatile field type in Penbox. It captures single-line or multi-line text input, making it ideal for names, addresses, descriptions, notes, IDs, and any other free-form text data.
Text fields can be configured with character limits, validation patterns, and placeholder hints. They support both simple input (like a name) and complex multi-line content (like detailed notes or descriptions).
## When to Use
**Use Text fields for:**
* Names (person, company, product)
* Addresses (street, city, full address)
* Descriptions and notes
* IDs and reference numbers
* Email addresses (simple text, or use Email element in forms)
* Phone numbers (simple text, or use Phone element in forms)
* URLs and website addresses
* Comments and feedback
* Any free-form text input
**Consider alternatives:**
* Use **Number** for numeric values (enables calculations)
* Use **Date** for dates (enables date-based features)
* Use **Choices** for predefined options (ensures consistency)
## Configuration Options
| Option | Description | Type | Default | Example |
| - | - | - | - | - |
| `key` | Unique identifier | String | Required | `company_name` |
| `name` | Display label | String | Required | "Company Name" |
| `description` | Help text for users | String | Optional | "Legal name of your company" |
| `multiline` | Enable multi-line textarea | Boolean | `false` | `true` |
| `maxlength` | Maximum character count | Number | None | `500` |
| `pattern` | Regex validation pattern | String | None | `^[A-Z0-9]+$` |
| `placeholder` | Hint text shown in empty field | String | None | "Enter company name" |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Examples
### Basic Single-Line Text
Collect a company name:
```json theme={null}
{
"key": "company_name",
"type": "text",
"name": "Company Name",
"description": "Official registered name of your company"
}
```
### Multi-Line Text (Notes)
Collect detailed notes or descriptions:
```json theme={null}
{
"key": "claim_description",
"type": "text",
"name": "Claim Description",
"description": "Provide detailed description of the incident",
"multiline": true,
"maxlength": 2000,
"placeholder": "Describe what happened, when it occurred, and any relevant details..."
}
```
### Validated Text (IBAN)
Collect structured text with validation:
```json theme={null}
{
"key": "iban",
"type": "text",
"name": "IBAN",
"description": "International Bank Account Number",
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]+$",
"placeholder": "BE68539007547034"
}
```
### Hidden Text Field (System Use)
Store data not shown to users:
```json theme={null}
{
"key": "external_crm_id",
"type": "text",
"name": "CRM ID",
"description": "External system identifier",
"visibility": "always-hide"
}
```
## Validation
Text fields support several validation mechanisms:
### Character Length
Use `maxlength` to limit input:
* Prevents overly long entries
* Ensures data fits in external systems
* Useful for regulated fields with character limits
```json theme={null}
{
"maxlength": 500
}
```
### Pattern Matching
Use `pattern` for regex validation:
* Format validation (IBANs, postal codes, IDs)
* Character restrictions (alphanumeric only)
* Structure enforcement
**Common patterns:**
| Use Case | Pattern | Example |
| - | - | - |
| Alphanumeric only | `^[A-Z0-9]+$` | ABC123 |
| Email format | `^[^\s@]+@[^\s@]+\.[^\s@]+$` | [user@domain.com](mailto:user@domain.com) |
| Phone (simple) | `^\+?[0-9\s\-\(\)]+$` | +1 (555) 123-4567 |
| Postal code (BE) | `^[0-9]{4}$` | 1000 |
| IBAN | `^[A-Z]{2}[0-9]{2}[A-Z0-9]+$` | BE68539007547034 |
Pattern validation only applies when users fill the field. It doesn't validate
existing data or data from API imports.
## Best Practices
**Use descriptive names:**
* "Company Legal Name" is better than "Name"
* "Incident Description" is better than "Description"
* Clear names help users and Intelligence understand what's expected
**Add help text:**
* Use the `description` field to guide users
* Explain format requirements, especially for validated fields
* Mention if the field is required for compliance
**Choose single vs multi-line appropriately:**
* Single-line for short, structured text (names, IDs, codes)
* Multi-line for longer content (descriptions, notes, comments)
* Set appropriate `maxlength` for multi-line to prevent excessive input
**Use validation wisely:**
* Only validate when necessary (IBANs, IDs, codes)
* Don't over-validate (strict patterns can frustrate users)
* Test patterns thoroughly before deploying
**Consider visibility:**
* Use "hide when empty" for optional supplementary fields
* Use "always hide" for system IDs and technical data
* Keep essential fields always visible
***
## Related Field Types
Use for numeric values that need calculations
Use when input should be from predefined options
Use for date values to enable date-based features
Back to Data Schema overview
# What are Cases
Source: https://docs.penbox.io/cases/introduction
The core of the Case Intelligence platform
A **Case** is an intelligent workflow involving a case manager (workspace member) and one or more contacts. Cases combine email, SMS, forms, documents, and data collection into a single managed workflow.
A case can be as simple as sending a single form or email, or as complex as a multi-month process with dozens of steps, multiple contacts, document generation, digital signatures, and intelligent automations. Every case has a timeline with events and steps (the complete journey of what happened and what's next), contacts (people involved), a data schema (information to collect), statuses (where the case stands), and optionally, automations (rules that drive the workflow forward).
Cases don't require a template. You can create a blank case and build it as you go. For recurring workflows, templates let you pre-configure the structure so every new case starts with the right steps, contacts, and data schema already in place.
Cases are the core of Penbox. Sending a form is the simplest action you can perform within a case.
## Main Contact
Every case requires at least one **Main Contact** to function effectively. The main contact is the primary individual the case is about and the recipient for all external communications and interactions.
**The main contact:**
* Receives forms sent from the case
* Receives email communications and notifications
* Is the primary point of contact for the matter
* Can be an individual person or organization representative
* Must have at least an email address or phone number to receive communications
A case without a main contact cannot send forms or communications to external parties. Always add a main contact to enable full case functionality.
You can add additional contacts with different roles as secondary contacts, but the main contact is essential for the case workflow.
If you create a case from a form submission or email, the sender's information is automatically added as the main contact.
[Learn more about Contacts →](/cases/contacts)
## Case Reference
Each case is automatically assigned a unique **6-character alphanumeric reference** (e.g., `AB12XY`) for easy identification and external communication.
**Uses for reference numbers:**
* Quick lookup and search in your system
* Share with customers and partners (instead of internal IDs)
* Reference in emails and customer communications
* Tracking and reporting
* Linking to external systems (CRM, accounting software)
* Regulatory and compliance documentation
* Phone support and customer inquiries
Reference numbers provide a human-friendly way to discuss cases with external parties while maintaining internal organization.
## Case Owner
Every case can be assigned to an **owner** — a team member responsible for managing the case.
**The owner:**
* Receives notifications about case updates
* Can update case data and status
* Is accountable for case progress
* Appears in case history
Assigning clear ownership prevents cases from falling through the cracks and ensures accountability.
## Waiting For Status
Cases track what they're waiting for to help teams prioritize work:
* **None** - No action required, case is progressing
* **Owner** - Waiting for internal team action
* **Contact** - Waiting for external contact response
This status helps you:
* Identify cases that need immediate attention
* Filter cases waiting on external parties
* Prioritize your workload
* Prevent cases from stalling
The "Waiting For" status can be set manually or updated automatically by Intelligence based on email content.
## Case Timeline
Cases automatically track all activities in a chronological timeline:
* Case created
* Status changes
* Field updates
* Emails sent and received
* SMS sent
* Forms sent to contacts
* Form responses received
* Internal notes added
* Workflow steps completed
This creates a complete audit trail of everything that happened with the case.
## Archiving Cases
Cases can be archived when they're no longer actively needed but should be retained:
* Don't appear in default case lists
* Can still be searched and accessed
* Retain all data and history
* Can be unarchived if needed
## Intelligence Features
Penbox includes AI-powered features to help manage cases:
### AI-Generated Case Titles
When enabled, Penbox can automatically generate meaningful case titles based on the case data, making it easier to identify cases at a glance.
### Email Analysis
Penbox automatically analyzes emails sent from cases to:
* Generate concise summaries
* Determine who needs to take the next action
* Update the "Waiting For" status automatically
### Document Intelligence
AI can help extract information from documents and emails to automatically populate case fields. AI descriptions on data points guide the extraction process, helping Intelligence understand what to look for.
***
## Next Steps
Learn how cases are created
Understand fields and data organization
Learn about workflow steps
Design reusable case templates
# Statuses & Lifecycle
Source: https://docs.penbox.io/cases/statuses_lifecycle
The status model and case lifecycle
Every case has a status that indicates its current state in the workflow. Statuses help teams understand where each case is in the process and what needs to happen next. Cases progress through statuses from creation through active management to archiving or closure.
## Default Statuses
Penbox provides four default statuses that serve as the foundation for all case workflows:
Case is being prepared, not yet active
**Common uses:** Initial setup, gathering preliminary info, preparing case before activation
Case is waiting to be started or for an external trigger
**Common uses:** Awaiting documents, awaiting customer action, scheduled to start later
Case is actively being worked on
**Common uses:** Data collection, verification, processing, review
Case is complete
**Common uses:** Approved, completed, rejected, cancelled
## Status Hierarchy
Cases use a hierarchical status system where custom statuses are grouped under the four default parent statuses.
**Why hierarchical?**
* **Flexibility** - Create specific statuses for your workflow
* **Consistency** - All statuses map to standard states
* **Filtering** - Filter by parent status to see all "in progress" cases
* **Reporting** - Group by parent status for high-level metrics
**Example hierarchy:**
```
📁 draft
└─ preparing
└─ review_needed
📁 pending
└─ awaiting_documents
└─ awaiting_approval
└─ awaiting_payment
📁 in_progress
└─ collecting_data
└─ verification
└─ compliance_review
└─ final_approval
📁 closed
└─ approved
└─ completed
└─ rejected
└─ cancelled
```
## Custom Statuses
Case templates can define custom statuses specific to their workflow. Each custom status is defined with:
**Status properties:**
* **Key** - Unique identifier (e.g., `awaiting_documents`, `compliance_review`)
* **Label** - Display name shown to users (e.g., "Awaiting Documents", "Compliance Review")
* **Parent status** - Must be one of: `draft`, `pending`, `in_progress`, `closed`
* **Auto transition** - Optional conditions for automatic status changes
Custom statuses are defined in case templates. Individual cases inherit these statuses and progress through them based on your workflow.
[Learn more about Case Templates →](/cases/case_templates)
## Status Transitions
Cases move through statuses either manually or automatically.
### Manual Status Changes
Team members can change status:
* Select new status from dropdown
* Status updates immediately
* Change is logged in timeline
* Can trigger automations
### Automatic Status Transitions
Statuses can change automatically based on conditions:
* All required fields filled
* Documents uploaded
* Forms completed
* External data received
* Time conditions met
[Learn more about Automations →](/cases/automations)
### Waiting For Indicator
Beyond the status, cases also track "Waiting For" to indicate who needs to act next:
* **None** - No action required, case is progressing
* **Owner** - Waiting for internal team action
* **Contact** - Waiting for external contact response
This indicator helps teams prioritize work and identify cases that need immediate attention. It can be set manually or updated automatically by Intelligence based on email content.
## Case Lifecycle
Cases progress through a defined lifecycle from creation to closure:
### Creation
Cases enter the system through one of four methods:
* **Manually in Penbox** - Team member creates from app
* **From incoming email** - Email Intelligence or dedicated mailbox
* **From completed form** - Form linked to case creation
* **Via API** - Programmatic creation from external systems
New cases typically start in Draft or Pending status.
[Learn more about Case Creation →](/cases/case_creation)
### Active Management
During active management, cases:
* Progress through statuses based on workflow
* Collect data through forms and manual updates
* Execute steps (emails, SMS, forms)
* Trigger automations based on conditions
* Track all activities in timeline
* Update "Waiting For" indicator as needed
Team members work on cases, contacts respond to forms, and automations move the workflow forward.
### Archiving
Cases can be archived when they're no longer actively needed but should be retained:
**Archived cases:**
* Don't appear in default case lists
* Can still be searched and accessed
* Retain all data and history
* Can be unarchived if needed
* Maintain complete audit trail
**When to archive:**
* Case is closed but may need future reference
* Regulatory retention period requires keeping records
* Historical data needed for reporting
* Legal holds or compliance requirements
Archive closed cases to keep your active list clean while maintaining searchability for audits and historical reference.
### Deletion
Cases can only be permanently deleted under specific conditions:
**Deletion rules:**
* **A case can only be permanently deleted before any steps are executed**
* Once steps are executed, the case enters the permanent record
* Executed cases must be archived, not deleted
* This preserves audit trails for compliance
**Why this matters:**
* Maintains regulatory compliance
* Preserves audit trails
* Prevents accidental loss of case history
* Ensures data integrity
Once a case has executed steps (sent emails, forms, SMS), it cannot be permanently deleted. This ensures complete audit trails for compliance and regulatory requirements.
## Status Best Practices
**Use action-oriented names** - Status names should indicate what's happening or what's needed. Good: "Awaiting Customer Response", "Under Review". Avoid: "Status 1", "Phase 2".
**Keep parent status logical** - Choose parent statuses that match the actual case state. Use `pending` when waiting for something external, `in_progress` when team is actively working, `closed` only for final terminal states.
**Don't create too many statuses** - Each status should represent a meaningful stage in your process. Recommended: 5-10 custom statuses per template.
**Make statuses sequential** - If your workflow has clear stages, make statuses follow that sequence. Example: Onboarding → Verification → Review → Approval → Closed.
**Plan for edge cases** - Include statuses for exceptions like "Rejected", "Cancelled", "On Hold" to handle cases that don't complete the standard workflow.
***
## Next Steps
Configure statuses in templates
Automate status transitions
Learn about cases
Understand case data
# Steps
Source: https://docs.penbox.io/cases/steps
The building blocks of a case workflow
Steps are the individual actions that make up a case, executed in sequence or on demand. A step can be an email sent to a contact, an SMS message, a form to collect information, or an internal form completed by the case manager.
For each step type, the configuration determines what it does, what can be customized, and how it appears in the case timeline. Steps can be predefined in a case template or added ad-hoc during case execution.
## Step Types
Cases support four types of steps:
**Outbound email to a contact**
Configure sender, recipients, subject, and body. Can include attachments and form links.
**Outbound text message**
Send quick notifications or updates via SMS to contact phone numbers.
**Send an external form to a contact**
Email containing a link to a form that the contact fills out. Form can be a template or created on-the-fly.
**Form completed by case manager**
Structured data collection for internal workflows, completed by team members rather than external contacts.
## Predefined Steps
When you create a case from a template, predefined workflow steps are available. These steps are configured in the case template with specific fields, forms, or email templates. They appear ready to activate with a single click, ensuring consistency across all cases created from that template.
**Predefined steps:**
* Are defined in the case template
* Include pre-configured content (email templates, form templates, etc.)
* Can be conditional (shown or hidden based on case data)
* Can be automated (triggered when conditions are met)
* Appear in the case as available actions
[Learn more about Case Templates →](/cases/case_templates)
## Ad-Hoc Steps
You can create steps manually at any time while working on a case. Ad-hoc steps are executed immediately and appear in the case timeline once completed.
**Common ad-hoc steps:**
* Send an email to a contact
* Request information via form
* Send an SMS notification
* Complete an internal form
Ad-hoc steps are useful for unique situations that don't fit predefined workflows or for responding to unexpected needs during case management.
## How Steps Appear in the Timeline
All steps are recorded in the case timeline, creating a complete audit trail:
**Email steps show:**
* When the email was sent
* Who it was sent to
* Subject and body content
* Delivery status
* Any attachments included
**SMS steps show:**
* When the SMS was sent
* Recipient phone number
* Message content
* Delivery status
**Form steps show:**
* When the form was sent
* Who it was sent to
* Form template used
* Response status (pending, in progress, completed)
* When response was received
* Collected data
**Internal form steps show:**
* Who completed the form
* When it was completed
* Data collected
Each step includes a timestamp and the team member who executed it, maintaining a complete record of all case interactions.
## Modifying and Deleting Steps
**Modifying steps:**
* Predefined steps can be edited in the case template
* Changes to templates don't affect existing cases
* Individual case steps can't be modified after execution
* Draft steps (not yet executed) can be edited or discarded
**Deleting steps:**
* Executed steps can't be deleted (preserves audit trail)
* Draft steps (not yet sent) can be removed
* Steps appear permanently in timeline once executed
This ensures cases maintain an immutable history for compliance and audit purposes.
## Adding Internal Notes
While there isn't a dedicated "Note" step type, you can add internal context to cases in several ways:
**Internal form steps:**
* Create an internal form for team members to complete
* Use text fields to document decisions, observations, or context
* Captured in the timeline with full auditability
**Email steps to internal addresses:**
* Send emails to internal team members
* Include notes, updates, or requests for review
* Appears in case timeline
**Case data fields:**
* Add notes fields to your case data schema
* Update these fields to document progress
* Changes appear in timeline
For regulatory compliance, use internal form steps to document key decisions. This creates a timestamped, auditable record in the case timeline.
## Step Patterns
### Email with Form
The most common pattern for collecting information from contacts:
1. Create an Email step
2. Write professional email content explaining what you need
3. Attach a form link (from template or quick form)
4. Send to contact
5. Contact receives email, clicks link, completes form
6. Response automatically appears in case
**Best practice:** Always provide context in the email. Don't just send a bare form link.
### Sequential Steps
Multiple steps executed in order, with each step dependent on the previous:
1. **Initial email** - Introduce yourself and the process
2. **Form 1** - Collect basic information
3. **Form 2** - Collect additional details (triggered automatically after Form 1 is completed)
4. **Review email** - Send summary for contact confirmation
5. **Final form** - Collect signature or final approval
Use automations to trigger subsequent steps based on completion of previous steps.
[Learn more about Automations →](/cases/automations)
### Conditional Steps
Steps that appear or execute based on case data:
* Show "Additional documentation" form only if contact selects certain options
* Send different emails based on contact language preference
* Trigger specific workflows based on collected data
Configure conditional logic in case templates using automations and step visibility rules.
## Common Configurations
### Email Step Configuration
* **Sender** - Select from connected mailboxes
* **Recipients** - Main contact, secondary contacts, or custom addresses
* **Subject** - Plain text or with variable injection
* **Body** - Rich text editor with variable support
* **Attachments** - Upload files to include
* **Form link** - Optional form to include
### SMS Step Configuration
* **Recipient** - Contact phone number
* **Message** - Text content (160 character limit recommended)
* **Sender** - Workspace SMS number
### Form Step Configuration
* **Form template** - Select from existing templates or create quick form
* **Recipients** - Which contacts receive the form
* **Delivery method** - Email or SMS
* **Deadline** - Optional expiration
* **Reminders** - Automatic follow-up configuration
### Internal Form Configuration
* **Form structure** - Fields for team to complete
* **Assigned to** - Which team member completes it
* **Required fields** - Mandatory data points
* **Visibility** - Who can see the completed form
***
## Next Steps
Design predefined steps in templates
Learn about form design
Automate step execution
Understand case fields
# Product updates January, 2026
Source: https://docs.penbox.io/changelog/2026-01
## Penbox Connect API 2.0: Connect Anything, Effortlessly
We're excited to announce Penbox Connect API 2.0: a complete reimagining of our integration platform that makes connecting Penbox to your tools, workflows, and systems simpler than ever.
Whether you're building a CRM integration, automating workflows, or creating custom dashboards, Connect API 2.0 gives you the flexibility and power to connect anything to Penbox with minimal friction.
## What's New
### 🔐 Simple Token Authentication
**Getting started is now instant.**
We've replaced complex OAuth flows with simple Bearer token authentication. Create a token in your dashboard, copy it, and start making API calls immediately—no redirect URIs, client secrets, or authorization codes required.
Go to Settings → API Tokens, create a token, and you're ready to build.
**Security you can trust:**
* Instant revocation from the dashboard
* Usage tracking and audit trails
* Workspace-scoped permissions
* Secure token storage with industry-standard encryption
[Learn about Authentication →](https://docs.penbox.io/api-reference/authentication)
***
### 🏢 Multi-Workspace Support
**One integration, unlimited workspaces.**
Organizations managing multiple Penbox workspaces can now use a single API token across all of them. No more juggling separate integrations for different subsidiaries, brands, or client environments.
New `/v1/workspaces` endpoint lets you discover available workspaces and filter resources by workspace for consolidated reporting and cross-workspace automation.
Perfect for:
* Multi-tenant applications
* Agency workflows managing multiple clients
* Organizations with multiple brands or subsidiaries
* Consolidated analytics and reporting
[View Workspaces API →](https://docs.penbox.io/api-reference/workspaces/list-workspaces)
***
### 📊 Complete Case Management API
**Build sophisticated workflows programmatically.**
We've expanded case management with comprehensive endpoints for the entire case lifecycle:
* **Create cases** with templates, contacts, and prefilled data
* **Update case data** with batch operations and full attribution tracking
* **Manage contacts** on existing cases
* **Start case steps** to progress workflows programmatically
* **Count and filter cases** for dashboards and reporting
* **Discover case templates** to understand available workflows
Everything you need to integrate Penbox cases into your existing systems and processes.
[Explore Case APIs →](https://docs.penbox.io/api-reference/cases/list-cases)
***
### 🔍 Two Levels of Filtering
**Simple when you need it, powerful when you want it.**
We've introduced a dual-tier filtering system that scales with your needs:
**Method 1: Direct Query Parameters**
Clean, readable URL parameters for everyday filtering:
```bash theme={null}
GET /v1/cases?workspace[id]=abc-123&owner[email]=john@acme.com&status=pending
```
Perfect for straightforward queries—simple to construct, easy to read, and covers most common use cases.
**Method 2: Advanced JSON Filter**
When you need complex queries, use the `filter` parameter with operators:
```bash theme={null}
GET /v1/cases?filter={"attributes":{"created_at":{"$gt":"2024-01-01"}}}
```
Build sophisticated queries with:
* **Comparison operators:** `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
* **Attribute filtering:** Filter on any case field
* **Relationship filtering:** Query across related entities
* **Combined conditions:** Mix multiple criteria in a single query
Go as deep as you need without custom backend logic.
[Learn about Advanced Filters →](https://docs.penbox.io/api-reference/advanced-filters)
***
### 📈 Enhanced Forms & Templates
**More control over form workflows.**
Expanded capabilities for form management:
* **Count endpoint** with grouping by status, template, or custom fields
* **Advanced filtering** on forms with date ranges and complex queries
* **Template discovery** to list available forms and understand their structure
* **Template configuration** access to get options and field definitions
Build form creation flows directly into your applications with full template awareness.
[View Forms API →](https://docs.penbox.io/api-reference/requests/list-requests)\
[View Templates API →](https://docs.penbox.io/api-reference/flows/list-flows)
***
### 📎 Better Attachment Management
**Simplified file operations.**
* Download multiple attachments merged into a single PDF
* Upload files with metadata for better organization
* Access signatures and signed documents programmatically
[Attachments API →](https://docs.penbox.io/api-reference/attachments/get-attachment)
***
## Why This Matters
**For Developers:**
* Get started in minutes instead of hours
* Simpler authentication with no OAuth complexity
* Consistent patterns across all endpoints
* Complete API documentation with interactive examples
**For Integration Teams:**
* One token for all your workspaces
* Build once, deploy everywhere
* Two-tier filtering eliminates custom query logic
* Clear rate limits and error handling
**For Product Teams:**
* Connect Penbox to any tool in your stack
* Build custom dashboards and analytics
* Automate case creation from any source
* Create embedded workflows in your applications
***
## Getting Started
1. **Create an API token** at [app.penbox.io/settings/api](https://app.penbox.io/settings/api)
2. **Make your first request:**
```bash theme={null}
curl https://connect.penbox.io/v1/workspaces \
-H "Authorization: Bearer pnbx_your_token_here"
```
3. **Explore the full API** at [docs.penbox.io/api-reference](https://docs.penbox.io/api-reference/introduction)
***
## Documentation & Resources
* **Complete API Reference:** [docs.penbox.io/api-reference](https://docs.penbox.io/api-reference/introduction)
* **Authentication Guide:** [docs.penbox.io/api-reference/authentication](https://docs.penbox.io/api-reference/authentication)
* **All API Endpoints:** [docs.penbox.io/api-reference/all-endpoints](https://docs.penbox.io/api-reference/all-endpoints)
* **Advanced Filtering:** [docs.penbox.io/api-reference/advanced-filters](https://docs.penbox.io/api-reference/advanced-filters)
* **Pagination & Sorting:** [docs.penbox.io/api-reference/pagination-and-sorting](https://docs.penbox.io/api-reference/pagination-and-sorting)
***
## Backward Compatibility & Migration
**All existing integrations continue to work without changes.**
This release is fully backward compatible—your current API integrations will continue to function exactly as they do today.
**For new integrations or future-proofing existing ones:**
We recommend exploring the new endpoints and Bearer token authentication. The 2.0 endpoints provide better consistency, more powerful filtering, and expanded capabilities that will serve as the foundation for future API development.
Check out the [new endpoints](https://docs.penbox.io/api-reference/all-endpoints) to see what's possible.
***
## Feedback
We built Connect API 2.0 to make integration simple, powerful, and flexible. If you have suggestions or questions, we'd love to hear from you.
Contact your Customer Success Manager or email us at [product@penbox.io](mailto:product@penbox.io).
This update is available to all customers immediately.
**— The Penbox Team**
# Product updates February, 2026
Source: https://docs.penbox.io/changelog/2026-02
# Granular Data Retention & Deletion Audit Log
**Data governance has always been at the center of Penbox.** We've taken a major step forward with two new capabilities.
## Granular Data Retention & Lifecycle Settings
You can now define **granular data retention and lifecycle settings** for both cases and forms, including cascade options for associated forms and contacts. For example, delete cases after 90 days of inactivity, remove closed cases 30 days after closure, or set a hard cap regardless of status.
## Data Deletion Audit Log
Administrators get a **detailed data deletion audit log** that shows exactly what was deleted from Penbox, when, and which rule triggered it—so you can demonstrate compliance and trace any data removal.
[Data Security documentation →](/workspace/settings/data-security)
# Document Intelligence API: Extract Data from Any Document
Penbox Document Intelligence is now available directly from Connect API. Extract structured data from invoices, ID cards, contracts, and forms—all in one API call. Built for real-time workflows, it delivers frontier results with fast processing tailored to the administrative documents your users deal with every day.
## What's New
### Direct API Access
**Document Intelligence is now in your API.**
Send document images or PDFs to `POST /document_intelligence`, define the fields you want to extract, and get back structured JSON—no separate setup or integration required. Perfect for automating invoice processing, onboarding flows, compliance checks, or any workflow that starts with a document.
The engine is fast, built for real-time use, and tuned for the kinds of documents Penbox users typically process: administrative forms, invoices, bank statements, ID documents, and contracts.
[Create Document Intelligence →](/api-reference/document-intelligence/create-document-intelligence)
### List Field Type
**Extract repeating items—invoice lines, table rows, or complex lists.**
You can now define fields with `type: "list"` to extract structured arrays from documents. Each item in the list can have its own sub-fields (product, quantity, price, etc.), so you get fully typed invoice line items, table rows, or any repeating structure—not just flat text.
Use `fields` to define the structure of each item, and the API returns an array of objects with extracted values per item. Empty lists return `[]`; missing regular fields return `null`.
### Validation & Confidence
**Know how reliable each extraction is.**
Every extracted field now includes a `confidence` level (`high`, `medium`, or `low`), so you can decide when to auto-approve or flag for review. The response also includes a `validation` object with:
* **`is_valid`** – Whether the document passes your validation rules
* **`user_explanation`** – A human-readable explanation in your chosen language
* **`is_blurry`** – Whether image quality may affect readability
Use this to route low-confidence extractions or blurry documents to human review automatically.
[Learn more in the API Reference →](/api-reference/document-intelligence/create-document-intelligence)
# Product updates March, 2026
Source: https://docs.penbox.io/changelog/2026-03
# Store and reuse files across your workspace
Penbox now includes a dedicated file storage area under **Console > Files**. Upload documents, images, and assets once, then reference them wherever you need them: in forms, cases, or templates. The new workspace file picker shows authenticated image previews inline, so you see what you are selecting before you select it.
### Improvements and fixes
* **Forms.** Italian and Portuguese are now available as form languages. The translation system has been rebuilt around a cleaner structure, making future language additions faster.
* **Case inbox.** Change status and "waiting for" directly from the datatable, without opening the full case view.
* **Document Intelligence.** Drag and drop to reorder fields in the template editor.
* **Analytics.** Filter reports by a specific form to see only the data that matters for that process.
* **Cases.** Cancelled cases now appear in the All tab, making them searchable without switching views.
# Publish, version, and revert your case templates
**Case templates** now support versioning. Publish a template to lock its current configuration as an immutable snapshot, complete with a version number. Revert to any previous version if something needs to change back. Every case created from a template records which version it used.
### Publishing
When a template is ready, publish it. Penbox creates a numbered snapshot of the full template configuration: fields, structure, rules. The template stays editable for future changes, but the published version is frozen and available for use across the platform.
### Reverting
Roll back a template to any previously published version. The revert restores the full configuration from that snapshot. Useful when a change turns out to be wrong, or when a team needs to return to a known good state quickly.
### Version tracking on cases
Every case created from a published template records the version number it was built from. For templates without a published version, existing behavior is unchanged. No migration, no disruption.
### API
Integrations that create or update cases through the API automatically use the latest published version. No code changes required on the caller side.
[Docs →](/docs/template-versioning)
# Document Intelligence templates
**Document Intelligence now has a template system.** You can define reusable templates that combine **data extraction rules and document validation rules** in one place — then reference them from the API or directly inside a case, without redefining anything each time.
## Template editor
The new visual **template editor** lets you build, test, and trust your document rules without writing any code. Define extraction fields and validation conditions, run them against real documents to see results instantly, then save the template. Once saved, you can **copy its JSON** for direct API use or reference it by ID anywhere in Penbox. For example, build a template for expense reports once — with required fields and validation rules — and reuse it across every integration and case flow that processes them.
## Templates in Connect
**CONNECT's `POST /document-intelligence` endpoint now accepts a `template` reference**, so integrations no longer need to send full rule definitions on every call. For example, pass a template ID instead of an inline configuration and let Penbox resolve the rules server-side — cleaner payloads, easier maintenance.
## Live results in cases
On any **file element** inside a case, you can now attach a **Document Intelligence template**, map its output fields to case data, and see the results appear live as soon as a document is uploaded. For example, attach a contract template to a file element, map extracted clauses and validation outcomes to case attributes, and have everything populated automatically the moment an agent uploads the document — no manual entry required.
# UX, forms, and intelligence improvements
**A round of improvements across cases, forms, and document intelligence** — from a new case status to smarter forms and real-time sync.
## Cancelled status for cases
Cases that are stopped but not resolved now have a dedicated **Cancelled** status, separate from **Closed**. Track cancelled cases in your analytics, filter them independently, and get a clearer picture of where work stops and why. For example, distinguish between cases closed after resolution and cases abandoned mid-process without mixing them in your reporting.
## Revamped Ask with Form
**Ask with Form** has been redesigned to be more precise and configurable. You can now define **predefined values** directly in the settings of a case or case template, giving your contacts guided options rather than open-ended fields. You can also toggle whether to **include the existing value** in the form sent — useful when you want contacts to confirm current information or start fresh. For example, pre-fill an address field with the value already on file and let the contact confirm or update it.
## Skip welcome page on forms
**Smart Checklists** now support a **Skip Welcome Page** option. Enable it on any form where you want contacts to land directly on the first question — no introductory screen, no friction. For example, use it for short, targeted data collection requests where the context is already clear from the email or message that accompanied the link.
## Whitelabel links for generic forms
Generic forms now fully support **whitelabel domains**. Copy the whitelabelled link directly from the app — no need to use `flow.penbox.io` anymore. For example, share a branded form link with contacts without any Penbox domain appearing in the URL.
### Improvements & fixes
* **Email Intelligence.** Improved document mapping accuracy and a cleaner UX for reviewing extraction results.
* **Live case sync.** Case pages now update in real time — every event is pushed live, and you can see when a teammate is viewing the same case alongside you.
* **Performance.** Multiple enhancements across the platform for faster load and smoother interactions.
# Analytics
**Admins now have a dedicated Analytics page** to monitor case performance, agent productivity, and form engagement across the workspace—filtered by date range, owner, or flow.
## Overview
The **Overview tab** gives you an at-a-glance summary of your workspace: active cases, closed cases, average resolution time, and average satisfaction rating. Two charts—**daily case activity** and **case age distribution**—let you spot trends and backlogs before they become problems. For example, use the daily case activity chart to identify spikes in incoming requests and correlate them with team capacity.
## Cases
The **Cases tab** breaks down resolution performance by flow: average resolution time, median resolution time, and resolution rate per template. For example, pinpoint which flows consistently take the longest to close and prioritize process improvements there.
## Owners
The **Owners tab** surfaces per-agent performance so managers can see who is handling the most cases and how quickly. For example, compare resolution times across your team to identify where coaching or workload balancing is needed.
## Forms
The **Forms tab** tracks **Smart Checklist** engagement: forms created, forms completed, completion rate, and average completion time—broken down per form. For example, identify which checklists have low completion rates and adjust them to remove friction.
# Product updates April, 2026
Source: https://docs.penbox.io/changelog/2026-04
# AI-powered email templates
Email templates can now act as AI prompts for automated emails and draft replies. Define the strict canvas once — structure, tone, required sections, variables — and Penbox uses the case context and previous emails to generate messages that stay compliant with the template while still reading as specific and human.
### Template as prompt
The template becomes the prompt. Use it to control what every automatic email or suggested reply must include, while letting AI adapt the wording to the recipient, the case, and the conversation so far.
### Automatic, but personal
Workflows can send AI-generated emails automatically, or provide them as draft replies for review. Teams keep the consistency of a fixed email template without losing the human tone that makes a message feel written for the case in front of them.
### Case links in emails and SMS
Email and SMS messages sent from workflows can now automatically include a direct link to the related **Case**. Recipients and teammates can jump back to the right case without searching, keeping the full conversation connected to the work it belongs to.
# Penbox Agent is now available in beta
**Penbox Agent** is now available in beta for every workspace. It gives teams an AI assistant inside Penbox that can help create, adapt, explain, and refine complex configuration work across forms, logic, signatures, variables, and Document Intelligence.
### Build and edit faster
The agent can create new forms, adapt existing ones, and make precise surgical changes without forcing you to rebuild a full flow. Ask it to change copy, restructure steps, translate content, manage variables, configure signatures, or apply advanced **Penscript** logic.
### Understand what to change
Penbox Agent can also explain how a form or configuration works, what a setting does, and what should change before you apply it. Use it to reason through complex logic, review form behavior, or understand how variables and conditions connect.
### Undo and redo agent actions
Every action performed by the agent can be undone and redone. Try a change, inspect the result, and roll it back if it is not what you wanted.
### Research version for Document Intelligence Templates
We've also added Penbox Agent in a research version for **Document Intelligence Templates**. It can help shape extraction fields, validation logic, and template configuration for document-heavy workflows.
# Install ready-made case templates from the marketplace
Workspace admins can now browse a Penbox-curated **Marketplace** of ready-made **case templates** and install copies into their own workspace. Open **Browse Marketplace** from the case templates page, filter by categories like **Broker**, **Insurance**, or **HR**, and start from a complete operational blueprint instead of a blank template.
### Complete case templates
Marketplace templates can include the pieces that make a case work end to end: pre-made forms, step sequences, case data, automations, and Document Intelligence configuration. Installing a template also installs the forms referenced by its steps, so the copied case template is ready to adapt inside your workspace.
### Independent workspace copies
Installed templates belong to your workspace. Teams can edit their copy without changing the original marketplace template, while Penbox keeps a reference to the source template for future marketplace features.
# Any form can now become a case
Forms now fit directly into the Penbox case model. When **Forms as cases** is enabled, every sent form can create or attach to a **Case**, with the timeline, contacts, workflow steps, and automations that teams use to manage work from start to finish.
### Forms as cases
Forms shared from campaigns, integrations, or direct links no longer have to live outside the operational workflow. Penbox can wrap each form in a case, apply the right case template when one is configured, and keep contact details in sync when the recipient updates their information.
### Case references
Cases now display a short **reference** in the case list and case header. Click the reference to copy it, share it with teammates, or use it when connecting external conversations back to the right case.
### Email mapping
Email workflows can use case references to keep messages attached to the correct case. Replies and forwarded conversations are easier to route, so context stays with the case instead of getting lost in a separate inbox thread.
# A new Penbox brand and redesigned app experience
Penbox has a new visual identity across the product. The redesigned app introduces our updated color system, including our signature **Zen** color, refreshed buttons, cleaner surfaces, and a more consistent interface from first login to daily workspace management.
### Sign-up and sign-in
The new **sign-up** and **sign-in** screens bring the updated brand forward while keeping authentication focused on the next action. New teammates get a calmer, more direct path into the workspace.
### Workspace menu
We've refreshed the **Workspace menu** with a cleaner structure and stronger hierarchy across navigation, actions, and settings. Switch context, find workspace settings, and manage daily work with fewer visual distractions.
### Filters and controls
We've added new filters across the app and updated the color and button styles that power common actions. Filters are easier to scan, buttons feel more consistent, and the updated palette makes important states clearer.
# Product updates May, 2026
Source: https://docs.penbox.io/changelog/2026-05
# Embed forms securely in your website
You can now embed **forms** directly into your public website, customer zone, or application using an `
```
Listen for `postMessage` events from the iframe to know when the form is ready and when it's completed.
## Configuration
Embedding requires a **double opt-in**:
1. **Workspace level**: declare which origins are allowed to embed forms (in **Settings > Branding**)
2. **Form level**: enable embedding on each individual form template
This prevents accidental exposure — a workspace with 50 forms won't have them all embeddable just because one origin is configured.
### Allowed Origins
Origins must be exact matches — no wildcards, no paths, no trailing slashes. HTTPS is required in production. `http://localhost` (with optional port) is allowed for development.
| Valid | Invalid |
| - | - |
| `https://app.example.com` | `https://app.example.com/` (trailing slash) |
| `https://portal.example.com` | `https://*.example.com` (wildcard) |
| `http://localhost:3000` | `https://app.example.com/path` (path) |
You can configure up to **20 origins** per workspace.
If the embedding toggle is on for a form but no origins are configured at
workspace level, embedding will be blocked.
## Query Parameters
| Parameter | Description |
| - | - |
| `embed_v=1` | **Required.** Activates embed mode: hides the top navigation bar and enables postMessage events. |
| `autostart` | **Optional.** Skips the welcome page and starts the form automatically. Recommended for embedded forms. |
A typical embedded URL looks like:
```
https://fill.penbox.io/f/?embed_v=1&autostart
```
## Events
Penbox sends events to the parent window using `postMessage`. All events share the same envelope:
```json theme={null}
{
"source": "penbox",
"type": "",
"v": 1
}
```
### `ready`
Sent when the form layout has mounted and is ready to be displayed.
```json theme={null}
{
"source": "penbox",
"type": "ready",
"v": 1
}
```
### `completed`
Sent exactly once when the form is submitted. Includes the `request_id` for reference.
```json theme={null}
{
"source": "penbox",
"type": "completed",
"v": 1,
"request_id": ""
}
```
The `completed` event fires regardless of whether an auto-redirect is
configured on the form. It is sent before any redirect delay.
### `close`
Sent when the user clicks the close action inside the form. Includes the `request_id` for reference.
```json theme={null}
{
"source": "penbox",
"type": "close",
"v": 1,
"request_id": ""
}
```
## Integration Example
```html theme={null}
```
## Security
Penbox uses the `Content-Security-Policy: frame-ancestors` header to control which origins can embed forms. When embedding is properly configured, the `X-Frame-Options: DENY` header is replaced with a CSP header listing only your allowed origins.
If a page tries to embed a form from an unauthorized origin, the browser blocks it — the iframe will show an error or remain blank.
Always filter incoming `postMessage` events by checking `event.data?.source === 'penbox'` and `event.origin === 'https://fill.penbox.io'` to avoid
processing unrelated messages.
## Known Limitations
* **Exact origins only** — wildcards and regex patterns are not supported. Each origin must be declared explicitly.
* **20 origins max** — contact support if you need more.
* **Token visible to parent** — the parent page can read the iframe URL. This is standard iframe behavior and does not expose additional data.
* **Third-party cookie restrictions** — Safari ITP and Chrome strict mode may block third-party cookies. Penbox uses sessionStorage-based authentication, so this is generally not an issue.
* **Custom form domains** — embedding currently only works with `fill.penbox.io` URLs. Custom domain support is planned.
## Next Steps
Protect forms with access controls
Build and configure form templates
# Form Presets (Flow Customizations)
Source: https://docs.penbox.io/forms/form-presets
Configure and reuse form templates with custom settings
A **Form Preset** (technically called a "Flow Customization" in Penbox) is a configured instance of a Form Template with specific options, security settings, and defaults. Presets allow you to reuse the same template in different contexts with different configurations.
**Terminology**: In the API and some interfaces, Form Presets are called "Flow Customizations." Both terms refer to the same concept.
## Why Use Form Presets?
Form Presets solve a common problem: you've designed a great form template, but you need to use it in different ways for different situations.
### Without Presets
* Create separate form templates for each variation
* Duplicate work when making changes
* Hard to maintain consistency
* Template library becomes cluttered
### With Presets
* One template, multiple configurations
* Update template once, all presets benefit
* Consistent form structure
* Clean, organized template library
* Easy to create variations
## Preset vs. Template
| Aspect | Form Template (Flow) | Form Preset (Flow Customization) |
| - | - | - |
| **Purpose** | Defines form structure and elements | Configures how template is used |
| **Content** | Steps, fields, validation, automations | Options, security, defaults, branding |
| **Created in** | Penbox Studio | Admin settings |
| **Versioning** | Yes, explicit versions | No, links to template version |
| **Relationship** | One template → many presets | Many presets → one template |
## Creating Form Presets
Form Presets are created from published Form Templates.
### Basic Information
| Field | Description | Required |
| - | - | - |
| **Name** | Preset identifier | Optional |
| **Title** | Display name for the preset | Optional |
| **Enabled** | Active/inactive status | Yes (default: true) |
### Linking to Template
Each preset links to a specific Form Template:
```json theme={null}
{
"relationships": {
"flow": {
"data": {
"id": "uuid-of-form-template",
"type": "flows"
}
}
}
}
```
The preset automatically uses the latest published version of the template unless you specify otherwise.
## Preset Configuration
### Options
The `options` object overrides default values from the Form Template.
**Example use cases:**
* Custom welcome message per customer segment
* Different help text for internal vs. external users
* Specific default values for different contexts
* Custom branding elements
```json theme={null}
{
"options": {
"welcome_title": "Welcome, Premium Customer",
"help_email": "premium-support@company.com",
"default_account_type": "business"
}
}
```
### Options Metadata
Control which options are hidden from users creating forms:
```json theme={null}
{
"options_meta": {
"options.help_email": {
"hidden": true
}
}
}
```
This keeps the form creation interface clean by hiding administrative settings.
## Access Security
One of the most powerful features of Form Presets is the ability to configure security requirements.
### OTP Email Security
Require one-time password sent via email:
```json theme={null}
{
"access_security": {
"otp": {
"email": {
"enabled": true,
"default": true,
"mandatory": true,
"template": "otp-email"
}
}
}
}
```
**Properties:**
* `enabled`: Make this option available
* `default`: Use by default when creating forms
* `mandatory`: Must be used (can't be disabled for individual forms)
* `template`: Email template to use for sending OTP
### OTP SMS Security
Require one-time password sent via SMS:
```json theme={null}
{
"access_security": {
"otp": {
"sms": {
"enabled": true,
"default": false,
"mandatory": false,
"text": "Your verification code is: {code}. Valid for 10 minutes."
}
}
}
}
```
**Properties:**
* `enabled`: Make this option available
* `default`: Use by default when creating forms
* `mandatory`: Must be used (can't be disabled for individual forms)
* `text`: SMS message template (must include `{code}`)
### Password Security
Require username and password:
```json theme={null}
{
"access_security": {
"password": {
"enabled": true,
"default": false,
"mandatory": false,
"length": 8,
"lower": 1,
"upper": 1,
"numeric": 1,
"alpha": 2,
"login": {
"username": "client",
"password": "secure123"
}
}
}
}
```
**Properties:**
* `enabled`: Make this option available
* `default`: Use by default
* `mandatory`: Must be used
* `length`: Minimum password length
* `lower`: Minimum lowercase characters
* `upper`: Minimum uppercase characters
* `numeric`: Minimum numeric characters
* `alpha`: Minimum alphabetic characters
* `login`: Default username/password (optional)
### Combining Security Methods
You can enable multiple security methods and let users choose, or require specific combinations:
**Example 1: Choose one**
```json theme={null}
{
"access_security": {
"otp": {
"email": { "enabled": true, "default": true },
"sms": { "enabled": true, "default": false }
},
"password": { "enabled": true, "default": false }
}
}
```
**Example 2: Require both**
```json theme={null}
{
"access_security": {
"otp": {
"email": { "enabled": true, "mandatory": true }
},
"password": { "enabled": true, "mandatory": true }
}
}
```
## Invitations
Customize invitation emails for forms created from this preset:
```json theme={null}
{
"invitations": {
"subject": "Please complete your onboarding form",
"from": {
"email": "onboarding@company.com",
"name": "Onboarding Team"
},
"template": "custom-invitation-template",
"reminders": {
"enabled": true,
"count": 3,
"interval": 2,
"unit": "days"
}
}
}
```
## In-Portal Forms
Form Presets can be made available in a public portal where contacts can self-serve:
```json theme={null}
{
"in_portal": true
}
```
When enabled:
* Form appears in your customer portal
* Contacts can start the form themselves
* No invitation needed
* Still respects access security settings
**Use cases:**
* Self-service document upload
* Public application forms
* Customer portal request forms
* Support ticket submission
## Archiving Presets
Presets can be archived when no longer needed:
```json theme={null}
{
"archived_at": "2024-01-15T10:00:00Z"
}
```
Archived presets:
* Don't appear in active preset lists
* Can't be used to create new forms
* Existing forms still work normally
* Can be unarchived if needed
## Working with Form Presets
### Creating Forms from Presets
When you create a form from a preset:
1. Select the Form Preset
2. Enter contact information
3. Security settings from preset are applied
4. Options from preset are used as defaults
5. Form is created and ready to send
### Use Case Examples
**Scenario**: Same onboarding form, different experience for different customer tiers
**Presets:**
* **Premium Onboarding**
* Personalized welcome message
* Dedicated support email
* SMS + Email OTP for security
* **Standard Onboarding**
* Standard welcome message
* General support email
* Email OTP only
* **Partner Onboarding**
* Partner-specific branding
* Partner support contact
* Password protection
**Scenario**: Same form structure, different languages and compliance per region
**Presets:**
* **EU Customer Form**
* GDPR-compliant text
* EU support contacts
* Privacy policy link
* **US Customer Form**
* US-specific disclosures
* US support contacts
* Different privacy policy
* **Asia Customer Form**
* Regional language support
* Local support contacts
* Region-specific requirements
**Scenario**: Same information needed, different security and defaults
**Presets:**
* **External Client Form**
* High security (OTP + password)
* Formal tone
* External help resources
* **Internal Team Form**
* Lower security (auto-access)
* Casual tone
* Internal wiki links
**Scenario**: Same form triggers different automations
**Presets:**
* **Sales Lead Form**
* Routes to sales team
* Creates CRM entry
* Sends to sales automation
* **Support Request Form**
* Routes to support team
* Creates ticket
* Sends to support automation
## Tracking Preset Usage
Form Presets track how many forms have been created from them:
```json theme={null}
{
"$requests_count": 142
}
```
This helps you understand:
* Which presets are most used
* Which configurations work best
* When to retire old presets
* Usage patterns over time
## Preset Lifecycle
```mermaid theme={null}
graph LR
A[Create Preset] --> B[Configure Settings]
B --> C[Enable Preset]
C --> D[Create Forms]
D --> E{Still Needed?}
E -->|Yes| D
E -->|No| F[Archive Preset]
F --> G{Need Again?}
G -->|Yes| C
G -->|No| H[Keep Archived]
```
## Best Practices
Name presets clearly so team members know when to use each one. "Premium Customer Onboarding" is better than "Form Config 1."
High-security forms for sensitive data (PII, financial, health). Lower security for general inquiries or surveys.
Use the description or internal documentation to explain when and why to use each preset.
Check `$requests_count` to identify unused presets. Archive or delete ones that aren't being used.
Always test the complete form flow with security settings enabled to ensure good user experience.
Don't create presets for every tiny variation. Group similar use cases together.
When updating the underlying template, consider if presets need configuration updates too.
Archive old presets instead of deleting them. This preserves history and allows reactivation if needed.
## Common Configurations
### High Security Preset
```json theme={null}
{
"name": "High Security Form",
"access_security": {
"otp": {
"email": {
"enabled": true,
"default": true,
"mandatory": true
},
"sms": {
"enabled": true,
"default": true,
"mandatory": true
}
}
}
}
```
**Use for:** Financial information, health data, legal documents
### Public Self-Service Preset
```json theme={null}
{
"name": "Public Self-Service",
"in_portal": true,
"access_security": {
"otp": {
"email": {
"enabled": true,
"default": true,
"mandatory": false
}
}
}
}
```
**Use for:** General inquiries, support tickets, feedback forms
### Internal Team Preset
```json theme={null}
{
"name": "Internal Use Only",
"access_security": {
"password": {
"enabled": true,
"default": true,
"mandatory": true,
"login": {
"username": "team",
"password": "internal123"
}
}
}
}
```
**Use for:** Internal data collection, team surveys, process forms
### Premium Customer Preset
```json theme={null}
{
"name": "Premium Customer",
"options": {
"welcome_title": "Welcome, Valued Customer",
"support_email": "premium@company.com",
"priority": "high"
},
"access_security": {
"otp": {
"email": {
"enabled": true,
"default": true,
"template": "premium-otp-email"
}
}
}
}
```
**Use for:** VIP customers, enterprise clients, high-value accounts
## Next Steps
Learn about creating form templates
Understand form instances
Complete guide to form security
Set up your customer portal
# Form Templates
Source: https://docs.penbox.io/forms/form-templates
Design and build form templates in Penbox Studio
A **form template** defines the structure, appearance and behaviour of the forms you send to contacts. It is what you design in **Penbox Studio**, the form builder.
**For administrators and creators**: this section is for the people who design
form templates. If you only need to send forms to contacts, see
[Forms](/forms/introduction).
## What a template defines
* **Structure** — [steps](/forms/form-templates/steps) and the [elements](/forms/form-templates/elements) that collect data
* **Portal experience** — the [welcome, review and ending pages](/forms/form-templates/portal-pages)
* **Behaviour** — conditional logic, variables, calculations and integrations
* **Notifications** — invitations, reminders and completion emails
* **Automations** — actions triggered by what happens to the form
* **Appearance** — branding and layout
Every element type you can put in a form, and how to configure it
Organise elements into steps and branch on answers
Welcome, review and ending screens
## Versioning
Templates are versioned, so you can keep iterating on a design without disturbing the forms already in the wild.
1. **Create a template** — starts as version 1
2. **Make changes** — edit in draft
3. **Publish the version** — locks it for use
4. **Create a new version** — keep iterating
5. **Publish when ready** — new forms use the latest published version
### Version properties
* **Version number** — auto-incremented integer (1, 2, 3…)
* **Published** — published versions can be used in form presets
* **Deprecated** — marks an old version as no longer recommended
* **Active version** — form presets follow the latest published version by default
A form always keeps the version it was created with. Publishing a new version
never changes forms already in progress — only newly created forms pick it up.
## Basic information
| Field | Description | Required |
| - | - | - |
| **Name** | Template identifier (max 64 chars) | Yes |
| **Slug** | URL-friendly identifier | Auto-generated |
| **Version** | Version number | Auto |
| **Locale** | Default language (2-char code) | Yes |
| **Description** | What this template is for (max 1000 chars) | No |
## Multiple languages
A template supports several languages through its `locales` and `strings` configuration.
**Locales**
```json theme={null}
["en", "fr", "es", "de"]
```
**Strings**
```json theme={null}
{
"en": {
"welcome_title": "Welcome",
"submit_button": "Submit"
},
"fr": {
"welcome_title": "Bienvenue",
"submit_button": "Soumettre"
}
}
```
Contacts can switch language in the portal, and every translated string follows.
## Automations
Automations are actions triggered by what happens to a form.
An automation has a `name`, an optional `icon`, an optional `delay` in minutes, the list of events it reacts to in `on`, and its `actions`.
### Triggers
| Event | Fires when |
| - | - |
| `responses:created` | A response is created, as a draft |
| `responses:updated` | A response is updated |
| `responses:completed` | The form is completed and submitted |
| `responses:declined` | The contact declines the form |
| `requests:active` | The form becomes active |
| `requests:expired` | The form expires without being completed |
| `manual` | A team member runs it by hand |
### Actions
Each action has a `type` and an `options` object, plus optional `ref`, `name`, `if`, `as` and `result`.
| Type | Does |
| - | - |
| `email` | Sends an email |
| `data-push-email-v2` | Sends the collected data by email |
| `http` | Calls an external HTTP endpoint |
| `core` | Acts on Penbox data |
| `file` | Produces or transforms a file |
| `connection_fetch` | Reads from a connected system |
| `ai_generate_data` | Generates data with the assistant |
```json theme={null}
{
"automations": [
{
"id": "8b1c…",
"name": "Notify the broker",
"icon": "envelope",
"delay": 0,
"on": ["responses:completed"],
"actions": [{ "type": "email", "options": { "…": "…" } }]
}
]
}
```
Use `delay` to wait before running — `1440` for a reminder one day after the response was created.
## Notifications
Notifications are emails about the form itself, sent to your team rather than driven by an automation.
```json theme={null}
{
"notifications": [
{
"type": "email",
"to": [{ "email": "admin@company.com" }, { "role": "owner" }],
"on": ["responses:completed"]
}
]
}
```
Each recipient is either an `email` or a `role` — `owner` or `creator`, never both at once. Notifications fire on `responses:completed` or on `request_notifications:bounced`, when an invitation email bounces.
Emails sent to the contact — invitations, reminders, confirmations — are configured separately. See [Notifications](/forms/notifications).
## Publishing
1. **Build and test** the template
2. **Check** every step and element behaves as expected
3. **Publish** the version, which locks it
4. The version can now be used in form presets
Before publishing, make sure that:
* Conditional logic behaves as expected
* Required fields are the right ones
* Images and assets load
* Translations are complete, if the template is multilingual
* Automations are correctly configured
* A test submission works end to end
## Best practices
Most contacts complete forms on a phone. Test on a small screen.
Only ask for what you need. Every extra field costs completion rate.
Break a long form into logical steps, but don't overdo it — three to five
steps is usually the sweet spot.
Use the `help` on a title to explain what you expect, especially on fields
that are unusual or formatted.
Always run the whole flow before publishing. Submit test data and check the
automations actually ran.
Conditional steps and elements keep the form short for each contact.
Send a confirmation on completion. It builds trust and acts as a receipt.
Don't cut a new version for a typo. Batch changes to avoid version sprawl.
## Next steps
Configure presets from a template
Invitations, reminders and confirmations
Show a form inside your own site
Understand form instances
# Elements
Source: https://docs.penbox.io/forms/form-templates/elements
Every element type you can put in a form, and how to configure it
Elements are the building blocks of a form. Each step holds a list of them: input fields that collect an answer, content blocks that only display something, and a few technical elements that drive behaviour.
Every option on this page is read by the form engine.
## Anatomy of an element
An element is an object with a `type`. Everything else is optional and depends on that type.
```json theme={null}
{
"key": "company_name",
"type": "text",
"title": "Company name",
"placeholder": "Acme Corporation",
"required": true
}
```
These properties work on every element type:
| Property | Type | Default | Description |
| - | - | - | - |
| `type` | `string` | **Required** | The element type, such as `text` or `file`. |
| `key` | `string` | — | Where the answer is stored. See [Keys](#keys). |
| `title` | `string \| object` | — | The label shown above the field. See [Titles and help text](#titles). |
| `required` | `boolean` | `false` | Whether an answer is mandatory. See [Required](#required). |
| `default` | `any` | — | Value used when the field has never been answered. |
| `value` | `any` | — | Value forced onto the field, overriding stored data. |
| `id` | `string` | — | Explicit identifier. Generated automatically when omitted. |
| `error` | `string \| object` | — | Custom error message, replacing the validation message. |
| `meta` | `object` | — | Free-form data attached to the element. Ignored by the engine. |
## How elements behave
The `key` decides where the answer lands in the form data.
A key without a dot is automatically prefixed with `data.` — so `"key": "birth_date"` stores the answer in `data.birth_date`. A key that already contains a dot is used as-is, which is how you write into the contact:
```json theme={null}
{ "key": "user.email", "type": "text", "format": "email" }
```
An element with no `key` collects nothing. That is expected for content blocks such as `paragraph` or `image`.
`title` accepts a plain string, or an object carrying an extra help message shown next to the label:
```json theme={null}
{
"key": "vat_number",
"type": "text",
"title": {
"text": "VAT number",
"help": "Found on any invoice, starting with your country code."
}
}
```
Some elements also accept a `label`, which is the text shown *inside* the control rather than above it — the text next to a `checkbox`, or the caption of a `button`. Where both exist, `title` is the field label and `label` is the control's own text.
`required: true` only takes effect when the element can actually be answered. The engine ignores it when there is nothing to answer: a `choices` element with an empty `choices` list, a `signature` or `download` with no `items`, and always on `paragraph`, `image` and `toggle`.
A required `checkbox` must be *checked*, not merely answered.
To show an element only under a condition, wrap it in an `:if` / `:then` block instead of putting a property on the element:
```json theme={null}
{
":if": { ":cmp": "{data.account_type}", ":eq": "business" },
":then": {
"key": "company_registration",
"type": "text",
"title": "Company registration number"
}
}
```
`:then` accepts a single element or an array of elements. The full operator syntax lives in the [penscript reference](/penscript/logic).
Most interactive elements accept `submit_on_change`. When set to `true`, answering the element submits the step immediately instead of waiting for the submit button. The Studio labels this option **Auto-advance**.
Auto-advance works well on a step that asks a single question — a yes/no
choice that branches the rest of the form. On a step with several fields it
submits before the contact is done.
## Text and numbers
Single-line or multi-line free text. `format` also turns it into an email or phone input.
| Option | Type | Default | Description |
| - | - | - | - |
| `format` | `string` | `text` | `text`, `email` or `tel`. Drives the keyboard and the validation. |
| `multiline` | `boolean` | `false` | Renders a textarea. Only with `format: "text"`. |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
| `min` | `number` | `0` | Minimum number of characters. |
| `max` | `number` | — | Maximum number of characters. |
| `pattern` | `string` | — | Regular expression the answer must match. |
| `mask` | `string` | — | Input mask. Only with `format: "text"`. |
| `prefix` | `string` | — | Text displayed before the value. |
| `suffix` | `string` | — | Text displayed after the value. |
| `transforms` | `array` | — | Transformations applied to the typed value, such as uppercasing. |
| `autocomplete` | `string` | — | Browser autocomplete hint, e.g. `given-name`, `postal-code`. |
| `clearable` | `boolean` | `true` | Shows the clear button. Set to `false` to hide it. |
| `readonly` | `boolean` | `false` | Displays the value without allowing edits. |
```json theme={null}
{
"key": "claim_description",
"type": "text",
"title": "What happened?",
"multiline": true,
"max": 2000,
"placeholder": "Describe the incident, when it happened, and who was involved."
}
```
For phone numbers, the [`phone`](#phone) element gives a better experience
than `format: "tel"`: country prefix selector, national formatting, and
mobile-only validation.
| Option | Type | Default | Description |
| - | - | - | - |
| `min` | `number` | — | Lowest accepted value. |
| `max` | `number` | — | Highest accepted value. |
| `decimals` | `number` | `0` | Maximum number of decimals, up to 100. |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
| `prefix` | `string` | — | Text displayed before the value. |
| `suffix` | `string` | — | Text displayed after the value, e.g. `km`. |
| `autocomplete` | `string` | — | Browser autocomplete hint. |
| `clearable` | `boolean` | `true` | Shows the clear button. |
| `readonly` | `boolean` | `false` | Displays the value without allowing edits. |
```json theme={null}
{
"key": "mileage",
"type": "number",
"title": "Mileage",
"suffix": "km",
"min": 0,
"max": 999999
}
```
Same shape as `number`, but the answer is always capped at two decimals and rendered with thousands separators.
| Option | Type | Default | Description |
| - | - | - | - |
| `min` | `number` | `0` | Lowest accepted amount. |
| `max` | `number` | — | Highest accepted amount. |
| `prefix` | `string` | — | Currency symbol shown before the amount. |
| `suffix` | `string` | — | Currency symbol shown after the amount. |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
| `clearable` | `boolean` | `true` | Shows the clear button. |
```json theme={null}
{
"key": "damage_estimate",
"type": "currency",
"title": "Estimated damage",
"prefix": "€"
}
```
The answer is validated against the IBAN checksum, stored without spaces, and displayed grouped by four characters.
| Option | Type | Default | Description |
| - | - | - | - |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
```json theme={null}
{
"key": "iban",
"type": "bank-account",
"title": "Account to refund",
"placeholder": "BE00 0000 0000 0000",
"required": true
}
```
## Dates
The answer is stored as `YYYY-MM-DD`.
| Option | Type | Default | Description |
| - | - | - | - |
| `pattern` | `string` | `locale-dependent` | Display format, e.g. `D/M/Y`. Defaults to `M/D/Y` in English and `D/M/Y` in French, Dutch and German. |
| `patterns` | `object` | — | One pattern per locale, e.g. `{ "en": "M/D/Y", "fr": "D/M/Y" }`. |
| `min` | `date` | `1900-01-01` | Earliest accepted date. |
| `max` | `date` | `min + 200 years` | Latest accepted date. |
| `weekDays` | `boolean` | `false` | Restricts the picker to weekdays. |
| `picker` | `boolean` | `true` | Set to `false` to force manual typing instead of the calendar. |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
```json theme={null}
{
"key": "incident_date",
"type": "date",
"title": "Date of the incident",
"max": "today",
"required": true
}
```
Same options as [`date`](#date), minus `picker`. The answer is stored as an ISO 8601 timestamp.
## Contact details
Phone input with a country prefix selector. The answer is stored in international E.164 format, and displayed in national format when it matches the configured country.
| Option | Type | Default | Description |
| - | - | - | - |
| `country` | `string` | — | Default country, as a two-letter code, e.g. `BE`. |
| `accept` | `string` | — | `mobile` or `fixed-line`. Rejects numbers of the other kind. |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
| `autocomplete` | `boolean` | `false` | Enables browser autocomplete. |
```json theme={null}
{
"key": "user.phone",
"type": "phone",
"title": "Mobile number",
"country": "BE",
"accept": "mobile",
"required": true
}
```
Use `accept: "mobile"` whenever you plan to send an SMS — a reminder, or an
SMS signature. It stops a landline from being accepted at fill time instead
of failing silently later.
The list is built from the ISO 3166 country list and translated into the form locale (English, French, Dutch and German; any other locale falls back to English). The answer is stored as a two-letter country code.
| Option | Type | Default | Description |
| - | - | - | - |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
| `readonly` | `boolean` | `false` | Displays the value without editing. |
| `submit_on_change` | `boolean` | `false` | Submits the step on selection. |
## Choices and ratings
Every choice element shares the same `choices` list:
```json theme={null}
"choices": [
{ "value": "car", "label": "Car" },
{ "value": "bike", "label": "Bike" },
{ "value": "other", "label": "Something else" }
]
```
`value` can be a string, a number, a boolean or `null`. `label` is what the contact reads; when omitted, the value itself is displayed. A label can also carry help text, like a title: `{ "text": "Car", "help": "Including vans under 3.5t" }`.
A `null` choice — an explicit "none of these" — is only added when the element
is not required.
Handles both single and multiple selection, and renders either as a list or as cards.
| Option | Type | Default | Description |
| - | - | - | - |
| `choices` | `array` | `[]` | The available options. |
| `min` | `number` | — | Minimum number of selected options. |
| `max` | `number` | — | Maximum number of selected options. `max: 1` makes it a single selection. |
| `display` | `string` | — | `horizontal` or `vertical`. |
| `cards` | `boolean` | `false` | Renders each option as a clickable card. |
| `submit_on_change` | `boolean` | `false` | Submits the step on selection. |
With `max: 1` the answer is stored as a single value; otherwise it is stored as an array.
```json theme={null}
{
"key": "vehicle_type",
"type": "choices",
"title": "What was damaged?",
"choices": [
{ "value": "car", "label": "Car" },
{ "value": "bike", "label": "Bike" }
],
"max": 1,
"cards": true,
"display": "horizontal",
"submit_on_change": true
}
```
Multiple selection rendered as a list of checkboxes. Same options as [`choices`](#choices).
Single selection rendered as radio buttons.
| Option | Type | Default | Description |
| - | - | - | - |
| `choices` | `array` | `[]` | The available options. |
| `allow_custom` | `boolean` | `false` | Accepts a free-text answer outside the list. |
| `submit_on_change` | `boolean` | `false` | Submits the step on selection. |
Single selection rendered as a row of toggle buttons. Same options as [`radio`](#radio).
Single selection from a searchable dropdown. Use it when the list is too long for radio buttons.
| Option | Type | Default | Description |
| - | - | - | - |
| `choices` | `array` | `[]` | The available options. |
| `allow_custom` | `boolean` | `false` | Accepts a value typed outside the list. |
| `placeholder` | `string` | — | Hint shown inside the empty field. |
| `hint` | `string` | — | Persistent hint shown under the field. |
| `readonly` | `boolean` | `false` | Displays the value without editing. |
| `submit_on_change` | `boolean` | `false` | Submits the step on selection. |
For a consent or an acknowledgement. The answer is a boolean.
| Option | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | — | The text shown next to the box. |
| `submit_on_change` | `boolean` | `false` | Submits the step on change. |
```json theme={null}
{
"key": "terms_accepted",
"type": "checkbox",
"label": "I confirm the information above is accurate",
"required": true
}
```
A required `checkbox` must be ticked to pass validation. Unticking it blocks
the step.
Same options as [`checkbox`](#checkbox), plus `inline` to place it on the same line as its title.
A `toggle` can never be required — use a `checkbox` when the answer must be positive.
The answer is an integer between 0 and 5. This element takes no options.
## Files and signatures
| Option | Type | Default | Description |
| - | - | - | - |
| `multiple` | `boolean` | `false` | Allows several files. Changes the answer from a single file to a list. |
| `min` | `number` | `0` | Minimum number of files. Only with `multiple: true`. |
| `max` | `number` | — | Maximum number of files. Only with `multiple: true`. |
| `accept` | `string` | — | Comma-separated list of accepted types, e.g. `".pdf,.jpg,image/*"`. |
| `minSize` | `number` | `0` | Minimum size per file, in bytes. |
| `maxSize` | `number` | — | Maximum size per file, in bytes. |
| `custom_name` | `string` | — | Renames uploaded files, so attachments arrive with a predictable name. |
| `extract` | `object` | — | Document intelligence extraction. See [Document intelligence](/agent/templates/document-intelligence). |
| `hint` | `string` | — | Persistent hint shown under the field. |
```json theme={null}
{
"key": "registration_certificate",
"type": "file",
"title": "Vehicle registration certificate",
"accept": ".pdf,.jpg,.jpeg,.png",
"maxSize": 10485760,
"custom_name": "registration",
"required": true
}
```
`accept` is a single comma-separated string, not an array. It takes
extensions (`.pdf`), exact MIME types (`application/pdf`) and wildcards
(`image/*`).
Offers one or more documents to the contact — a policy, a quote, terms and conditions. Documents can be filled with form data before being served.
| Option | Type | Default | Description |
| - | - | - | - |
| `items` | `array` | **Required** | The documents to offer. Each item takes `uri`, `key`, `name`, `type`, `size`, `fill` (data merged into the document) and `fillOptions.convertToPdf`. |
| `custom_name` | `string` | — | Renames the downloaded files. |
| `submit_on_change` | `boolean` | `false` | Submits the step once a document has been downloaded. |
| Option | Type | Default | Description |
| - | - | - | - |
| `items` | `array` | `[]` | The documents to sign. Each item takes a `uri` pointing at the document, an optional `name`, a `fill` object merged into it, and a `signatures` array placing each signature — by page coordinates (`page`, `left`, `top`, and optionally `width`, `height`), by form field name (`field`), or by text hint (`hint`). |
| `method` | `string` | `sms` | `sms`, `email`, `handwritten`, `id-card`, `itsme` or `swisscom`. |
| `merge` | `boolean` | `true` | Merges all documents into a single signed file. |
| `allow_rejection` | `boolean` | `false` | Lets the contact refuse to sign without blocking the form. |
| `additional_signers` | `array` | `[]` | Other people who must sign, each with `given_name`, `family_name`, `email`, and optionally `phone`, `locale` and `signature_hint`. |
| `hide_files` | `boolean` | `false` | Hides the document list. |
| `hide_download` | `boolean` | `false` | Hides the download button. |
| `legal_notice` | `object` | — | Custom legal notice shown before signing. |
| `name` | `string` | — | Name of the resulting signed document. |
| `locale` | `string` | — | Forces the signing interface language. |
| `submit_on_change` | `boolean` | `false` | Submits the step once signed. |
A `signature` with an empty `items` list cannot be required — there is
nothing to sign. The same applies to [`download`](#download).
## Content blocks
These elements display something and collect no answer. They take no `key` and cannot be required.
| Option | Type | Default | Description |
| - | - | - | - |
| `content` | `string` | — | The text to display. HTML is supported. |
Optionally with an icon, a colour and action buttons.
| Option | Type | Default | Description |
| - | - | - | - |
| `content` | `string` | — | The text inside the card. HTML is supported. |
| `color` | `string` | — | Background colour, e.g. `primary lighten-5`. |
| `dark` | `boolean` | `false` | Switches the text to its light variant, for dark backgrounds. |
| `icon` | `string` | — | Icon shown in the card. |
| `actions` | `array` | — | Buttons, each with a `title`, an optional `icon`, and either a `url` or a `key`. |
| Option | Type | Default | Description |
| - | - | - | - |
| `src` | `string` | — | Image URL. Must start with `https://` or `//`. |
| `alt` | `string` | — | Alternative text, read by screen readers. |
| `width` | `string` | `100%` | CSS width. |
| `height` | `number \| auto` | `200` | Height in pixels, between 1 and 1000, or `auto`. |
| `justify` | `string` | `center` | `left`, `right`, `center`, `start` or `end`. |
## Technical elements
| Option | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | — | The button caption. |
| `return` | `any` | — | Value stored when the step is submitted. |
You rarely need to declare it: when a step contains no `submit` element, one is appended automatically — unless the last element of the step has `submit_on_change: true`, in which case answering it submits the step.
Use it to branch a form without a visible choice list.
| Option | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | — | The button caption. |
| `return` | `any` | `null` | Value stored when the button is clicked. |
| `outlined` | `boolean` | `false` | Renders the button outlined. |
| `submit_on_change` | `boolean` | `false` | Submits the step when clicked. |
Typically used to carry a campaign source, an external identifier, or a computed value.
```json theme={null}
{
"key": "source",
"type": "hidden",
"default": "email_campaign"
}
```
A required `hidden` element blocks the form until the value is non-empty — useful to guarantee that a computed value was actually resolved.
Calls an external API from inside the form and stores the response, so later steps and pricing can use it.
| Option | Type | Default | Description |
| - | - | - | - |
| `url` | `string` | **Required** | The endpoint to call. |
| `method` | `string` | `GET` | `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. |
| `headers` | `object` | `{}` | Request headers. |
| `body` | `object` | `{}` | Request body. |
| `mapping` | `object` | — | Maps the response into form data keys. |
| `store_response` | `boolean` | `true` | Stores the raw response alongside the mapped values. |
| `validate_step` | `boolean` | `false` | Makes a failed call block the step. |
| `invalidate_on_change` | `array` | `[]` | Data keys to watch. When any of them changes, the stored response is treated as stale and the call must run again. |
| `invalidate_message` | `string` | — | Message shown when the response has been invalidated. |
| `auth` | `object` | — | Authentication, e.g. `{ "method": "creditsafe", "username": "…", "password": "…" }`. |
| `submit_on_change` | `boolean` | `false` | Submits the step once the call succeeds. |
```json theme={null}
{
"key": "pricing",
"type": "api",
"url": "https://api.example.com/quote",
"method": "POST",
"body": { "vehicle": "{data.vehicle_type}", "value": "{data.vehicle_value}" },
"invalidate_on_change": ["data.vehicle_type", "data.vehicle_value"],
"invalidate_message": "Your quote is out of date, please recalculate it."
}
```
Without `invalidate_on_change`, a contact who goes back and changes an input
keeps the response computed from the old answers. List every key the call
depends on.
Sends the contact to an external web flow — an identity check, a third-party payment — and stores what comes back.
| Option | Type | Default | Description |
| - | - | - | - |
| `href` | `string` | **Required** | The external URL. |
| `mode` | `string` | `redirect` | `redirect` or `popup`. |
| `setup.payload` | `object` | — | Data sent to the external flow on start. |
| `submit_on_change` | `boolean` | `false` | Submits the step once the flow returns. |
## Next steps
Organise elements into steps and branch on answers
Welcome, review and ending screens
The expression language behind conditions and variables
Back to form templates
# Portal pages
Source: https://docs.penbox.io/forms/form-templates/portal-pages
The welcome, review and ending screens that frame a form
Around the form steps, a template defines three screens: the **welcome** page a contact lands on, the **review** page shown before final submission, and the **ending** page shown once the form is sent.
The contact opens the link and reads what the form is for.
They fill in the [elements](/forms/form-templates/elements), step by step.
They check their answers, then send.
They get a confirmation, and optionally a redirect.
## Disabling a page
Every page takes an `enabled` flag. Turning it off does more than hide the screen:
| Page | `enabled: false` means |
| - | - |
| Welcome | The contact lands directly on the first step. |
| Review | The form **submits automatically** once the last step is done. |
| Ending | The contact is **redirected automatically** to `redirect-url`, after a short delay. |
The automatic redirect is driven by the ending page being *disabled*, not by
setting `redirect-url` alone. To redirect without showing a confirmation
screen, set `redirect-url` **and** `enabled: false`.
## Page options
Each page carries its texts under `options`. Every text can be localised, and every one falls back to a built-in default when left empty — so a template with no `options` at all still renders a complete portal.
The first screen a contact sees when opening the form.
| Option | Type | Default | Description |
| - | - | - | - |
| `image` | `string \| object` | `cdn://pen-fill/hello.svg` | Header image. A URL, a `cdn://` path, or an uploaded attachment as `{ "type": "attachment", "id": "…" }`. |
| `title` | `string` | `Hello {user.given_name}` | Page title. Variables are resolved, so the default greets the contact by name. |
| `message` | `string` | `Please use this secure form to provide us the required data` | Welcome message. HTML is supported. |
| `start-button` | `string` | `Let's get started` | Caption of the button that opens the first step. |
| `show-help-button` | `boolean` | `true` | Shows the help button. |
| `help-text` | `string` | — | Custom help content, replacing the default help panel. |
| `show-privacy-policy` | `boolean` | `true` | Shows the privacy policy notice. |
| `custom-privacy-policy` | `string` | — | Your own privacy policy text, replacing the Penbox one. |
```json theme={null}
{
"welcome": {
"enabled": true,
"options": {
"image": "cdn://pen-fill/hello.svg",
"title": "Hello {user.given_name}",
"message": "
Please use this secure form to send us your claim details.
",
"start-button": "Let's get started",
"show-help-button": true,
"show-privacy-policy": true
}
}
}
```
A clear welcome page raises completion rates. Say what the form is for, how
long it takes, and why the information is needed.
Shown once every step is done, before the contact sends their answers. It has two states — **valid**, when everything required has been answered, and **invalid**, when something is still missing — each with its own texts.
**Valid state**
| Option | Type | Default | Description |
| - | - | - | - |
| `valid-image` | `string \| object` | `cdn://pen-fill/one_last_thing.svg` | Image shown when the form is complete. |
| `valid-title` | `string` | `Send your responses !` | Title shown when the form is complete. |
| `valid-message` | `string` | `Please click on Send to complete. To check or modify your data, click on modify.` | Instructions shown above the buttons. |
| `valid-submit-button` | `string` | `Send` | Caption of the send button. |
| `valid-modify-button` | `string` | `Modify` | Caption of the button that goes back to the form. |
| `valid-confirmation-message` | `string` | `By sending the information, you confirm it is correct and accurate.` | Statement the contact confirms by sending. |
**Invalid state**
| Option | Type | Default | Description |
| - | - | - | - |
| `invalid-image` | `string \| object` | `cdn://pen-fill/one_last_thing.svg` | Image shown when answers are missing. |
| `invalid-title` | `string` | `Your responses are incomplete !` | Title shown when answers are missing. |
| `invalid-message` | `string` | `We still need some information from you.` | Explanation of what is left to do. |
| `invalid-button` | `string` | `Go back` | Caption of the button that returns to the form. |
```json theme={null}
{
"submit": {
"enabled": true,
"options": {
"valid-title": "Send your claim",
"valid-submit-button": "Send",
"valid-modify-button": "Modify",
"invalid-title": "Something is still missing",
"invalid-button": "Back to the form"
}
}
}
```
The review page is configured under the `submit` key, not `review`.
Shown after a successful submission.
| Option | Type | Default | Description |
| - | - | - | - |
| `image` | `string \| object` | `cdn://pen-fill/well-done.svg` | Confirmation image. |
| `title` | `string` | `Your answers are being treated!` | Confirmation title. |
| `message` | `string` | `You can now close this window.` | Closing message. HTML is supported. |
| `rate-ux` | `boolean` | `true` | Shows the satisfaction rating widget. |
| `redirect-url` | `string` | — | Where to send the contact afterwards. Combine with `enabled: false` to redirect automatically. |
```json theme={null}
{
"ending": {
"enabled": true,
"options": {
"image": "cdn://pen-fill/well-done.svg",
"title": "Thank you, your claim is on its way",
"message": "Our team will come back to you within two working days.",
"rate-ux": true
}
}
}
```
## Next steps
Every element type and its options
Organise elements into steps and branch on answers
Show a form inside your own site
Back to form templates
# Steps and logic
Source: https://docs.penbox.io/forms/form-templates/steps
Organise elements into steps, and branch the form on what contacts answer
A form is a list of steps. Each step is one screen the contact sees, holding the elements that collect data. Splitting a form into steps keeps each screen short and lets you skip whole sections that don't apply.
## Declaring a step
```json theme={null}
{
"id": "company_information",
"label": "Company information",
"elements": [
{ "key": "company_name", "type": "text", "title": "Company name" },
{ "key": "vat_number", "type": "text", "title": "VAT number" }
]
}
```
| Property | Type | Description |
| - | - | - |
| `id` | String | Identifier for the step. |
| `label` | String | Step name shown in the progress indicator. Optional. |
| `enabled` | Boolean | Whether the step is part of the form. Defaults to `true`. |
| `elements` | Array | The [elements](/forms/form-templates/elements) on this screen. |
| `meta` | Object | Free-form data attached to the step. Ignored by the engine. |
## Submitting a step
A step needs a way to move forward. You don't have to declare it: when a step contains no `submit` element, one is appended automatically.
Declare a `submit` element yourself when you want to control its caption:
```json theme={null}
{ "type": "submit", "label": "Continue" }
```
The automatic button is skipped when the last element of the step has `submit_on_change: true` — answering that element submits the step on its own. That is the pattern for a one-question step that branches the rest of the form.
## Conditional steps
Wrap a step in an `:if` / `:then` block to include it only when a condition holds:
```json theme={null}
{
":if": { ":cmp": "{data.account_type}", ":eq": "business" },
":then": {
"id": "business_details",
"label": "Business details",
"elements": [
{ "key": "company_registration", "type": "text", "title": "Registration number" }
]
}
}
```
The same wrapper works around individual elements, so you can hide a single field rather than a whole screen. See [Conditional elements](/forms/form-templates/elements#conditional-elements).
Conditions are written in penscript — the full operator list is in the [logic reference](/penscript/logic).
Prefer a conditional step over a long screen of conditional fields. A contact
who sees a screen half-empty because most of its fields were hidden reads it
as a broken form.
## Variables
Variables are values defined once and reused across the whole form — static constants, or values computed from answers.
### Defining variables
Without dependencies, use an object:
```json theme={null}
{
"variables": {
"company_email": "support@company.com",
"max_upload_size": 10485760
}
}
```
When one variable depends on another, use an array — entries are resolved in order:
```json theme={null}
{
"variables": [
{ "base_price": 100 },
{ "tax_rate": 0.2 },
{ "total_price": "{base_price} * (1 + {tax_rate})" }
]
}
```
### Using variables
Reference a variable anywhere in the form with `{variable_name}`:
```json theme={null}
{
"type": "paragraph",
"content": "Any question? Write to {company_email}."
}
```
`user`, `data`, and any name starting with `$` are reserved. Do not use them
as variable names.
## Next steps
Every element type and its options
Welcome, review and ending screens
The expression language behind conditions and variables
Back to form templates
# Introduction
Source: https://docs.penbox.io/forms/introduction
Understanding forms for data collection
**Forms** in Penbox are individual form instances sent to specific contacts for data collection. Each form has a unique link and can be secured with various authentication methods.
**Terminology**: In Penbox's technical documentation and API, forms are referred to as "requests." In this user documentation, we'll primarily use "form" since that's more intuitive.
## What is a Form?
Think of a form as a personalized questionnaire sent to a specific person. Each form:
* Has a **unique link** that only works for that specific recipient
* Can be **secured** with passwords or one-time codes
* Tracks its own **status** (pending, completed, etc.)
* Stores the **response** data when submitted
* Can **expire** after a certain time period
* Triggers **automations** when completed
## When to Use Forms
Forms are ideal for collecting information from external parties:
Collect customer information, documents, and agreements
Request specific documents from clients or partners
Gather structured data for compliance, verification, or analysis
Process applications, registrations, or submissions
Collect feedback, surveys, or satisfaction ratings
Gather Know Your Customer and compliance information
## Form Reference Numbers
Each form is automatically assigned a unique **6-character alphanumeric reference** (e.g., `A4K7X9`) for easy identification and tracking.
**Reference numbers are used for:**
* Quick lookup and search
* Customer support
* Email communications
* Tracking conversations
* Audit trails
## How Forms Work
### Creating Forms
Forms can be created from **Form Presets**:
1. Select the Form Preset to use
2. Enter contact information (email, name, phone)
3. Optionally pre-fill data
4. Set expiration date (if needed)
5. Form is created and ready to send
### Sending Forms
When you send a form, the contact receives:
1. **Invitation email** (if configured)
* Link to the form
* Instructions
* Your branding
* Deadline (if applicable)
2. **Unique access link**
* Can be shared separately
* Works on any device
* Can use custom domains
### Contact Experience
1. Contact clicks the form link
2. Security check (if configured): OTP, password, or auto-access
3. Welcome page with instructions
4. Fill out form steps
5. Review page to check answers
6. Submit or decline
7. Confirmation page
### After Submission
When a contact submits a form:
* Response is stored
* Automations are triggered
* Team notifications are sent
* Status changes to "completed"
* Confirmation sent to contact
## Form Components
Every form consists of:
### Portal Pages
* **Welcome Page**: Introduction and instructions
* **Form Steps**: The actual form with fields
* **Review Page**: Review before submission
* **Ending Page**: Thank you and next steps
### Security
* **Access control**: OTP email, OTP SMS, password, or open
* **Expiration**: Optional deadline for completion
* **Link security**: Unique, non-guessable URLs
### Notifications
* **Invitations**: Initial email to start the form
* **Reminders**: Automated reminders if not completed
* **Confirmations**: Confirmation when submitted
### Data
* **Pre-filled data**: Information you already know
* **Response data**: Information collected from contact
* **Attachments**: Files uploaded by contact
* **Metadata**: Tracking information and timestamps
## Best Practices
Match security level to data sensitivity. Use OTP for sensitive information, auto-access for surveys.
Give contacts enough time to complete forms. Typical: 7-14 days for standard requests, 48 hours for urgent ones.
Always pre-fill data you already have. This respects the contact's time and improves completion rates.
Automated reminders significantly improve completion rates. Set 2-3 reminders before expiration.
Always test forms before sending to contacts. Click through the entire process to ensure it works smoothly.
Contacts expect acknowledgment when they submit forms. Configure automated confirmation emails.
## Forms vs. Cases
Understanding the relationship:
| Aspect | Forms | Cases |
| - | - | - |
| **Purpose** | Collect data from external contacts | Track internal work and processes |
| **Who uses** | Customers, clients, partners | Your team |
| **Lifespan** | Short (minutes to weeks) | Long (days to months) |
| **Creation** | From Form Presets | From Case Templates |
| **Relationship** | Can create or update cases | Can trigger forms |
Forms and Cases work together:
* Forms collect data that flows into cases
* Case workflows can automatically send forms
* Form submissions can create new cases
* Case updates can trigger new forms
## Next Steps
Learn how to build form templates
Configure form variations
Protect forms with security controls
Set up invitations and reminders
# Form Notifications
Source: https://docs.penbox.io/forms/notifications
Configure invitations, reminders, and confirmation emails
Form notifications keep contacts informed and drive form completion through invitations, reminders, and confirmations. Effective notification strategies significantly improve response rates.
## Types of Notifications
Forms support three main types of notifications:
Initial email when form is sent
**Purpose:** Introduce the form and provide access
Automated follow-ups if not completed
**Purpose:** Encourage completion
Email after form submission
**Purpose:** Acknowledge receipt
## Invitation Emails
The invitation is the first communication your contact receives about the form. It should be clear, professional, and action-oriented.
### Invitation Components
A well-crafted invitation includes:
1. **Subject Line**
* Clear and specific
* Mentions what's needed
* Creates appropriate urgency
* Example: "Action Required: Complete Your Onboarding Form"
2. **Opening**
* Personal greeting
* Context for why they're receiving this
* Who it's from
3. **Instructions**
* What the form is for
* Estimated time to complete
* Deadline (if applicable)
* Why their input matters
4. **Call-to-Action**
* Clear button or link
* Action-oriented text
* Example: "Complete Form Now" or "Get Started"
5. **Additional Information**
* Support contact
* Security information
* Privacy assurance
### Configuring Invitations
Invitations are configured in the Form Template:
```json theme={null}
{
"invitations": {
"subject": "Action Required: Complete Your Information",
"from": {
"email": "no-reply@company.com",
"name": "Company Name"
},
"body": "Dear {user.given_name},\n\nPlease complete your information form...",
"template": "custom-invitation-template"
}
}
```
### Personalization Variables
Use variables to personalize invitation emails:
| Variable | Description | Example |
| - | - | - |
| `{user.given_name}` | Contact's first name | "John" |
| `{user.family_name}` | Contact's last name | "Smith" |
| `{user.email}` | Contact's email | "[john@example.com](mailto:john@example.com)" |
| `{reference}` | Form reference number | "A4K7X9" |
| `{link}` | Form access link | Full URL to form |
| `{expires_at}` | Expiration date | "Dec 31, 2024" |
**Example:**
```
Hi {user.given_name},
We need some information from you to complete your onboarding.
This form will take approximately 10 minutes to complete.
Please submit by {expires_at}.
Click here to get started: {link}
Your reference number is {reference} if you need assistance.
Thank you!
```
### Invitation Best Practices
Tell contacts exactly what the form is for and why you need it. Mystery invitations get ignored.
Let contacts know how long the form will take and when you need it completed. This helps them plan.
Customize the from name and email to match your company. This builds trust and improves open rates.
The link or button to access the form should be impossible to miss. Use action-oriented text.
Include how to get help if they have questions. This reduces confusion and abandonment.
## Reminder Emails
Reminders automatically follow up with contacts who haven't completed the form. They're critical for improving completion rates.
### Why Reminders Matter
**Statistics show:**
* First reminder can increase completion by 20-30%
* Second reminder adds another 10-15%
* Third reminder adds 5-10%
* Beyond three reminders, returns diminish
### Configuring Reminders
```json theme={null}
{
"invitations": {
"reminders": {
"enabled": true,
"count": 3,
"interval": 2,
"unit": "days",
"subject": "Reminder: Complete Your Form",
"body": "This is a friendly reminder..."
}
}
}
```
**Properties:**
* `enabled`: Turn reminders on/off
* `count`: Number of reminders to send
* `interval`: Time between reminders
* `unit`: "hours", "days", or "weeks"
* `subject`: Email subject line
* `body`: Email content
### Reminder Timing Strategies
**Pattern:** Send reminders at 2, 5, and 10 days
```json theme={null}
{
"count": 3,
"intervals": [2, 5, 10],
"unit": "days"
}
```
**Best for:** Standard forms, 14-day deadline
**Pattern:** Send reminders at 1, 2, and 4 days
```json theme={null}
{
"count": 3,
"intervals": [1, 2, 4],
"unit": "days"
}
```
**Best for:** Time-sensitive forms, 7-day deadline
**Pattern:** Send reminders at 3, 10, and 24 days
```json theme={null}
{
"count": 3,
"intervals": [3, 10, 24],
"unit": "days"
}
```
**Best for:** Non-urgent forms, 30-day deadline
**Pattern:** Send reminder every 2 days
```json theme={null}
{
"count": 5,
"interval": 2,
"unit": "days"
}
```
**Best for:** Critical compliance forms
### Reminder Content Strategy
Each reminder should be slightly different:
**First Reminder (Gentle)**
```
Hi {user.given_name},
Just a friendly reminder that we're still waiting for your form submission.
It only takes about 10 minutes to complete.
[Complete Form Now]
```
**Second Reminder (Urgency)**
```
Hi {user.given_name},
This form is due in 3 days. Please complete it at your earliest convenience.
If you're having any issues, please let us know.
[Complete Form Now]
```
**Final Reminder (Last Chance)**
```
Hi {user.given_name},
Final reminder: This form expires tomorrow.
Please submit today to avoid delays in your application.
[Complete Form Now - Last Chance]
```
### Reminder Best Practices
First reminder is friendly, final reminder creates urgency. Escalate tone gradually.
More than 3-4 reminders becomes spam. If they haven't responded by then, try a different approach.
Send reminders when people are likely to act - early week, mid-morning. Avoid Friday evenings.
If contact declines or isn't interested, let them opt out easily. Respect their decision.
Monitor which reminders generate responses. Adjust timing and count based on data.
## Confirmation Emails
Send confirmation emails when contacts submit forms. This provides peace of mind and serves as a receipt.
### Configuring Confirmations
Confirmations are set up as notifications in the Form Template:
```json theme={null}
{
"notifications": [
{
"type": "email",
"to": [{ "role": "creator" }],
"on": ["responses:completed"],
"subject": "Thank you for your submission",
"body": "We received your form..."
}
]
}
```
Or as automations:
```json theme={null}
{
"automations": [
{
"name": "Send confirmation",
"on": ["responses:completed"],
"actions": [
{
"type": "email",
"config": {
"to": "{user.email}",
"subject": "Submission Confirmed",
"body": "Thank you, {user.given_name}..."
}
}
]
}
]
}
```
### Confirmation Components
A good confirmation email includes:
1. **Clear confirmation**
* "We received your submission"
* Reference number for tracking
2. **What happens next**
* Timeline for review
* Next steps in process
* When to expect response
3. **Contact information**
* Who to contact with questions
* Support email/phone
4. **Receipt/Summary**
* Summary of what was submitted (optional)
* Link to view submission (if applicable)
### Confirmation Example
```
Subject: Submission Confirmed - Reference {reference}
Hi {user.given_name},
Thank you for completing your onboarding form!
What's next:
- Our team will review your submission within 2 business days
- You'll receive an email once your account is activated
- If we need any additional information, we'll reach out
Your reference number: {reference}
If you have questions, contact us at support@company.com
Thank you!
Company Name Team
```
## Team Notifications
In addition to contact notifications, notify your team when forms are submitted.
### Configuring Team Notifications
```json theme={null}
{
"notifications": [
{
"type": "email",
"to": [
{ "email": "team@company.com" },
{ "role": "owner" }
],
"on": ["responses:completed"]
}
]
}
```
**Notification recipients:**
* `{ "email": "specific@email.com" }` - Specific email address
* `{ "role": "owner" }` - Case owner (if form is part of case)
* `{ "role": "creator" }` - Person who created the form
### Team Notification Content
Include relevant information for quick action:
* Who submitted (name, email)
* Form reference number
* Submission timestamp
* Link to view response
* Next action required
## Bounce Handling
Sometimes emails fail to deliver (bounce). Penbox tracks bounces and can notify you.
### Bounce Notifications
```json theme={null}
{
"notifications": [
{
"type": "email",
"to": [{ "email": "admin@company.com" }],
"on": ["request_notifications:bounced"]
}
]
}
```
**When to take action on bounces:**
* Verify contact email address
* Try alternative contact method (phone, SMS)
* Update contact information
* Resend with corrected address
## Notification Analytics
Track notification performance to optimize your strategy:
### Key Metrics
* **Open Rate**: Percentage who open invitation
* **Click Rate**: Percentage who click form link
* **Completion Rate**: Percentage who submit form
* **Reminder Effectiveness**: Completion rate per reminder
### Optimization Based on Data
| Metric | If Low | Try This |
| - | - | - |
| **Open Rate** | Under 40% | Improve subject lines, verify email addresses |
| **Click Rate** | Under 60% of opens | Clearer call-to-action, better email design |
| **Completion Rate** | Under 70% of clicks | Simplify form, reduce required fields |
| **Reminder Response** | Under 10% | Adjust timing, improve reminder content |
## Best Practices Summary
Send invitations as soon as the form is ready. Delays reduce response rates.
This is the sweet spot for most forms. More becomes spam, fewer leaves completions on the table.
Confirmations build trust and provide receipts. They take seconds to configure but matter to contacts.
Use contact name, reference numbers, and specific details. Generic emails get ignored.
Before launching, send test forms to ensure emails arrive in inbox (not spam).
Track metrics and adjust timing, content, and frequency based on actual performance.
## Next Steps
Configure notifications in templates
Customize invitations per preset
Back to Forms overview
Secure your forms
# Form Security
Source: https://docs.penbox.io/forms/security
Protecting forms with access controls and authentication
Forms can be protected with various security methods to ensure only the intended recipient can access them. Choosing the right security level balances protection with user convenience.
## Security Methods
Penbox offers multiple ways to secure form access:
One-time password sent via email
**Security Level:** Medium to High
One-time password sent via SMS
**Security Level:** High
Username and password protection
**Security Level:** Medium
Direct access via link
**Security Level:** Low
## OTP Email Security
**One-Time Password via Email** requires the contact to verify their email address before accessing the form.
### How It Works
1. Contact clicks the form link
2. System prompts for email verification
3. One-time code is sent to their email
4. Contact enters the code
5. Form becomes accessible
6. Code expires after use or timeout (typically 10 minutes)
### Configuration
```json theme={null}
{
"access_security": {
"otp": {
"email": {
"enabled": true,
"default": true,
"mandatory": true,
"template": "otp-email"
}
}
}
}
```
**Properties:**
* `enabled`: Make this option available
* `default`: Use by default when creating forms
* `mandatory`: Must be used (can't be disabled for individual forms)
* `template`: Email template to use for sending OTP
### When to Use
* Moderate security needs
* Email verification required
* Professional/business contexts
* When you already have email addresses
* Documents and data collection
* Highest security requirements
* When contacts may not have email access
* Time-sensitive forms (email delays)
* Very short forms (friction may reduce completion)
## OTP SMS Security
**One-Time Password via SMS** requires the contact to verify their phone number before accessing the form.
### How It Works
1. Contact clicks the form link
2. System prompts for phone verification
3. One-time code is sent via SMS
4. Contact enters the code
5. Form becomes accessible
6. Code expires after use or timeout
### Configuration
```json theme={null}
{
"access_security": {
"otp": {
"sms": {
"enabled": true,
"default": false,
"mandatory": false,
"text": "Your verification code is: {code}. Valid for 10 minutes."
}
}
}
}
```
**Properties:**
* `enabled`: Make this option available
* `default`: Use by default
* `mandatory`: Must be used
* `text`: SMS message template (must include `{code}`)
SMS messages must include the `{code}` placeholder where the actual code will be inserted.
### When to Use
* High security requirements
* Phone number verification needed
* Financial or sensitive information
* When email is unreliable
* Identity verification
* Contacts without mobile phones
* International users (SMS costs)
* Areas with poor mobile coverage
* Budget-sensitive situations (SMS costs money)
## Password Security
**Password Protection** requires a username and password to access the form.
### How It Works
1. Contact clicks the form link
2. System prompts for username and password
3. Contact enters credentials
4. Form becomes accessible
5. Credentials can be reused (no expiration)
### Configuration
```json theme={null}
{
"access_security": {
"password": {
"enabled": true,
"default": false,
"mandatory": false,
"length": 8,
"lower": 1,
"upper": 1,
"numeric": 1,
"alpha": 2,
"login": {
"username": "client",
"password": "SecurePass123"
}
}
}
}
```
**Properties:**
* `enabled`: Make this option available
* `default`: Use by default
* `mandatory`: Must be used
* `length`: Minimum password length
* `lower`: Minimum lowercase characters
* `upper`: Minimum uppercase characters
* `numeric`: Minimum numeric characters
* `alpha`: Minimum alphabetic characters
* `login`: Default username/password (optional)
### Password Requirements
You can enforce password complexity:
| Requirement | Description | Example |
| - | - | - |
| **length** | Minimum total characters | 8 |
| **lower** | Minimum lowercase letters | 1 (a-z) |
| **upper** | Minimum uppercase letters | 1 (A-Z) |
| **numeric** | Minimum numbers | 1 (0-9) |
| **alpha** | Minimum alphabetic characters | 2 (a-z, A-Z) |
### When to Use
* Shared access (multiple people, same credentials)
* Internal team forms
* Reusable access
* Partner portals
* When you control credential distribution
* Individual verification
* One-time use
* High security (passwords can be shared)
* Forgot password support needed
## Auto Access
**Automatic Access** provides direct access to the form without additional authentication.
### How It Works
1. Contact clicks the form link
2. Form opens immediately
3. No additional verification
### Configuration
```json theme={null}
{
"access_security": {
// No security configured = auto access
}
}
```
### When to Use
* Public surveys
* Feedback forms
* Low-sensitivity data
* Maximum convenience
* High completion rates needed
* General inquiries
* Personal information
* Financial data
* Legal documents
* Compliance requirements
* Verification needed
**Security Risk**: Anyone with the link can access the form. Only use auto-access for non-sensitive information.
## Combining Security Methods
You can enable multiple security methods and require specific combinations.
### Multiple Options (Choose One)
Allow contacts to choose their preferred verification method:
```json theme={null}
{
"access_security": {
"otp": {
"email": { "enabled": true, "default": true },
"sms": { "enabled": true, "default": false }
},
"password": { "enabled": true, "default": false }
}
}
```
**Contact experience:**
* Sees options: "Verify by Email", "Verify by SMS", "Use Password"
* Chooses preferred method
* Completes that verification
### Multiple Requirements (All Required)
Require multiple authentication factors:
```json theme={null}
{
"access_security": {
"otp": {
"email": { "enabled": true, "mandatory": true }
},
"password": { "enabled": true, "mandatory": true }
}
}
```
**Contact experience:**
* Must enter password first
* Then must verify email with OTP
* Both required to access form
**Multi-factor authentication** (like password + OTP) provides the highest security for sensitive forms.
## Security Best Practices
Choose security level based on data sensitivity:
* **High**: Financial, health, legal → OTP SMS + Password
* **Medium**: Personal info, documents → OTP Email
* **Low**: Surveys, feedback → Auto Access or Password
More security = more friction = lower completion rates
Balance security needs with completion goals. Don't use high security for low-risk forms.
Before sending forms to contacts, test each security method to ensure it works smoothly and emails/SMS are delivered.
In invitation emails, explain why you're using security measures. This builds trust and reduces confusion.
Track failed verification attempts. Multiple failures may indicate contact issues or security concerns.
If using SMS, have an email backup. Some contacts may not receive SMS or prefer email verification.
For password-protected forms with shared credentials, update passwords regularly and track who has access.
## Security Configurations by Use Case
### Financial Information
```json theme={null}
{
"access_security": {
"otp": {
"email": { "enabled": true, "mandatory": true },
"sms": { "enabled": true, "mandatory": true }
}
}
}
```
**Why:** Multi-factor authentication for high-value data
### Standard Document Collection
```json theme={null}
{
"access_security": {
"otp": {
"email": { "enabled": true, "default": true, "mandatory": true }
}
}
}
```
**Why:** Email verification ensures correct recipient
### Partner Portal
```json theme={null}
{
"access_security": {
"password": {
"enabled": true,
"mandatory": true,
"login": { "username": "partner", "password": "SecurePass123" }
}
}
}
```
**Why:** Shared credentials for partner access
### Public Feedback Form
```json theme={null}
{
"access_security": {}
}
```
**Why:** No barriers to completion for low-risk data
## Form Expiration
In addition to access security, forms can have expiration dates:
```json theme={null}
{
"expires_at": "2024-12-31T23:59:59Z"
}
```
**When a form expires:**
* The form link shows an expiration message
* Contact cannot submit the form
* Helps maintain data freshness
* Creates urgency for completion
**Use expiration for:**
* Time-sensitive offers
* Compliance deadlines
* Event registrations
* Limited-time data requests
## Custom Domains
Forms can be accessed through custom domains for improved trust:
* Default: `forms.penbox.io/abc123`
* Custom: `forms.yourcompany.com/abc123`
**Benefits:**
* Increased trust and brand recognition
* Can be whitelisted in corporate networks
* Matches your email domain
* Professional appearance
## Next Steps
Configure security in form presets
Build secure form templates
Back to Forms overview
Set up form communications
# Statuses
Source: https://docs.penbox.io/forms/statuses
Understanding form statuses and state transitions
Every form has a status that indicates its current state:
| Status | Description | Can Change? |
| - | - | - |
| **draft** | Form is being prepared, not yet sent | Yes |
| **pending** | Form has been sent, waiting for completion | Yes |
| **completed** | Contact has submitted the form | No |
| **declined** | Contact has declined to fill the form | No |
| **processed** | Form response has been processed/reviewed | No |
## Status Transitions
* **Draft → Pending**: When you send the form to the contact
* **Pending → Completed**: When contact submits the form
* **Pending → Declined**: When contact chooses to decline
* **Completed → Processed**: When you mark the response as processed
* **Pending → Expired**: When the form passes its expiration date
Once a form reaches **completed**, **declined**, or **processed** status, the contact can no longer modify their response. The form becomes read-only.
# Core Concepts
Source: https://docs.penbox.io/get-started/core_concepts
The mental model behind the Case Intelligence platform
Penbox is the Case Intelligence platform. At its center is the **Case** — an intelligent workflow that orchestrates all interactions with contacts through steps (emails, SMS, forms, internal tasks). Cases collect structured data, track statuses, handle documents, and can be automated with intelligent triggers.
Workspaces contain Members who manage Cases. Forms are a tool used within cases to collect information from contacts. Documents flow through cases — extracted from emails, generated from templates, validated, signed, and stored. Everything is configurable through the visual interface and, for advanced logic, via penscript. All configuration is also accessible through the API.
## Core Concepts
### Cases
A **Case** is the fundamental unit of work in Penbox. Each case is an intelligent workflow involving a case manager (workspace member) and one or more contacts. Cases combine email, SMS, forms, documents, and data collection into a single managed workflow.
A case can be as simple as sending a single form or email, or as complex as a multi-month process with dozens of steps, multiple contacts, document generation, digital signatures, and intelligent automations. Every case has a timeline with events and steps (the complete journey of what happened and what's next), contacts (people involved), a data schema (information to collect), statuses (where the case stands), and optionally, automations (rules that drive the workflow forward).
Cases don't require a template. You can create a blank case and build it as you go. For recurring workflows, templates let you pre-configure the structure so every new case starts with the right steps, contacts, and data schema already in place.
[Learn more about Cases →](/cases/introduction)
### Forms
A Form is a collection of steps and elements used to collect information. Forms can be external (sent to a contact to fill out) or internal (completed by a workspace member). Within a case, forms are the primary way to gather structured data from contacts.
A form has three parts: a Welcome Page (explains what the recipient should expect), the form itself (steps containing elements), and a Completion Page (confirmation message or redirect URL). Forms can be distributed via email, SMS, or a generic shareable link.
Forms are a tool that cases use. Sending a form is the simplest action you can perform within a case.
[Learn more about Forms →](/forms/introduction)
### Document Generation
Document Generation transforms collected data into professional documents by injecting variables into templates. Penbox supports Word (.docx) and PDF templates with variable placeholders. Templates can reference case data, form responses, contact information, and member details. Generated documents can be downloaded, attached to a case, or sent for digital signature.
### Signatures
Digital Signatures enable legally binding electronic signatures on documents within cases. Signatures can be applied to generated documents or pre-uploaded files. Multiple authentication methods are available (handwritten, SMS OTP, email OTP, Itsme, Swisscom), and workflows can require multiple signers in sequence. Once all signatures are collected, the document is finalized and stored in the case.
### penscript
The secret engine behind Penbox's versatile structure. penscript is a proprietary JSON language that adds advanced logic to static JSON configuration. Everything visible in the Penbox UI — form structure, notifications, automations, options, case templates — is represented as penscript JSON underneath.
The visual front-end handles most configuration needs. But penscript is where the real power lives: conditional logic, complex automations, dynamic behavior, and configurations that go beyond what the visual editor exposes. Because every configuration is JSON, the entire platform is manageable via API.
### Workspace & Members
A **Workspace** is your organization's Penbox environment. It contains all your cases, forms, templates, contacts, and settings. Workspaces have Members — users who can log in and work with cases. Members have roles (Administrator, Manager, or Restricted Access) that control what they can do and see.
### Contacts
The people involved in cases. Every case has a **Main Contact** — the primary individual the case is about. Cases can also have **Secondary Contacts** — additional stakeholders like brokers, experts, partners, or opposing parties. Each contact is identified with a unique key when defining the case.
***
## Next Steps
Learn how to work with cases
Understand forms and form templates
Quick reference for all Penbox terms
Integrate Penbox with your systems
# Glossary
Source: https://docs.penbox.io/get-started/glossary
Quick reference for Penbox terminology
This glossary provides quick-reference definitions for Penbox-specific terms. Each entry defines what the term means in plain language, with links to relevant feature pages for more details.
***
## A
### Automation
A rule that makes cases or forms work without manual intervention. Automations can trigger status transitions, show or hide steps, execute actions automatically, or send data to external systems when conditions are met.
[Learn more about Automations →](/cases/automations)
***
## C
### Case
The fundamental unit of work in Penbox. A case is an intelligent workflow that orchestrates all interactions with contacts through steps, collecting structured data and handling documents throughout the workflow.
[Learn more about Cases →](/cases/introduction)
### Case Template
A reusable blueprint for recurring case types. Templates pre-configure the steps, contacts, data schema, automations, and statuses that new cases will start with.
[Learn more about Case Templates →](/cases/case_templates)
### Contact
A person involved in a case. Every case has a Main Contact (the primary individual the case is about) and can have Secondary Contacts (additional stakeholders like brokers, experts, or partners).
### Main Contact
The primary individual a case is about. Every case has exactly one Main Contact.
### Secondary Contact
Additional stakeholders in a case beyond the Main Contact. Secondary Contacts can include brokers, experts, partners, or opposing parties.
***
## D
### Data Schema
The structured information a case collects. A data schema defines what data points the case tracks, organized into sections, with each data point having a type, visibility settings, and optional AI descriptions.
[Learn more about Data →](/cases/data)
### Document Generation
Creating documents by injecting collected data into templates. Supports Word and PDF templates with variable placeholders, allowing documents to be generated, downloaded, attached to cases, or sent for signature.
### Document Intelligence
AI-powered processing that automatically extracts and validates data from documents received within cases. Document Intelligence uses AI descriptions on data points to understand what to look for and where.
### Digital Signature
Legally binding electronic signature applied to documents within Penbox. Supports multiple authentication methods (handwritten, SMS OTP, email OTP, Itsme, Swisscom) and multi-signer workflows where documents require sequential signatures from multiple parties.
***
## E
### Email Intelligence
AI-powered email classification and drafting. Email Intelligence automatically labels incoming emails, can trigger case creation, and prepares draft responses based on configurable prompts.
***
## F
### Form
A collection of steps and elements used to collect information. Forms can be external (sent to a contact) or internal (completed by a case manager). Within cases, forms are the primary way to gather structured data from contacts.
[Learn more about Forms →](/forms/introduction)
### Form Template
A reusable structure that defines a form's steps, elements, welcome page, completion page, notifications, and behavior. Form templates are what you design in the visual editor or through penscript.
[Learn more about Form Templates →](/forms/form-templates)
### Form Preset
A saved configuration of a form template with specific options, settings, and defaults. Presets let you reuse the same form template with different security requirements, default values, or invitation templates.
[Learn more about Form Presets →](/forms/form-presets)
***
## I
### Internal Form
A step type where a form is completed by the case manager rather than sent to a contact. Internal forms are used for internal documentation, approvals, or team-facing data collection.
***
## M
### Member
A user who can log in to a Penbox workspace. Members have roles (Administrator, Manager, or Restricted Access) that control their permissions and access to cases and settings.
***
## P
### penscript
A proprietary JSON language that powers all Penbox configuration. penscript adds advanced logic to static JSON, enabling conditional behavior, complex automations, and dynamic configurations that go beyond the visual editor.
***
## S
### Status
An indicator of where a case or form stands in its lifecycle. Cases progress through statuses like draft, pending, in\_progress, and closed. Forms have their own status model including created, in\_progress, completed, and processed.
[Learn more about Case Statuses →](/cases/statuses) [Learn more about Form Statuses →](/forms/statuses)
### Step
An individual action within a case workflow. Steps can be Email (outbound email), SMS (outbound text message), Email + Form (sends a form to a contact), or Internal Form (completed by the case manager).
[Learn more about Steps →](/cases/steps)
***
## V
### Variable
A reference to data collected or available within Penbox. Variables can reference form responses, case data, contact information, or member details. Variable syntax is documented in the penscript section.
***
## W
### Workspace
Your organization's Penbox environment. A workspace contains all your cases, forms, templates, contacts, settings, and members. Each workspace operates independently with its own branding, configuration, and data.
# Automatic case status transitions
Source: https://docs.penbox.io/guides/automatic-case-transition
Drive case statuses from data schema values or step completion — watch fields, set conditions, and keep running cases current without manual updates.
In [Configure statuses in a case template](/guides/configure-case-template-statuses), you shaped **child statuses** so the lifecycle matches your process. This guide adds **automatic transitions**: when watched **data** or **steps** satisfy a **condition**, Penbox can move the case into the right **status** without someone clicking through each change.
You will configure **both** kinds of triggers on one template: a transition when a **step** reaches **completed**, and another when a **data schema** field is **defined**. The example uses **Collect info about new employee**; swap step identifiers and `data.*` paths for your own template.
**Auto-transition conditions are Penscript-powered.** The JSON you put under **`condition`** is evaluated with the same **Penscript** engine as everywhere else in Penbox: you can use **any Penscript function, operator, or pattern** the language supports (not only the `:eval` / `:defined` examples below). When in doubt, start with [Penscript](/penscript/introduction), [How Penscript works](/penscript/how_it_works), and the [Penscript reference](/penscript/reference).
## What you'll build
When you finish, your **case template** will:
* Open **Statuses** in **Case settings** and attach **auto-transition conditions** to specific **child statuses**
* Use **`watch`** so the engine knows which **data keys** or **steps** to observe
* Use **`condition`** with **`:eval`** (expression) or **`:defined`** (field present) — and extend with **full Penscript** where you need richer logic
* Be ready for **running cases** whose status stays aligned with form completion and captured fields — after you click **Save**
**Estimated time:** 10–15 minutes
***
Go to **Templates** → **Cases**, then open the **case template** you want to automate (for example **Collect info about new employee**).
In **Template Edition**, click the **settings** (gear) icon in the upper-right corner.
In **Case settings**, under **Case lifecycle**, select **Statuses**.
Click the **child status** that should be reached automatically when your condition becomes true (for example a custom **In Progress** child such as **Info collected from the new employee**, or **Closed**).
In the panel, find **Auto-transition condition (optional)**. Every condition uses the same overall shape:
1. **`watch`** — an array of paths to observe. Use **`data.…`** paths for schema values (for example `data.bank_name`) or **`steps.…`** for a step in this template (for example `steps.mail-new-employee-1`).
2. **`condition`** — rules that must hold for the transition to run. Common patterns include **`:eval`** with an expression (often on step state) and **`:defined`** to require that a data field has a value. Everything here is **Penscript**: the same functions and syntax as in flows, templates, and the rest of the docs apply.
See [Penscript](/penscript/introduction) for variables, [logic](/penscript/logic), [dates](/penscript/dates), [arrays](/penscript/arrays), and the full [reference](/penscript/reference) — use them inside **`condition`** the same way you would in any other expression field.
Replace **`steps.mail-new-employee-1`** with the **technical id** of your step (as it appears in the template). Replace **`data.bank_name`** with your **data schema** path.
For the status **Info collected from the new employee**, transition when the first onboarding step has finished — for example when an **email + form** step reaches **completed** (the new employee submitted the form).
Paste a payload like this into **Auto-transition condition (optional)**:
```json theme={null}
{
"watch": [
"steps.mail-new-employee-1"
],
"condition": {
":eval": "{{steps.mail-new-employee-1.status == 'completed'}}"
}
}
```
For the **Closed** status (or any status you choose), transition when **bank name** is present in case data — for example after **Penbox Intelligence** extraction or manual entry fills **`data.bank_name`**.
Select the **Closed** child (or your target status), then use:
```json theme={null}
{
"watch": [
"data.bank_name"
],
"condition": {
":defined": "{data.bank_name}"
}
}
```
Click **Save** on the **Statuses** screen when both conditions are in place and correct for your template.
***
## Step status values (quick reference)
Mail and mail+form steps expose different **status** strings. Use the values below when you write **`:eval`** conditions that compare your step path (for example **`steps.mail-new-employee-1.status`**) to the right value.
**Mail** (email only)
| Stage | `status` value |
| - | - |
| Mail not sent | `pending` |
| Mail sent | `executed` |
**Mail + form** (email with a form)
| Stage | `status` value |
| - | - |
| Form sent | `pending` |
| Form opened | `ongoing` |
| Form completed | `completed` |
***
## You're done
Your **case template** can now **advance statuses automatically** from **step** progress and from **data** appearing on the case. Running cases stay closer to reality without extra manual clicks, as long as **`watch`** lists everything that should trigger a re-check and **`condition`** matches what you intend.
***
## What's next?
Add or rename child statuses if you have not already.
Expression language for conditions — functions, variables, and reference.
Explore broader automation options for cases.
Read how parent and child statuses work in Penbox.
Validate behavior on a live case.
# Send a client update campaign
Source: https://docs.penbox.io/guides/brio-bulk-client-update-campaign
Send mass client file update requests to your Brio clients via Penbox, using Brio export files and Penbox Campaigns.
**Goal:** Send a mass client file update request to your clients listed in Brio, from Penbox, and based on Brio export files.
This guide walks you through every step needed to send bulk client update requests to your clients.
***
## Part 1: Generate your export files from Brio
You need to produce two export files from Brio: one for your clients and one for your contracts. Download the two command files below first, then follow the steps for each one.
| Export | Command file |
| - | - |
| Client listing | [Export listing clients v1.0.bsr](https://storage.googleapis.com/pnbx-cdn/brio/Export%20listing%20clients%20v1.0.bsr) |
| Contract listing | [Export listing contrats v1.0.bsr](https://storage.googleapis.com/pnbx-cdn/brio/Export%20listing%20contrats%20v1.0.bsr) |
Repeat the following steps once for the client .bsr file, then once more for the contract .bsr file.
Open Brio.
Click **Sélections → Sélection et rapport** (or **Selectie → Selectie en rapporten**).
Drag and drop the `.bsr` command file into the **Structure** panel on the left side of the screen.
Click **Exécuter sélection** / **Selectie uitvoeren** and wait for the selection to complete.
Once the operation has finished, click **OK**.
Click **Exporter le résultat** / **Resultaat exporteren**, then choose **Excel file**. Your export file is ready.
Repeat the steps above with the second `.bsr` file to generate your second export.
In your **client export file**, make sure every mobile number respects the following rules:
* One mobile number per field
* In one of these formats: `00324…` · `+324…` · `04…`
***
## Part 2: Set up in Penbox
Open your Penbox workspace.
Navigate to **Templates → Forms** (or **Sjablonen → Formulieren**) and confirm that the **"Mise à jour de la fiche client" / "Klantenbestand update"** form template is present in your workspace.
If you don't see this form template, contact Penbox so they can install it in your workspace.
***
## Part 3: Create and configure the campaign
Click **Campaigns** in the left-hand navigation.
Click **Create a campaign**.
Give your campaign a clear, recognisable name.
Click **Add data**.
Choose the form you want to send in bulk — in this case, select **"Mise à jour de la fiche client"**.
Choose **Brio** as the file type.
Upload the two export files you generated from Brio:
* Your **client export**
* Your **contract export**
Fill in your Brio number in the field provided.
Click **Upload files**.
Review the mapping screen that appears and confirm that all fields have been imported correctly.
Click **Validate mapping**.
You will now see a preview of the individual forms that will be sent. Take a moment to check the content of a few.
Click **Validate options**.
Click **Start creation** to generate all the individual forms. This may take a moment.
***
## Part 4: Schedule your sends
Once the forms are created, click **Schedule** to define when and how sends go out.
Fill in the following options:
* **Sends per wave** — how many forms go out per batch
* **Start date** — when sending should begin
* **Send time** — the time of day for each wave
* **Send days** — the days of the week on which sends happen
**Example:** 3 sends per day · send days: Monday and Wednesday · send time: 11:00 AM → 3 forms will go out every Monday and Wednesday at 11 AM.
Click **Start scheduling**. This may take a moment.
***
## You're done 🎉
Your campaign is created and your sends are scheduled. Well done!
***
## What's next?
Learn how to trigger a single client-file update from Brio and import the response back.
Configure the invitation and reminder emails your clients receive.
# Customize the client update form
Source: https://docs.penbox.io/guides/brio-customize-client-update-form
Tailor the content and notifications of the client update form to match your office's needs.
You will often be sending the client update form, whether from Brio, Outlook, or Penbox directly. It is important that this form fits your office's needs as closely as possible.
This guide explains how to customize both the **form content** and the **notifications** sent to your clients.
## What you'll build
By the end of this guide you will have:
* Configured which sections and questions appear in the **"Mise à jour de la fiche client"** / **"klantenbestand update"** form
* Customized the email and/or SMS notifications your clients receive
**Estimated time:** 10–15 minutes
## Getting started
In Penbox, click on **Templates → Forms**.
Click on the **"Mise à jour de la fiche client"** / **"klantenbestand update"** form to open it.
## Part 1: Customize the form content
Click on **"Default options"**.
Click on **"Default options"**.
Browse through the different tabs in Default Options. For each tab, you can:
* Choose which **sections** should be visible or hidden
* Select which **questions** are asked to your clients
* Define whether each question requires a **mandatory or optional** answer
Click on **"Personalize commercial questions"** to configure one or more commercial questions to include in the form when clients fill in their details. Skip this step if you don't need any commercial questions.
Once you have made all your content changes, click **"Save"** to apply them.
## Part 2: Customize the notifications
Click on **"Invitations"**.
Click on **"Invitations"**.
Click on **"Edit"**.
For each notification, you can activate or deactivate delivery by **email** and/or **SMS**.
For each notification, you can also edit the message content to match your office's tone and communication style.
Once you are done, click **"Save"** to apply your changes.
## You're done 🎉
Your form is now fully customized, both in terms of content and client notifications. Any form sent from Brio, Outlook, or Penbox will reflect your changes.
## What's next?
Send the client update form in bulk to all your Brio clients at once.
Send a one-off client update form directly from a Brio client file.
# Reset your Brio/Penbox connection
Source: https://docs.penbox.io/guides/brio-reset-connection
Restore the connection between Brio and Penbox if it has stopped working.
**Goal:** Restore the connection between Brio and Penbox if it has stopped working.
When your Penbox account was set up, Penbox established the connection between Brio and Penbox on your behalf. However, this connection can occasionally break and needs to be re-established.
Follow this process if you notice that your **"mise à jour de la fiche client" / "klantenbestand update"** forms are no longer being sent from Brio, or that you can no longer see form responses in Brio.
Go to **Brio**.
Click on the **profile icon** (the person icon).
Click **"Signalétiques - Paramètres"** / **"Signaletiek - Parameters"**.
Click **"Signalétiques - Paramètres"** / **"Signaletiek - Parameters"**.
Click **"Données courtier suite"** / **"Makelaarsgegevens suite"**.
Click **"Données courtier suite"** / **"Makelaarsgegevens suite"**.
Click **"Désactiver Penbox"** / **"Penbox deactiveren"**.
Click **"Activer Penbox"** / **"Penbox activeren"**.
Click **"Activer Penbox"** / **"Penbox activeren"**.
The connection between Brio and Penbox is now restored.
***
## What's next?
Trigger a client-file update from Brio and import the response back.
Send bulk client update requests using Brio export files and Penbox Campaigns.
# How to send and receive a client update starting from Brio
Source: https://docs.penbox.io/guides/brio-send-receive-client-update
Broker guide: trigger a Penbox client-data update from Brio and write the verified result back to your Brio record — no manual re-keying.
As a broker working in **Brio**, you can send a client a form to verify and update their client file, then import their response straight back into the Brio record — no copy-pasting and no chasing missing details by email.
This guide covers the full round-trip for an individual (*particulier*) client file: sending the update form from Brio, and integrating the response once the client has completed it.
## Watch the walkthrough
Prefer to watch first? Pick your language.
***
## What you'll build
By the end, you will have run a complete client-update round-trip that:
* **Sends an update form** to an individual client directly from their Brio client file
* Invites the client (with reminders, where appropriate) to **verify, complete, or correct** their information through a questionnaire
* **Imports the response back into Brio**, letting you choose field by field which new values to keep
**Estimated time:** 5 minutes
***
## Send a client-update form
Go to **Brio** and search for the client you want to send a client-file update form to.
Once you are on the client file, click the two arrows — **Messages** / **Berichten**.
Click **envoyer une nouvelle demande** / **nieuw aanvraag versturen**.
Click **envoyer une nouvelle demande** / **nieuw aanvraag versturen**.
You will see the contact details of the person the update form will be sent to. Confirm they are correct before sending.
You will see the contact details of the person the update form will be sent to. Confirm they are correct before sending.
Click **envoyer demande** / **aanvraag versturen**.
Your client then receives an invitation — and reminders, where appropriate — inviting them to complete a questionnaire to verify, complete, or modify their client information.
Click **envoyer demande** / **aanvraag versturen**.
Your client then receives an invitation — and reminders, where appropriate — inviting them to complete a questionnaire to verify, complete, or modify their client information.
***
## Integrate the client's response
Once the client has completed their client-file update, import the response into Brio.
Go to **Brio** and click the two arrows — **Messages** / **Berichten**.
Go to **Brio** and click the two arrows — **Messages** / **Berichten**.
Click **traiter la / les réponse(s) entrante(s)** / **binnengekomen antwoord(en) behandelen**. You will then see all the responses that have come in.
Click **traiter la / les réponse(s) entrante(s)** / **binnengekomen antwoord(en) behandelen**. You will then see all the responses that have come in.
Click the response you want to integrate.
Click the response you want to integrate.
You will see a page with the **original Brio values on the left** and the **new values submitted through the update form on the right**. Select the responses you want to import — and leave out the ones you don't.
You will see a page with the **original Brio values on the left** and the **new values submitted through the update form on the right**. Select the responses you want to import — and leave out the ones you don't.
Click **enregistrer** / **opslaan** to write the selected values back into the Brio client file.
Click **enregistrer** / **opslaan** to write the selected values back into the Brio client file.
***
## You're done
You've sent a client-file update form from Brio to a client, and integrated their response back into the Brio record — keeping the client file current with no manual re-keying.
***
## What's next?
Design the questionnaire clients fill in to update their file.
Configure the invitation and reminders clients receive.
# Build Your First Case Template
Source: https://docs.penbox.io/guides/build-first-case-template
Create a case template to collect information from a new employee — in 5 to 10 minutes.
Get up and running in minutes — this guide walks you through creating a case template to collect information from a new employee.
## What you'll build
By the end of this guide, you'll have a ready-to-use case template that:
* Sends a form to your new employee to collect their personal details
* Automatically follows up with a welcome email
**Estimated time:** 5–10 minutes
***
Head over to your Penbox workspace and click **Templates** in the sidebar, then select **Cases**.
Click **+ New template**, give it a name (for example, *Collect info about new employee*), and hit **Create**.
Every case has a main contact — the person you'll be communicating with. In this scenario, that's your new employee.
1. Click on **Main Contact** to rename it.
2. Change the name to **New employee**.
This label will appear throughout the case, so pick something that makes it easy to understand at a glance.
Now let's define the information you need to collect. For a new employee, you'll typically need six data points:
| Data field | Data type |
| - | - |
| Birth date | Date |
| Start date | Date |
| Street name | Text |
| City | Text |
| Zip code | Text |
| Driving license number | Text |
Here's how to add them:
1. Click **+ Add Data**.
2. Select the appropriate data type (e.g., *Date* for Birth date).
3. Click on the new field's name and rename it (e.g., *Birth date*).
4. Repeat for each data point.
Need to collect something extra later? Just click **+ Add Data** at any time to add more fields — your template is flexible.
Time to set up the communication flow. Your first step will send an email with a form so your new employee can fill in their details.
1. Select the six data points you just created.
2. Click **Ask with form**.
3. Review the form preview to make sure all the right fields are included, then click **Done**.
4. Penbox's AI will automatically generate an email inviting your new employee to fill out the form. Review the email content, tweak it if needed, and click **Save**.
Now let's add a follow-up email to thank your new employee and welcome them aboard.
1. Click **Email**.
2. Click on the email subject line and change it to something like **Thank you and welcome**.
3. Write a friendly welcome message in the email body.
4. Click **Save**.
***
## You're all set!
Your case template now has two steps:
1. **Step 1** — An email with a form to collect your new employee's information
2. **Step 2** — A welcome email to thank them and say hello
The template is ready to use. Next time you onboard someone, just create a new case from this template and Penbox will handle the rest.
***
## What's next?
Put your template to work — launch a case, collect data, and close it in minutes.
Add more steps, attach documents, or include additional data fields as your onboarding process evolves.
Case templates work for any multi-step data collection workflow, not just onboarding.
# Build your first form in Penbox
Source: https://docs.penbox.io/guides/build-first-form
Create a form template in Penbox to collect information and documents from your clients.
In Penbox, you will often need to send forms to collect information and documents from your clients.
A form in Penbox contains questions organised into sections. You can make some questions mandatory and others optional. Around the form itself, we recommend setting up notifications toward the person filling in the form (**notifications to contact**) and notifications toward yourself — the person responsible for the form (**notifications to team**).
## Build your form
Go to your Penbox workspace.
Click **Templates** in the left-hand navigation.
Click **Forms**.
Click **Create template**.
Choose a name for your form, then click **"Create a form"**.
Start building your form with the help of the Penbox Agent by clicking **Assistant**.
In the chat, describe the form you want the assistant to build for you — or upload a PDF of an existing form you want to digitalise.
The assistant will describe each action it takes in the form. If any action does not suit you, click **Undo** next to that action.
Go back and forth with the assistant in the chat until the form matches your needs 100%.
Browse through all the form tabs — **Welcome page**, **Form**, **Completion page**, **Notifications to contact**, and **Notifications to team** — to verify the result.
Make sure notifications are set up both for the contact (the person filling in the form) and for the team (the person who sent the form). This ensures everyone stays informed throughout the process.
Once you are happy with the result, click **Publish**.
You have just created the first version of your form. It is now ready to be sent.
***
## What's next?
Configure the invitation and reminder emails your contacts receive.
Learn more about how form templates work in Penbox.
# Configure statuses in a case template
Source: https://docs.penbox.io/guides/configure-case-template-statuses
Add and rename child statuses under Draft, Pending, In Progress, Closed, and Cancelled so your team sees where each case stands — worked example: Collect info about new employee.
Well-configured **statuses** make cases legible at a glance: everyone sees which phase a case is in and what still needs to happen. This guide opens a **case template**, goes to **Case settings**, and adjusts **child statuses** under each parent category.
The worked example uses the template **Collect info about new employee**; the same steps apply to any case template.
## What you'll build
When you finish, your **case template** will have **child statuses** that match how your team works — for example, multiple steps under **In Progress** instead of a single generic label. You will have:
* Opened **Statuses** from the template’s **settings**
* Either **renamed** existing child statuses or **added** new ones with **+** next to a parent
* **Saved** the lifecycle so new cases pick up the structure
**Estimated time:** 5–10 minutes
***
In the sidebar, expand **Templates**, then click **Cases**.
Click the **case template** you want to configure — for this walkthrough, open **Collect info about new employee** (or your own template).
In **Template Edition**, click the **settings** (gear) icon in the upper-right corner.
In **Case settings**, under **Case lifecycle**, choose **Statuses**.
Penbox gives you **five parent statuses** — **Draft**, **Pending**, **In Progress**, **Closed**, and **Cancelled**. Each parent starts with **one** child status that shares its name. You refine the lifecycle by renaming those children or adding more under a parent.
**Rename an existing child status**
Click the **child** you want to change, then edit the **Label** field.
**Add a new child status**
1. Click **+** beside the **parent** (for example **In Progress**).
2. Click the newly created child (it may appear with a default name such as **In Progress New**).
3. Update **Label** to the name your team should see.
Click **Save** when the structure matches your process.
Here is one possible outcome for **Collect info about new employee**: under **In Progress**, two clear child statuses instead of one — for example **Info collected from the new employee** and **Extra information asked to the new employee**.
***
## You're done
Your **case template** now exposes **child statuses** that reflect how work actually moves. New cases still **start** in the first child under **Draft** by default. While a case is open, your team **changes status manually** from one value to the next unless you add automation elsewhere.
**Automatic status transitions** — when watched data or steps satisfy a condition — are covered in [Automatic case status transitions](/guides/automatic-case-transition). Use the **Auto-transition condition** field on each child status to add that logic.
***
## What's next?
Create a template from scratch if you are new to case templates.
Walk through a case end-to-end in the app.
Read how parent and child statuses fit the case lifecycle in Penbox.
Deep-dive on case templates in the main documentation.
# Create a Case via the API
Source: https://docs.penbox.io/guides/create-case-via-api
Open a case from your own code, set its owner and contacts, and write data into it.
Creating a case takes one API call. You choose where its fields come from — a case template, or an
inline definition in the same request — and the response returns the case `id` you use for
everything that follows.
This guide covers the most common path: instantiating a case template. Creating a case without a
template is covered under [Create a case without a template](#create-a-case-without-a-template).
## Before you start
You need:
* A **workspace API token** (`pnbx_…`). See [Authentication](/api-reference/authentication).
* The **id of a case template** in your workspace. Step 1 shows how to list them.
* Base URL: `https://connect.penbox.io/v1`.
The examples below use these values:
| Value | Example |
| - | - |
| Case template id | `3f8a1c42-9b7e-4d51-8f2a-6c1d0e5b7a93` |
| Case id | `c1d2e3f4-5a6b-47c8-9d0e-1f2a3b4c5d6e` |
| Owner | `claims@acme.com`, a member of the workspace |
| Contact | Marie Dupont, the customer the case is about |
Read the template ids with
[List Case Templates](/api-reference/case-templates/list-case-templates):
```bash theme={null}
curl -X GET 'https://connect.penbox.io/v1/case_templates' \
-H "Authorization: Bearer $PENBOX_API_TOKEN"
```
Template ids are stable. Cache them per workspace rather than listing before every case.
Pass the template id. The case inherits the template's fields, sections, statuses and steps.
```bash theme={null}
curl -X POST 'https://connect.penbox.io/v1/cases' \
-H "Authorization: Bearer $PENBOX_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"template": { "id": "3f8a1c42-9b7e-4d51-8f2a-6c1d0e5b7a93" },
"title": "Claim 2026-0042 - Dupont",
"status": "in_progress",
"reference": "CLAIM-2026-0042",
"owner": { "email": "claims@acme.com" },
"contacts": [
{
"key": "main",
"given_name": "Marie",
"family_name": "Dupont",
"email": "marie.dupont@example.com",
"locale": "fr"
}
]
}'
```
**`title` is required.** `template`, `status`, `reference`, `owner` and `contacts` are optional;
each optional field has an automatic behaviour when omitted — see
[Defaults](#defaults-when-you-omit-a-field).
**`owner` and `contacts` are different populations.** The owner is a **member** of the workspace,
someone on your team who works the case. Contacts are the **customers** the case is about, and
the people you ask documents from. A contact cannot own a case.
The `key` of a contact is the role it fills, such as `main` or `billing`. Use the keys the
template declares.
Response, partial:
```json theme={null}
{
"id": "c1d2e3f4-5a6b-47c8-9d0e-1f2a3b4c5d6e",
"workspace": { "id": "d5c9f2a1-4e7b-4c83-9f16-2b8a7e3d0c54" },
"title": "Claim 2026-0042 - Dupont",
"reference": "CLAIM-2026-0042",
"status": "in_progress",
"template": "Claim intake",
"locale": "fr",
"schema": {
"data": [
{
"key": "signed_contract",
"name": "Signed contract",
"type": "file",
"options": { "accept": ["application/pdf", "image/*"], "multiple": true }
},
{
"key": "policy_number",
"name": "Policy number",
"type": "text"
}
],
"other": []
}
}
```
Keep `id`. Every later call needs it.
Three things to know when you parse this response:
* `schema` is an **array in the request and an object in the response**, with the case fields
under `schema.data`.
* A field with no value **has no `value` key**. Test for the key rather than comparing to `null`.
* `template` is returned as the template's **name**, not as the object you sent. Keep the id on
your side if you need it later.
The case takes the template's `locale`, which sets the language of everything a contact sees.
Set any field of the schema with
[Update Case Data](/api-reference/cases/update-case-data). One call accepts as many fields as you
need:
```bash theme={null}
curl -X POST 'https://connect.penbox.io/v1/cases/c1d2e3f4-5a6b-47c8-9d0e-1f2a3b4c5d6e/data' \
-H "Authorization: Bearer $PENBOX_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{ "data": { "policy_number": "POL-2026-0042" } }'
```
Penbox keeps the full history of each field. Sending a new value keeps the previous one
retrievable under `history`, so you do not need to version case data yourself.
Documents use a different sequence: upload the file first, then save its reference. See
[Add a Document to a Case](/guides/upload-document-to-case).
## Create a case without a template
Declare the fields inline with `schema`. Each entry needs a `key`, a `name` and a `type`. An entry
with a `value` prefills the field; an entry without one creates it empty.
```bash theme={null}
curl -X POST 'https://connect.penbox.io/v1/cases' \
-H "Authorization: Bearer $PENBOX_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"title": "Claim 2026-0042 - Dupont",
"status": "in_progress",
"schema": [
{ "key": "signed_contract", "name": "Signed contract", "type": "file" },
{ "key": "policy_number", "name": "Policy number", "type": "text", "value": "POL-2026-0042" }
]
}'
```
The case then has no template, no statuses beyond the default ones, and no steps. Its `locale`
defaults to `en` unless you set it.
Field types and their options are listed in the [Data Schema](/cases/data_schema) reference.
## Choose the workspace
A token scoped to a single workspace needs nothing: the case is created there.
A token scoped to several workspaces, or a partner token, must name the target workspace **in the
request body**:
```json theme={null}
{
"template": { "id": "3f8a1c42-9b7e-4d51-8f2a-6c1d0e5b7a93" },
"title": "Claim 2026-0042 - Dupont",
"workspace": { "id": "d5c9f2a1-4e7b-4c83-9f16-2b8a7e3d0c54" }
}
```
Set the workspace in the body, not in the query string. This endpoint ignores a `workspace[id]`
query parameter and answers `200`, having created the case in the token's own workspace. The
`workspace[id]` query parameter is read on
[Upload Attachment](/api-reference/attachments/upload-attachments), which makes the difference easy
to miss.
A workspace outside the token's scope answers `404`.
## Defaults when you omit a field
| Field | When omitted |
| - | - |
| `status` | The case is created as `draft`. Send `"status": "in_progress"` to open it directly, or change it later with `POST /v1/cases/{id}` — the endpoint documented as [Archive Case](/api-reference/cases/archive-case). With a template, you can use the statuses the template declares. |
| `reference` | Penbox generates a short reference such as `U7TP18`. Send your own if you need to find the case from your system later; it cannot be inferred afterwards. |
| `locale` | Taken from the template, or `en` without a template. |
## Contact fields in the schema
`schema.data` contains a field per contact role and identity attribute — `main_given_name`,
`main_family_name`, `main_email` for the `main` role. They carry a `contact` property naming what
they mirror, such as `"contact": "main.family_name"`, and they appear whether or not you send a
`contacts` array.
Read them if it is convenient, but do not write to them, and do not declare data fields of your own
for a contact's personal information. The values live on the contact record.
## Fields outside the schema
`POST /v1/cases/{id}/data` accepts any key. A key the schema does not declare is stored under
`schema.other` instead of `schema.data`, and it is not displayed as a case field.
Check your keys against the schema returned at creation if a value you sent does not appear on the
case.
## Related
Uploading a file and saving it on a case field
The endpoint reference, with every parameter
Every field type and its options
Writing values into case fields
# Build your first Document Intelligence template
Source: https://docs.penbox.io/guides/document-intelligence-first-template
Step through a complete Document Intelligence template using Penbox Intelligence — validation, typed extraction, and a live test, with a bank RIB as the worked example.
This guide walks you through building a **simple, production-ready Document Intelligence template** powered by **Penbox Intelligence**: natural-language validation, structured fields the model must respect, and an in-app test loop so you trust the output before anyone uploads a real file.
We use a **bank RIB** (*Relevé d'Identité Bancaire*) as the example document — the same pattern applies to invoices, IDs, contracts, or any PDF or image you need to understand at scale.
## What you'll build
When you finish, you will have a **fully functional Document Intelligence template** that:
* Uses **Penbox Intelligence** to **validate** uploads against criteria you write in plain language, so bad or irrelevant files are caught early
* **Extracts** a strict schema of **typed** values (text, number, date, or list) you can reuse in cases, forms, and automations — not loose blobs of text
* Ships with a **verified test run**: you have already seen validation, confidence, and field-level results on a real sample
**Estimated time:** 10–15 minutes
***
In your Penbox workspace, open **Templates** in the sidebar, then choose **Document Intelligence**.
Click **+ New**.
Give your template a name that will read clearly in your workspace — for this example, use *RIB extraction* — then click **Create**.
The editor keeps **configuration** and **Try it** in one place, so you can define the template and prove it on a sample file without switching context.
Under **Validation**, tell Penbox Intelligence what must be true for this document type. That grounds extraction: the model checks the file against your rules before you trust the fields.
For our RIB example, you might use:
*A RIB is valid if it contains the following fields: bank name, bank logo, IBAN account number, bank account holder.*
Under **Fields to Extract**, click **+ Add field** for each value you want from the document.
For each field:
1. **Choose a type** — **Text**, **Number**, **Date**, or **List**. Penbox Intelligence returns values in that shape, so downstream steps and APIs stay predictable.
2. **Name the field** — mirror the wording on the document when you can (e.g. *IBAN account number*) so the model anchors on the right region.
3. **Add an optional hint** — steer the model when the layout is ambiguous (e.g. for French IBANs: *An IBAN bank account starts with FR*).
Repeat for every field your template must output. For the RIB walkthrough, add **four** text fields and hints like below — then open **Configure** and confirm the full schema matches what you want in production.
| Field | Type | Hint (example) |
| - | - | - |
| IBAN account number | Text | An IBAN bank account starts with FR |
| BIC | Text | *Optional* |
| Bank account holder name | Text | Extract the full name: given name and family name |
| Bank name | Text | Name of the bank where the account is hosted |
On the left, under **Test Document**, upload a representative file (PDF, JPG, or PNG). Here we use a sample **RIB**; for your own template, pick a file that matches the document type you described in validation.
With your test file in place, click **Try it** to run Penbox Intelligence end-to-end on that upload. After you tweak validation or fields, use **Retry** to re-run without leaving the editor.
Open the **Results** tab: you get a validation verdict, image-quality signal, and each extracted value with confidence — the same signals your live flows can rely on once the template is attached to a **File** element.
If the output matches the source document, your template is ready to ship. If not, iterate in **Configure** — tighter validation, clearer field names, and sharper hints usually close the gap in one or two cycles.
***
## You're done
You have built and battle-tested a **Document Intelligence** template on **Penbox Intelligence**: human-readable validation, a strict extraction schema, and proof from a real upload. Swap the RIB for any document class you need — the workflow is the same, and the template is ready to plug into your Penbox flows.
***
## What's next?
Create or update templates programmatically via Pen Connect.
See how Document Intelligence fits into recent Penbox releases.
# Document Intelligence models
Source: https://docs.penbox.io/guides/document-intelligence-models
Choose between the Fast and Advanced extraction models
Document Intelligence 3 introduces two extraction models instead of one, so you can match the level of extraction to the difficulty of the document rather than paying the same rate for every page.
Models apply to [Document Intelligence templates](/guides/document-intelligence-first-template). The model you pick changes how a document is read, not what is extracted: your fields, types, and hints stay exactly as you configured them.
## What changed in Document Intelligence 3
* **Fast** replaces the previous extraction model on every existing document type, at the same rate of 3 credits per page. It is 30% faster and 25% more accurate than the model it replaces.
* **Advanced** is new, at 6 credits per page. It is 50% more accurate and reasons over the whole document instead of reading it field by field.
The Fast upgrade applies automatically. There is nothing to reconfigure and nothing changes in your credit usage.
## Fast
Fast is the default model and covers the documents most workspaces process every day: ID cards, bank details, invoices, policy schedules, certificates, and other structured or printed documents where the values sit in predictable places.
At 3 credits per page it is the cheapest model, and it is now also the quickest: a page comes back 30% faster than before, with fewer values needing a manual correction afterwards.
## Advanced
Advanced is built for documents Fast has to guess at. Instead of locating each field independently, it reads the document as a whole and reasons across it, which is what messy handwriting, checkbox grids, and multi page context require.
Use it on:
* **European accident statements (constat amiable).** Handwritten boxes, free text, and the collision sketch have to be read together to produce a coherent result.
* **Complex handwritten documents.** Medical certificates, filled-in paper forms, annotated contracts.
* **Documents that need inference.** Cases where a field is not written anywhere as such and has to be derived from the rest of the document.
Advanced runs only 10% slower than the new Fast model, which still makes it faster than the model it replaces.
## Choosing between the two
| | Fast | Advanced |
| - | - | - |
| Cost | 3 credits per page | 6 credits per page |
| Best for | Printed and structured documents | Handwriting, sketches, inference |
| Accuracy vs previous model | +25% | +50% |
| Speed vs previous model | 30% faster | Faster than before, 10% slower than Fast |
| Applied | Automatically, everywhere | Per document type, on request |
Leave Fast on by default and turn Advanced on for the specific document types where corrections keep coming back. Paying 6 credits per page only where it earns its keep is cheaper than paying 3 credits twice because the first pass was wrong.
## Credits
Both models are billed per page processed by the LLM, drawn from your shared [workspace credit pool](/workspace/credits). A five page document extracted with Fast consumes 15 credits, and 30 credits with Advanced.
Switching a document type to Advanced changes the rate for pages processed from that point on. It does not re-run or re-bill extractions that already completed.
## Enabling Advanced
Advanced is enabled per document type from your workspace settings, or by your Penbox contact. Turn it on for the templates that need it and leave the rest on Fast.
## Availability
The Fast model is live today in all workspaces. Advanced is available on request, per document type.
An **Expert** model, for the hardest documents, is in development and planned for September.
***
## Next Steps
Define what to extract, then test it live
Run extraction on upload and map fields to your data schema
How credits are consumed and renewed
Build and refine extraction templates with Penbox Agent
# Create a Case on the Fly
Source: https://docs.penbox.io/guides/headless-create-case
Open a Penbox case from inside your own product, fill it with data, and attach a document.
A user of your product says *"open a case for Mrs Dupont"*. This guide is what happens next: a
real Penbox case appears, owned by the right person, carrying your data and your documents — and
your user never leaves your app.
## What you'll have
By the end of this guide:
* A case created from one of your templates, owned by a member of your client's team
* Its contact set to the customer the case is about
* Structured data written into it
* A document uploaded and stored on one of its fields
**Estimated time:** 10 minutes
Finish [Onboard a Client](/guides/headless-onboard-client) first. You need the workspace id and
the token it returned.
***
The templates you listed in `template_source` were copied into the workspace. Read their ids
with [List Case Templates](/api-reference/case-templates/list-case-templates):
```bash theme={null}
curl --url https://connect.penbox.io/v1/case_templates \
--header 'Authorization: Bearer '
```
Cache the ids per workspace — they are stable, and you need one every time you open a case.
Instantiate the template with [Create Case](/api-reference/cases/create-case):
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"title": "Dupont file",
"workspace": { "id": "" },
"template": { "id": "" },
"owner": { "email": "amina@acme.example" },
"contacts": [{ "key": "main", "email": "j.dupont@mail.example", "given_name": "Jean" }]
}'
```
`workspace.id` is **required** for an API token — it is never inferred. The case inherits the
template's fields and statuses.
`owner` must be a **member** you registered in guide 1 — someone on your client's team.
`contacts` are their **customers**, the people the case is about or the ones asked for
documents. Swapping the two is the most common integration mistake: a contact can never own a
case, and a member should never be invited as a contact.
Write any field of the case's schema with
[Update Case Data](/api-reference/cases/update-case-data):
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id}/data \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "data": { "policy_number": "AB-12345" } }'
```
Penbox keeps the **full history** of every field: send a new value and the previous one stays
retrievable — you never have to version data on your side. Field types and on-the-fly schema
additions are covered in the [Data Schema](/cases/data_schema) reference.
Upload the file with
[Upload Attachment](/api-reference/attachments/upload-attachments) — multipart or base64, up to
10GB:
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/attachments \
--header 'Authorization: Bearer ' \
--form 'file=@contract.pdf'
```
The response carries the attachment's `id`, `name` and `type`. Store them in one of the case's
[file fields](/cases/data_schema/file) as a **reference object** — not as a bare id:
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id}/data \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"data": {
"documents": {
"id": "",
"name": "contract.pdf",
"type": "application/pdf"
}
}
}'
```
Always send the complete reference. This value is not validated, so a bare id can be saved
successfully and then fail to display or download. A field configured for several files takes an
array of references.
Uploading alone does not put the file on the case — the second call is what does. Like any
other field, a file field keeps the full history of everything ever added to it.
Limits, access rules and the reading path are covered in
[Add a Document to a Case](/guides/upload-document-to-case).
## You've created a case
The workspace now holds a real case:
* Built from your template, with its fields and its statuses
* Owned by a member of your client's team
* Pointing at the customer it is about
* Carrying structured data and a document, both with full history
Your user got all of that without ever leaving your product. This is the call you put behind
*"open a case for this customer"*.
**Next:** [Drive the case](/guides/headless-drive-case).
# Drive the Case
Source: https://docs.penbox.io/guides/headless-drive-case
Move a case through its statuses, assign follow-up tasks, and hand your client the switch that revokes your access.
A case that never moves is a form. This guide is what turns it into a lifecycle your client's team
actually works on — and it ends with the switch that makes the whole arrangement safe for them.
## What you'll have
By the end of this guide:
* The case moving through the statuses its template defines
* Follow-up tasks assigned to your client's team, next to the ones Penbox creates itself
* Your client able to cut your integration off in one click, and you able to explain how
**Estimated time:** 10 minutes
Finish [Create a Case on the Fly](/guides/headless-create-case) first. You need a case id.
***
Send a `status` with [Update Case](/api-reference/cases/archive-case):
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "status": "in_progress" }'
```
Read the keys the case accepts from its own `statuses` array, returned by
[Get Case](/api-reference/cases/get-case). Each template defines its own — never hardcode a
custom status in your app.
The change lands in the case history, attributed to your integration by name. Your client can
see what your app did and when.
Put your own follow-ups next to the ones Penbox creates, assigned to the members you registered
in guide 1:
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id}/tasks \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"title": "Call the client back",
"due_at": "2026-09-15T09:00:00Z",
"assignee": { "email": "amina@acme.example" }
}'
```
The assignee is resolved by email against the workspace members — silent ones included. Omit
`assignee`, or send `null`, to leave the task for whoever picks it up. See
[List Case Tasks](/api-reference/tasks/list-case-tasks),
[Create Case Task](/api-reference/tasks/create-case-task) and
[Update Case Task](/api-reference/tasks/update-case-task).
The workspace owner can cut your integration off at any time, from
**Settings → Integrations → Disconnect**. One click revokes your token immediately and removes
your support account from the workspace. Everything you created stays; only your access dies.
Tell your clients this exists. It is the reason they can hand you their case management in the
first place.
## You've integrated Penbox
The three guides are done. Your product can now:
* Onboard a client with no manual step on either side
* Open a case from inside your own screens
* Fill it with data and documents
* Move it through its lifecycle and put follow-ups on the right people
* Be switched off by your client in one click
That is the complete headless loop. Penbox is your case engine, and your users never see it.
## Going further
Read [Statuses and Lifecycle](/cases/statuses_lifecycle) for how templates define their own
transitions, and [Automations](/cases/automations) for the work Penbox does on the case without you
asking.
# Onboard a Client
Source: https://docs.penbox.io/guides/headless-onboard-client
Provision a Penbox workspace for one of your clients, store its token, and register their team — in three calls.
Your client signs up in your product. This guide turns that into a fully configured Penbox
workspace, with no manual step on either side.
## What you'll have
By the end of this guide:
* A Penbox workspace for that client, seeded with your case templates
* An API token scoped to it, stored on your side
* Your client's team registered, ready to own cases and receive tasks
**Estimated time:** 10 minutes
Read the [Overview](/guides/headless-overview) first — it names the five actors and the auth
header every call below uses.
***
One call creates the workspace, registers its admins, copies your case templates into it, and
returns a token scoped to it. See
[Provision Workspace](/api-reference/workspaces/provision-workspace) for every field.
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/workspaces \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"name": "Acme",
"admin": { "email": "admin@acme.example" },
"template_source": { "case_template_ids": [""] },
"integration": { "legalops": { "source_workspace_id": "acme-42" } }
}'
```
The call is **idempotent** on `source_workspace_id` — your own identifier for that client. A
`201` means the workspace was created; replaying the same call returns the existing workspace
with a `200` and no token. It also never fails halfway: an optional step that could not
complete (a template that no longer exists, for instance) is reported in a `warnings` array,
not as an error. Log the warnings.
Omit `template_source` entirely and **all** the case templates of your own workspace are
copied — treat your workspace as the template matrix for every client you provision.
**Two admins are created here, both silent.** The `admin` you send is your client's, so
someone on their side formally owns the workspace. Penbox also adds **your own support
account**, so your team can help them while the workspace stays headless. That address is
configured once with Penbox on your partner workspace — it is never sent in this payload. If
it is missing, provisioning still succeeds and tells you so in `warnings`.
Silent means Penbox never emails them. Your users never hear from Penbox, and never see a
Penbox screen, unless you decide otherwise.
The `201` response carries a `token`:
```json theme={null}
{
"workspace": { "id": "…", "name": "Acme", "slug": "acme" },
"token": "pnbx_0f1e2d3c4b5a69788796a5b4c3d2e1f001122334455…"
}
```
Penbox stores only its hash and can never show it again. Persist it before anything else: it is
the only secret you keep per client, and every call in the next guides uses it.
The two admins from step 1 already exist — do not re-create them. What is left is everyone who
will actually **own cases and receive tasks**. Add them one call each, with
[Create Member](/api-reference/members/create-member).
```bash theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/members \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"workspace": { "id": "" },
"email": "amina@acme.example",
"given_name": "Amina"
}'
```
People added here are **Handlers**: they work on cases and forms, and cannot change workspace
settings. Send `"is_handler": false` instead for someone who should only see what they are
assigned. The three roles are described in [Members](/workspace/settings/members).
Like provisioning, the call is idempotent — on the email this time — and members created
through the API are always silent. Call it again whenever your client hires someone; there is
no batch to prepare up front.
## You've onboarded a client
Three calls in, this client now has:
* A Penbox workspace, seeded with your case templates
* A token scoped to it, stored on your side
* Two silent admins — your client's owner and your own support account
* Their team registered as Handlers, ready to own cases
Nobody was emailed. Nobody opened Penbox. Repeat these three calls for every client you sign, and
onboarding costs you zero manual steps.
**Next:** [Create a case on the fly](/guides/headless-create-case).
# Bring the power of Penbox Cases inside your app
Source: https://docs.penbox.io/guides/headless-overview
Run Penbox headless: provision a workspace per client, then drive its cases, statuses, tasks and documents entirely over the API.
**You are a Penbox partner.** You run your own product — an AI assistant, a portal, a
back-office — and your users need **cases**: a container with a status, structured data, documents
collected from their customers, and follow-up tasks. Building that engine is months of work outside
your core. Penbox already has it.
Headless mode lets you drive the whole engine from your own app, so your users never see a Penbox
screen. Here is what you will be able to do.
## What you'll be able to do
* Create a fully configured Penbox workspace for each of your clients, in one call, with no manual
step on the Penbox side
* Open a case from inside your product, fill it with data and documents, and move it through its
statuses
* Put follow-up tasks on your client's team
* Hand your client a one-click switch to cut your access off, which is what makes the arrangement
safe for them
## Who is who
Headless mode involves five actors. Getting them right is most of the integration.
| Actor | In Penbox | Created by |
| - | - | - |
| Your app | An API token scoped to one workspace | Provisioning, guide 1 |
| Your support team | Administrator, silent | Provisioning, automatically |
| Your client | Administrator, silent | Provisioning, the `admin` you send |
| Your client's team | Handler — owns cases, receives tasks | One call each, guide 1 |
| Their customers | Contact — the person a case is about | On the case, guide 2 |
A **member** is on your client's side of the desk. A **contact** is on the other side. Penbox never
mistakes one for the other, and neither should your code.
## Before you start
Every call uses the same base URL and auth header:
```bash theme={null}
curl https://connect.penbox.io/v1/... \
--header 'Authorization: Bearer '
```
Workspace provisioning must be enabled on your account. Talk to Penbox to have your workspace
enabled, and read [Authentication](/api-reference/authentication) to create your API key.
## The three guides
Follow them in order — each one starts where the previous one stopped.
Provision a workspace, store the token it returns, and register your client's team. You end with
a live workspace you can drive.
Open a case from your own product, fill it with data, and attach a document. You end with a real
case your client's team can work on.
Move the case through its statuses, assign follow-up tasks, and show your client the switch that
revokes your access. You end with a complete case lifecycle.
# Install the Penbox extension on Outlook
Source: https://docs.penbox.io/guides/install-outlook-extension
Use Penbox directly from your Outlook inbox by installing the Penbox extension from the Microsoft Marketplace.
The Penbox extension for Outlook lets you send forms and collect responses directly from your inbox, without switching between applications.
Your Outlook email address must be added as a member of your Penbox workspace before you can use the extension. If it isn't, contact your workspace administrator.
## Install and connect the extension
Go to the [Microsoft Marketplace](https://marketplace.microsoft.com/fr-fr/) and search for **Penbox**, or go directly to the [Penbox listing](https://marketplace.microsoft.com/fr-fr/search/products?search=penbox\&page=1).
Go to the [Microsoft Marketplace](https://marketplace.microsoft.com/fr-fr/) and search for **Penbox**, or go directly to [Penbox on the Marketplace](https://marketplace.microsoft.com/fr-fr/search/products?search=penbox\&page=1).
Sign in with your **Outlook email address**.
Click **Get it now**.
Click **Get it now**.
Go to your Outlook inbox and click the **three dots** (more options).
Go to your Outlook inbox and click the **three dots** (more options).
Locate the Penbox extension you just installed.
Click the **pin icon** to pin the extension so it remains visible every time you open Outlook.
Click **Log in** inside the Penbox extension to connect it to your Penbox workspace.
Click **Log in** inside the Penbox extension to connect it to your Penbox workspace.
A page will automatically open in your browser asking you to confirm that you want to connect a new device. Click **Confirm**.
A page will automatically open in your browser asking you to confirm that you want to connect a new device. Click **Confirm**.
Congratulations — you can now use Penbox directly from your Outlook inbox.
***
## What's next?
Discover all the ways to send a Penbox form to your contacts.
Configure the invitation and reminder emails your contacts receive.
# Modify an existing form
Source: https://docs.penbox.io/guides/modify-existing-form
Edit an existing form template in Penbox using the Penbox Agent.
You can modify any existing form template at any time using the Penbox Agent.
Go to your Penbox workspace.
Click **Templates** → **Forms**, then select the form you want to modify.
Click **Edit**.
Click **Assistant** to open the Penbox Agent.
Tell the assistant the modifications you want to make to your form.
The assistant will describe each action it takes. If any action does not suit you, click **Undo** next to that action.
Browse through all the form tabs — **Welcome page**, **Form**, **Completion page**, **Notifications to contact**, and **Notifications to team** — to verify that the changes meet your needs 100%.
Make sure notifications are set up both for the contact (the person filling in the form) and for the team (the person who sent the form). This ensures everyone stays informed throughout the process.
Once you are happy with the result, click **Publish**.
Only forms sent from this point onwards will inherit the changes. Forms that were already sent before publishing will not be affected.
***
## What's next?
Create a new form template from scratch.
Discover all the ways to send a Penbox form to your contacts.
# Run Your First Case
Source: https://docs.penbox.io/guides/run-first-case
Put your case template to work — launch a case, collect data, and close it in minutes.
You've built your case template — now let's put it to work. This guide walks you through running a case from start to finish with a real new employee.
## What you'll do
By the end of this guide, you'll have:
* Launched a case from your template
* Sent a form to your new employee and collected their data
* Sent a welcome email
* Closed the case
**Estimated time:** 5 minutes (plus waiting for your employee to fill in the form)
Make sure you've already built your case template before starting. If not, check out [Build Your First Case Template](/guides/build-first-case-template) first.
***
Find your case template **Collect info about new employee** in the Templates section, and click the **+** button next to it.
Give your case a name (e.g., the employee's name), fill in the **email address** of your new employee, and click **Create**.
Your case is now live and ready to go.
Open your first pre-configured step — the **email + form** step. Take a moment to review the email and form content, then hit **Send**.
That's it on your end for now. Your new employee will receive an email invitation with a link to the form.
On their side, your new employee receives the email, opens the form, and fills in their details — birth date, start date, address, and so on.
When the first step is completed, you'll see all the data your employee submitted right inside your case.
Take a moment to check everything looks good. If something needs correcting — say, a typo in the zip code — just click on the value and type in the correct one.
You can edit any data field at any time, so don't worry if something needs updating later.
Now that you have all the information you need, it's time to move on to step two: thanking your new employee and welcoming them aboard.
Open the second step, review the email content (and tweak it if you'd like), then click **Send**.
Your employee will receive a friendly confirmation that everything is in order.
Both steps are done — the data is collected and your employee has been welcomed. Time to wrap things up.
Click on the **status** of your case and switch it to **Closed**.
And that's it — your first case is complete!
***
## Recap
Here's what just happened in a few clicks:
1. You launched a case from your template
2. Penbox sent an automated form to your new employee
3. The employee filled it in, and the data landed directly in your case
4. You reviewed (and optionally edited) the data
5. You sent a welcome email
6. You closed the case
All of this without a single spreadsheet, manual email thread, or lost attachment.
***
## What's next?
Use the same template every time you onboard a new employee. Each case runs independently.
As your onboarding process evolves, update your template with new steps or additional data fields.
Case templates aren't just for onboarding — use them for client intake, document collection, vendor qualification, and more.
# Send a campaign
Source: https://docs.penbox.io/guides/send-a-campaign
Send mass form requests to your clients via Penbox, using Excel CSV files and Penbox Campaigns.
**Goal:** Send a form in bulk to a large number of recipients, based on an Excel file containing the information needed to pre-fill your forms.
A campaign lets you send a specific form to a large number of people at once. In this guide, you will learn how to — starting from an Excel file containing data that maps to your form fields — send a campaign to your recipients.
This guide walks you through every step: from creating a campaign to scheduling your sends.
***
## Part 1: Prepare your Excel file
Your Excel file is the source of data for your campaign. Each row represents one recipient, and each column represents a piece of information — either about the person to contact, or data to pre-fill in their form.
The **column headers must match the variable names used in your Penbox form**. Penbox will use these to map each column to the right field when you upload the file.
Once your file is ready, save it as a **CSV file** — Penbox requires a CSV format to import your data and launch the campaign.
For contact variables, the standard Penbox names are: `user.given_name` (first name), `user.family_name` (last name), `user.email` (email), `user.phone` (mobile number).
Make sure every mobile number in your file respects the following rules:
* One mobile number per field
* In one of these formats: `00324…` · `+324…` · `04…`
To find the variable name of a field in one of your forms: go to **Templates → Forms**, open the form, click **Edit**, find the question, then click the **six dots** icon next to it. The variable name appears next to the **\** symbol.
***
## Part 2: Review and test your form
Before launching your campaign, make sure the form you want to send is ready and works as expected.
Navigate to **Templates → Forms**.
Click on the form you want to send as a campaign.
Click **New request** to send the form to yourself and verify that everything looks correct.
***
## Part 3: Create and configure the campaign
Click **Campaigns** in the left-hand navigation.
Click **Create a campaign**.
Give your campaign a clear, recognisable name.
Click **Add data**.
Choose the form you want to send in bulk.
Choose **CSV** as the file type.
Upload the CSV file you prepared in Part 1.
Click **Upload files**.
Review the mapping screen that appears and confirm that all fields have been imported correctly.
Click **Validate mapping**.
You will now see a preview of the individual forms that will be sent. Take a moment to check the content of a few.
Click **Validate options**.
Click **Start creation** to generate all the individual forms. This may take a moment.
***
## Part 4: Schedule your sends
Once the forms are created, click **Schedule** to define when and how sends go out.
Fill in the following options:
* **Sends per wave** — how many forms go out per batch
* **Start date** — when sending should begin
* **Send time** — the time of day for each wave
* **Send days** — the days of the week on which sends happen
**Example:** 3 sends per day · send days: Monday and Wednesday · send time: 11:00 AM → 3 forms will go out every Monday and Wednesday at 11 AM.
Click **Start scheduling**. This may take a moment.
***
## You're done 🎉
Your campaign is created and your sends are scheduled. Well done!
***
## What's next?
Configure the invitation and reminder emails your recipients receive.
# Make a form available
Source: https://docs.penbox.io/guides/send-form
The different ways to send a Penbox form to your contacts and collect their responses.
Once you have created a form, you will want to send it out to collect responses from your contacts.
You have several options for sending a form:
* Directly from **Brio**
* From the **Penbox extension on Outlook**
* In bulk via a **Campaign** in Penbox
* Individually from **Penbox**
* Via a **generic link** on your website or in an email signature
This guide covers the last two options in detail.
***
## Send a form individually from Penbox
Go to your Penbox workspace.
Click the **+** next to **Forms**.
Select the form you want to send.
Set the person you want to send the form to:
* **Existing contact:** search by email address to check if the contact is already known in Penbox.
* **New contact:** fill in their first name, last name, email address, and phone number.
Click **Send**.
Your contact will shortly receive an invitation to complete the form.
***
## Share a form via a generic link
You can make a form available via a generic link to embed on your website or add to an email signature.
Go to your Penbox workspace.
Click **Templates** → **Forms**, then select the form you want to share.
Click **Default options** and make sure that any mandatory options have a default value. If they don't, set them and click **Save**.
Go back to your form's home page and click **Copy link** in the **"Generic link to embed on your website"** banner.
You now have a generic link that leads directly to your form.
***
## What's next?
Create a form template in Penbox from scratch.
Configure the invitation and reminder emails your contacts receive.
# Set up your new workspace
Source: https://docs.penbox.io/guides/set-up-workspace
The essential settings to configure in your Penbox workspace before you start.
To get the best experience in Penbox from day one, we recommend completing the following settings in your newly created workspace.
Go to **Settings** in your workspace, then work through each tab below.
***
## Information
In the **Information** tab:
* **Company name:** verify and update it if necessary.
* **Website:** verify and update your company website. This is useful for redirecting your clients to your site at the end of a form.
* **Phone number and general email address:** verify and update these. They are typically used in certain form signatures.
***
## Members
In the **Members** tab, invite your teammates to join your workspace:
Click **Invite member**.
Enter their **email address**, **first name**, and **last name** (all required).
Choose the role you want to assign to them.
Choose whether to give them access to edit **case templates** and **form templates**.
Click **Send**.
***
## Branding
In the **Branding** tab, define your visual identity to improve the experience for your clients:
* Upload your **logo**, **icon**, and **favicon**.
***
## Domains
In the **Domains** tab, configure where your forms are hosted and from which address your emails are sent.
We strongly recommend configuring your own domain rather than using Penbox's default domain. Your clients will trust an email from an address they recognise, and will feel more comfortable navigating a form hosted on your own domain.
Define the domain on which your forms will be hosted.
Define the domain from which your emails will be sent.
Click **Share** to retrieve the configuration instructions to send to your domain administrator.
Once your domain administrator confirms the changes are done, click **Verify** and make sure all statuses show as **Connected**.
***
## What's next?
Create your first form template in Penbox.
Learn more about roles and permissions in your workspace.
# Single Sign-On (SSO)
Source: https://docs.penbox.io/guides/sso-configuration
Configure Single Sign-On so your users sign in to Penbox with their company identity provider.
SSO is available on the **Penbox Enterprise** plan only. If you would like to enable it, contact your Penbox representative.
## Overview
Single Sign-On lets your users connect to Penbox with their existing company identity. Once enabled, your team signs in through your identity provider, and you keep control of access from your own side.
Select your identity provider below and follow the setup steps. More methods are coming soon.
Microsoft Entra ID (formerly Azure AD) lets your users sign in to Penbox with their company Microsoft account. An administrator of your Microsoft tenant creates an application registration and shares the resulting credentials with Penbox.
You need a **Global Administrator** of your Microsoft Entra tenant to complete these steps.
### Step 1: Register the application in Microsoft Entra
In the Microsoft Entra admin center, go to **App registrations** then **New registration**. Name it `Penbox SSO` (or a name of your choice).
Under supported account types, select **Accounts in this organizational directory only (Single tenant)**.
Choose type **Web** and enter this value exactly, with no trailing slash:
```text theme={null}
https://penbox.eu.auth0.com/login/callback
```
This value must match exactly. A mismatch is the most common cause of sign-in failure (Microsoft error `AADSTS50011`).
Click **Register**. From the **Overview** screen, note the **Application (client) ID** and the **Directory (tenant) ID**.
Go to **Certificates and secrets** then **New client secret**. Copy the secret **Value** immediately (not the Secret ID, they are different) and note its expiry date.
Go to **API permissions**, add the Microsoft Graph **delegated** permissions `openid`, `profile`, and `email`, then click **Grant admin consent**.
### Step 2: Share the credentials with Penbox
Send the following four items to Penbox **through the secure link Penbox provided to you**. Do not send these by email or chat.
* Application (client) ID
* Client secret (the Value)
* Tenant primary domain (for example `yourcompany.onmicrosoft.com` or your verified domain)
* Directory (tenant) ID
Always use the secure link Penbox shared with you to transmit the client secret. Never share it over email, Slack, or any other channel.
### After setup
Once Penbox receives and configures your credentials, your users will sign in to Penbox with their Microsoft account. Standard logins are disabled for your workspace, so Microsoft becomes the only way in.
The client secret has an expiry date. Let Penbox know that date so renewal can be planned ahead of time and sign-in is never interrupted.
# Add a Document to a Case
Source: https://docs.penbox.io/guides/upload-document-to-case
Upload a file, save its reference in a case field, and retrieve it later.
Adding a document to a case takes two API calls: upload the file, then save its reference in a case
field. Uploading alone does not attach anything to the case — the second call is what places the
document on it.
Check these three points before you build on this sequence:
* Uploading requires a **workspace API token** (`pnbx_…`). A user token obtained through OAuth is
rejected on the upload endpoint.
* **Downloads have a lower size limit than uploads**: 10 GB up, 50 MB back. Check the download limit
before uploading documents you need to retrieve through the API.
* Saving a document on a field **does not run Document Intelligence**. Extraction on this path is an
explicit call — see [Extract data from the document](#extract-data-from-the-document).
## Before you start
You need:
* A workspace API token (`pnbx_…`). See [Authentication](/api-reference/authentication).
* A case with a **file field**, and its id. See
[Create a Case via the API](/guides/create-case-via-api).
* Base URL: `https://connect.penbox.io/v1`.
The examples below use these values:
| Value | Example |
| - | - |
| Case id | `c1d2e3f4-5a6b-47c8-9d0e-1f2a3b4c5d6e` |
| File field key | `signed_contract` |
| Local file | `signed-contract.pdf` |
Send the file as `multipart/form-data`:
```bash theme={null}
curl -X POST 'https://connect.penbox.io/v1/attachments' \
-H "Authorization: Bearer $PENBOX_API_TOKEN" \
-F 'file=@./signed-contract.pdf;type=application/pdf'
```
Response `201`, partial:
```json theme={null}
{
"id": "7b3e5f10-2c48-4a91-b6d3-8e5f2a1c9d47",
"name": "signed-contract.pdf",
"type": "application/pdf"
}
```
Keep `id`, `name` and `type`. The next call needs all three.
The full response also returns the uploaded file itself, base64-encoded, in a `data` field. Read
the three fields you need and discard the rest, and size your HTTP client's response buffer for
the file you are sending rather than for the fields you keep.
The response does not carry the file size. Take it from the file on disk if you want to store
one.
Write the reference into `signed_contract`. The same call sets any other field, so send the
scalar values you already have in the same request:
```bash theme={null}
curl -X POST 'https://connect.penbox.io/v1/cases/c1d2e3f4-5a6b-47c8-9d0e-1f2a3b4c5d6e/data' \
-H "Authorization: Bearer $PENBOX_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"data": {
"signed_contract": {
"id": "7b3e5f10-2c48-4a91-b6d3-8e5f2a1c9d47",
"name": "signed-contract.pdf",
"type": "application/pdf",
"size": 48213
},
"policy_number": "POL-2026-0042"
}
}'
```
`id`, `name` and `type` are the reference. `size` is optional.
Always send the complete `{ id, name, type }` reference. The endpoint does not validate this
value, so a bare id string, or an id that does not exist, can be saved successfully and then
fail to display or download.
Response `200`, partial:
```json theme={null}
{
"schema": {
"data": [
{
"key": "signed_contract",
"name": "Signed contract",
"type": "file",
"value": {
"id": "7b3e5f10-2c48-4a91-b6d3-8e5f2a1c9d47",
"name": "signed-contract.pdf",
"type": "application/pdf",
"size": 48213
}
}
]
}
}
```
`GET /v1/cases/{id}` returns the reference under
`schema.data[] | select(.key == "signed_contract") | .value`.
To get the file itself, call the attachment endpoint. It returns JSON with the content
base64-encoded in `data`:
```bash theme={null}
curl -sS 'https://connect.penbox.io/v1/attachments/7b3e5f10-2c48-4a91-b6d3-8e5f2a1c9d47' \
-H "Authorization: Bearer $PENBOX_API_TOKEN" \
| jq -r .data | base64 -d > signed-contract.pdf
```
This response is limited to 50 MB. A larger document returns `400` and cannot currently be
retrieved through the API. Keep documents you need to download under 50 MB, or deliver them to
your recipients by another route.
## Upload as JSON instead of multipart
Send the file base64-encoded in `data`:
```bash theme={null}
curl -X POST 'https://connect.penbox.io/v1/attachments' \
-H "Authorization: Bearer $PENBOX_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "signed-contract.pdf",
"data": "JVBERi0xLjQKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCg=="
}'
```
Two differences from multipart:
* The MIME type comes from the **extension of `name`**. A `type` field in the body is not used, and a
name without an extension produces `application/octet-stream`. Use multipart when the MIME type
matters.
* Base64 inflates the payload by about a third, and the 10 GB limit applies to what is transmitted.
The largest file you can send this way is roughly 7.5 GB.
## Save several files on one field
A field configured with `multiple: true` takes an array of references:
```json theme={null}
{
"data": {
"signed_contract": [
{ "id": "7b3e5f10-2c48-4a91-b6d3-8e5f2a1c9d47", "name": "signed-contract.pdf", "type": "application/pdf" },
{ "id": "1a9c8d72-6b04-4e35-8c7f-3d2e1b0a5f68", "name": "annex.pdf", "type": "application/pdf" }
]
}
}
```
The array replaces the previous value. Include the files already on the field to keep them.
## Upload before the case exists
An attachment does not need a case, so you can upload first and pass the reference as a field value
when you [create the case](/guides/create-case-via-api):
```json theme={null}
{
"title": "Claim 2026-0042 - Dupont",
"schema": [
{
"key": "signed_contract",
"name": "Signed contract",
"type": "file",
"value": {
"id": "7b3e5f10-2c48-4a91-b6d3-8e5f2a1c9d47",
"name": "signed-contract.pdf",
"type": "application/pdf"
}
}
]
}
```
## Extract data from the document
The automatic extraction configured on a file field runs when a person uploads the document in the
app or in a form. Saving a reference through the API does not trigger it.
To extract from a document uploaded through the API, call
[`POST /v1/document_intelligence`](/api-reference/document-intelligence/create-document-intelligence)
with the same reference, then write the values it returns with a second `POST /v1/cases/{id}/data`.
```json theme={null}
{
"attachments": [
{
"id": "7b3e5f10-2c48-4a91-b6d3-8e5f2a1c9d47",
"name": "signed-contract.pdf",
"type": "application/pdf"
}
],
"template": { "id": "6d0b4e93-1f52-4a86-b3c7-9e8d5a2f1b04" }
}
```
## The whole sequence in one script
```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail
API="https://connect.penbox.io/v1"
AUTH="Authorization: Bearer $PENBOX_API_TOKEN"
CASE_ID="c1d2e3f4-5a6b-47c8-9d0e-1f2a3b4c5d6e"
DOCUMENT="./signed-contract.pdf"
# 1. Upload the file, keeping only the reference fields.
# The size comes from the file: the response does not carry it.
REFERENCE=$(curl -sS --fail-with-body -X POST "$API/attachments" -H "$AUTH" \
-F "file=@$DOCUMENT;type=application/pdf" \
| jq -ce --argjson size "$(wc -c < "$DOCUMENT")" '{id, name, type, size: $size}')
# 2. Save the reference on the case field.
curl -sS --fail-with-body -X POST "$API/cases/$CASE_ID/data" -H "$AUTH" \
-H 'Content-Type: application/json' \
-d '{
"data": {
"signed_contract": '"$REFERENCE"',
"policy_number": "POL-2026-0042"
}
}' | jq '.schema.data[] | select(.key == "signed_contract")'
```
## Limits and behaviours
| | |
| - | - |
| **Token type** | Uploading requires a workspace API token (`pnbx_…`). A user token obtained through OAuth is rejected with `403` on `POST /v1/attachments`. The other calls in this guide accept either kind. |
| **Upload size** | 10 GB per upload. On the JSON form the limit applies to the transmitted, base64-inflated payload, so roughly 7.5 GB of file. |
| **Download size** | 50 MB per attachment. |
| **Who can download** | The attachment belongs to the workspace, not to the case. Your API token and workspace admins can download it. Other members, and the contacts filling a form on the case, cannot. Send the file as a step attachment if a recipient needs to download it. |
| **`scope`** | The `scope` body field is not applied: every upload is created with the access rules above. Do not use it to make a document more, or less, confidential. |
| **Case document list** | A referenced attachment appears in the case field, not in the case's own document list. |
## Related
Opening the case this document goes on
The endpoint reference, with every parameter
Configuring a file field in a case template
Extracting structured data from a document
# Use a Document Intelligence template in a case template
Source: https://docs.penbox.io/guides/use-document-intelligence-in-case-template
Attach your Penbox Intelligence extraction template to a File element in a case template, map extracted fields to your data schema, and run extraction on upload — with a bank RIB as the worked example.
In [Build your first Document Intelligence template](/guides/document-intelligence-first-template), you configured **Penbox Intelligence** on a document: validation, fields to extract, and a test run. This guide connects that template to a **case template** so real cases automatically extract structured data when someone uploads a file.
We use **RIB extraction** on a File element named **RIB** as the example — the same steps apply to any Document Intelligence template and document type.
## What you'll build
When you finish, your **case template** will:
* Include a **File** element aligned with the documents your extraction template expects
* Run **Document Intelligence** on that element using your chosen template
* **Map** each extracted field to your case **data schema** (existing fields or new ones created in one action)
* Be **ready to use** in new cases, with **Automatically extract on file upload** available where you need it
**Estimated time:** 5–10 minutes
***
Open the **case template** where you want extraction to run.
In the sidebar, expand **Templates**, then click **Cases**.
You land on **Case Templates**. Open the template you want to edit.
In the template **data schema**, add a **File** element that matches how you will attach the document in production (one upload per case for a single RIB, or **Allow multiple files** if you need more than one).
Click **+ Add Data**, then under **Select data type**, choose **File**.
Name the element so operators recognize it — in this walkthrough, name it **RIB** (and use your **RIB extraction** template in the next step).
Click the **File** element, then choose **Document Intelligence**.
In the **Document Intelligence** dialog, the title matches your file element (for example **RIB** followed by Document Intelligence). Open the **Template** dropdown and select your extraction template — for this example, **RIB extraction**.
Under **Field mapping**, connect what Penbox Intelligence extracts to your schema:
* **Existing fields:** click the control after **Not mapped** for each extraction field and pick the matching data schema field.
* **New fields in one step:** click **Add all fields as new fields** so each extracted field gets a matching new schema field.
This walkthrough uses the fastest path: map everything to **new** fields via **Add all fields as new fields**.
Turn on **Automatically extract on file upload** when you want extraction to run as soon as a file is attached — leaving it off is fine if you trigger extraction manually elsewhere.
Click **Save**.
***
## You're done
Your **case template** now includes your **Document Intelligence** template on the **File** element, with extracted values flowing into your **data schema** (whether you mapped to existing fields or added new ones). New cases from this template can collect uploads and structured extraction results together — swap the RIB example for any template and file element naming you use in production.
***
## What's next?
Define validation and fields to extract if you have not already.
Read how File elements behave in cases.
Fetch template definitions via Pen Connect when automating workspaces.
Exercise a template end-to-end in the app.
# Install the Penbox plugin
Source: https://docs.penbox.io/install
Connect Claude, Codex or any MCP client to your Penbox workspace in two commands.
**Running inside Claude Code?** Follow the **Claude Code** tab. Run the two shell commands, then tell the user to open a new session.
The Penbox plugin is one MCP server and five skills. The server gives the agent tools on your cases, case templates, form templates and forms. The skills teach it the order of operations. Sign-in is OAuth in your browser. No token to paste.
```bash theme={null}
claude plugin marketplace add penbox-io/penbox-plugin && claude plugin install penbox@penbox
```
Then open a new session. A plugin installed mid-session stays invisible to the session that installed it.
On the first Penbox tool call, Claude Code opens your browser. You sign in to Penbox and approve the connection. The agent then acts as you, with your rights.
1. Open **Settings**, then **Connectors**.
2. Click **Add custom connector**.
3. Name it `Penbox` and paste the URL `https://connect.penbox.io/mcp`.
4. Click **Add**, then **Connect**. Sign in to Penbox in the window that opens.
You get the tools, without the skills. Ask Claude to call `get_skill` when it builds a template.
A listing in the Claude connectors directory is coming. Until then, the custom connector is the path.
Install the plugin once for every member of your Claude organization.
1. Open your claude.ai **organization settings**, then **Plugins**.
2. Add a marketplace with the GitHub source `penbox-io/penbox-plugin`.
3. Enable the `penbox` plugin for the organization.
The plugin syncs to every user. Each user signs in to Penbox with their own account on first use.
```bash theme={null}
curl -sL https://connect.penbox.io/plugin.zip -o penbox-plugin.zip
unzip -q penbox-plugin.zip -d ~/penbox-plugin
codex plugin marketplace add ~/penbox-plugin
codex plugin install penbox
```
Then open a new session. Codex asks you to approve the install, and again on the first tool call. Answer those prompts in an interactive session: `codex exec` cannot.
Any MCP client can use the server without the plugin.
```bash theme={null}
claude mcp add --transport http penbox https://connect.penbox.io/mcp
```
You get the same tools and the same OAuth sign-in. You do not get the skills. The agent then has no built-in order of operations: it may write a template from memory instead of loading the reference first. Prefer the plugin when your client supports it.
## What to ask
Copy a prompt, replace the names, send it.
* "Open an onboarding case for Marie Dupont, [marie@example.com](mailto:marie@example.com), from our client onboarding template. Send her the first form."
* "Create a case from the 'Claim' template for Jan Peeters. Add him as the main contact. Do not send anything yet."
* "Which of my cases are waiting on the client for more than a week? List the contact and what is missing."
* "Find the case of Marie Dupont. What has she not sent yet? Draft a reminder, do not send it."
* "Send the pending reminder on the Dupont case now."
* "Create a case template named 'Mortgage file' with statuses New, Documents pending, In review, Closed. Move to In review automatically when every form is completed."
* "Add a step to the 'Mortgage file' template that sends the 'Income proof' form to the borrower."
* "Create a form template in French that asks for an ID card upload, an IBAN and a signature."
* "Add a repeatable 'Vehicle' section to the 'Fleet declaration' form, with plate number and first registration date."
* "Show me the answers of the last completed form on the Peeters case."
* "List the forms of the Dupont case with their status."
* "Upload this PDF as an attachment on the Dupont case."
* "Archive every case closed before January."
* "How many cases were created this month? Use the API."
Tools, skills and the two ways to sign in.
What the agent can never do, and what leaves your workspace.
# What is Penbox
Source: https://docs.penbox.io/introduction
The Case Intelligence platform
Penbox is the Case Intelligence platform — the modern version of case management. It manages operational cases end-to-end, combining email, SMS, forms, documents, digital signatures, and structured data collection into intelligent workflows. Its AI layer extracts data from emails and documents, drafts responses, and automates workflow transitions. This makes Penbox an intelligent interaction layer that bridges seamlessly with existing back-office and legacy systems.
Penbox is built for security. The platform meets best industry standards for data protection, encryption, and compliance — giving organizations confidence that sensitive case data and documents are handled with the highest level of care.
Most configuration happens through a visual front-end. For advanced logic and full customization, penscript — a proprietary JSON language — powers everything underneath. And because every configuration is JSON, the entire platform is manageable via API.
## Case + Intelligence
### Cases
The center of Penbox. A case is an intelligent workflow that orchestrates all interactions between a case manager and one or more contacts. Cases combine email, SMS, forms, documents, and data collection into a single managed workflow. A case can be as simple as sending a single form or as complex as a multi-month process with dozens of steps, multiple contacts, document generation, digital signatures, and intelligent automations.
[Learn about Cases →](/cases/introduction)
### Intelligence
The AI layer that defines Penbox as a Case Intelligence platform. Email Intelligence automatically classifies incoming emails and prepares draft responses. Document Intelligence extracts and validates data from incoming documents. This automation layer understands communications, extracts structured data, and orchestrates intelligent responses — making cases intelligent, not just managed.
## Getting Started
Understand the mental model and key concepts
Quick reference for Penbox terminology
Learn how to work with cases
Understand form creation and management
Integrate Penbox with your systems
# Loops & arrays
Source: https://docs.penbox.io/penscript/arrays
Iterating, transforming, filtering, and building collections in penscript
penscript provides a full set of operators for working with collections — iterating, transforming, filtering, querying, and building arrays. These are used to generate dynamic form fields, validate uploaded documents, compute aggregates, and build conditional structures based on variable-length data.
## Context Variables
When iterating over an array (with `:map`, `:every`, `:some`, `:find`, or `:filter`), penscript makes the following context variables available inside the loop body:
| Variable | Description |
| - | - |
| `{@item}` | The current item value |
| `{@index}` | Current index (0, 1, 2...) |
| `{@position}` | Current position (1, 2, 3...) |
| `{@first}` | `true` if the current item is the first |
| `{@last}` | `true` if the current item is the last |
Access nested properties of the current item with dot notation: `{@item.name}`, `{@item.role}`, `{@item.amount}`.
## Normalizing to Arrays: `:array`
Wraps a value in an array if it isn't one already. Useful for ensuring consistent array input when a value might be a single item or an array.
```json theme={null}
{ ":array": 1 }
// Result: [1]
{ ":array": "{data.tags}" }
// Scope: { "data": { "tags": [1, 2, 3] } }
// Result: [1, 2, 3]
{ ":array": "{data.tags}" }
// Scope: { "data": { "tags": "urgent" } }
// Result: ["urgent"]
```
### Generating Arrays with `:fill`
Combine `:array` with `:fill` to generate arrays of a specific length. Each element is created from the `:fill` template, with context variables available.
```json theme={null}
{
":array": 3,
":fill": { "id": "item_{@index}" }
}
// Result: [{ "id": "item_0" }, { "id": "item_1" }, { "id": "item_2" }]
```
## Mapping: `:map`
Transforms every item in an array. The transformation expression has access to `{@item}`, `{@index}`, `{@position}`, `{@first}`, and `{@last}`.
**Using `:to` syntax:**
```json theme={null}
{
":map": ["a", "b", "c"],
":to": "Value: {@item} (pos: {@position})"
}
// Result: ["Value: a (pos: 1)", "Value: b (pos: 2)", "Value: c (pos: 3)"]
```
**Using array syntax** — the second element is the transformation expression:
```json theme={null}
{
":map": [
"{data.numbers}",
{ ":sum": ["@item", "@item"] }
]
}
// Scope: { "data": { "numbers": [1, 2, 3] } }
// Result: [2, 4, 6]
```
**Complex mapping with local variables using `:with`:**
This is the most powerful pattern — generating dynamic structures from data. The `:with` operator creates local variables for each iteration, keeping the template readable.
```json theme={null}
{
":map": [
{ ":range-array": [0, "{data.count}"] },
{
":with": [
{ "pos": { ":sum": ["{@index}", 1] } },
[
{ "type": "paragraph", "title": "Person {pos}" },
{
"key": "name_{@index}",
"type": "text",
"title": "Person {pos} name"
}
]
]
}
]
}
// Scope: { "data": { "count": 2 } }
// Result:
// [
// { "type": "paragraph", "title": "Person 1" },
// { "key": "name_0", "type": "text", "title": "Person 1 name" },
// { "type": "paragraph", "title": "Person 2" },
// { "key": "name_1", "type": "text", "title": "Person 2 name" }
// ]
```
## Filtering: `:filter`
Removes items from an array based on a condition. Works by mapping items to themselves (kept) or `false` (removed), then stripping the falsy values.
```json theme={null}
{
":filter": {
":map": [
"{data.numbers}",
{
":if": [
{ ":cmp": "@item", ":gt": 2 },
"@item",
false
]
}
]
}
}
// Scope: { "data": { "numbers": [1, 2, 3, 4, 5] } }
// Result: [3, 4, 5]
```
Filtering with inline expressions:
```json theme={null}
{
":filter": {
":map": [
"{data.emails}",
{
":if": [
"{{ @item.endsWith('@example.com') }}",
"@item",
false
]
}
]
}
}
// Scope: { "data": { "emails": ["a@example.com", "b@other.com", "c@example.com"] } }
// Result: ["a@example.com", "c@example.com"]
```
## Finding Items: `:find`
Returns the first item in an array that matches a condition. If no match is found, returns `undefined`.
```json theme={null}
{
":find": ["{data.users}", { ":eq": ["@item.role", "admin"] }]
}
// Scope: {
// "data": {
// "users": [
// { "id": 1, "role": "user" },
// { "id": 2, "role": "admin" },
// { "id": 3, "role": "admin" }
// ]
// }
// }
// Result: { "id": 2, "role": "admin" } (first match only)
```
## Membership & Intersections
### `:includes`
Tests if an array contains a specific value.
```json theme={null}
{ ":includes": [[1, 2, 3], 2] }
// Result: true
{ ":includes": [[1, 2, 3], 4] }
// Result: false
```
Works with `:if` for access control patterns:
```json theme={null}
{
":if": { ":includes": ["{data.roles}", "admin"] },
":then": "Full access",
":else": "Limited access"
}
// Scope: { "data": { "roles": ["user", "admin"] } }
// Result: "Full access"
```
### `:intersects`
Tests if two arrays share any common elements.
```json theme={null}
{ ":intersects": ["{data.user_tags}", ["vip", "premium"]] }
// Scope: { "data": { "user_tags": ["new", "vip"] } }
// Result: true
// Scope: { "data": { "user_tags": ["basic"] } }
// Result: false
```
## Counting: `:count`
Returns the number of items in an array.
```json theme={null}
{ ":count": "{data.items}" }
// Scope: { "data": { "items": [1, 2, 3] } }
// Result: 3
```
### Conditional Counting with `:where`
Count only items that satisfy a condition:
```json theme={null}
{
":count": "{data.items}",
":where": { ":cmp": "@item", ":gt": 1 }
}
// Scope: { "data": { "items": [1, 2, 3, 4] } }
// Result: 3 (counts 2, 3, 4)
```
### Excluding Items with `:unless`
Combine `:where` and `:unless` for fine-grained filtering:
```json theme={null}
{
":count": "{data.items}",
":where": { ":cmp": "@item", ":gt": 1 },
":unless": { ":eq": ["@item", 3] }
}
// Scope: { "data": { "items": [1, 2, 3, 4] } }
// Result: 2 (counts 2 and 4 — excludes 3)
```
## Range Arrays: `:range-array`
Generates an array of sequential integers. The start is inclusive, the end is exclusive.
```json theme={null}
{ ":range-array": [0, 3] }
// Result: [0, 1, 2]
{ ":range-array": [2, 6] }
// Result: [2, 3, 4, 5]
```
Commonly used with `:map` to generate a dynamic number of form fields or UI elements based on a user-provided count.
## Flattening: `:flatten`
Deeply flattens nested arrays into a single flat array.
```json theme={null}
{ ":flatten": [[1, [2, [3]]]] }
// Result: [1, 2, 3]
{
":flatten": ["{data.items}", [null, 4, [[5], [[[[6]]]]]], false]
}
// Scope: { "data": { "items": [1, 2, 3] } }
// Result: [1, 2, 3, null, 4, 5, 6, false]
```
Useful after a `:map` that produces arrays of arrays — for example, when each mapped item generates multiple form fields and you need them in a single flat list.
## Sequence Check: `:increasing`
Returns `true` if all values in the array are in strictly increasing order.
```json theme={null}
{ ":increasing": "{data.daily_balances}" }
// Scope: { "data": { "daily_balances": [100, 150, 200] } }
// Result: true
// Scope: { "data": { "daily_balances": [100, 90, 120] } }
// Result: false
```
Useful for validating that sequential inputs are in the expected order (e.g., dates, amounts, installment schedules).
***
## Next Steps
:every and :some for array conditions
Aggregate calculations on arrays
Context variables in loops
Dynamic form generation with :map
# Dates & time
Source: https://docs.penbox.io/penscript/dates
Date creation, formatting, comparison, and arithmetic in penscript
penscript provides operators for creating, formatting, comparing, and manipulating dates. These are used for deadline calculations, age-based eligibility rules, contract expiration checks, and time-sensitive automations.
## Date Creation: `:date`
Creates a date from a string or retrieves the current date/time.
```json theme={null}
{ ":date": "now" }
// Result: "2026-01-27T16:34:54.757Z"
{ ":date": "2000-11-20" }
// Result: "2000-11-20T00:00:00.000Z"
```
Strings in ISO 8601 format (`"2024-01-15T00:00:00.000Z"`) and `YYYY-MM-DD` format (`"2024-01-15"`) are automatically parsed as dates.
The system variable `{$today}` is also available in inline expressions for the current date.
## Date Formatting: `:format-date`
Formats a date according to a pattern string.
```json theme={null}
{
":format-date": { ":date": "now" },
":pattern": "Y"
}
// Result: "2026"
{
":format-date": { ":date": "now" },
":pattern": "Y-M-D"
}
// Result: "2026-01-27"
{
":format-date": { ":date": "now" },
":pattern": "D/M/Y"
}
// Result: "27/01/2026"
```
### Pattern Characters
| Character | Description |
| - | - |
| `Y` | Year, 4 digits |
| `y` | Year, 2–4 digits |
| `M` | Month, 2 digits (zero-padded) |
| `m` | Month, 1–2 digits |
| `D` | Day, 2 digits (zero-padded) |
| `d` | Day, 1–2 digits |
| `x` | Any non-digit separator |
### Inline Formatting with Pipes
For quick formatting inside strings, use the `formatDdMmYyyy` pipe:
```json theme={null}
"{$today | formatDdMmYyyy}"
// → "27/01/2026"
"{data.created_at | formatDdMmYyyy}"
// Scope: { "data": { "created_at": "2015-10-20" } }
// → "20/10/2015"
```
## Date Comparison
### Using `:cmp`
Combine `:cmp` with dates and the `| age` pipe for age-based conditions:
```json theme={null}
{
":if": [
{
":cmp": "{data.birthdate | age}",
":gte": 18,
":lte": 65
}
],
":then": "Eligible",
":else": "Not eligible"
}
```
All standard comparison modifiers work: `:eq`, `:neq`, `:gt`, `:gte`/`:ge`, `:lt`, `:lte`/`:le`.
### Inline Date Comparisons
Simple date comparisons can be expressed directly inside strings:
```json theme={null}
{
":if": "{{ myDate > now }}",
":then": "Future date",
":else": "Past or current date"
}
```
Direct inline comparison patterns:
```json theme={null}
"{ my_date > $today }"
// → true if my_date is after today
"{ my_date == $today }"
// → equality check with today
"{ data.birthdate | age >= 18 }"
// → age check
"{ my_date > $today ? 'Future' : 'Past' }"
// → ternary
```
Combined conditions:
```json theme={null}
"{ my_date != $today | my_date < $today }"
// → true if my_date is not today or is in the past
```
## Date Difference: `:diff`
Calculates the difference between two dates in a specified unit.
```json theme={null}
{
":diff": [
"{data.date1}",
"{data.date2}",
{
":comparator": "day"
}
]
}
// Scope: { "data": { "date1": "2024-01-01", "date2": "2024-02-04" } }
// Result: 34
```
### Available Comparators
| Comparator | Returns |
| - | - |
| `"day"` | Number of days between the dates |
| `"hour"` | Number of hours |
| `"minute"` | Number of minutes |
| `"second"` | Number of seconds |
## Age Calculation: `| age`
Calculates the age in years from a date value. Available as an inline pipe.
```json theme={null}
"{data.birthdate | age}"
// Scope: { "data": { "birthdate": "2007-01-01" } }
// Result: 18
```
Commonly combined with `:cmp` for eligibility rules:
```json theme={null}
{
":if": [
{ ":cmp": "{data.birthdate | age}", ":gte": 18 }
],
":then": "Adult",
":else": "Minor"
}
```
## Date Arithmetic: `:sum` with Dates
Add or subtract time from dates using duration strings.
**Single duration:**
```json theme={null}
{
":format-date": {
":sum": ["{$today}", "2d"]
}
}
// Result: Current date + 2 days
```
**Multiple durations combined:**
```json theme={null}
{
":format-date": {
":sum": ["{$today}", "2d", "3d", "72h", "2y"]
}
}
// Result: Current date + 2 days + 3 days + 72 hours + 2 years
```
### Supported Duration Units
| Unit | Example | Description |
| - | - | - |
| Days | `"2d"`, `"3d"` | Add days |
| Hours | `"72h"` | Add hours |
| Years | `"2y"` | Add years |
### Raw Numbers and Strings
* **Raw numbers** are treated as **milliseconds**. Negative numbers subtract time.
* **Numeric strings** (e.g., `"+86400"`) are treated as **seconds**.
```json theme={null}
{
":format-date": {
":sum": [
{ ":date": "now" },
-8640000000
],
":pattern": "D-M-Y"
}
}
// Result: Current date minus 100 days
```
### Building Deadlines
A common pattern — calculate a deadline and format it for display:
```json theme={null}
{
":format-date": {
":sum": ["{$today}", "30d"]
},
":pattern": "D/M/Y"
}
// → "13/03/2026" (30 days from today)
```
***
## Next Steps
\$today and inline pipes
Date-based conditions with :cmp
:sum for date arithmetic
Date examples in automations
# Dynamic evaluation & scope
Source: https://docs.penbox.io/penscript/dynamic_evaluation
Local variables, deferred evaluation, and value pipelines in penscript
penscript supports local variable definitions, deferred evaluation, and value pipelines. These operators let you break complex expressions into readable parts, build reusable templates, and chain transformations step by step.
## Local Variables: `:define` + `:in`
Defines local variables that are available only within the `:in` expression. Variables can reference each other sequentially — each definition can use variables defined before it.
```json theme={null}
{
":define": [
{ "t": "{s} {s}" },
{ "u": "{t} {t}" }
],
":in": "{u}"
}
// Scope: { "s": "hello" }
// Result: "hello hello hello hello"
```
Variables can be computed using operators:
```json theme={null}
{
":define": [
{ "base_premium": { ":product": [0.7355, "{data.horses_power}"] } },
{ "tax": { ":multiply": ["{base_premium}", 0.21] } },
{ "total": { ":sum": ["{base_premium}", "{tax}"] } }
],
":in": "Total premium: {total}"
}
// Scope: { "data": { "horses_power": 110 } }
// Result: "Total premium: 97.7"
```
This is essential for complex calculations where intermediate values improve readability and avoid repeating expressions.
## Inline Local Bindings: `:with`
Creates local variable bindings directly within an expression — typically inside a `:map`. The first argument defines the variables, the second is the expression that uses them.
```json theme={null}
{
":with": [
{ "pos": { ":sum": ["{@index}", 1] } },
{ "title": "Person {pos}" }
]
}
// Inside a :map where @index is 0:
// Result: { "title": "Person 1" }
```
The difference from `:define`/`:in`: `:with` is designed for use inside loops and transformations where you need a quick local binding without a full `:define` block.
**Generating complex dynamic structures:**
```json theme={null}
{
":map": [
{ ":range-array": [0, "{data.count}"] },
{
":with": [
{ "pos": { ":sum": ["{@index}", 1] } },
[
{ "type": "paragraph", "title": "Person {pos}" },
{ "key": "name_{@index}", "type": "text", "title": "Person {pos} name" },
{ "key": "email_{@index}", "type": "email", "title": "Person {pos} email" }
]
]
}
]
}
// Scope: { "data": { "count": 2 } }
// Result:
// [
// { "type": "paragraph", "title": "Person 1" },
// { "key": "name_0", "type": "text", "title": "Person 1 name" },
// { "key": "email_0", "type": "email", "title": "Person 1 email" },
// { "type": "paragraph", "title": "Person 2" },
// { "key": "name_1", "type": "text", "title": "Person 2 name" },
// { "key": "email_1", "type": "email", "title": "Person 2 email" }
// ]
```
## Raw Expressions: `:raw`
Captures an expression without evaluating it. The result is the expression structure itself (the AST), not the evaluated value. This is the foundation for building reusable expression templates.
```json theme={null}
{ ":raw": ["{a}", "{a}"] }
// Scope: { "a": 42 }
// Result: ["{a}", "{a}"] (not evaluated — still contains variable references)
```
Defining a reusable template with `:define`:
```json theme={null}
{
":define": [
{ "exp": { ":raw": ["{value}", "{value}"] } }
],
":in": "{exp}"
}
// Scope: { "value": 5 }
// Result: ["{value}", "{value}"] (still raw)
```
The raw expression is stored for later evaluation with `:eval`.
## Dynamic evaluation: `:eval`
Evaluates an expression that was previously captured with `:raw` or built dynamically. This is the counterpart to `:raw` — it takes a stored expression and runs it in the current scope.
**Simple evaluation:**
```json theme={null}
{ ":eval": { ":sum": [1, 2, 3] } }
// Result: 6
```
**Combined with `:raw` for reusable templates:**
```json theme={null}
{
":using": {
"duplicateInArray": { ":raw": ["{a}", "{a}"] }
},
":eval": "{duplicateInArray}"
}
// Scope: { "a": 7 }
//
// Evaluation steps:
// 1. "duplicateInArray" is defined as a raw expression ["{a}", "{a}"]
// 2. :eval resolves "{duplicateInArray}" to that raw expression
// 3. The raw expression is evaluated in a child scope where "a" is 7
//
// Result: [7, 7]
```
The `:using` operator defines named expressions — like `:define`, but specifically designed for storing expression templates that `:eval` will run.
## Pipelines: `:pipe`
Passes a value through multiple transformation steps sequentially. Each step receives the result of the previous step as `@value`.
```json theme={null}
{
":pipe": [
"{data.raw_amount}",
{ ":sum": ["@value", 1] },
{ ":multiply": ["@value", 2] }
]
}
// Scope: { "data": { "raw_amount": 10 } }
//
// Flow:
// step 1 → 10
// step 2 → 10 + 1 = 11
// step 3 → 11 × 2 = 22
//
// Result: 22
```
Pipelines are useful when a value needs to pass through a series of transformations — adding fees, applying tax rates, rounding — where each step depends on the result of the previous one. The `@value` context variable always contains the output of the most recent step.
***
## Next Steps
Scope and variable resolution
:with inside :map
Calculations in :define and :pipe
Dynamic evaluation examples
# How penscript works
Source: https://docs.penbox.io/penscript/how_it_works
Real-time expressions that power dynamic behavior across Penbox
penscript expressions are evaluated in real time. They can be embedded within forms, case templates, automations, notifications, and API calls. Every expression receives a **scope** — the set of variables and data available at evaluation time — and returns a result.
This page is a tour of the language. It introduces the two expression modes, shows how operators compose, and walks through the major categories of what penscript can express.
## Two ways to write expressions
### JSON Operators
Structured objects where the key defines the operation. Operators start with a colon (`:`), accept arguments, and return a value.
```json theme={null}
{ ":sum": [10, 20, 30] }
// → 60
```
Operators can be nested — the result of one operator becomes the input of another:
```json theme={null}
{
":if": { ":cmp": "{score}", ":gte": 50 },
":then": "Passed",
":else": "Failed"
}
// Scope: { "score": 72 }
// → "Passed"
```
Here, `:cmp` evaluates first (is 72 ≥ 50?), returns `true`, and `:if` uses that result to pick the `:then` branch.
### Inline Expressions
Variable references and simple logic embedded inside strings. Lightweight, readable, and ideal for labels, notifications, and short conditions.
```json theme={null}
"Hello {user.given_name}, your case #{case.reference} is {status}."
// Scope: { "user": { "given_name": "Marie" }, "case": { "reference": "2024-0847" }, "status": "active" }
// → "Hello Marie, your case #2024-0847 is active."
```
Inline expressions also support pipes, comparisons, and ternaries:
```json theme={null}
"{data.birthdate | age >= 18 ? 'Adult' : 'Minor'}"
// → "Adult" or "Minor"
```
Both modes can be mixed freely. A JSON operator can contain inline expressions in its arguments, and inline expressions can reference values computed by operators elsewhere in the configuration.
## Composing operators
The real power of penscript comes from composing operators — nesting them to express complex logic in a single, declarative structure.
Consider this: you want to display a formatted message that changes based on the number of documents a contact has uploaded.
```json theme={null}
{
":if": { ":cmp": { ":count": "{data.documents}" }, ":eq": 0 },
":then": "No documents uploaded yet.",
":else": {
":if": { ":cmp": { ":count": "{data.documents}" }, ":eq": 1 },
":then": "1 document uploaded.",
":else": "{ :count: data.documents } documents uploaded."
}
}
```
Reading from the inside out: `:count` counts the documents, `:cmp` compares the count, and `:if` picks the right message. Each operator does one thing, and composition builds the behavior.
Or, using `:case` for cleaner multi-branch logic:
```json theme={null}
{
":case": { ":count": "{data.documents}" },
":when": [
[0, "No documents uploaded yet."],
[1, "1 document uploaded."]
],
":else": "{ :count: data.documents } documents uploaded."
}
```
## What you can express
### Conditions and Branching
penscript handles everything from simple toggles to complex multi-condition logic.
**Show or hide a form element based on a previous answer:**
```json theme={null}
{
":if": "{data.has_vehicle}",
":then": { "visible": true, "required": true },
":else": { "visible": false }
}
```
**Route a notification based on a contact's language:**
```json theme={null}
{
":case": "{contacts.main.language}",
":when": [
["fr", "Votre dossier a été mis à jour."],
["nl", "Uw dossier is bijgewerkt."],
["de", "Ihre Akte wurde aktualisiert."]
],
":else": "Your case has been updated."
}
```
**Combine multiple conditions to determine eligibility:**
```json theme={null}
{
":if": [
{ ":cmp": "{data.birthdate | age}", ":gte": 18 },
{ ":in": ["{data.country}", ["BE", "FR", "LU", "NL"]] },
{ ":not": "{data.has_existing_policy}" }
],
":then": "Eligible for new policy",
":else": "Not eligible"
}
```
Each condition is a separate operator. The `:if` evaluates all of them — if they all pass, the `:then` branch is returned.
→ Full reference: [Logic & comparisons](/penscript/logic)
### Calculations and number formatting
Arithmetic, formatting, and number-driven logic.
**Calculate an insurance premium based on vehicle power:**
```json theme={null}
{
":digits": 2,
":format-number": {
":product": [0.7355, "{data.horses_power}"]
}
}
// Scope: { "data": { "horses_power": 110 } }
// → "80.91"
```
**Sum multiple amounts:**
```json theme={null}
{ ":sum": ["{data.amount_1}", "{data.amount_2}", "{data.amount_3}"] }
```
**Check whether a total exceeds a threshold:**
```json theme={null}
{
":if": {
":cmp": { ":sum": ["{data.deductible}", "{data.premium}"] },
":gt": 10000
},
":then": "Requires manager approval",
":else": "Auto-approved"
}
```
→ Full reference: [Numbers & calculations](/penscript/numbers)
### Working with collections
Iterate, transform, filter, and query arrays of data.
**Generate form fields dynamically based on a count the user entered:**
```json theme={null}
{
":map": [
{ ":range-array": [0, "{data.number_of_children}"] },
{
":with": [
{ "pos": { ":sum": ["{@index}", 1] } },
[
{ "type": "paragraph", "title": "Child {pos}" },
{ "key": "child_name_{@index}", "type": "text", "title": "Name of child {pos}", "required": true },
{ "key": "child_birthdate_{@index}", "type": "date", "title": "Date of birth of child {pos}" }
]
]
}
]
}
```
This creates a set of form fields for each child — dynamically. If the user enters 3, three sets of fields appear. The `{@index}` and `{@position}` variables track where you are in the loop. The `:with` operator creates a local `pos` variable (1-based) for display labels.
**Filter a list to find only completed items:**
```json theme={null}
{
":filter": {
":map": [
"{data.tasks}",
{
":if": [
{ ":eq": ["@item.status", "completed"] },
"@item",
false
]
}
]
}
}
```
**Check whether any uploaded document is an ID card:**
```json theme={null}
{
":some": [
"{data.documents}",
{ ":eq": ["@item.type", "id_card"] }
]
}
// → true if at least one document is tagged as an ID card
```
**Count how many items meet a condition:**
```json theme={null}
{
":count": "{data.line_items}",
":where": { ":cmp": "@item.amount", ":gt": 100 }
}
// → number of line items above 100
```
→ Full reference: [Loops & arrays](/penscript/arrays)
### Dates, time, and age
Create dates, format them, compare them, and do arithmetic.
**Check whether a contract has expired:**
```json theme={null}
{
":if": "{{ data.contract_end_date < $today }}",
":then": "Contract expired",
":else": "Contract active"
}
```
**Calculate a deadline 30 days from now:**
```json theme={null}
{
":format-date": {
":sum": ["{$today}", "30d"]
},
":pattern": "D/M/Y"
}
// → "13/03/2026"
```
**Determine eligibility based on age:**
```json theme={null}
{
":if": { ":cmp": "{data.birthdate | age}", ":gte": 18, ":lte": 65 },
":then": "Eligible",
":else": "Not eligible"
}
```
**Calculate the number of days between two events:**
```json theme={null}
{
":diff": ["{data.start_date}", "{data.end_date}", { ":comparator": "day" }]
}
// → 34 (number of days)
```
→ Full reference: [Dates & time](/penscript/dates)
### Internationalization
Serve content in the right language automatically.
```json theme={null}
{
":i18n": {
"fr": "Bonjour {user.given_name}, veuillez compléter votre dossier.",
"nl": "Hallo {user.given_name}, gelieve uw dossier te vervolledigen.",
"en": "Hello {user.given_name}, please complete your case."
}
}
```
The `:i18n` operator reads the active locale from the scope and returns the matching translation. Variables inside translations are resolved normally.
→ Full reference: [Internationalization](/penscript/internationalization)
### Dynamic evaluation
Define local variables, build reusable expression templates, and pipe values through transformation chains.
**Define intermediate values for a complex calculation:**
```json theme={null}
{
":define": [
{ "base_premium": { ":product": [0.7355, "{data.horses_power}"] } },
{ "tax": { ":multiply": ["{base_premium}", 0.21] } },
{ "total": { ":sum": ["{base_premium}", "{tax}"] } }
],
":in": "Total premium: {total}"
}
// Scope: { "data": { "horses_power": 110 } }
// → "Total premium: 97.7"
```
Each variable can reference the ones defined before it. The `:in` expression has access to all of them.
**Pipe a value through multiple steps:**
```json theme={null}
{
":pipe": ["{data.raw_amount}", { ":sum": ["@value", 100] }, { ":multiply": ["@value", 1.21] }]
}
// Scope: { "data": { "raw_amount": 500 } }
// Flow: 500 → 600 → 726
// → 726
```
**Capture an expression for reuse:**
```json theme={null}
{
":using": {
"double": { ":raw": { ":multiply": ["{x}", 2] } }
},
":eval": "{double}"
}
// Scope: { "x": 7 }
// → 14
```
The `:raw` operator captures the expression without evaluating it. `:eval` evaluates it later, in a scope where the variables have values.
→ Full reference: [Dynamic evaluation & scope](/penscript/dynamic_evaluation)
## Real-world composition
These capabilities are designed to be combined. A single penscript configuration might use conditions to control which form elements appear, calculations to compute a premium, loops to generate dynamic fields, date arithmetic to set deadlines, and internationalization to serve it all in the contact's language.
Here's a realistic fragment from a case automation — automatically moving a case to "Ready for Review" when all required documents are uploaded and the contact is an adult:
```json theme={null}
{
":if": [
{ ":cmp": "{data.birthdate | age}", ":gte": 18 },
{
":every": [
["id_card", "proof_of_address", "income_statement"],
{ ":some": ["{data.documents}", { ":eq": ["@item.type", "@item"] }] }
]
}
],
":then": { "status": "ready_for_review" },
":else": { "status": "in_progress" }
}
```
Reading this: the first condition checks the contact's age. The second iterates over the list of required document types and, for each one, checks whether any uploaded document matches that type. If both conditions pass, the case moves to "Ready for Review."
This is a single JSON object. No procedural code, no external scripts — just declarative logic that Penbox evaluates in real time.
## Where penscript runs
penscript expressions appear throughout the platform:
* **Form templates** — element visibility, validation, default values, computed fields, conditional steps
* **Case templates** — data schema defaults, status transition conditions, step visibility rules
* **Automations** — trigger conditions, status transitions, post-automation payloads
* **Notifications** — dynamic content in emails and SMS (subject lines, body text, conditional sections)
* **Document generation** — variable injection into Word and PDF templates
* **API payloads** — outbound data sent by post-automations to external systems
The visual editor handles configuration for most of these. penscript lets you go further — adding logic, conditions, and dynamic behavior that the visual editor doesn't expose.
***
## Next Steps
Learn about variable syntax and scope
Conditions, branching, and boolean logic
Arithmetic and number formatting
Working with collections
# Internationalization
Source: https://docs.penbox.io/penscript/internationalization
Locale-aware content with the :i18n operator in penscript
penscript supports locale-aware content through the `:i18n` operator. This allows forms, notifications, case labels, and any text content to be served in the right language automatically — based on the contact's or user's locale.
## Inline Translations: `:i18n`
Returns a localized string based on the active locale. The scope must include a `locales` array that defines the user's preferred languages, ordered by preference.
```json theme={null}
{
":i18n": {
"fr": "Bonjour {user.given_name}",
"en": "Hello {user.given_name}"
}
}
// Scope (FR): { "locales": ["fr", "en"], "user": { "given_name": "Marie" } }
// Result: "Bonjour Marie"
// Scope (EN): { "locales": ["en", "fr"], "user": { "given_name": "Alex" } }
// Result: "Hello Alex"
```
The operator checks the `locales` array in order and returns the first matching translation. If the preferred locale isn't available, it falls back to the next one in the list.
## Variable Interpolation
Translations support full variable interpolation — any penscript variable can be used inside the translated strings:
```json theme={null}
{
":i18n": {
"fr": "Votre dossier #{case.reference} a été créé le {case.created_at | formatDdMmYyyy}.",
"nl": "Uw dossier #{case.reference} werd aangemaakt op {case.created_at | formatDdMmYyyy}.",
"en": "Your case #{case.reference} was created on {case.created_at | formatDdMmYyyy}."
}
}
```
Variables are resolved after the locale is selected, so each translation can reference any value available in the scope.
## Where to Use `:i18n`
The `:i18n` operator works anywhere penscript is evaluated:
* **Form labels and descriptions** — display element titles in the contact's language
* **Notification content** — emails and SMS in the right language
* **Welcome and completion pages** — localized form instructions
* **Case status labels** — localized status names for display
* **Document generation** — language-specific content in generated documents
For forms, the contact's language preference determines which translation is shown. For internal-facing content, the workspace member's language is used.
***
## Next Steps
Variable interpolation in strings
Conditional content by locale
:i18n in notifications
Contact language preferences
# What is penscript
Source: https://docs.penbox.io/penscript/introduction
The proprietary JSON language that powers Penbox configuration
penscript is the proprietary JSON language that powers every configurable element of Penbox. It adds advanced logic — conditions, calculations, loops, dynamic content — to static JSON structures.
Everything visible in the Penbox UI is penscript underneath. Form structure, notification rules, automations, element visibility, case templates — all represented as JSON that the visual editor reads and writes.
## Visual Editor vs penscript
The visual front-end handles most configuration needs. penscript is where the real power lives: conditional logic, complex data transformations, dynamic behavior, and configurations that go beyond what the visual editor exposes.
Changes made in penscript are immediately reflected in the visual editor, and vice versa. This means there's no "script mode" separate from the product — it's two views of the same configuration.
**The visual editor is best for:**
* Standard configurations
* Common use cases
* Quick setup and testing
* Learning the platform
* Day-to-day adjustments
**penscript is best for:**
* Complex conditional logic
* Advanced calculations and transformations
* Dynamic behavior based on data
* Configurations beyond visual editor limits
* API-driven configuration management
## API-First Architecture
Because every configuration is JSON, the entire platform is API-manageable. penscript is what makes Penbox a natural integration layer between contact interactions and back-office systems.
**This enables:**
* Programmatic configuration management
* Template generation from external systems
* Dynamic workflow creation
* Configuration as code
* Version control for configurations
## What You Can Do with penscript
penscript powers all configuration across Penbox:
**Case Configuration:**
* Define data schemas with conditional fields
* Create automations with complex triggers
* Build dynamic step visibility rules
* Configure status transition logic
**Form Configuration:**
* Add conditional element visibility
* Implement dynamic validation rules
* Create calculated fields
* Configure multi-step conditional logic
**Automation Logic:**
* Conditional status transitions
* Data transformations and calculations
* Dynamic step execution
* Complex trigger conditions
**Content Generation:**
* Dynamic email content
* Conditional document sections
* Personalized notifications
* Variable-based templates
**Integration:**
* API call configurations
* Response data mapping
* Request parameter building
* Authentication logic
## How penscript Works
penscript extends JSON with special syntax for dynamic behavior:
**Variables** reference data from cases, forms, and contacts:
```json theme={null}
"{data.company_name}"
```
**Functions** perform calculations and transformations:
```json theme={null}
{":add": ["{data.base_amount}", "{data.tax_amount}"]}
```
**Conditions** control logic flow:
```json theme={null}
{":if": {":eq": "{data.country}", "belgium"}, ":then": "EU", ":else": "non-EU"}
```
**Loops** iterate over collections:
```json theme={null}
{":map": "{data.line_items}", {":multiply": "{item.quantity}", "{item.price}"}}
```
These building blocks combine to create sophisticated behavior while remaining readable and manageable as JSON.
## Learning penscript
penscript follows consistent patterns that make it learnable:
1. **Start with variables** - Reference existing data
2. **Add conditions** - Make configurations dynamic
3. **Use functions** - Transform and calculate
4. **Combine patterns** - Build complex logic
The visual editor shows you the penscript behind every configuration, making it easy to learn by example. When you configure something visually, you can see the generated penscript and learn the patterns.
***
## Next Steps
Learn expression modes and operator composition
Reference data from cases, forms, and contacts
Add conditional logic to configurations
Learn from real-world penscript patterns
# Logic & comparisons
Source: https://docs.penbox.io/penscript/logic
Conditional operators and comparison logic in penscript
Conditional logic is the foundation of dynamic behavior in penscript. These operators control which content appears, which rules apply, and which branches a workflow follows.
## Conditional: `:if`
Evaluates a condition and returns one of two branches.
```json theme={null}
{
":if": "{data.is_active}",
":then": "Active",
":else": "Inactive"
}
// Scope: { "data": { "is_active": true } }
// Result: "Active"
```
The condition can be a variable, an inline expression, or another operator:
```json theme={null}
{
":if": { ":cmp": "{data.count}", ":gt": 0 },
":then": "There are {data.count} items",
":else": "No items"
}
// Scope: { "data": { "count": 3 } }
// Result: "There are 3 items"
```
Multiple conditions can be passed as an array — all must be true for the `:then` branch:
```json theme={null}
{
":if": [
{ ":cmp": "{data.age}", ":gte": 18 },
{ ":in": ["{data.country}", ["BE", "FR", "LU"]] }
],
":then": "Eligible",
":else": "Not eligible"
}
```
The return values can be any type — strings, numbers, objects, arrays, or nested operators:
```json theme={null}
{
":if": "{data.premium_member}",
":then": ["feature_a", "feature_b", "feature_c"],
":else": "{data.default_features}"
}
// Scope: { "data": { "premium_member": true } }
// Result: ["feature_a", "feature_b", "feature_c"]
```
## Switch: `:case`
Matches a value against a list of options. Returns the result for the first match, or the `:else` fallback if nothing matches.
```json theme={null}
{
":case": "{data.status}",
":when": [
["pending", "Status is pending"],
["done", "Status is done"],
["error", "Status is error"]
],
":else": "Status is unknown"
}
// Scope: { "data": { "status": "done" } }
// Result: "Status is done"
```
Cleaner than nested `:if` chains when you have multiple known values to match against.
## Comparison: `:cmp`
Compares a value against one or more thresholds. Returns `true` or `false`.
**Supported modifiers:**
| Modifier | Meaning |
| - | - |
| `:eq` | Equal to |
| `:neq` | Not equal to |
| `:gt` | Greater than |
| `:gte` / `:ge` | Greater than or equal to |
| `:lt` | Less than |
| `:lte` / `:le` | Less than or equal to |
**Single threshold:**
```json theme={null}
{ ":cmp": "{data.count}", ":gt": 0 }
// Scope: { "data": { "count": 5 } }
// Result: true
{ ":cmp": "{data.count}", ":eq": 3 }
// Scope: { "data": { "count": 5 } }
// Result: false
```
**Multiple thresholds** — all must be satisfied:
```json theme={null}
{ ":cmp": "{data.count}", ":gt": 0, ":lt": 10 }
// Scope: { "data": { "count": 5 } }
// Result: true (5 > 0 AND 5 < 10)
{ ":cmp": "{data.age}", ":gte": 18, ":lte": 65 }
// Range check: is the value between 18 and 65 inclusive?
```
Most commonly used as the condition inside `:if`:
```json theme={null}
{
":if": { ":cmp": "{data.score}", ":gte": 50 },
":then": "Passed",
":else": "Failed"
}
```
Works with numbers, dates, and values produced by pipes like `| age`.
## Equality: `:eq`
Tests whether all values in a list are equal to each other.
```json theme={null}
{ ":eq": ["{data.a}", "{data.b}", 42] }
// Scope: { "data": { "a": 42, "b": 42 } }
// Result: true
{ ":eq": [1, 2] }
// Result: false
```
Useful for validating that multiple fields contain the same value (e.g., password confirmation, duplicate detection).
## Uniqueness: `:distinct`
Returns `true` if all values in the list are different from each other.
```json theme={null}
{ ":distinct": [1, 2, 3] }
// Result: true
{ ":distinct": [1, 1, 2] }
// Result: false
```
Useful for dynamic validation — ensuring all generated fields have unique values:
```json theme={null}
{
"required": {
":distinct": ["{@index}", { ":sum": ["{@array.length}", -1] }]
}
}
```
## Membership: `:in` / `:nin`
Tests whether a value exists (or doesn't exist) in a given list.
**`:in`** — value is in the list:
```json theme={null}
{ ":in": ["{data.role}", ["admin", "manager"]] }
// Scope: { "data": { "role": "admin" } }
// Result: true
```
**`:nin`** — value is NOT in the list:
```json theme={null}
{ ":nin": ["{data.role}", ["banned", "suspended"]] }
// Scope: { "data": { "role": "user" } }
// Result: true
```
Works naturally with `:if` for access control and routing:
```json theme={null}
{
":if": { ":in": ["{data.country}", ["FR", "BE", "CH"]] },
":then": "French-speaking region",
":else": "Other region"
}
// Scope: { "data": { "country": "BE" } }
// Result: "French-speaking region"
```
## Boolean Helpers
### `:not`
Negates a boolean value.
```json theme={null}
{ ":not": "{data.is_blocked}" }
// Scope: { "data": { "is_blocked": true } }
// Result: false
```
### `:every`
Returns `true` if every item in an array satisfies a condition. The condition is evaluated for each item with `@item` as the current element.
```json theme={null}
{
":every": [
"{data.scores}",
{ ":cmp": "@item", ":ge": 10 }
]
}
// Scope: { "data": { "scores": [10, 12, 15] } }
// Result: true (all scores ≥ 10)
```
### `:some`
Returns `true` if at least one item satisfies a condition.
```json theme={null}
{
":some": [
"{data.users}",
{ ":eq": ["@item.role", "admin"] }
]
}
// Scope: {
// "data": {
// "users": [
// { "id": 1, "role": "user" },
// { "id": 2, "role": "admin" }
// ]
// }
// }
// Result: true (at least one admin exists)
```
## Logical Constants
Explicit boolean and null values for use in expressions where you need to return a fixed value.
```json theme={null}
{ ":true": null } // → true
{ ":false": null } // → false
{ ":null": null } // → null
{ ":undefined": null } // → undefined
```
These are typically used inside `:if` branches or `:map` transformations when you need to produce a specific constant value programmatically.
***
## Next Steps
Variable references and scope
Arithmetic and formatting
Working with collections
Expression modes and composition
# Numbers & calculations
Source: https://docs.penbox.io/penscript/numbers
Arithmetic, formatting, and numeric comparisons in penscript
penscript supports arithmetic, number formatting, and numeric comparisons. These operators are used in computed form fields, premium calculations, validation rules, and automation conditions.
## Addition: `:sum`
Returns the sum of all numbers in a list.
```json theme={null}
{ ":sum": [11, 5, 6, -2] }
// Result: 20
```
Works with variables:
```json theme={null}
{ ":sum": ["{data.amount_1}", "{data.amount_2}", "{data.amount_3}"] }
// Scope: { "data": { "amount_1": 100, "amount_2": 250, "amount_3": 50 } }
// Result: 400
```
Also used for date arithmetic — see the [Dates & time](/penscript/dates) page for details.
## Subtraction: `:substract`
Returns the sequential subtraction of all numbers in a list. The first value is the starting point, and each subsequent value is subtracted from it.
```json theme={null}
{ ":substract": [100, 30] }
// Result: 70
{ ":substract": [100, 20, 5] }
// Result: 75
```
Works with variables:
```json theme={null}
{ ":substract": ["{data.total}", "{data.discount}", "{data.tax}"] }
// Scope: { "data": { "total": 500, "discount": 75, "tax": 25 } }
// Result: 400
```
Also supports date arithmetic — see the [Dates & time](/penscript/dates) page for details.
## Multiplication: `:product`
Returns the product of all numbers in the input array.
```json theme={null}
{ ":product": [5, 3] }
// Result: 15
{ ":product": ["{data.quantity}", "{data.unit_price}"] }
// Scope: { "data": { "quantity": 4, "unit_price": 25 } }
// Result: 100
```
Commonly used inside `:pipe` for sequential transformations:
```json theme={null}
{ ":product": ["@value", 2] }
// Result: double the current @value
```
## Division: `:divide`
Divides the first number by the second.
```json theme={null}
{ ":divide": [100, 4] }
// Result: 25
{ ":divide": ["{data.total}", "{data.count}"] }
// Scope: { "data": { "total": 750, "count": 3 } }
// Result: 250
```
## Power: `:power`
Raises a base to an exponent.
```json theme={null}
{ ":power": [2, 3] }
// Result: 8
{ ":power": [10, 2] }
// Result: 100
```
## Min / Max: `:min`, `:max`
Returns the lowest or highest value from an array.
```json theme={null}
{ ":max": [3, 7, 2, 9, 1] }
// Result: 9
{ ":min": [3, 7, 2, 9, 1] }
// Result: 1
```
Works with variables:
```json theme={null}
{ ":max": ["{data.offer_a}", "{data.offer_b}", "{data.offer_c}"] }
```
## Fixed Decimals: `:to-fixed`
Converts a number to a string with a fixed number of decimal places. Defaults to 2 digits if `:digits` is not specified.
```json theme={null}
{ ":to-fixed": 123.456 }
// Result: "123.46"
{ ":to-fixed": 123.456, ":digits": 1 }
// Result: "123.5"
{ ":to-fixed": 99, ":digits": 2 }
// Result: "99.00"
```
Works with variables:
```json theme={null}
{ ":to-fixed": "{data.price}", ":digits": 2 }
// Scope: { "data": { "price": 49.9 } }
// Result: "49.90"
```
## Type Coercion: `:number`
Converts a value to a number. Useful when form inputs are strings that need to be used in calculations.
```json theme={null}
{ ":number": "123" }
// Result: 123
{ ":number": "45.67" }
// Result: 45.67
{ ":number": "abc" }
// Result: NaN
```
Works with variables:
```json theme={null}
{ ":number": "{data.quantity}" }
// Scope: { "data": { "quantity": "10" } }
// Result: 10
```
## Number Formatting: `:format-number`
Formats a number for display. Use `:digits` to control decimal precision.
```json theme={null}
{
":digits": 0,
":format-number": {
":product": [0.7355, "{data.horses_power}"]
}
}
// Scope: { "data": { "horses_power": 110 } }
// Result: 81
```
```json theme={null}
{
":digits": 2,
":format-number": { ":sum": ["{data.subtotal}", "{data.tax}"] }
}
// Scope: { "data": { "subtotal": 99.5, "tax": 20.895 } }
// Result: 120.40
```
## Age Calculation: `:age`
Calculates age in years from a date value. Typically used as an inline pipe (see [Dates & time](/penscript/dates) for the full reference), but also available as an operator in numeric contexts.
```json theme={null}
"{data.birthdate | age}"
// → 34
{
":cmp": "{data.birthdate | age}",
":gte": 18
}
// → true if the person is 18 or older
```
## Numeric Comparisons
Use `:cmp` with numeric values for conditional logic based on calculations:
```json theme={null}
{
":if": { ":cmp": "{data.price}", ":gte": 100 },
":then": "Premium tier",
":else": "Standard tier"
}
// Scope: { "data": { "price": 110 } }
// Result: "Premium tier"
```
Combining arithmetic with comparison:
```json theme={null}
{
":if": {
":cmp": { ":sum": ["{data.deductible}", "{data.premium}"] },
":gt": 10000
},
":then": "Requires approval",
":else": "Auto-approved"
}
```
***
## Next Steps
Conditional logic with numeric results
Date arithmetic with :sum
Aggregate calculations on collections
Referencing numeric data
# Operator reference
Source: https://docs.penbox.io/penscript/reference
Complete lookup of every penscript operator
A complete lookup of every penscript operator, organized by category. Each entry shows the operator name, what it does, and a minimal example. For full documentation and detailed examples, follow the link to the dedicated page.
## Logic & conditions
→ Full reference: [Logic & comparisons](/penscript/logic)
| Operator | Description | Example |
| - | - | - |
| `:if` / `:then` / `:else` | Conditional branching | `{ ":if": "{active}", ":then": "Yes", ":else": "No" }` |
| `:case` / `:when` / `:else` | Switch-style matching | `{ ":case": "{status}", ":when": [["a", "Alpha"]], ":else": "Other" }` |
| `:cmp` | Comparison with thresholds | `{ ":cmp": "{x}", ":gt": 0, ":lt": 100 }` |
| `:eq` | Equality test (all values equal) | `{ ":eq": ["{a}", "{b}", 42] }` |
| `:distinct` | Uniqueness test (all values different) | `{ ":distinct": [1, 2, 3] }` |
| `:in` | Value exists in list | `{ ":in": ["{role}", ["admin", "manager"]] }` |
| `:nin` | Value does not exist in list | `{ ":nin": ["{role}", ["banned"]] }` |
| `:not` | Boolean negation | `{ ":not": "{flag}" }` |
| `:every` | All items satisfy condition | `{ ":every": ["{arr}", { ":cmp": "@item", ":gt": 0 }] }` |
| `:some` | At least one item satisfies condition | `{ ":some": ["{arr}", { ":eq": ["@item", "x"] }] }` |
### Comparison Modifiers (used with `:cmp`)
| Modifier | Meaning |
| - | - |
| `:eq` | Equal to |
| `:neq` | Not equal to |
| `:gt` | Greater than |
| `:gte` / `:ge` | Greater than or equal to |
| `:lt` | Less than |
| `:lte` / `:le` | Less than or equal to |
### Constants
| Operator | Result |
| - | - |
| `:true` | `true` |
| `:false` | `false` |
| `:null` | `null` |
| `:undefined` | `undefined` |
## Numbers
→ Full reference: [Numbers & calculations](/penscript/numbers)
| Operator | Description | Example |
| - | - | - |
| `:sum` | Addition | `{ ":sum": [1, 2, 3] }` → `6` |
| `:substract` | Subtraction | `{ ":substract": [100, 30] }` → `70` |
| `:product` | Multiplication | `{ ":product": [5, 3] }` → `15` |
| `:multiply` | Multiplication (alias) | `{ ":multiply": [5, 3] }` → `15` |
| `:divide` | Division | `{ ":divide": [100, 4] }` → `25` |
| `:power` | Exponentiation | `{ ":power": [2, 3] }` → `8` |
| `:max` | Maximum value from array | `{ ":max": [3, 7, 9, 1] }` → `9` |
| `:min` | Minimum value from array | `{ ":min": [3, 7, 9, 1] }` → `1` |
| `:to-fixed` | Fixed decimal places | `{ ":to-fixed": 123.456, ":digits": 1 }` → `"123.5"` |
| `:number` | Coerce to number | `{ ":number": "123" }` → `123` |
| `:format-number` | Number formatting | With `:digits` for decimal precision |
## Arrays & collections
→ Full reference: [Loops & arrays](/penscript/arrays)
| Operator | Description | Example |
| - | - | - |
| `:array` | Normalize to array | `{ ":array": "x" }` → `["x"]` |
| `:array` + `:fill` | Generate array of length N | `{ ":array": 3, ":fill": "{@index}" }` |
| `:map` / `:to` | Transform each item | `{ ":map": [arr], ":to": expr }` |
| `:filter` | Remove items by condition | Wraps `:map` with `:if` returning `false` |
| `:find` | First matching item | `{ ":find": [arr, condition] }` |
| `:includes` | Array contains value | `{ ":includes": [arr, val] }` |
| `:intersects` | Arrays share elements | `{ ":intersects": [arr1, arr2] }` |
| `:count` | Count items | `{ ":count": arr }` with `:where` / `:unless` |
| `:range-array` | Generate integer range | `{ ":range-array": [0, 5] }` → `[0,1,2,3,4]` |
| `:flatten` | Deep flatten nested arrays | `{ ":flatten": [[1,[2]]] }` → `[1,2]` |
| `:increasing` | Strictly increasing check | `{ ":increasing": [1,2,3] }` → `true` |
### Context Variables (available inside loops)
| Variable | Description |
| - | - |
| `{@item}` | The current item value |
| `{@index}` | Current index (0, 1, 2...) |
| `{@position}` | Current position (1, 2, 3...) |
| `{@first}` | `true` if the current item is the first |
| `{@last}` | `true` if the current item is the last |
## Dates & time
→ Full reference: [Dates & time](/penscript/dates)
| Operator | Description | Example |
| - | - | - |
| `:date` | Create / parse a date | `{ ":date": "now" }` |
| `:format-date` | Format date with pattern | With `:pattern`: `"D/M/Y"` |
| `:diff` | Difference between dates | With `:comparator`: `"day"` |
| `:sum` (dates) | Date arithmetic | `{ ":sum": ["{$today}", "2d"] }` |
### Inline Pipes (dates)
| Pipe | Description | Example |
| - | - | - |
| `\| age` | Age calculation | `"{data.birthdate \| age}"` → `34` |
| `\| formatDdMmYyyy` | Format as DD/MM/YYYY | `"{$today \| formatDdMmYyyy}"` → `"27/01/2026"` |
### Date Pattern Characters
| Character | Description |
| - | - |
| `Y` | Year, 4 digits |
| `y` | Year, 2–4 digits |
| `M` | Month, 2 digits |
| `m` | Month, 1–2 digits |
| `D` | Day, 2 digits |
| `d` | Day, 1–2 digits |
| `x` | Any non-digit separator |
### Duration Units (for date arithmetic)
| Unit | Example |
| - | - |
| Days | `"2d"`, `"30d"` |
| Hours | `"72h"` |
| Years | `"2y"` |
Raw numbers = milliseconds. Numeric strings = seconds.
## Dynamic evaluation
→ Full reference: [Dynamic evaluation & scope](/penscript/dynamic_evaluation)
| Operator | Description | Example |
| - | - | - |
| `:define` / `:in` | Local variable scope | `{ ":define": [{"x": 1}], ":in": "{x}" }` |
| `:with` | Inline local bindings | `{ ":with": [{"x": 1}, "{x}"] }` |
| `:raw` | Capture without evaluating | `{ ":raw": "{expr}" }` |
| `:eval` | Evaluate captured expression | `{ ":eval": "{stored_expr}" }` |
| `:using` | Define named expressions | Combined with `:eval` |
| `:pipe` | Sequential transformation | `{ ":pipe": [val, step1, step2] }` |
## Internationalization
→ Full reference: [Internationalization](/penscript/internationalization)
| Operator | Description | Example |
| - | - | - |
| `:i18n` | Locale-based string | `{ ":i18n": { "fr": "Bonjour", "en": "Hello" } }` |
## System variables
| Variable | Description |
| - | - |
| `{$today}` | The current date |
***
## Related
Introduction to penscript
Expression modes and composition
# Variables & scope
Source: https://docs.penbox.io/penscript/variables
Reference data from forms, cases, contacts, and system values
Every penscript expression runs within a **scope** — the collection of variables available at evaluation time. The scope contains form data, contact information, case data, and system values. Operators read from the scope to produce dynamic results.
## Referencing Variables
Variables are referenced using curly braces:
```json theme={null}
"{user.given_name}"
```
Dot notation accesses nested values:
```json theme={null}
"{data.address.city}"
"{contacts.main.email}"
```
When a variable is used inside a JSON string, it's resolved at evaluation time and replaced with its value. When used as the entire value of a JSON key, it resolves to its native type (number, array, object, etc.) rather than being converted to a string.
## System Variables
penscript provides built-in system variables available in every scope.
| Variable | Description |
| - | - |
| `{$today}` | The current date |
System variables are prefixed with `$` to distinguish them from user-defined data.
## Inline Pipes
Variables support pipe expressions for inline transformations — lightweight operations applied directly inside a string reference, without needing a full JSON operator.
```json theme={null}
"{$today | formatDdMmYyyy}"
// → "27/01/2026"
"{my_var | formatDdMmYyyy}"
// Scope: { "my_var": "2015-10-20" }
// → "20/10/2015"
"{data.birthdate | age}"
// → 34
```
Pipes are evaluated left to right. The variable value is passed through the pipe function, and the result replaces the entire expression.
## Inline Comparisons & Ternaries
Simple logic can be expressed directly inside strings, without switching to JSON operators like `:if` or `:cmp`. This keeps lightweight conditions readable and compact.
**Boolean comparisons:**
```json theme={null}
"{ my_date > $today }"
// → true if my_date is after today
"{ my_date == $today }"
// → equality check with today
"{ data.birthdate | age >= 18 }"
// → true or false
```
**Combined conditions:**
```json theme={null}
"{ my_date != $today | my_date < $today }"
// → true if my_date is not today or is in the past
```
**Ternary expressions:**
```json theme={null}
"{ my_date > $today ? 'Future' : 'Past' }"
// → "Future" or "Past"
```
Inline expressions are ideal for short conditions in notifications, labels, and simple visibility rules. For complex branching with multiple outcomes, use the `:if` or `:case` JSON operators instead.
## Scope Resolution
When an expression references a variable, penscript resolves it by looking through the current scope. If a variable is not found, the reference resolves to `undefined` rather than throwing an error.
In nested contexts — like a `:map` loop inside a `:define` block — inner scopes can access variables from outer scopes. If a variable name exists in both the inner and outer scope, the inner scope takes precedence.
The full variable reference — all namespaces, every available key, and where each can be used — is documented in the Reference section.
***
## Next Steps
Expression modes and operator composition
Conditions, branching, and boolean logic
Arithmetic and formatting
Full variable reference
# Manage workspace credits
Source: https://docs.penbox.io/workspace/credits
Learn how workspace credits are consumed and billed
Penbox uses a credit-based system to measure and bill resource consumption across your organization. Activities such as collecting electronic signatures, running automations, utilizing Penbox Intelligence, and generating documents all draw from a shared pool of workspace credits.
## Credit Pooling
Credits are managed entirely at the workspace level. They are not tied to individual users.
Each seat in your workspace includes a dedicated credit allotment. These credits compound at the workspace level, creating a single, shared pool that any member or automation in the workspace can draw from.
Because credits are pooled, individual team members do not have personal limits. All resource consumption is consolidated, making it easy to manage usage and scale your operations.
## Credit Renewal
Your credit allotment resets automatically every month depending on your plan type:
* **Monthly plans:** Credits renew on your monthly billing date.
* **Annual plans:** Credits renew each month on the same date as your annual billing date (for example, if your annual plan started on October 15, your credits will renew on the 15th of every month).
Unused credits do not roll over to the next billing cycle.
### Top-Ups and Extra Credits
If your workspace runs low on credits before your next renewal date, you can buy extra credit packages. To purchase additional credit packs, contact your **Account Manager** directly.
***
## Action Consumption Rates
Credits are consumed dynamically as your workspace executes actions. Penbox maps credits directly to specific, discrete actions, ensuring you only pay for what you run.
### Forms
You are not billed when sending forms. Instead, Penbox only consumes credits when a form is effectively activated by the recipient:
* **Started Form:** When a recipient begins interacting with a form (meaning they actively start filling in information or entering data), it consumes **50 credits**. This is a one-time charge per request, triggered only when data entry is initiated, rather than when the form is sent or simply opened.
### Penbox Intelligence
AI-powered parsing, analysis, and validation use credits based on the volume processed:
* **Document Intelligence:** Extracting and analyzing structured data from uploaded documents consumes credits per page processed by the LLM, at a rate that depends on the model: **3 credits per page** with the **Fast** model, **6 credits per page** with the **Advanced** model. See [Document Intelligence models](/guides/document-intelligence-models) for how to choose.
* **Email Intelligence:** Processing inbound communications, such as auto-triaging with **Case-inbound** or organizing with **Labelize**, consumes **2 credits** per execution.
* **Penbox Agent:** Because the Penbox Agent is currently in beta, interacting with it does not consume any credits. This policy is temporary and is subject to change when the Penbox Agent transitions out of beta.
### Automations and Communications
Standard automation runs and background communication tasks consume credits as they execute:
* **Automation (non-AI):** Triggering and executing any standard, non-AI workflow or automated step consumes **1 credit**. This includes operations such as automated reminders, automatic step triggering, automatic status transitions, and automated API calls.
* **SMS Notifications:** Sending text messages to recipients consumes **4 credits per SMS part** (each segment of up to 160 characters). Longer messages that span multiple parts will consume credits for each individual part sent.
### Document Generation
Creating documents directly from form data or case inputs is billed per file:
* **Document Generation:** Generating a PDF, DOCX, or other supported file formats consumes **20 credits**.
### Electronic Signatures
Collecting signatures is billed per transaction:
* **Signature Execution:** Completing a signature request consumes **65 credits**. This covers standard signature methods, including those initiated via SMS, Email, Handwritten, or ID-card verification.
* **Advanced Signature Providers:** Using **Itsme** and **Swisscom** signature types consumes the base **65 credits** and incurs an additional provider surcharge, which is billed separately.
* **Your Own Signature Provider:** When a signature is executed through your organization's own subscription with an external provider (for example, **Connective**), the standard 65 credits do not apply. Instead, each signature consumes **5 credits**, which cover the integration and its maintenance. Your provider bills its own fees directly under your contract with them.
### Integrations
Connecting and syncing data with external third-party systems is billed according to system interactions:
* **Brio Transactions:** Interacting with Brio consumes **3 credits per unique object** within a rolling 24-hour window. For example, any number of read or write operations performed on a single claim object within the same day only consumes 3 credits total. However, if a workflow interacts with multiple distinct objects, such as updating a claim and a separate contact, each unique object is billed separately at 3 credits.
# API
Source: https://docs.penbox.io/workspace/settings/api
Create and manage API tokens to access the Penbox Connect API
The **API** page lets you create and manage tokens used to authenticate requests to the Penbox Connect API. Access it from **Settings → API**.
This page is only accessible to **Administrators**.
## Creating a token
Click **Create token** and fill in:
* **Name** — A label to identify what this token is used for (e.g. `CRM integration`, `n8n automation`).
* **Description** — Optional. Additional context about the token's purpose.
* **Workspaces** — Select which workspaces this token is allowed to access. A single token can cover multiple workspaces.
After saving, the token value is displayed **once**. Copy it immediately and store it securely — it will never be shown again.
Once you close the creation dialog, the token value cannot be retrieved. If you lose it, you will need to revoke the token and create a new one.
## Managing tokens
The token list shows each token's name, when it was last used, when it was created, and who created it. Click any row to edit the token's name, description, or workspace access.
To permanently disable a token, open it and click **Revoke token**. Revoked tokens can no longer authenticate API requests.
## Using a token
Pass the token in the `Authorization` header of your API requests:
```
Authorization: Bearer
```
For full details on available endpoints and authentication, see the [API Reference](/api-reference/introduction).
# Branding
Source: https://docs.penbox.io/workspace/settings/branding
Customize your workspace's visual identity
The **Branding** page lets you configure the visual identity applied to your forms, email notifications, and the app. Access it from **Settings → Branding**.
## Images
| Image | Where it appears |
| - | - |
| **Logo** | Top of your forms and in email notifications sent to recipients. |
| **Icon** | Inside the Penbox app (workspace switcher, navigation). |
| **Favicon** | Browser tab icon when recipients open a form. |
Click any image to open the image editor. After selecting a file, a crop dialog opens — **drag to reposition** and **scroll with your mouse wheel to resize** the image within the crop frame. Click **Pick** to confirm.
## Colors
Six colors can be customized to match your brand:
| Color | Used for |
| - | - |
| **App bar** | Background of the top navigation bar in forms. |
| **Primary** | Main accent color — buttons, active steps, progress indicators. |
| **Info** | Informational tags and callouts. |
| **Success** | Validated and completed steps. |
| **Warning** | Missing or incomplete steps. |
| **Error** | Errors in steps or form elements. |
A live preview of your logo and primary color is shown on the right side of the page.
## Multiple brandings
If your plan supports it, you can create multiple branding profiles — useful when running forms under different brands or for different clients. Use the dropdown at the top to switch between profiles and the **+** button to add a new one.
Each branding profile has its own images and colors and can be assigned independently to forms and templates.
### Using branding on generic links
Apply a specific branding profile when someone opens a **generic link** by appending a query parameter to the URL. When you copy a generic link from Penbox, only the base URL is copied — the app does not add a branding parameter for you.
#### Step 1: Copy the generic link
1. Go to **Templates** and open the form template.
2. Click **Copy link** on the generic link card.
The base URL looks like this:
```
https://{hostname}/f/{flow-customization-id}
```
#### Step 2: Find the branding slug
1. Open **Settings → Branding**.
2. If you have multiple profiles, select the one you want from the dropdown.
3. Note the slug displayed next to the selector (for example, `slug: partner-acme`).
Do not use `default` as the slug — that label is for the primary workspace profile in the UI only. It is not a valid slug for URLs or the API.
#### Step 3: Append the branding parameter
Add `branding[slug]` to the generic link:
```
https://{hostname}/f/{flow-customization-id}?branding[slug]=partner-acme
```
When someone opens that URL, Penbox looks up the matching branding profile in the workspace and attaches it to the new form.
#### Default behavior
If you omit `branding[slug]`, the form uses the workspace's default branding — the primary profile configured under **Settings → Branding**.
#### Requirements
* The slug must exist in the same workspace as the form template.
* The slug must match exactly (lowercase, as shown in **Settings → Branding**).
* If the slug does not match any profile in that workspace, the parameter is ignored and the workspace default branding is used.
#### Example
```
https://forms.acme.com/f/a1b2c3d4-e5f6-7890-abcd-ef1234567890?branding[slug]=partner-brand
```
That link creates a new anonymous form with the `partner-brand` profile applied to the form experience.
There is no UI option on the generic link copy button to pick a branding profile. Build the URL manually, or generate it with your own tooling or scripts.
### Using branding via the Connect API
When creating forms programmatically, pass the branding slug in the request body instead of a URL parameter. See [Create Form](/api-reference/requests/create-request#branding) for details.
# Data Security
Source: https://docs.penbox.io/workspace/settings/data-security
Data retention and lifecycle settings, deletion audit logs
Data Security settings control how long your data is retained in Penbox and provide a complete audit trail of all deletions. Access them from **Settings → Data Security** in the app.
## Data Retention Settings
You can define **granular data retention and lifecycle settings** for both cases and forms. Each rule can be enabled independently and configured with a retention period in days.
### Cases Deletion
| Rule | Description |
| - | - |
| **After Inactivity** | Delete cases after a specific period of inactivity |
| **Closed Case** | Delete cases X days after they are closed |
| **Archived Case** | Delete cases X days after they are archived |
| **Max Retention** | Absolute limit: delete cases X days after creation, regardless of status. Overrides all other rules. |
### Forms Deletion
| Rule | Description |
| - | - |
| **Archived Form** | Delete forms X days after they are archived |
| **Max Retention** | Absolute limit: delete forms X days after activation, regardless of status. Overrides all other rules. |
### Cascade Options
When a case is deleted, you can optionally:
* **Delete associated forms** — Automatically remove all forms linked to the case
* **Delete associated contacts** — Remove contacts that are no longer referenced by any case
**Max Retention** acts as a hard limit and overrides all other deletion rules. Use it carefully.
## Data Deletion Audit Log
The **Logs** tab in Data Security shows every deletion event with full traceability:
* **What** was deleted (cases, forms, attachments, contacts)
* **When** it was deleted
* **Which rule** triggered it (inactivity, closed, archived, max retention)
* **How many entities** were affected (including cascaded deletions)
Use the audit log for compliance reviews, internal audits, and understanding exactly how retention rules are applied across your workspace.
# Domains
Source: https://docs.penbox.io/workspace/settings/domains
Connect custom domains for form hosting and email sending
The **Domains** page lets you connect your own domains to Penbox — one for hosting forms and one for sending emails. Access it from **Settings → Domains**.
Setting up custom domains requires adding DNS records in your domain provider. If you are not familiar with DNS configuration, use the **Share** button to forward the instructions to your IT team.
## Domain types
| Type | Purpose |
| - | - |
| **Form Hosting** | The domain where your forms are served. Most workspaces use a subdomain like `forms.yourdomain.com`. |
| **Email Sending** | The domain used to send email notifications to recipients. Most workspaces use their primary domain or a subdomain. |
## Setting up a domain
1. Click **Set up this domain** next to the domain type you want to configure.
2. Enter your hostname and click **Generate Records**.
3. Penbox generates a list of DNS records (CNAME, TXT, or MX) that you need to add in your DNS provider.
4. Add the records in your DNS provider, then come back and click **Verify Domain**.
Each DNS record shows its current status — **Connected** once the record is active, or **Pending** while propagation is in progress.
DNS propagation can take up to a few hours depending on your provider and TTL settings. If verification fails, wait and try again.
## Email sending domain — sender address
When setting up an email domain, you also configure a **default sender address** (e.g. `noreply@yourdomain.com`). This is the address used when no specific sender is defined for a form or notification. Make sure this address exists in your email system.
You can update the sender address at any time from the domain details.
## Sharing DNS records
Once DNS records are generated, click **Share** to send the record details to your IT team or the person responsible for managing your DNS. This lets you hand off the configuration step without giving them access to your Penbox workspace.
## Statuses
| Status | Meaning |
| - | - |
| **Connected** | The DNS records are verified and the domain is active. |
| **Pending** | The records have been generated but not yet detected. |
# Email
Source: https://docs.penbox.io/workspace/settings/email
Configure email addresses and connected mailboxes for your workspace
The **Email** page lets you configure how Penbox sends and receives emails on behalf of your workspace. There are two distinct approaches: send-only addresses from your own domain, and fully connected mailboxes (Gmail or Outlook). Access it from **Settings → Email**.
## Email addresses from your domain
You can create custom email addresses on your authenticated domain (e.g. `support@yourdomain.com`) to use as senders in notifications and forms.
* Emails sent from these addresses are **send-only** — they will not appear in any mailbox "Sent" folder.
* You need a verified **Email Sending domain** configured first. If none is set up yet, this section will prompt you to go to [Settings → Domains](/workspace/settings/domains).
* You can set a **display name** for each address to control how it appears to recipients.
## Connected mailboxes
You can connect a Gmail or Outlook mailbox at the workspace level. This enables both sending and receiving, and unlocks **Inbox Automations**.
Click **Add new mailbox connection** and choose Gmail or Outlook. You will be redirected to authenticate with your account and grant Penbox access.
A mailbox cannot be connected at the workspace level if it is already connected to a member's personal profile. Each mailbox can only be linked to one place at a time.
### Inbox automations
Once a mailbox is connected, you can enable the following automations from the **Inbox Automations** tab:
| Feature | Description |
| - | - |
| **Mailbox Drafts** | Penbox adds a ready-to-send draft directly to the conversation in Gmail or Outlook when relevant. |
| **Conversation Notifications** | When a case is created, Penbox adds a message with key case details to the related email conversation. |
You can also configure **email labels** to categorize incoming emails and trigger Penbox actions.
### Email labels
Each label has a name, a color, and two independent toggles:
| Toggle | What it does |
| - | - |
| **Auto Label** | When enabled, Penbox Intelligence automatically reads incoming emails and applies this label to the ones that match. Each label has an **Instructions** field where you describe what kinds of emails should receive it — Penbox uses this to decide. |
| **In Penbox** | When enabled, every email that receives this label automatically creates a new Penbox case using the associated case template. |
These two toggles are independent — you can auto-label without creating cases, create cases without auto-labeling, or use both together.
You can test your labels immediately by clicking **Apply to the last 50 emails**, which runs Penbox Intelligence on your recent inbox to show how the labels would be applied.
# Members
Source: https://docs.penbox.io/workspace/settings/members
Manage your team members, roles, and workspace access
The **Members** page lets you invite and manage the people who have access to your workspace. Access it from **Settings → Members** in the app.
## Member roles
Every workspace member is assigned one of three roles. Roles control what actions a member can perform across the workspace.
| Role | Description |
| - | - |
| **Administrator** | Full access to the workspace. Can invite members, change roles, manage all settings, and perform any action. |
| **Handler** | Can work on cases and forms. Cannot manage members or change workspace settings. |
| **Limited** | Restricted access. Can view and interact with content they are assigned to, but has no administrative capabilities. |
Only **Administrators** can invite new members, change roles, and manage workspace settings.
## Studio access
In addition to their role, a member can have **Studio** access enabled. This gives them access to the Penbox Studio to build and edit forms and case templates. Studio access is independent of the member's role and can be granted to any member.
## Member statuses
| Status | Description |
| - | - |
| **Active** | The member has accepted their invitation and has access to the workspace. |
| **Invited** | An invitation has been sent but not yet accepted. You can resend the invitation from the actions column. |
## Inviting a member
Click **Invite member** in the top right to open the invitation dialog. Enter the email address of the person you want to invite and select their role. They will receive an email with a link to join the workspace.
Only **Administrators** can invite new members.
## Changing a member's role
You can change a member's role at any time using the role dropdown in the members list. Changes take effect immediately.
You cannot change your own role.
## Removing a member
To remove a member from the workspace, click the delete icon in the **Actions** column.
**You cannot remove a member who has the Administrator role.** Before deleting an admin, you must first change their role to **Handler** or **Limited**, then delete them.
You also cannot remove yourself from the members list — use the **Leave workspace** button instead (available in the top right of the Members page).
## Leaving the workspace
If you want to remove yourself from a workspace, click **Leave workspace** in the top right. You will lose access to all content in the workspace immediately. To regain access, a workspace Administrator will need to invite you again.
# Settings Overview
Source: https://docs.penbox.io/workspace/settings/overview
Workspace configuration and administration
Workspace settings let you configure how Penbox behaves for your organization. Access them from the app via **Settings** in the workspace menu.
## Quick Configuration
Get started quickly with essential setup steps. This section guides you through the most important configuration choices when first setting up your workspace.
## Personal
Settings that apply to your user account, not the workspace.
| Section | Description |
| - | - |
| **Profile** | Your name, avatar, and personal preferences. |
| **Email** | Email addresses linked to your account for notifications and authentication. |
## Workspace
Settings that apply to the entire workspace. These affect all members and how the workspace operates.
| Section | Description |
| - | - |
| **General Information** | Workspace name, slug, and basic identification. |
| **Members** | [Invite and manage workspace members, roles, and permissions](/workspace/settings/members). |
| **Email** | [Configure email addresses and connected mailboxes for workspace communications](/workspace/settings/email). |
| **Branding** | [Customize logos, colors, and visual identity for forms and communications](/workspace/settings/branding). |
| **Domains** | [Set up custom domains for forms and email](/workspace/settings/domains). |
| **Data Security** | [Data retention rules and deletion audit logs](/workspace/settings/data-security). Control how long data is kept and trace what was deleted. |
| **Secrets** | [Store API keys, credentials, and other sensitive values for use in Penscript and automations](/workspace/settings/secrets). |
| **API** | [Create and manage API tokens for Connect API access](/workspace/settings/api). |
| **Usage** | View usage metrics, limits, and consumption across the workspace. |
# Secrets
Source: https://docs.penbox.io/workspace/settings/secrets
Securely store credentials and sensitive values for use in automations
The **Secrets** page lets you store sensitive values — such as API keys, passwords, or tokens — that your automations need to function. Values are stored securely and never exposed in plain text in forms or case templates. Access it from **Settings → Secrets**.
## How secrets work
Each secret has a **key** and a **value**. Once saved, the value is hidden but can be updated at any time. You reference a secret anywhere in Penbox that supports Penscript using:
```
{ $secrets.your_key }
```
For example, if you stored an API key under the key `my_api_key`, you can use `{ $secrets.my_api_key }` in an API call step or automation without exposing the raw value.
## Key format
Keys can only contain letters (uppercase or lowercase), numbers, hyphens (`-`), and underscores (`_`). No spaces or special characters.
## Managing secrets
Only **Administrators** can create, update, or delete secrets. The list shows the key, when it was last changed, and who created it.
To update a secret's value, click the edit icon — the key cannot be changed, only the value. To remove a secret, use the delete icon and confirm.
Deleting a secret is immediate and permanent. Any automation or Penscript expression referencing it will stop working.