Submissions API | BttrForm

The Submissions API lets you retrieve, filter, and export form responses programmatically. Use it to integrate form data with your CRM, data warehouse, notification systems, or any other part of your stack.

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/:form_id/submissions`	List submissions for a form
`GET`	`/v1/submissions/:id`	Get a specific submission
`DELETE`	`/v1/submissions/:id`	Delete a submission
`GET`	`/v1/forms/:form_id/submissions/export`	Export submissions as CSV

List Submissions

Retrieves a paginated list of submissions for a specific form. Submissions are returned in reverse chronological order (newest first).

Request

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

JavaScript Example

const formId = 'frm_a1b2c3d4e5f6'

const response = await fetch(
  `https://api.bttrlabs.com/v1/forms/${formId}/submissions?limit=10`,
  {
    headers: {
      'X-API-Key': process.env.BTTRFORM_API_KEY,
      'Content-Type': 'application/json'
    }
  }
)

const { data, pagination } = await response.json()

data.forEach(submission => {
  console.log(`${submission.id}: ${submission.answers.full_name}`)
})

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of submissions to return (1-100)
`cursor`	string	—	Cursor for pagination
`date_from`	string	—	Filter: submissions after this ISO 8601 date
`date_to`	string	—	Filter: submissions before this ISO 8601 date
`search`	string	—	Search within submission answers
`utm_source`	string	—	Filter by UTM source parameter
`utm_medium`	string	—	Filter by UTM medium parameter
`utm_campaign`	string	—	Filter by UTM campaign parameter

Response (200 OK)

{
  "data": [
    {
      "id": "sub_x1y2z3w4v5u6",
      "form_id": "frm_a1b2c3d4e5f6",
      "answers": {
        "full_name": "Jane Smith",
        "email": "jane@example.com",
        "rating": 5,
        "feedback": "Great product! The onboarding experience was smooth and intuitive."
      },
      "metadata": {
        "submitted_at": "2026-02-07T15:32:00Z",
        "ip_country": "US",
        "device": "desktop",
        "browser": "Chrome",
        "completion_time_seconds": 94,
        "utm_source": "newsletter",
        "utm_medium": "email",
        "utm_campaign": "february_update"
      },
      "ai_insights": {
        "sentiment": "positive",
        "sentiment_score": 0.92,
        "categories": ["onboarding", "user-experience"],
        "language": "en"
      }
    },
    {
      "id": "sub_t7s8r9q0p1o2",
      "form_id": "frm_a1b2c3d4e5f6",
      "answers": {
        "full_name": "Carlos Rivera",
        "email": "carlos@example.com",
        "rating": 3,
        "feedback": "The form builder is good but I had trouble with conditional logic. Documentation could be clearer."
      },
      "metadata": {
        "submitted_at": "2026-02-07T12:18:00Z",
        "ip_country": "MX",
        "device": "mobile",
        "browser": "Safari",
        "completion_time_seconds": 156,
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "form_builder_search"
      },
      "ai_insights": {
        "sentiment": "mixed",
        "sentiment_score": 0.45,
        "categories": ["conditional-logic", "documentation"],
        "language": "en"
      }
    }
  ],
  "pagination": {
    "total": 342,
    "limit": 10,
    "has_more": true,
    "next_cursor": "eyJpZCI6InN1Yl90N3M4cjlxMHAxbzIifQ=="
  }
}

AI Insights

The ai_insights object is populated automatically when AI analysis is enabled for your form. It includes sentiment analysis, category tags, and language detection. AI insights are available on all plans, subject to your daily AI action limits.

Filtering by Date Range

Combine date_from and date_to to retrieve submissions within a specific time window. Both parameters accept ISO 8601 format:

curl -X GET "https://api.bttrlabs.com/v1/forms/frm_a1b2c3d4e5f6/submissions?date_from=2026-02-01T00:00:00Z&date_to=2026-02-07T23:59:59Z" \
  -H "X-API-Key: bttrform_sk_live_your_key_here"

Filtering by UTM Parameters

Retrieve submissions from a specific marketing campaign:

curl -X GET "https://api.bttrlabs.com/v1/forms/frm_a1b2c3d4e5f6/submissions?utm_campaign=february_update&utm_medium=email" \
  -H "X-API-Key: bttrform_sk_live_your_key_here"

You can combine multiple filters. All filters are applied with AND logic — only submissions matching all specified filters are returned.

Pro Tip

Use UTM filters to measure campaign-specific response quality. For example, compare the average sentiment score between submissions from paid ads versus organic traffic to understand which channel attracts more engaged respondents.

Pagination

The Submissions API uses the same cursor-based pagination as the Forms API. Fetch subsequent pages by passing the next_cursor value:

async function getAllSubmissions(formId) {
  const submissions = []
  let cursor = null

  do {
    const url = new URL(`https://api.bttrlabs.com/v1/forms/${formId}/submissions`)
    url.searchParams.set('limit', '100')
    if (cursor) url.searchParams.set('cursor', cursor)

    const response = await fetch(url.toString(), {
      headers: { 'X-API-Key': process.env.BTTRFORM_API_KEY }
    })
    const result = await response.json()

    submissions.push(...result.data)
    cursor = result.pagination.next_cursor
  } while (cursor)

  return submissions
}

Get a Submission

Retrieves the full details of a single submission by its ID.

Request

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

Response (200 OK)

Returns the same submission object structure as shown in the List Submissions response, but for a single submission:

{
  "data": {
    "id": "sub_x1y2z3w4v5u6",
    "form_id": "frm_a1b2c3d4e5f6",
    "answers": {
      "full_name": "Jane Smith",
      "email": "jane@example.com",
      "rating": 5,
      "feedback": "Great product! The onboarding experience was smooth and intuitive."
    },
    "metadata": {
      "submitted_at": "2026-02-07T15:32:00Z",
      "ip_country": "US",
      "device": "desktop",
      "browser": "Chrome",
      "completion_time_seconds": 94,
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "february_update"
    },
    "ai_insights": {
      "sentiment": "positive",
      "sentiment_score": 0.92,
      "categories": ["onboarding", "user-experience"],
      "language": "en"
    }
  }
}

Error (404 Not Found)

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

Delete a Submission

Permanently deletes a single submission. This action is irreversible.

Request

curl -X DELETE "https://api.bttrlabs.com/v1/submissions/sub_x1y2z3w4v5u6" \
  -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.

GDPR and Data Deletion

If you receive a data deletion request under GDPR or similar regulations, use this endpoint to remove specific submissions. For bulk deletion, iterate through submissions using the List endpoint and delete individually. Contact support if you need to delete all data for a specific respondent across multiple forms.

Export Submissions as CSV

Exports all submissions for a form as a CSV file. This is useful for importing data into spreadsheets, BI tools, or data warehouses.

Request

curl -X GET "https://api.bttrlabs.com/v1/forms/frm_a1b2c3d4e5f6/submissions/export?format=csv" \
  -H "X-API-Key: bttrform_sk_live_your_key_here" \
  --output submissions.csv

Query Parameters

Parameter	Type	Default	Description
`format`	string	`csv`	Export format: `csv` or `json`
`date_from`	string	—	Include submissions after this date
`date_to`	string	—	Include submissions before this date
`fields`	string	—	Comma-separated list of field IDs to include

JavaScript Export Example

async function exportSubmissions(formId, dateFrom, dateTo) {
  const params = new URLSearchParams({ format: 'csv' })
  if (dateFrom) params.set('date_from', dateFrom)
  if (dateTo) params.set('date_to', dateTo)

  const response = await fetch(
    `https://api.bttrlabs.com/v1/forms/${formId}/submissions/export?${params}`,
    {
      headers: { 'X-API-Key': process.env.BTTRFORM_API_KEY }
    }
  )

  if (!response.ok) {
    throw new Error(`Export failed: ${response.status}`)
  }

  const csvData = await response.text()
  return csvData
}

// Export February submissions
const csv = await exportSubmissions(
  'frm_a1b2c3d4e5f6',
  '2026-02-01T00:00:00Z',
  '2026-02-28T23:59:59Z'
)

CSV Format

The exported CSV includes one row per submission with columns for each form field, plus metadata columns:

submission_id,submitted_at,full_name,email,rating,feedback,ip_country,device,utm_source
sub_x1y2z3w4v5u6,2026-02-07T15:32:00Z,Jane Smith,jane@example.com,5,"Great product!",US,desktop,newsletter
sub_t7s8r9q0p1o2,2026-02-07T12:18:00Z,Carlos Rivera,carlos@example.com,3,"Good but needs work",MX,mobile,google

Pro Tip

Use the fields parameter to export only specific columns. This is useful when you only need a subset of data — for example, exporting just email addresses for a mailing list: ?fields=fld_002&format=csv.

Error Codes

All Submissions API errors follow the standard BttrForm error format:

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

Status	Error Code	Description
400	`validation_error`	Invalid query parameters or date format
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	API key does not have access to this resource
404	`not_found`	Submission or form not found
429	`rate_limit_exceeded`	Too many requests — check rate limit headers
500	`internal_error`	Server error — retry or contact support

Next Steps

Forms API — Manage the forms that collect these submissions.
Authentication — Review rate limits and API key management.
Conversion Tracking — Use UTM parameters with the Submissions API to analyze campaign performance.