Skip to main content
GET
/
requests
curl -X GET 'https://connect.penbox.io/v1/requests?filter={"active":true}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

[
  {
    "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>"
    },
    "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",
        "declined_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>",
            "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"
      }
    ]
  }
]
Retrieve a list of forms (API: requests) matching specific criteria. Use filters to narrow down results.
In the API, forms are referred to as requests. This is the technical term used in all endpoints and parameters.
curl -X GET 'https://connect.penbox.io/v1/requests?filter={"active":true}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Query Parameters

ParameterTypeDescription
filterstringJSON-encoded filter object
page[offset]numberPagination offset
page[limit]numberResults per page (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 (company slug)
  • Form Template (flow 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[limit] and page[offset] for pagination when working with large datasets. The maximum limit is 100 forms per request.

Authorizations

​
Authorization
string
header
required

OAuth2 access token. Include as: Authorization: Bearer {access_token}

Query Parameters

​
filter
string

JSON-encoded filter object (e.g., {"flow":{"slug":"hello-world"}, "user":{"email":"[email protected]"}})

​
page[offset]
integer

Pagination offset

​
page[limit]
integer

Results per page (max 100)

Required range: x <= 100

Response

200 - application/json

Successful response

​
id
string<uuid>

Request UUID

​
created_at
string<date-time>

Creation timestamp

​
status
enum<string>

Current request status

Available options:
draft,
pending,
completed,
declined,
processed
​
archived
boolean

Whether the request is archived

​
archived_at
string<date-time> | null

Timestamp when archived

​
processed_at
string<date-time> | null

Timestamp when marked as processed

​
active_from
string<date-time> | null

When the form becomes active

​
active_until
string<date-time> | null

When the form expires

​
links
object

URLs for accessing the request

​
user
object

Contact information

​
owner
object

Request owner information

​
flow
object

Form template information

​
data
object

Pre-filled form data

​
external_args
object

Custom metadata

​
options
object

Form-specific options

​
responses
object[]

Array of form responses

​
notifications
object[]

Array of notifications sent for this request