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

# Forms API

> The Forms API allows you to create, read, update, and delete forms programmatically.

The Forms API allows you to create, read, update, and delete forms programmatically.

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/forms` | List all forms |
| `GET` | `/v1/forms/{id}` | Get a specific form |
| `POST` | `/v1/forms` | Create a new form |
| `PATCH` | `/v1/forms/{id}` | Update a form |
| `DELETE` | `/v1/forms/{id}` | Delete a form |
| `GET` | `/v1/forms/{id}/analytics` | Views, submissions and conversion for a form (`analytics:read`) |

## Query Parameters

Use these query parameters when listing forms:

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | Page number (default: 1) |
| `per_page` | integer | Results per page (default: 20, max: 100) |
| `status` | string | Filter by status: published, draft, or archived |

## List Forms

Returns a paginated list of all forms in your team.

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Contact Form",
      "slug": "contact-form",
      "type": "standard",
      "status": "published",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}
```

## Get Form

Returns detailed information about a specific form, including fields and settings.

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Contact Form",
    "slug": "contact-form",
    "description": "Get in touch with our team",
    "type": "standard",
    "status": "published",
    "fields": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "type": "email",
        "label": "Email Address",
        "name": "email",
        "placeholder": "you@example.com",
        "required": true,
        "position": 0
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440002",
        "type": "textarea",
        "label": "Message",
        "name": "message",
        "required": false,
        "position": 1
      }
    ],
    "settings": {
      "redirect_url": "https://example.com/thank-you",
      "default_phone_country": "FR"
    },
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}
```

## Update a Form

Send only the fields you want to change. `settings` is merged into the form's existing settings, so a request that sets one key leaves every other setting untouched. Protected keys (`password`, `notifications`, `email_verification`, `security`, `custom_js`, `custom_html`, `thank_you_custom_html`) are ignored by the public API and can only be changed in the dashboard.

```bash theme={null}
curl -X PATCH https://app.useorbitcrm.ai/api/v1/forms/{id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "default_phone_country": "FR"
    }
  }'
```

| Field | Type | Description |
| - | - | - |
| `title` | string | Form title (max 200 characters) |
| `description` | string | Form description (max 1000 characters) |
| `status` | string | draft, published, or archived |
| `settings` | object | Form settings, merged with the existing settings (see below) |

The same `settings` keys are accepted when creating a form with `POST /v1/forms`.

### Form Settings

| Key | Type | Description |
| - | - | - |
| `redirect_url` | string | URL respondents are sent to after submitting |
| `thank_you_message` | string | Heading shown on the thank-you page |
| `default_phone_country` | string | ISO 3166-1 alpha-2 country code (e.g. `FR`, `US`) every phone field on the form starts on. Respondents can still pick another country. Omit or set to `null` to detect the country from the visitor's location. Anything other than a two-letter code is rejected with `400 invalid_request`. |

> [!TIP]
>
> **Regional forms:** if you run one form per market, set `default_phone_country` on each so the phone field opens on the right dialing code (`FR` for +33, `US` for +1) no matter where the visitor is browsing from. The same setting is available in the form editor under **Settings → Phone Fields → Default country code**.

## Form Analytics

`GET /v1/forms/{id}/analytics?days=30`

`days` covers today and the days before it (1 to 90, default 30), in UTC. `period` counts are live; `daily` and `breakdown` come from nightly rollups, so they end with yesterday and skip days without views.

```json theme={null}
{
  "data": {
    "form_id": "550e8400-e29b-41d4-a716-446655440000",
    "all_time": { "views": 4210, "submissions": 388 },
    "period": {
      "days": 30,
      "since": "2026-09-28T00:00:00.000Z",
      "views": 1250,
      "completed_submissions": 117,
      "partial_submissions": 4,
      "conversion_rate": 0.0936
    },
    "daily": [
      { "date": "2026-10-26", "views": 52, "unique_views": 47, "submissions": 5, "completed_submissions": 5 }
    ],
    "breakdown": {
      "by_source": { "google": 610, "linkedin": 190 },
      "by_device": { "desktop": 820, "mobile": 400 },
      "by_country": { "US": 900, "GB": 120 }
    }
  }
}
```

`conversion_rate` is completed submissions divided by views for the period, or `null` when there were no views.

[Next: Submissions API](https://docs.useorbitcrm.ai/developers/api/submissions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.