Skip to main content
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

FieldTypeDescription
flow.slugstringFlow (form template) identifier

​
Optional

FieldTypeDescription
company.slugstringWorkspace identifier (if multiple authorized)
user.emailstringContact email address
user.phonestringContact phone number
user.given_namestringContact first name
user.family_namestringContact last name
user.localestringContact language (e.g. en, fr)
dataobjectPre-filled data (keys must match field keys)
optionsobjectRequest-specific options
external_argsobjectYour custom metadata
redirect_urlstringHTTPS URL to redirect after completion
draftbooleanCreate as draft (default: false)
active_fromstringISO 8601 date when the request becomes active
active_untilstringISO 8601 date when the request expires
owner.emailstringRequest owner email (or null)
branding.slugstringBranding profile slug
webhooksobjectMap 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

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