> ## 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.
# Update Case Task
> Close, reopen, or reassign a follow-up task
Update a task of a case. Send `status` to close or reopen it, `due_at` to move its
deadline, `assignee` to hand it to someone else. At least one field is required.
## Statuses
| Key | Meaning |
| ------------- | ----------------------- |
| `open` | not started |
| `in_progress` | being worked on |
| `done` | finished |
| `dismissed` | closed without doing it |
`done` and `dismissed` both close the task and stamp `completed_at`. Setting `open`
or `in_progress` on a closed task reopens it and clears `completed_at`.
This works on any **team-side** task of the case, including the ones Penbox created
itself — so your integration can close a Penbox follow-up once your side has done
the work.
Tasks assigned to a **contact** are read-only through the API: they close when the
contact submits the form Penbox sent them. Updating one returns `403`, and so does
moving a team-side task onto a contact.
There is no delete. Removing a task stays a manual action inside Penbox. Use
`dismissed` for "this no longer needs doing".
The task must belong to the case in the path. A task id from another case returns
a `404`.
```bash Close it theme={null}
curl --request PATCH \
--url https://connect.penbox.io/v1/cases/{id}/tasks/{taskId} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "status": "done" }'
```
```bash Reassign theme={null}
curl --request PATCH \
--url https://connect.penbox.io/v1/cases/{id}/tasks/{taskId} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "assignee": { "email": "karel@firm.example" } }'
```
```bash Unassign theme={null}
curl --request PATCH \
--url https://connect.penbox.io/v1/cases/{id}/tasks/{taskId} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "assignee": null }'
```
```json 200 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": "done",
"due_at": "2026-09-04T00:00:00.000Z",
"completed_at": "2026-09-02T14:31:00.000Z",
"step_key": null,
"assignee": {
"kind": "member",
"id": "5f7e2c17-e9be-47c9-8049-0b35d8eb0ada",
"email": "amina@firm.example",
"given_name": "Amina",
"family_name": "Berger"
}
}
```
```json 404 theme={null}
{
"statusCode": 404,
"error": "Not Found",
"message": "Task with ID \"2c7e2ddd-ece1-4c38-9c2d-47aaaf50be97\" not found on this case"
}
```
## OpenAPI
````yaml PATCH /cases/{id}/tasks/{taskId}
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/{taskId}:
parameters:
- name: id
in: path
required: true
description: Case UUID
schema:
type: string
format: uuid
- name: taskId
in: path
required: true
description: Task UUID
schema:
type: string
format: uuid
patch:
summary: Update Case Task
description: >-
Update a task of a case: close it, reopen it, change its due date or its
assignee. At least one field is required. Tasks cannot be deleted
through the API — removing a task stays a manual action in Penbox.
operationId: update-case-task
requestBody:
required: true
content:
application/json:
schema:
type: object
minProperties: 1
properties:
status:
type: string
enum:
- open
- in_progress
- done
- dismissed
description: The task status. `done` and `dismissed` both close it.
example: done
due_at:
type: string
format: date-time
nullable: true
description: New due date, or `null` to clear it.
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:
'200':
description: Task updated
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'400':
description: Invalid body or unknown assignee email
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such task on this case
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}
````