Submissions API

Submit form data and retrieve responses. Supports both client-side (browser) and server-side submissions.

Submit Form

POST /v1/forms/{formId}/submissions

Submit data to a form. Use publishable keys for client-side submissions or secret keys for server-side submissions.

Client-Side Submission

Use publishable keys (pk_live_... or pk_test_...) which are safe to expose in frontend code:

POST /v1/forms/{formId}/submissions
x-publishable-key: pk_live_...
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Hello from the contact form!"
}

Server-Side Submission

Use secret keys (sk_live_... or sk_test_...) via Authorization header:

POST /v1/forms/{formId}/submissions
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Hello from the server!"
}

Response

{
  "id": "sub_123",
  "formId": "form_123",
  "submittedAt": "2024-01-01T00:00:00Z",
  "status": "completed",
  "answers": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello!"
  }
}

List Responses

GET /responses

Retrieve all form responses. Requires authentication with a secret key or session token.

Query Parameters

form_id - Filter by form ID
status - Filter by status (completed, partial, abandoned)
limit - Number of results (default: 50)
offset - Pagination offset
format - Export format (csv, json)

Export Responses

GET /responses?format=csv

Export responses as CSV or JSON. Useful for data analysis and reporting.

Response Status

completed - Form was fully submitted

partial - Form submission was started but not completed

abandoned - User started but abandoned the form

Forms API →Webhooks →Authentication →