---
title: Getting Started - APIs
description: Retrieve Voice of Customer surveys and responses programmatically with the Responses API.
source_url:
  html: https://docs.contentsquare.com/en/api/responses/
  md: https://docs.contentsquare.com/en/api/responses/index.md
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

The Contentsquare Responses API gives you programmatic access to your Voice of Customer surveys and their responses. The API is organized around REST. It has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS.

Not a developer? Contact your CSM.

* **Base URL of the API:** `https://api.contentsquare.com/`
* **Current version of the API:** 1.0
* **Availability:** Pro plan, web only. The API must be enabled for your project, otherwise requests return a `403` error.

## Key concepts

### Survey

A Voice of Customer survey created in Contentsquare. Its ID has the form `survey_<uuid>`. A survey has a type (`link`, `full_screen`, `popover`, `button`, `inline`, `bubble`, or `mobile_popover`), a language, and an enabled status.

### Question

A question inside a survey. Its ID has the form `question_<survey_uuid>_<short_id>`. Question types are `reaction`, `reaction-binary`, `long-text`, `short-text`, `single-option`, `multiple-option`, `email`, `rating-1-5`, `rating-1-7`, `nps`, `statement`, and `thank-you`.

### Response

One respondent's submission to a survey. A response contains answers, an optional comment, tags, and sentiment per answer, and context such as device, browser, OS, country, and the page where the survey was answered.

## Pagination

List endpoints use cursor-based pagination. Send `limit` (default 20, max 100). If more results exist, the response includes `next_cursor`. Pass it as `cursor` in your next request. `next_cursor` is `null` on the last page.

Treat cursors as opaque values: don't parse or build them.

```json
{ "results": [ ... ], "next_cursor": "eyJ..." }
```

## Errors

The HTTP status code is authoritative. Except for `401` (see below), error responses have a JSON body with a `message`:

```json
{ "message": "Survey not found." }
```

| Status | Meaning |
| - | - |
| `400` | Invalid survey ID format, or invalid cursor |
| `401` | Missing, invalid, or expired access token |
| `403` | API access not available for this project |
| `404` | Survey not found |
| `422` | Invalid query parameter (for example `limit` out of range). `message` lists the offending fields |

A `401` response is generated by the gateway and has a different body:

```json
{
  "success": false,
  "errorMessage": "Auth token is invalid.",
  "errorCode": "JWT_INVALID"
}
```


```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"Getting Started","description":"Retrieve Voice of Customer surveys and responses programmatically with the Responses API.","url":"https://docs.contentsquare.com/en/api/responses/","inLanguage":"en","dateModified":"2026-11-04T13:03:38+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}}
```