Surveys

Surveys allow you to collect feedback using CSAT, NPS, or Polls. Use these endpoints to list surveys and fetch their responses.

List surveys

GET /api/v1/surveys/

Retrieve a paginated list of surveys.

Query parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	20	Results per page (max 100).
`offset`	integer	No	0	Number of results to skip.

Example request

curl -sS \
  -H 'Authorization: Api-Key scalar*live*...' \
  'https://<your-host>/api/v1/surveys/'

Success response (200 OK)

{
    "results": [
        {
            "id": 1,
            "survey_type": "NPS",
            "prompt": "How likely are you to recommend us?",
            "published": true,
            "views": 150,
            "responses": 42,
            "response_rate": 28.0,
            "widget_position": "bottom-right",
            "slug": "nps-q1-abc123",
            "created": "2025-01-01T10:00:00Z"
        }
    ],
    "count": 1
}

List survey responses

GET /api/v1/surveys/<slug>/responses/

Retrieve a paginated list of responses for a specific survey.

Query parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	20	Results per page (max 100).
`offset`	integer	No	0	Number of results to skip.

Example request

curl -sS \
  -H 'Authorization: Api-Key scalar*live*...' \
  'https://<your-host>/api/v1/surveys/nps-q1-abc123/responses/'

Success response (200 OK)

{
    "results": [
        {
            "id": 101,
            "user": {
                "id": 5,
                "first_name": "Sam",
                "email": "[email protected]"
            },
            "rating": 9,
            "poll_choice": null,
            "text_response": "Great product!",
            "session_id": "sess_abc123",
            "created": "2025-01-05T12:00:00Z"
        }
    ],
    "count": 1
}

Objects

Survey object

Field	Type	Description
`id`	integer	Unique internal ID.
`survey_type`	string	Survey type: `NPS`, `CSAT`, or `POLL`.
`prompt`	string	The survey question displayed to users.
`published`	boolean	Whether the survey is currently active.
`views`	integer	Number of times the survey has been displayed.
`responses`	integer	Number of responses received.
`response_rate`	float	Percentage of views that resulted in responses.
`widget_position`	string	Widget display position (e.g. `bottom-right`).
`slug`	string	URL-safe identifier.
`created`	datetime	ISO 8601 creation timestamp.

Survey Response object

Field	Type	Description
`id`	integer	Unique internal ID.
`user`	object	Nested object with `id`, `first_name`, and `email`.
`rating`	integer	Numeric score: 0-10 (NPS) or 1-5 (CSAT).
`poll_choice`	object	Selected choice object for Poll surveys (or null).
`text_response`	string	Optional text feedback provided by the user.
`session_id`	string	Session identifier for the response.
`created`	datetime	ISO 8601 response timestamp.

Choice object

Used in the poll_choice field.

Field	Type	Description
`id`	integer	Choice ID.
`title`	string	Choice title.