Skip to main content
GET
/
forms
List Forms
curl --request GET \
  --url https://connect.penbox.io/v1/forms \
  --header 'Authorization: Bearer <token>'
{
  "meta": {
    "total_count": 123,
    "total_pages": 123,
    "page_size": 123,
    "current_page": 123
  },
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_at": "2023-11-07T05:31:56Z",
      "status": "draft",
      "archived": true,
      "archived_at": "2023-11-07T05:31:56Z",
      "processed_at": "2023-11-07T05:31:56Z",
      "active_from": "2023-11-07T05:31:56Z",
      "active_until": "2023-11-07T05:31:56Z",
      "links": {
        "fill": "<string>",
        "app": "<string>"
      },
      "user": {
        "anonymous": true,
        "email": "<string>",
        "phone": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "company_name": "<string>",
        "internal_ref": "<string>"
      },
      "owner": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "email": "<string>"
      },
      "flow": {
        "slug": "<string>"
      },
      "data": {},
      "external_args": {},
      "options": {},
      "responses": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "completed_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "data": {},
          "user": {
            "anonymous": true,
            "ip": "<string>",
            "email": "<string>",
            "phone": "<string>",
            "locale": "<string>",
            "given_name": "<string>",
            "family_name": "<string>",
            "user-agent": "<string>",
            "accept-language": "<string>"
          },
          "attachments": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "name": "<string>",
              "type": "<string>",
              "scope": "<string>",
              "data": "<string>",
              "metadata": {
                "size": 123,
                "width": 123,
                "height": 123
              },
              "uri": "<string>"
            }
          ],
          "signatures": {},
          "files": {}
        }
      ],
      "notifications": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "status": "pending",
          "method": "sms",
          "at": "2023-11-07T05:31:56Z",
          "to": "<string>",
          "from": "<string>",
          "cc": "<string>",
          "bcc": "<string>",
          "system": true,
          "locale": "<string>",
          "template": "<string>",
          "variables": {},
          "active": true,
          "error": "<string>",
          "message_id": "<string>",
          "attachments": {},
          "deleted_at": "2023-11-07T05:31:56Z"
        }
      ],
      "webhooks": {}
    }
  ]
}
Retrieve a list of forms matching specific criteria. Use filters to narrow down results.

​
Query Parameters

ParameterTypeDescription
filterstringJSON-encoded filter object
page[number]numberPage number (starts at 1)
page[size]numberResults 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: 
{
  "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)

Advanced Filters Guide

See the complete filtering documentation with examples and use cases

​
Response Codes

CodeDescription
200Success - Returns list of forms
400Bad Request - Invalid filter parameters
401Unauthorized - Invalid or expired access token
403Forbidden - Token doesn’t have required permissions
429Too Many Requests - Rate limit exceeded
500Server 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.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
workspace[slug]
string

Filter by workspace slug

​
flow[slug]

Filter by flow slug (single value or array)

​
flow[customization]
string<uuid>

Filter by flow customization UUID

​
owner[email]
string<email>

Filter by owner email

​
user[given_name]
string

Filter by user first name

​
user[family_name]
string

Filter by user last name

​
user[email]
string<email>

Filter by user email

​
user[phone]
string

Filter by user phone number

​
archived
boolean
default:false

Filter by archived status

​
active
boolean

Filter by active status

​
completed
boolean

Filter by completed status

​
processed
boolean

Filter by processed status

​
filter
string

Filter using advanced JSON syntax. If specified, will ignore all other filter parameters. See the Advanced Filters guide for more information.

​
page[number]
integer
default:1

Page number (starts at 1)

Required range: x >= 1
​
page[size]
integer
default:10

Number of items per page (max: 100)

Required range: 1 <= x <= 100
​
sort
string
default:-created_at

Sort field (prefix with - for descending)

Response

200 - application/json

Successful response

​
meta
object
​
data
object[]