Responses

Retrieve and manage survey responses

The Responses API allows you to retrieve survey responses from the Management API and submit responses from the Client API.

The Response Object

Attributes

id · string

Unique identifier for the response

createdAt · string

ISO 8601 timestamp of when the response was created

updatedAt · string

ISO 8601 timestamp of when the response was last updated

surveyId · string

The ID of the survey this response belongs to

contactId · string | null

The ID of the contact who submitted the response (if identified)

finished · boolean

Whether the response is complete

data · object

Response data as key-value pairs (question ID to answer)

variables · object

Variables collected during the response (string or number values)

ttc · object

Time to complete (in seconds) for each question

meta · object

Metadata about the response including source, URL, userAgent, country, and action

contactAttributes · object | null

Contact attributes at the time of response

language · string | null

Language code of the response (e.g., “en”)

Management API

Use the Management API to retrieve responses from your surveys.

List Responses

cURL

curl "https://app.formbricks.com/api/v1/management/responses?surveyId=srv_123&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Query Parameters

surveyId · string

Filter responses by survey ID

contactId · string

Filter responses by contact ID

limit · number · default: "10"

Maximum number of responses to return (1-100)

offset · number · default: "0"

Number of responses to skip for pagination

startDate · string

Filter responses created after this date (ISO 8601)

endDate · string

Filter responses created before this date (ISO 8601)

sortBy · string · default: "createdAt"

Field to sort by: createdAt or updatedAt

order · string · default: "desc"

Sort order: asc or desc

Response

[
  {
    "id": "res_...",
    "createdAt": "2021-01-01T00:00:00.000Z",
    "updatedAt": "2021-01-01T00:00:00.000Z",
    "surveyId": "srv_...",
    "contactId": "con_...",
    "finished": true,
    "data": {
      "qst_1": "Great product!",
      "qst_2": 5
    },
    "variables": {
      "plan": "pro"
    },
    "ttc": {
      "qst_1": 12,
      "qst_2": 3
    },
    "meta": {
      "source": "https://example.com",
      "url": "https://example.com/dashboard",
      "userAgent": {
        "browser": "Chrome",
        "os": "Windows",
        "device": "desktop"
      },
      "country": "US"
    },
    "contactAttributes": {
      "email": "[e-mail]"
    },
    "language": "en"
  }
]

Retrieve a Response

Get a specific response by ID.

cURL

curl https://app.formbricks.com/api/v1/management/responses/{responseId} \
  -H "x-api-key: YOUR_API_KEY"

Path Parameters

responseId · string · required

The ID of the response to retrieve

Delete a Response

Delete a response permanently.

cURL

curl -X DELETE https://app.formbricks.com/api/v1/management/responses/{responseId} \
  -H "x-api-key: YOUR_API_KEY"

Path Parameters

responseId · string · required

The ID of the response to delete

Client API

Use the Client API to submit survey responses from your application.

Create a Response

Submit a new survey response.

cURL

curl -X POST https://app.formbricks.com/api/v1/client/{environmentId}/responses \
  -H "Content-Type: application/json" \
  -d '{
    "surveyId": "srv_...",
    "finished": false,
    "data": {
      "qst_1": "This is my answer"
    },
    "meta": {
      "source": "app",
      "url": "https://example.com/page"
    }
  }'

Path Parameters

environmentId · string · required

The environment ID where the survey exists

Body Parameters

surveyId · string · required

The ID of the survey being responded to

finished · boolean · required

Whether this is the final submission (true) or a partial response (false)

data · object · required

Response data as question ID to answer mapping

userId · string

User identifier for contact tracking (Enterprise only)

displayId · string

The display ID if tracking survey displays

singleUseId · string

Single-use ID for link surveys

language · string

Language code for the response

variables · object

Additional variables to store with the response

ttc · object

Time to complete (in seconds) for each question

meta · object

Metadata including source, url, and action

Response

{
  "id": "res_...",
  "quotaFull": false
}

id · string

The ID of the created response

quotaFull · boolean

Whether the survey quota has been reached

Update a Response

Update an existing response (for partial submissions).

cURL

curl -X PUT https://app.formbricks.com/api/v1/client/{environmentId}/responses/{responseId} \
  -H "Content-Type: application/json" \
  -d '{
    "finished": true,
    "data": {
      "qst_2": 5
    }
  }'

Path Parameters

environmentId · string · required

The environment ID

responseId · string · required

The ID of the response to update

Body Parameters

finished · boolean

Mark the response as finished

data · object

Additional response data to merge with existing data

language · string

Update the response language

variables · object

Additional variables to merge

ttc · object

Additional time to complete data

Response

Returns the same format as creating a response.

Responses marked as finished: true cannot be updated. You’ll receive a 400 error if you attempt to update a finished response.

Data Validation

The API validates response data against the survey’s validation rules:

• Required fields must be present when finished: true
• Data types must match question types
• File uploads are validated against allowed types
• Text length limits are enforced

Validation errors return a 400 Bad Request with details:

{
  "message": "Validation failed",
  "details": {
    "qst_1": "This field is required"
  }
}

Response Events

When responses are created or updated, events are sent to the pipeline:

• responseCreated - Fired when a response is first created
• responseUpdated - Fired when a response is updated
• responseFinished - Fired when a response is marked as finished

These events trigger webhooks and integrations.