Create Case

curl --request POST \
  --url https://connect.penbox.io/v1/cases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Dupont vs. Acme",
    "workspace": { "id": "<workspace-uuid>" },
    "template": { "id": "<case-template-uuid>" },
    "owner": { "email": "amina@firm.example" },
    "contacts": [{ "key": "main", "email": "j.dupont@mail.example" }]
  }'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "title": "<string>",
  "parent_status": "draft",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "workspace": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "description": "<string>",
  "locale": "<string>",
  "reference": "<string>",
  "status": "<string>",
  "status_label": "Waiting for documents",
  "waiting_for": "none",
  "statuses": [
    {
      "key": "waiting_for_documents",
      "label": "Waiting for documents",
      "parent_status": "draft"
    }
  ],
  "archived_at": "2023-11-07T05:31:56Z",
  "contacts": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "key": "<string>",
      "name": "<string>",
      "email": "jsmith@example.com",
      "given_name": "<string>",
      "family_name": "<string>",
      "phone": "<string>"
    }
  ],
  "template": "<string>",
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "jsmith@example.com",
    "given_name": "<string>",
    "family_name": "<string>"
  },
  "actor_type": "human",
  "channel": "app",
  "creator": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "jsmith@example.com"
  },
  "steps": [
    {
      "id": "<string>",
      "title": "<string>",
      "status": "<string>",
      "data": {}
    }
  ],
  "schema": [
    {
      "key": "<string>",
      "type": "<string>",
      "value": "<unknown>",
      "name": "<string>"
    }
  ]
}

POST

cases

curl --request POST \
  --url https://connect.penbox.io/v1/cases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Dupont vs. Acme",
    "workspace": { "id": "<workspace-uuid>" },
    "template": { "id": "<case-template-uuid>" },
    "owner": { "email": "amina@firm.example" },
    "contacts": [{ "key": "main", "email": "j.dupont@mail.example" }]
  }'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "title": "<string>",
  "parent_status": "draft",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "workspace": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "description": "<string>",
  "locale": "<string>",
  "reference": "<string>",
  "status": "<string>",
  "status_label": "Waiting for documents",
  "waiting_for": "none",
  "statuses": [
    {
      "key": "waiting_for_documents",
      "label": "Waiting for documents",
      "parent_status": "draft"
    }
  ],
  "archived_at": "2023-11-07T05:31:56Z",
  "contacts": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "key": "<string>",
      "name": "<string>",
      "email": "jsmith@example.com",
      "given_name": "<string>",
      "family_name": "<string>",
      "phone": "<string>"
    }
  ],
  "template": "<string>",
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "jsmith@example.com",
    "given_name": "<string>",
    "family_name": "<string>"
  },
  "actor_type": "human",
  "channel": "app",
  "creator": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "jsmith@example.com"
  },
  "steps": [
    {
      "id": "<string>",
      "title": "<string>",
      "status": "<string>",
      "data": {}
    }
  ],
  "schema": [
    {
      "key": "<string>",
      "type": "<string>",
      "value": "<unknown>",
      "name": "<string>"
    }
  ]
}

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.

curl --request POST \
  --url https://connect.penbox.io/v1/cases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Dupont vs. Acme",
    "workspace": { "id": "<workspace-uuid>" },
    "template": { "id": "<case-template-uuid>" },
    "owner": { "email": "amina@firm.example" },
    "contacts": [{ "key": "main", "email": "j.dupont@mail.example" }]
  }'

Authorizations

Authorization

string

header

required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Body

application/json

title

string

required

Case title

reference

string

Case reference. Use it to filter cases by reference.

status

string

Initial custom status

template

object

Show child attributes

workspace

object

Show child attributes

owner

object

Show child attributes

contacts

object[]

Show child attributes

schema

object[]

Array of data fields from the schema. Leave it empty to use the schema from the template. If you want to add new fields, you can add them here.

Show child attributes

Response

200 - application/json

Case created successfully

string<uuid>

required

Case UUID

title

string

required

Case title

parent_status

enum<string>

required

Parent status

Available options:

draft,

pending,

in_progress,

closed,

cancelled

created_at

string<date-time>

Creation timestamp

updated_at

string<date-time>

Last update timestamp

workspace

object

Workspace the case belongs to

Show child attributes

description

string | null

Case description

locale

string | null

Language/locale code

reference

string | null

Custom reference number

status

string | null

Key of the current status

status_label

string | null

Human-readable label of the current status. Custom statuses return the label configured on the case template, in the language it was written in. Built-in statuses (draft, pending, in_progress, closed, cancelled) return an English label, as the API has no notion of the reader's language.

Example:

"Waiting for documents"

waiting_for

enum<string>

Who the case is waiting for

Available options:

none,

owner,

contact

statuses

object[] | null

Statuses available on this case, inherited from its case template. Use it to resolve the status key into a readable label. Null when no status is configured.

Show child attributes

archived_at

string<date-time> | null

Timestamp when archived

contacts

object[]

Array of contact objects

Show child attributes

template

string | null

Template reference

owner

object | null

Case owner information

Show child attributes

actor_type

enum<string> | null

read-only

Who decided to create the case: 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. Read-only, and null on cases created before this was recorded.

Available options:

human,

ai,

automation,

partner,

system

channel

enum<string> | null

read-only

The surface the case came through: the Penbox app, the Outlook add-in, an AI assistant, this API, an email, a completed form, a connection or Penbox itself. Read-only, and null on cases created before this was recorded.

Available options:

app,

outlook,

mcp,

api,

email,

form,

connection,

system

creator

object | null

read-only

The workspace member who created the case. Null when no person created it, and null on cases created before this was recorded. Read-only.

Show child attributes

steps

object[]

Array of step objects representing the case workflow

Show child attributes

schema

object[]

Array of data fields with their current values

Show child attributes

API Reference

Workspaces

Cases

Tasks

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Authorizations

Body

Response