Upsert Case Field

curl --request PUT \
  --url https://connect.penbox.io/v1/cases/{id}/fields/delai_appel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Délai d'\''appel", "type": "date", "is_deadline": true }'

curl --request PUT \
  --url https://connect.penbox.io/v1/cases/{id}/fields/delai_appel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Délai d'\''appel (Cour)" }'

{
  "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>",
  "agent": {
    "instructions": "<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",
  "silent": true,
  "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": {
    "data": [
      {
        "key": "<string>",
        "name": "<string>",
        "type": "<string>",
        "value": "<unknown>",
        "is_reference": true,
        "is_deadline": true
      }
    ],
    "other": [
      {
        "key": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "embed_links": [
    {
      "role": "main",
      "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "https://form.penbox.io/embed/eyJhbGciOi..."
    }
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

PUT

cases

{id}

fields

{key}

curl --request PUT \
  --url https://connect.penbox.io/v1/cases/{id}/fields/delai_appel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Délai d'\''appel", "type": "date", "is_deadline": true }'

curl --request PUT \
  --url https://connect.penbox.io/v1/cases/{id}/fields/delai_appel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Délai d'\''appel (Cour)" }'

{
  "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>",
  "agent": {
    "instructions": "<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",
  "silent": true,
  "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": {
    "data": [
      {
        "key": "<string>",
        "name": "<string>",
        "type": "<string>",
        "value": "<unknown>",
        "is_reference": true,
        "is_deadline": true
      }
    ],
    "other": [
      {
        "key": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "embed_links": [
    {
      "role": "main",
      "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "https://form.penbox.io/embed/eyJhbGciOi..."
    }
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Declare a field on a case, or change an existing one. Update Case Data writes values; a field declared here gives a value its label, its type and its flags.

The key identifies the field and never changes. To rename a field, send a new name.
A field that does not exist yet needs a type.
The call is idempotent: replaying it lands on the same field.

Deadlines

A deadline is a date field with is_deadline: true. Its name says what the deadline is (an appeal deadline, a hearing), its value says when. Only a date field can be a deadline: is_deadline on any other type is refused with a 422. Deadlines show in Get Case under schema.data, with is_deadline: true. To clear a deadline’s date and keep the deadline, write null to its value with Update Case Data. To remove the deadline itself, use Delete Case Field.

Every change sends a fields.updated change in the case.updated webhook.

curl --request PUT \
  --url https://connect.penbox.io/v1/cases/{id}/fields/delai_appel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Délai d'\''appel", "type": "date", "is_deadline": true }'

curl --request PUT \
  --url https://connect.penbox.io/v1/cases/{id}/fields/delai_appel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Délai d'\''appel (Cour)" }'

Authorizations

Authorization

string

header

required

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

Path Parameters

string<uuid>

required

Case UUID

key

string

required

Field key: letters, digits and _, up to 120 characters

Pattern: ^[a-zA-Z0-9_]{1,120}$

Body

application/json

name

string

Field label

Maximum string length: 255

Example:

"Délai d'appel"

type

enum<string>

Field type. Required when the field does not exist yet.

Available options:

text,

number,

date,

file,

checkbox,

checkboxes,

choices,

signature

is_deadline

boolean

Mark a date field as a deadline. Only a date field can be one.

Response

The case, as Get Case returns it

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

agent

object

The case agent, as far as the API exposes it.

Show child attributes

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

silent

boolean

True for a Silent case: created from a connected mailbox, not picked up by anyone yet, and kept out of the team's case views. It is picked up, for good, at the first action a person takes on it.

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

The data of the case: its declared fields with their current values, and the values written without a declared field.

Show child attributes

embed_links

object[]

One embed link per contact who has the customer portal on this case. Empty when the case runs no portal, when the contact's role has no portal, or when the case requires a verification code.

Show child attributes

API Reference

Workspaces

Cases

Webhooks

Tasks

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Deadlines

Authorizations

Path Parameters

Body

Response

​Deadlines

Authorizations

Path Parameters

Body

Response

Deadlines