# Create a form

**Publié le** : 2026-05-08
**Catégorie** : Forms & Reviews

## `POST /forms`

**Create a form**

Creates a new form with a schema defining its fields. The schema
is a JSON array of field definitions with types, labels, validation
rules, and conditional logic.

Required permissions: `forms.create`

### Request Body

Content-Type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Required. Display name. 1-255 characters |
| `slug` | string | Yes | Required. URL-friendly identifier, unique per site and locale. 1-255 characters |
| `description` | string | No | Description text. Max 1000 characters |
| `schema` | object | Yes | Required. Field schema definition |
| `settings` | object | No | Configuration settings |
| `notifications` | object | No | Notification preferences |
| `honeypotEnabled` | boolean | No | Boolean |
| `recaptchaEnabled` | boolean | No | Boolean |
| `recaptchaSiteKey` | string | No | Max 255 characters |
| `recaptchaSecretKey` | string | No | Max 255 characters |
| `status` | "draft" \| "active" \| "closed" \| "archived" | No | One of: draft, active, closed, archived |
| `locale` | string | No | BCP 47 locale code (e.g. "en", "fr") |


### Responses

| Status | Description |
| --- | --- |
| `201` | Successful response |
| `401` | Unauthorized — invalid or missing API token |
| `403` | Forbidden — insufficient permissions |
| `422` | Validation error |


> **Notes:** - Forms are created in `draft` status by default.
> 
> - Set `status` to `"active"` to start accepting submissions immediately.

### Examples

```bash
curl -X POST https://api.lynkow.com/v1/forms \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "slug": "contact-form",
    "status": "active",
    "schema": [
      {"name": "name", "type": "text", "label": "Full Name", "required": true},
      {"name": "email", "type": "email", "label": "Email", "required": true},
      {"name": "message", "type": "textarea", "label": "Message", "required": true}
    ],
    "successMessage": "Thank you for reaching out!"
  }'
```

### Response Example

```json
{
  "data": {
    "id": 3,
    "name": "Contact Form",
    "slug": "contact-form",
    "status": "active",
    "locale": "en",
    "submissionCount": 0,
    "schema": [
      {
        "name": "name",
        "type": "text",
        "label": "Full Name",
        "required": true
      },
      {
        "name": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "name": "message",
        "type": "textarea",
        "label": "Message",
        "required": true
      }
    ],
    "successMessage": "Thank you for reaching out!",
    "redirectUrl": null,
    "createdAt": "2025-04-06T11:00:00.000Z",
    "updatedAt": "2025-04-06T11:00:00.000Z"
  }
}
```

---