Create a Case on the Fly

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 first. You need the workspace id and the token it returned.

Find the case template

The templates you listed in template_source were copied into the workspace. Read their ids with List Case Templates:

curl --url https://connect.penbox.io/v1/case_templates \
  --header 'Authorization: Bearer <token>'

Cache the ids per workspace — they are stable, and you need one every time you open a case.

Create the case

Instantiate the template with Create Case:

curl --request POST \
  --url https://connect.penbox.io/v1/cases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Dupont file",
    "workspace": { "id": "<workspace-uuid>" },
    "template": { "id": "<case-template-uuid>" },
    "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.

Push data into the case

Write any field of the case’s schema with Update Case Data:

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id}/data \
  --header 'Authorization: Bearer <token>' \
  --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 reference.

Attach a document

Upload the file with Upload Attachment — multipart or base64, up to 10GB:

curl --request POST \
  --url https://connect.penbox.io/v1/attachments \
  --header 'Authorization: Bearer <token>' \
  --form 'file=@contract.pdf'

The response carries the attachment’s id, name and type. Store them in one of the case’s file fields as a reference object — not as a bare id:

curl --request POST \
  --url https://connect.penbox.io/v1/cases/{id}/data \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "documents": {
        "id": "<attachment-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.

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.

Workspace settings

Form Templates

Case Templates

Document Intelligence

Campaign

Integrations

Penbox for AI agents

API

Penbox Headless

What you’ll have

You’ve created a case

​What you’ll have

​You’ve created a case

What you’ll have

You’ve created a case