> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Request

> Previous version of Create Form. Create a new request from a flow.

<Warning>
  Previous API version. Use [`POST /forms`](/api-reference/requests/create-request) for new integrations. This route still works but is deprecated.
</Warning>

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

```text theme={null}
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

```bash cURL theme={null}
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](/api-reference/previous-api-version/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                              |