> ## 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.
# List Forms
> Retrieve a paginated list of forms with optional filtering and sorting. By default, only non-archived forms are returned.
Retrieve a list of forms matching specific criteria. Use filters to narrow down results.
## Query Parameters
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------- |
| `filter` | string | JSON-encoded filter object |
| `page[number]` | number | Page number (starts at 1) |
| `page[size]` | number | Results per page (default: 10, max: 100) |
## Filter Options
You can filter forms using a JSON-encoded filter object. The Connect API supports filtering by workspace, template, user, status, and custom metadata.
**Quick Example:**
```json theme={null}
{
"flow": { "slug": "client-onboarding" },
"active": true,
"completed": false
}
```
**Available Filters:**
* **Workspace** (workspace slug)
* **Form Template** (form template slug)
* **User** (email, name, phone, internal\_ref, company\_name)
* **Owner** (email)
* **Status** (active, archived, completed, processed)
* **External args** (your custom metadata)
See the complete filtering documentation with examples and use cases
## Response Codes
| Code | Description |
| ----- | --------------------------------------------------- |
| `200` | Success - Returns list of forms |
| `400` | Bad Request - Invalid filter parameters |
| `401` | Unauthorized - Invalid or expired access token |
| `403` | Forbidden - Token doesn't have required permissions |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error |
Use `page[number]` and `page[size]` for pagination when working with large datasets. The maximum page size is 100 forms per request.
## OpenAPI
````yaml GET /forms
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:
/forms:
get:
summary: List Forms
description: >-
Retrieve a paginated list of forms with optional filtering and sorting.
By default, only non-archived forms are returned.
operationId: list-forms
parameters:
- $ref: '#/components/parameters/FormWorkspaceSlug'
- $ref: '#/components/parameters/FormFlowSlug'
- $ref: '#/components/parameters/FormFlowCustomization'
- $ref: '#/components/parameters/OwnerEmail'
- $ref: '#/components/parameters/FormUserGivenName'
- $ref: '#/components/parameters/FormUserFamilyName'
- $ref: '#/components/parameters/FormUserEmail'
- $ref: '#/components/parameters/FormUserPhone'
- $ref: '#/components/parameters/Archived'
- $ref: '#/components/parameters/FormActive'
- $ref: '#/components/parameters/FormCompleted'
- $ref: '#/components/parameters/FormProcessed'
- $ref: '#/components/parameters/AdvancedFilter'
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Sort'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
meta:
type: object
properties:
total_count:
type: integer
description: Total number of forms
total_pages:
type: integer
description: Total number of pages
page_size:
type: integer
description: Number of items per page
current_page:
type: integer
description: Current page number
data:
type: array
items:
$ref: '#/components/schemas/Form'
components:
parameters:
FormWorkspaceSlug:
name: workspace[slug]
in: query
description: Filter by workspace slug
schema:
type: string
FormFlowSlug:
name: flow[slug]
in: query
description: Filter by flow slug (single value or array)
schema:
oneOf:
- type: string
- type: array
items:
type: string
FormFlowCustomization:
name: flow[customization]
in: query
description: Filter by flow customization UUID
schema:
type: string
format: uuid
OwnerEmail:
name: owner[email]
in: query
description: Filter by owner email
schema:
type: string
format: email
FormUserGivenName:
name: user[given_name]
in: query
description: Filter by user first name
schema:
type: string
FormUserFamilyName:
name: user[family_name]
in: query
description: Filter by user last name
schema:
type: string
FormUserEmail:
name: user[email]
in: query
description: Filter by user email
schema:
type: string
format: email
FormUserPhone:
name: user[phone]
in: query
description: Filter by user phone number
schema:
type: string
Archived:
name: archived
in: query
description: Filter by archived status
schema:
type: boolean
default: false
FormActive:
name: active
in: query
description: Filter by active status
schema:
type: boolean
FormCompleted:
name: completed
in: query
description: Filter by completed status
schema:
type: boolean
FormProcessed:
name: processed
in: query
description: Filter by processed status
schema:
type: boolean
AdvancedFilter:
name: filter
in: query
description: >-
Filter using advanced JSON syntax. If specified, will ignore all other
filter parameters. See the [Advanced
Filters](/api-reference/advanced-filters) guide for more information.
schema:
type: string
PageNumber:
name: page[number]
in: query
description: Page number (starts at 1)
schema:
type: integer
default: 1
minimum: 1
PageSize:
name: page[size]
in: query
description: 'Number of items per page (max: 100)'
schema:
type: integer
default: 10
maximum: 100
minimum: 1
Sort:
name: sort
in: query
description: Sort field (prefix with - for descending)
schema:
type: string
default: '-created_at'
schemas:
Form:
type: object
properties:
id:
type: string
format: uuid
description: Form UUID
created_at:
type: string
format: date-time
description: Creation timestamp
status:
type: string
enum:
- draft
- pending
- completed
- declined
- processed
description: Current form status
archived:
type: boolean
description: Whether the form is archived
archived_at:
type: string
format: date-time
nullable: true
description: Timestamp when archived
processed_at:
type: string
format: date-time
nullable: true
description: Timestamp when marked as processed
active_from:
type: string
format: date-time
nullable: true
description: When the form becomes active
active_until:
type: string
format: date-time
nullable: true
description: When the form expires
links:
type: object
properties:
fill:
type: string
format: uri
description: Public form link for the contact
app:
type: string
format: uri
description: Internal app link to view the form
description: URLs for accessing the form
user:
type: object
properties:
anonymous:
type: boolean
email:
type: string
phone:
type: string
given_name:
type: string
family_name:
type: string
company_name:
type: string
internal_ref:
type: string
description: Contact information
owner:
type: object
nullable: true
properties:
id:
type: string
format: uuid
email:
type: string
description: Form owner information
flow:
type: object
properties:
slug:
type: string
description: Form template slug identifier
description: Form template information
data:
type: object
description: Pre-filled form data
external_args:
type: object
nullable: true
description: Custom metadata
options:
type: object
nullable: true
description: Form-specific options
responses:
type: array
items:
$ref: '#/components/schemas/ResponseFlat'
description: Array of form responses
notifications:
type: array
items:
$ref: '#/components/schemas/Notification'
description: Array of notifications sent for this form
webhooks:
type: object
nullable: true
description: Webhook URLs with event subscriptions
additionalProperties:
type: array
items:
type: string
ResponseFlat:
type: object
properties:
id:
type: string
format: uuid
description: Response UUID
completed_at:
type: string
format: date-time
nullable: true
description: Timestamp when the response was completed
updated_at:
type: string
format: date-time
description: Last update timestamp
data:
type: object
description: Form field values
user:
type: object
properties:
anonymous:
type: boolean
ip:
type: string
email:
type: string
phone:
type: string
locale:
type: string
given_name:
type: string
family_name:
type: string
user-agent:
type: string
accept-language:
type: string
description: User information
attachments:
type: array
items:
$ref: '#/components/schemas/AttachmentFlat'
description: Uploaded files
signatures:
type: object
description: Signature data
files:
type: object
description: Organized files by category
Notification:
type: object
properties:
id:
type: string
format: uuid
description: Unique notification identifier
status:
type: string
enum:
- pending
- sent
- failed
- skipped
description: Current status of the notification
method:
type: string
enum:
- sms
- email
description: Delivery method
at:
type: string
format: date-time
description: Timestamp when the notification was sent
to:
type: string
nullable: true
description: Recipient address (email or phone number)
from:
type: string
nullable: true
description: Sender address
cc:
type: string
nullable: true
description: Carbon copy recipient
bcc:
type: string
nullable: true
description: Blind carbon copy recipient
system:
type: boolean
description: Whether this is a system notification
locale:
type: string
description: Language/locale code (e.g., 'fr', 'en')
template:
type: string
nullable: true
description: Template name used for the notification
variables:
type: object
nullable: true
description: Template variables used in the message
active:
type: boolean
description: Whether the notification is active
error:
type: string
nullable: true
description: Error message if notification failed
message_id:
type: string
nullable: true
description: External message identifier from delivery provider
attachments:
type: object
nullable: true
description: Attached files
deleted_at:
type: string
format: date-time
nullable: true
description: Timestamp when the notification was deleted
required:
- id
- status
- method
- at
AttachmentFlat:
type: object
properties:
id:
type: string
format: uuid
description: Attachment UUID
name:
type: string
description: Original filename
type:
type: string
description: MIME type
scope:
type: string
nullable: true
description: Attachment scope
data:
type: string
nullable: true
description: Base64-encoded file content
metadata:
type: object
properties:
size:
type: integer
description: File size in bytes
width:
type: integer
nullable: true
height:
type: integer
nullable: true
uri:
type: string
format: uri
description: Direct download URL
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}
````