Forms API

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.

{
  "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.

{
  "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.

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`.

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.

{
  "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

Getting Started

API Reference

Webhooks

SDKs & Tools

Developer Resources

Endpoints

Query Parameters

List Forms

Get Form

Update a Form

Form Settings

Form Analytics

​Endpoints

​Query Parameters

​List Forms

​Get Form

​Update a Form

​Form Settings

​Form Analytics

Endpoints

Query Parameters

List Forms

Get Form

Update a Form

Form Settings

Form Analytics