Forms API | BttrForm

The Forms API lets you create, retrieve, update, and delete forms programmatically. This is useful for building custom form management workflows, syncing forms with external systems, or automating form creation at scale.

All endpoints require authentication via the X-API-Key header. See the Authentication guide for details.

Base URL

https://api.bttrlabs.com/v1

Endpoints Overview

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 an existing form
`DELETE`	`/v1/forms/:id`	Delete a form

List All Forms

Retrieves a paginated list of all forms in your account. Forms are returned in reverse chronological order (newest first).

Request

curl -X GET "https://api.bttrlabs.com/v1/forms?limit=10" \
  -H "X-API-Key: bttrform_sk_live_your_key_here"

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of forms to return (1-100)
`cursor`	string	—	Cursor for pagination (from `next_cursor` in response)
`status`	string	—	Filter by status: `draft`, `published`, `archived`
`search`	string	—	Search forms by title

Response (200 OK)

{
  "data": [
    {
      "id": "frm_a1b2c3d4e5f6",
      "title": "Customer Feedback Survey",
      "description": "Help us improve our product",
      "status": "published",
      "fields_count": 8,
      "responses_count": 342,
      "created_at": "2026-01-15T09:30:00Z",
      "updated_at": "2026-02-01T14:22:00Z",
      "published_at": "2026-01-16T10:00:00Z",
      "share_url": "https://forms.bttrlabs.com/f/frm_a1b2c3d4e5f6"
    },
    {
      "id": "frm_g7h8i9j0k1l2",
      "title": "Event Registration",
      "description": "Register for our annual conference",
      "status": "draft",
      "fields_count": 12,
      "responses_count": 0,
      "created_at": "2026-02-05T16:45:00Z",
      "updated_at": "2026-02-05T16:45:00Z",
      "published_at": null,
      "share_url": null
    }
  ],
  "pagination": {
    "total": 47,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImZybV9nN2g4aTlqMGsxbDIifQ=="
  }
}

Pagination

The Forms API uses cursor-based pagination for efficient traversal of large result sets. To fetch the next page, pass the next_cursor value from the response as the cursor query parameter:

curl -X GET "https://api.bttrlabs.com/v1/forms?limit=20&cursor=eyJpZCI6ImZybV9nN2g4aTlqMGsxbDIifQ==" \
  -H "X-API-Key: bttrform_sk_live_your_key_here"

When has_more is false, you have reached the last page and next_cursor will be null.

Why Cursor-Based Pagination?

Cursor-based pagination is more reliable than offset-based pagination when data changes frequently. New forms being created or deleted between page requests will not cause duplicates or missing results.

Get a Form

Retrieves the full details of a specific form, including its complete field schema.

Request

curl -X GET "https://api.bttrlabs.com/v1/forms/frm_a1b2c3d4e5f6" \
  -H "X-API-Key: bttrform_sk_live_your_key_here"

Response (200 OK)

{
  "data": {
    "id": "frm_a1b2c3d4e5f6",
    "title": "Customer Feedback Survey",
    "description": "Help us improve our product",
    "status": "published",
    "fields": [
      {
        "id": "fld_001",
        "type": "text",
        "label": "Full Name",
        "required": true,
        "placeholder": "Enter your name"
      },
      {
        "id": "fld_002",
        "type": "email",
        "label": "Email Address",
        "required": true,
        "placeholder": "you@example.com"
      },
      {
        "id": "fld_003",
        "type": "rating",
        "label": "How would you rate our product?",
        "required": true,
        "min": 1,
        "max": 5
      },
      {
        "id": "fld_004",
        "type": "textarea",
        "label": "Any additional feedback?",
        "required": false,
        "placeholder": "Tell us more...",
        "max_length": 2000
      }
    ],
    "settings": {
      "submit_button_text": "Send Feedback",
      "success_message": "Thank you for your feedback!",
      "notifications_enabled": true,
      "close_date": null
    },
    "responses_count": 342,
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-02-01T14:22:00Z",
    "published_at": "2026-01-16T10:00:00Z",
    "share_url": "https://forms.bttrlabs.com/f/frm_a1b2c3d4e5f6"
  }
}

Error (404 Not Found)

{
  "error": "not_found",
  "message": "Form not found. Check the form ID and ensure it belongs to your account."
}

Create a Form

Creates a new form. The form is created in draft status by default. You must explicitly publish it to start collecting responses.

Request

curl -X POST "https://api.bttrlabs.com/v1/forms" \
  -H "X-API-Key: bttrform_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contact Us",
    "description": "Get in touch with our team",
    "fields": [
      {
        "type": "text",
        "label": "Your Name",
        "required": true
      },
      {
        "type": "email",
        "label": "Email Address",
        "required": true
      },
      {
        "type": "textarea",
        "label": "Message",
        "required": true,
        "max_length": 5000
      }
    ],
    "settings": {
      "submit_button_text": "Send Message",
      "success_message": "We will get back to you within 24 hours."
    }
  }'

Request Body

Field	Type	Required	Description
`title`	string	Yes	Form title (max 200 characters)
`description`	string	No	Form description (max 1000 characters)
`fields`	array	Yes	Array of field objects (at least 1 field)
`settings`	object	No	Form configuration settings

Field Types

The following field types are supported:

Type	Description	Additional Properties
`text`	Single-line text input	`placeholder`, `max_length`
`textarea`	Multi-line text input	`placeholder`, `max_length`
`email`	Email address input	`placeholder`
`phone`	Phone number input	`placeholder`, `country_code`
`number`	Numeric input	`min`, `max`, `step`
`select`	Dropdown selection	`options` (array of strings)
`radio`	Radio button group	`options` (array of strings)
`checkbox`	Checkbox group	`options` (array of strings)
`rating`	Star or numeric rating	`min`, `max`
`date`	Date picker	`min_date`, `max_date`
`file`	File upload	`allowed_types`, `max_size_mb`

Response (201 Created)

{
  "data": {
    "id": "frm_m3n4o5p6q7r8",
    "title": "Contact Us",
    "status": "draft",
    "fields_count": 3,
    "created_at": "2026-02-08T10:00:00Z",
    "share_url": null
  }
}

Pro Tip

After creating a form via the API, publish it by sending a PATCH request that sets status to published. This two-step process lets you review the form in the dashboard before it goes live.

Update a Form

Updates an existing form. You only need to include the fields you want to change — all other fields remain unchanged.

Request

curl -X PATCH "https://api.bttrlabs.com/v1/forms/frm_m3n4o5p6q7r8" \
  -H "X-API-Key: bttrform_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contact Our Sales Team",
    "status": "published"
  }'

Updatable Fields

Field	Type	Description
`title`	string	Update the form title
`description`	string	Update the form description
`fields`	array	Replace the entire fields array
`settings`	object	Merge with existing settings
`status`	string	Change status: `draft`, `published`, or `archived`

Response (200 OK)

Returns the full updated form object (same structure as the Get a Form response).

Important

Updating the fields array replaces all fields entirely. To add or remove a single field, first fetch the current form, modify the fields array in your code, and send the complete array back. A future API version will support individual field operations.

Delete a Form

Permanently deletes a form and all associated submissions. This action is irreversible.

Request

curl -X DELETE "https://api.bttrlabs.com/v1/forms/frm_m3n4o5p6q7r8" \
  -H "X-API-Key: bttrform_sk_live_your_key_here"

Response (204 No Content)

A successful deletion returns no response body with a 204 status code.

Error (404 Not Found)

{
  "error": "not_found",
  "message": "Form not found. It may have already been deleted."
}

Destructive Action

Deleting a form permanently removes all associated submissions, analytics data, and A/B test results. Consider archiving the form (setting status to archived) instead of deleting if you may need the data later.

Error Codes

All Forms API errors follow this structure:

{
  "error": "error_code",
  "message": "Human-readable description of the error."
}

Status	Error Code	Description
400	`validation_error`	Request body is invalid or missing fields
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	API key does not have access to this resource
404	`not_found`	Form does not exist or belongs to another user
429	`rate_limit_exceeded`	Too many requests — see rate limit headers
500	`internal_error`	Server error — retry or contact support

Next Steps

Submissions API — Retrieve and manage the submissions collected by your forms.
Authentication — Review rate limits and security best practices.