POST/forms/:id/responses

Submit Response

Submit a form response via API (headless submission)

Scope: RESPONSES_WRITE

Overview

Submit a form response programmatically without a browser. This enables headless form submission — fetch the form schema, render it in your own UI (React, Angular, mobile app, etc.), and submit answers back to Formfex via API.

Formfex handles data storage, validation, analytics, webhooks, and integrations as if the response were submitted from a hosted form.

Request

POST/forms/:id/responses

Path Parameters

Headers

Header	Value
`Authorization`	`Bearer fxk_live_<your-api-key>`
`Content-Type`	`application/json`

Request Body

Field value types by field type:

Field Type	Expected Value	Example
`text`	`string`	`"John Doe"`
`email`	`string`	`"john@example.com"`
`number`	`number`	`42`
`textarea`	`string`	`"Long text answer..."`
`select`	`string`	`"option_value"`
`radio`	`string`	`"option_value"`
`checkbox`	`string[]`	`["option_1", "option_2"]`
`date`	`string`	`"2026-04-08"`
`rating`	`number`	`4`

File Fields Not Supported

File upload fields (type: "file") are not supported via the API. If the form contains file fields, they are excluded from required validation. Submitting data for a file field will return an error.

Example Request

curl -X POST "https://api.formfex.com/api/v1/public/forms/FORM_ID/responses" \
  -H "Authorization: Bearer $FORMFEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "field-name-id": "Alice Johnson",
      "field-email-id": "alice@example.com",
      "field-checkbox-id": ["option_1", "option_3"]
    }
  }'

Response

Response Fields

Field	Type	Description
`data.id`	`string`	Unique response identifier (UUID)
`data.formId`	`string`	Form identifier
`data.data`	`object`	Key-value map of `fieldId` to submitted answer
`data.respondentEmail`	`string \| null`	Always `null` for API submissions
`data.submittedAt`	`string`	ISO 8601 submission timestamp

Validation

The API enforces the same server-side validation as the hosted form:

Required fields — returns 400 if any required field is empty or missing
Validation rules — minLength, maxLength, min, max, pattern are all enforced
Conditional logic — hidden fields (based on conditional rules) are skipped during validation
Response size limits — maximum 200 fields, maximum 10,000 characters per value

Webhooks & Integrations

When a response is submitted via the API, the FORM_RESPONSE_CREATED event is triggered. This means:

Webhooks configured for this form will fire as normal
Slack and Teams integrations will receive the notification
n8n webhook triggers will pick up the new response

Headless Workflow

Combine Get Form (to fetch the schema) with Submit Response (to send answers) for a complete headless form experience. Use your own frontend to render the form, while Formfex handles storage, validation, analytics, and integrations.

PreviousDelete Field NextList Responses