Endpoints

Last updated Nov 4, 2026View as Markdown

All paths are relative to the base URL https://api.contentsquare.com. All endpoints require the surveys scope.

Path parameters

project_id integer Required: The unique identifier of a Contentsquare project.
public_survey_id string: The public survey ID, in the form survey_<uuid>. Required for the endpoints that target a single survey.

List surveys

GET /v1/public/projects/{project_id}/surveys

Get a paginated list of surveys for the project.

Query parameters

limit integer: Number of surveys to return. Default 20, min 1, max 100.
cursor string: Pass next_cursor from the previous response to get the next page.
with_questions boolean: Include each survey's questions. Default false.

Request example

curl --location 'https://api.contentsquare.com/v1/public/projects/789700/surveys?limit=20&with_questions=false' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response example (200)

{
  "results": [
    {
      "id": "survey_af479a77-abea-42bf-a73f-bc02f18503bf",
      "name": "Checkout feedback",
      "is_enabled": true,
      "created_time": "2026-03-12T09:41:07Z",
      "type": "popover",
      "language": "en",
      "url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf",
      "responses_url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf/responses",
      "sentiment_analysis_enabled": true,
      "questions": null
    }
  ],
  "next_cursor": "eyJ..."
}

Errors: 400 (invalid cursor), 401, 403, 422.

Get a survey

GET /v1/public/projects/{project_id}/surveys/{public_survey_id}

Get a single survey, including its questions.

Request example

curl --location 'https://api.contentsquare.com/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response example (200)

{
  "id": "survey_af479a77-abea-42bf-a73f-bc02f18503bf",
  "name": "Checkout feedback",
  "is_enabled": true,
  "created_time": "2026-03-12T09:41:07Z",
  "type": "popover",
  "language": "en",
  "url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf",
  "responses_url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf/responses",
  "sentiment_analysis_enabled": true,
  "questions": [
    {
      "id": "question_af479a77-abea-42bf-a73f-bc02f18503bf_a1b2c3",
      "type": "rating-1-5",
      "text": "How easy was it to check out?",
      "is_required": true,
      "image_url": null,
      "choices": null,
      "labels": { "low_label": "Very difficult", "high_label": "Very easy" }
    },
    {
      "id": "question_af479a77-abea-42bf-a73f-bc02f18503bf_d4e5f6",
      "type": "single-option",
      "text": "What brought you here today?",
      "is_required": false,
      "image_url": null,
      "choices": [
        { "text": "Browsing", "allow_comment": false },
        { "text": "Other", "allow_comment": true }
      ],
      "labels": null
    }
  ]
}

Errors: 400 (invalid survey ID), 401, 403, 404.

Survey object

id string: Public survey ID.
name string: Survey name.
is_enabled boolean: Whether the survey is enabled.
created_time string (ISO 8601): Creation time (UTC).
type string: link, full_screen, popover, button, inline, bubble, or mobile_popover.
language string: Survey language.
url string: Path of this survey resource.
responses_url string: Path of the survey's responses.
sentiment_analysis_enabled boolean: Whether sentiment analysis is enabled.
questions array or null: Questions. null on the list endpoint unless with_questions=true.

Question object

id string: Question ID (question_<survey_uuid>_<short_id>).
type string: reaction, reaction-binary, long-text, short-text, single-option, multiple-option, email, rating-1-5, rating-1-7, nps, statement, or thank-you.
text string: Question text.
is_required boolean: Whether an answer is required.
image_url string or null: Image attached to the question.
choices array or null: For single-option and multiple-option questions: text and allow_comment for each choice.
labels object or null: For scale questions: low_label and high_label.

List survey responses

GET /v1/public/projects/{project_id}/surveys/{public_survey_id}/responses

Get a paginated list of responses for a survey.

Query parameters

limit integer: Number of responses to return. Default 20, min 1, max 100.
cursor string: Pass next_cursor from the previous response to get the next page.

Request example

curl --location 'https://api.contentsquare.com/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf/responses?limit=20' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response example (200)

{
  "results": [
    {
      "id": "response_62e88f7c-7346-495a-a442-6567e175ab85",
      "answers": [
        {
          "question_id": "question_af479a77-abea-42bf-a73f-bc02f18503bf_a1b2c3",
          "answer": "2",
          "comment": "Too many form fields.",
          "tags": [{ "name": "checkout" }],
          "sentiment": "negative"
        }
      ],
      "browser": "Chrome",
      "country": "FR",
      "created_time": "2026-10-20T14:05:11Z",
      "updated_time": "2026-10-20T14:06:02Z",
      "device": "desktop",
      "visitor_id": "XXXX",
      "is_complete": true,
      "os": "macOS",
      "recording_url": "https://app.contentsquare.com/...",
      "response_origin_url": "https://www.example.com/checkout",
      "user_attributes": [{ "name": "plan", "value": "premium" }],
      "window_size": { "width": 1440, "height": 900 }
    }
  ],
  "next_cursor": null
}

Errors: 400 (invalid survey ID or cursor), 401, 403, 404, 422.

Response object

id string: Unique identifier of the response.
answers array: The answers to the survey questions (see the answer object below).
browser string: Respondent's browser. Empty string if unknown.
os string: Respondent's operating system. Empty string if unknown.
country string: Respondent's country, as an ISO 3166-1 alpha-2 code. Empty string if unknown.
device string: desktop, mobile, or tablet.
visitor_id string: Visitor identifier.
is_complete boolean: Whether the respondent completed the survey.
created_time string (ISO 8601): Time the response was submitted.
updated_time string (ISO 8601): Time the response was last updated.
recording_url string or null: Link to the Session Replay, if available.
response_origin_url string: Page where the survey was answered.
user_attributes array: User attributes, each with a name and a value (boolean, number, string, datetime, or null).
window_size object: width and height of the respondent's window, in pixels. Each can be null.

Answer object

question_id string: ID of the answered question.
answer string: The respondent's answer, as a string.
comment string or null: Optional comment added by the respondent.
tags array: Tags applied to the answer, each as an object with a name.
sentiment string or null: positive, negative, or neutral. null if there is no sentiment or sentiment analysis is disabled.