Skip to main content
POST
Add a task to a case. Use it to put your own follow-ups next to the ones Penbox creates, so the team sees a single to-do list. The task lands on the team side: assign it to a workspace member by email, or leave it unassigned. Assign by email and Penbox resolves the member for you — including members you registered through Create Member, who never receive Penbox emails.
You cannot create a task on the client side, nor move one there later. Those are created by Penbox when it sends a form, and they close when the client submits it — a client-side task you created would have no way to ever be closed.
The case and the assignee must both belong to a workspace your key covers. Referencing either from another workspace returns 403.
type is set to manual for every task you create. It is not a field you send: Penbox reserves its own keys (fill_form, review, follow_up) for the tasks it manages itself, and closes those automatically as the case moves.

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

id
string<uuid>
required

Case UUID

Body

application/json
title
string
required

What has to be done. Shown as-is in Penbox.

Maximum string length: 255
Example:

"Call the client back"

description
string

Optional detail.

Maximum string length: 2000
due_at
string<date-time>

Optional due date, ISO 8601.

assignee
object | null

The workspace member the task is assigned to, resolved by email. Silent members resolve too. Pass null to leave the task unassigned.

Response

Task created

id
string<uuid>

Task UUID

created_at
string<date-time>

When the task was created

case
object

The case this task belongs to

type
string

The kind of task. manual for every task created through the API. Tasks Penbox creates by itself carry their own key, such as fill_form, review or follow_up.

Example:

"manual"

title
string | null

What has to be done. Empty on some Penbox-created tasks, which Penbox labels from their type in the reader language.

description
string | null

Optional detail

status
enum<string>

Current task status

Available options:
open,
in_progress,
done,
dismissed
due_at
string<date-time> | null

Due date

completed_at
string<date-time> | null

When the task was closed

step_key
string | null

The case step that spawned the task, when Penbox created it

assignee
object | null

Who has to close the task. null when unassigned.