Surveys

Manage surveys via API

The Surveys API allows you to create, retrieve, update, and delete surveys programmatically.

The Survey Object

Surveys contain questions/blocks, endings, and configuration for display and targeting.

Attributes

id · string

Unique identifier for the survey

createdAt · string

ISO 8601 timestamp of when the survey was created

updatedAt · string

ISO 8601 timestamp of when the survey was last updated

environmentId · string

The environment this survey belongs to

blocks · array

Array of survey blocks containing questions and elements

questions · array

Legacy: Array of questions (for backwards compatibility)

endings · array

Survey endings/thank you screens

status · string

Survey status: draft, scheduled, inProgress, paused, or completed

List All Surveys

cURL

curl https://app.formbricks.com/api/v1/management/surveys \
  -H "x-api-key: YOUR_API_KEY"

Query Parameters

limit · number

Maximum number of surveys to return

offset · number

Number of surveys to skip (for pagination)

Response

[
  {
    "id": "srv_...",
    "createdAt": "2021-01-01T00:00:00.000Z",
    "updatedAt": "2021-01-01T00:00:00.000Z",
    "environmentId": "env_...",
    "status": "inProgress",
    "blocks": [...],
    "endings": [...]
  }
]

Retrieve a Survey

Get a specific survey by ID.

cURL

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

Path Parameters

surveyId · string · required

The ID of the survey to retrieve

Response

{
  "id": "srv_...",
  "createdAt": "2021-01-01T00:00:00.000Z",
  "updatedAt": "2021-01-01T00:00:00.000Z",
  "environmentId": "env_...",
  "status": "inProgress",
  "blocks": [
    {
      "id": "blk_...",
      "type": "question",
      "elements": [
        {
          "id": "qst_...",
          "type": "text",
          "headline": "What is your feedback?"
        }
      ]
    }
  ],
  "endings": [
    {
      "id": "end_...",
      "type": "endScreen",
      "headline": "Thank you!"
    }
  ]
}

Create a Survey

Create a new survey in your environment.

cURL

curl -X POST https://app.formbricks.com/api/v1/management/surveys \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env_...",
    "blocks": [
      {
        "type": "question",
        "elements": [
          {
            "type": "text",
            "headline": "What is your feedback?",
            "required": true
          }
        ]
      }
    ],
    "endings": [
      {
        "type": "endScreen",
        "headline": "Thank you!"
      }
    ],
    "finished": false,
    "data": {}
  }'

Body Parameters

environmentId · string · required

The environment ID where the survey will be created

blocks · array · required

Array of survey blocks containing questions and elements

endings · array

Array of survey endings/thank you screens

status · string

Survey status: draft, scheduled, inProgress, paused, or completed

Response

Returns the created survey object with a 201 Created status.

Update a Survey

Update an existing survey.

cURL

curl -X PUT https://app.formbricks.com/api/v1/management/surveys/{surveyId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

Path Parameters

surveyId · string · required

The ID of the survey to update

Body Parameters

Any survey fields you want to update. Only include fields that should be changed.

Response

Returns the updated survey object.

Delete a Survey

Delete a survey permanently.

This action cannot be undone. All responses associated with this survey will remain but the survey configuration will be deleted.

cURL

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

Path Parameters

surveyId · string · required

The ID of the survey to delete

Response

Returns the deleted survey object.

Legacy: Questions Format

For backwards compatibility, the API supports the legacy questions format. When a survey has blocks where each block contains exactly one element, the API automatically transforms it to the questions format in responses.

When creating or updating surveys with the questions field, they are automatically converted to the modern blocks format.

Feature Permissions

Some survey features require specific organization plans:

• Advanced targeting rules
• Custom survey logic
• Enterprise integrations

If you attempt to use a feature not available on your plan, you’ll receive a 403 Forbidden response.