> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Case Task
> Add a follow-up task to a case
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](/api-reference/members/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.
```bash Assigned theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id}/tasks \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"title": "Call the client back",
"description": "The client asked for a callback before Friday.",
"due_at": "2026-09-04T00:00:00.000Z",
"assignee": { "email": "amina@firm.example" }
}'
```
```bash Unassigned theme={null}
curl --request POST \
--url https://connect.penbox.io/v1/cases/{id}/tasks \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "title": "Check the policy number" }'
```
```json 201 theme={null}
{
"id": "2c7e2ddd-ece1-4c38-9c2d-47aaaf50be97",
"created_at": "2026-08-31T10:12:04.100Z",
"case": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
"type": "manual",
"title": "Call the client back",
"description": "The client asked for a callback before Friday.",
"status": "open",
"due_at": "2026-09-04T00:00:00.000Z",
"completed_at": null,
"step_key": null,
"assignee": {
"kind": "member",
"id": "5f7e2c17-e9be-47c9-8049-0b35d8eb0ada",
"email": "amina@firm.example",
"given_name": "Amina",
"family_name": "Berger"
}
}
```
```json 400 theme={null}
{
"statusCode": 400,
"error": "Bad Request",
"message": "Assignee with email \"nobody@firm.example\" not found in workspace"
}
```
## OpenAPI
````yaml POST /cases/{id}/tasks
openapi: 3.0.0
info:
title: Penbox API
version: '1.0'
description: >-
The Penbox API provides programmatic access to Penbox's form management,
case management, and document processing capabilities. Authenticate using
Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
- url: https://connect.penbox.io/v1
description: Production
- url: https://connect.aiboov.com/v1
description: Staging
security:
- BearerAuth: []
paths:
/cases/{id}/tasks:
parameters:
- name: id
in: path
required: true
description: Case UUID
schema:
type: string
format: uuid
post:
summary: Create Case Task
description: >-
Create a task on a case. The task lands on the team side: it is either
assigned to a workspace member or left unassigned. Contact-side tasks
are created by Penbox itself when a form step moves and cannot be
created through the API.
operationId: create-case-task
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- title
properties:
title:
type: string
maxLength: 255
description: What has to be done. Shown as-is in Penbox.
example: Call the client back
description:
type: string
maxLength: 2000
description: Optional detail.
due_at:
type: string
format: date-time
description: Optional due date, ISO 8601.
assignee:
type: object
nullable: true
description: >-
The workspace member the task is assigned to, resolved by
email. Silent members resolve too. Pass `null` to leave the
task unassigned.
required:
- email
properties:
email:
type: string
format: email
example: amina@firm.example
responses:
'201':
description: Task created
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'400':
description: Invalid body, unknown assignee email, or the case is a template
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Case not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Task:
type: object
properties:
id:
type: string
format: uuid
description: Task UUID
created_at:
type: string
format: date-time
description: When the task was created
case:
type: object
description: The case this task belongs to
properties:
id:
type: string
format: uuid
type:
type: string
description: >-
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:
type: string
nullable: true
description: >-
What has to be done. Empty on some Penbox-created tasks, which
Penbox labels from their `type` in the reader language.
description:
type: string
nullable: true
description: Optional detail
status:
type: string
enum:
- open
- in_progress
- done
- dismissed
description: Current task status
due_at:
type: string
format: date-time
nullable: true
description: Due date
completed_at:
type: string
format: date-time
nullable: true
description: When the task was closed
step_key:
type: string
nullable: true
description: The case step that spawned the task, when Penbox created it
assignee:
type: object
nullable: true
description: Who has to close the task. `null` when unassigned.
properties:
kind:
type: string
enum:
- member
- contact
description: '`member` for someone on the team, `contact` for the client'
id:
type: string
format: uuid
email:
type: string
nullable: true
given_name:
type: string
nullable: true
family_name:
type: string
nullable: true
Error:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
title:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: token
description: >-
API token (starts with pnbx_). Create at
https://app.penbox.io/workspace/settings/api. Include as: Authorization:
Bearer {token}
````