Skip to main content
PATCH
/
requests
/
{id}
curl -X PATCH 'https://connect.penbox.io/v1/requests/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"archived": true}'

{
  "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"
    }
  ]
}
Update a form’s (API: request) status or properties.
In the API, forms are referred to as requests. This is the technical term used in all endpoints and parameters.
curl -X PATCH 'https://connect.penbox.io/v1/requests/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"archived": true}'

​
Updatable Fields

FieldTypeDescription
archivedbooleanArchive or unarchive the form
draftbooleanSet draft status (true = draft, false = activate)
processedbooleanMark as processed or unprocessed
active_untilstringUpdate expiration date (ISO 8601)

​
Common Use Cases

​
Archive a Form

Archive completed or cancelled forms to keep your list organized: 
await fetch(`https://connect.penbox.io/v1/requests/${requestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ archived: true })
});

​
Mark as Processed

Track which forms you’ve reviewed in your system: 
await fetch(`https://connect.penbox.io/v1/requests/${requestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ processed: true })
});

​
Activate a Draft

Activate a draft form to send it to the contact: 
await fetch(`https://connect.penbox.io/v1/requests/${requestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ draft: false })
});

​
Response Codes

CodeDescription
200Success - Form updated successfully
400Bad Request - Invalid parameters
401Unauthorized - Invalid access token
403Forbidden - No access to this resource
404Not Found - Form doesn’t exist
422Unprocessable - Validation failed
429Too Many Requests - Rate limit exceeded
500Server Error - Internal error
You can only update certain fields. To modify form data or user information, you’ll need to create a new form.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

Request UUID

Body

application/json
​
archived
boolean

Archive or unarchive the request

​
draft
boolean

Set draft status

​
processed
boolean

Mark as processed or unprocessed

Response

200 - application/json

Request updated successfully

​
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