Create a Case via the API

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.

Before you start

You need:

A workspace API token (pnbx_…). See 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

List your case templates

Read the template ids with List Case Templates:

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.

Create the case

Pass the template id. The case inherits the template’s fields, sections, statuses and steps.

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.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:

{
  "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.

Write data into the case

Set any field of the schema with Update Case Data. One call accepts as many fields as you need:

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.

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.

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 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:

{
  "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, 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. 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.

Add a Document to a Case

Uploading a file and saving it on a case field

Create Case

The endpoint reference, with every parameter

Data Schema

Every field type and its options

Update Case Data

Writing values into case fields

Workspace settings

Form Templates

Case Templates

Document Intelligence

Campaign

Integrations

API

Penbox Headless

Before you start

Create a case without a template

Choose the workspace

Defaults when you omit a field

Contact fields in the schema

Fields outside the schema

Add a Document to a Case

Create Case

Data Schema

Update Case Data

​Before you start

​Create a case without a template

​Choose the workspace

​Defaults when you omit a field

​Contact fields in the schema

​Fields outside the schema

​Related

Add a Document to a Case

Create Case

Data Schema

Update Case Data

Before you start

Create a case without a template

Choose the workspace

Defaults when you omit a field

Contact fields in the schema

Fields outside the schema

Related