Create Case Input
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.
automode (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.suggestmode keeps every row as a proposal. Review it withPOST /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": "<file field 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.
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 byoptions.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 indocuments, 5 at most per call. Each file is either an attachment you already
uploaded, or an inline base64 file.
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.
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.
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."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.suggest mode the file is uploaded but not filed. Document Intelligence therefore runs
after the apply call, not after this one.
Authorizations
API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}
Path Parameters
Case UUID
Body
What this material is and where it comes from: free text, or any JSON (call id, agent, duration…)
"Transcript of an 11-minute call with the client on 2026-09-01"
The material itself: a string (transcript, notes, OCR…) or any JSON value (a parsed email, a webhook payload). Sent to the model as-is. Max 100 000 characters once serialized.
Explicit values, written as-is. An unknown key lands in the case's extra data, as with POST /cases/{id}/data.
Explicit contacts, same shape as POST /cases/{id}/contacts
Files to file on the case, 5 at most. Each item is either an existing attachment id, or an inline base64 file. The whole body must stay under 50 MB.
5Response
The input resource with its change list, plus the refreshed case
The case. On the write routes and on the single read it is the full case (same shape as GET /cases/{id}).
Provenance, inferred from your token: api
"api"
What the material is, derived by Penbox from the context and the content
call, note, chat, message, document, other What you sent as context
suggest, auto proposed, partially_applied, applied One paragraph on what the material is about, in the case language
Facts read in the content that no case field can hold. Never written.
The raw material, verbatim. Only returned by GET /cases/{id}/inputs/{input_id}.