Create Request

Previous API version. Use POST /forms for new integrations. This route still works but is deprecated.

Create a new request (now called a form) from a flow (form template).

POST https://connect.penbox.io/v1/requests

Request Body

Required

Field	Type	Description
`flow.slug`	string	Flow (form template) identifier

Optional

Field	Type	Description
`company.slug`	string	Workspace identifier (if multiple authorized)
`user.email`	string	Contact email address
`user.phone`	string	Contact phone number
`user.given_name`	string	Contact first name
`user.family_name`	string	Contact last name
`user.locale`	string	Contact language (e.g. `en`, `fr`)
`data`	object	Pre-filled data (keys must match field keys)
`options`	object	Request-specific options
`external_args`	object	Your custom metadata
`redirect_url`	string	HTTPS URL to redirect after completion
`draft`	boolean	Create as draft (default: `false`)
`active_from`	string	ISO 8601 date when the request becomes active
`active_until`	string	ISO 8601 date when the request expires
`owner.email`	string	Request owner email (or `null`)
`branding.slug`	string	Branding profile slug
`webhooks`	object	Map of HTTPS URL → array of subscribed events

Supported webhook events: requests:created, requests:updated, requests:deleted, requests:archived, requests:unarchived, responses:created, responses:updated, responses:deleted, responses:completed.

Example

cURL

curl -X POST 'https://connect.penbox.io/v1/requests' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": { "slug": "client-onboarding" },
    "user": { "email": "client@example.com", "given_name": "John", "family_name": "Doe" },
    "data": { "company_name": "Acme Corporation" },
    "external_args": { "crm_id": "12345" }
  }'

Response

Returns the created request object (same shape as Get Request).

Response Codes

Code	Description
`201`	Created
`400`	Bad Request — invalid parameters
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found — flow not enabled for the user
`409`	Conflict — more than one flow matches
`422`	Unprocessable — validation failed
`429`	Too Many Requests
`500`	Server Error

API Reference

Workspaces

Cases

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Request Body

Required

Optional

Example

Response

Response Codes

​Request Body

​Required

​Optional

​Example

​Response

​Response Codes

Request Body

Required

Optional

Example

Response

Response Codes