# Surveys

> Your surveys and their aggregate results, question by question. Counts, shares and rating averages; never individual responses.

- Audience: API
- Page type: reference
- Updated: 2026-10-08
- Canonical URL: https://www.rendezvu.co/docs/api/surveys

Survey results come back as aggregates: how many respondents chose each option, the average and spread of each rating, and how many answered each free-text question. The text of free-text answers, individual responses and who responded stay in the console.

Needs the `surveys:read` scope and a plan that includes Surveys.

## List surveys

`GET /api/brand/v1/surveys`

Your surveys, with how many responses each has collected.

Scope: `surveys:read`. Plan feature: Surveys. Paginated.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `page` | integer, optional, default `1` | The page to return, starting at 1. At most 10,000. |
| `per_page` | integer, optional, default `25` | Items per page, between 1 and 100. |
| `status` | enum, optional | Only surveys in this state. One of: `DRAFT`, `PUBLISHED`, `CLOSED`. |

**Returns**

A page of surveys. `data` is an array of objects with these attributes, and the body carries `pagination`.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | string | The survey id. |
| `title` | string | Survey title. |
| `description` | string, nullable | What respondents read first. |
| `visibility` | enum | `PRIVATE` (invited hosts) or `PUBLIC` (anyone with the link). |
| `status` | enum | DRAFT, PUBLISHED or CLOSED. |
| `response_count` | integer | Responses so far. |
| `published_at` | timestamp, nullable | When it opened. |
| `closed_at` | timestamp, nullable | When it closed. |
| `created_at` | timestamp | When it was created. |
| `updated_at` | timestamp | When it last changed. |

**Example request**

```bash
curl 'https://api.rendezvu.co/api/brand/v1/surveys?status=PUBLISHED' \
  -H "Authorization: Bearer $RENDEZVU_BRAND_API_KEY"
```

**Example response**

```json
{
  "success": true,
  "data": [
    {
      "id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "title": "Ridgeline 30L field test",
      "description": "Five questions after your first month with the pack.",
      "visibility": "PRIVATE",
      "status": "PUBLISHED",
      "response_count": 18,
      "published_at": "2026-09-01T16:00:00.000Z",
      "closed_at": null,
      "created_at": "2026-08-28T10:30:00.000Z",
      "updated_at": "2026-09-01T16:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  },
  "_timing": {
    "duration_ms": 42
  }
}
```

## Retrieve survey results

`GET /api/brand/v1/surveys/{id}/results`

Aggregate results for one survey, question by question. Individual responses, respondent names and emails are never returned, and free-text questions report a count of answers without the text.

Scope: `surveys:read`. Plan feature: Surveys.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string, required, path | The survey id (UUID). |

**Returns**

Totals for the survey and a result per question.

| Attribute | Type | Description |
| --- | --- | --- |
| `survey_id` | string | The survey id. |
| `total_responses` | integer | Responses collected. |
| `questions` | array of objects | One result per question, in survey order. |
| `questions.id` | string | Question id. |
| `questions.type` | enum | MULTIPLE_CHOICE, FREE_TEXT, RATING, YES_NO or DROPDOWN. |
| `questions.title` | string | The question. |
| `questions.position` | integer | Its place in the survey. |
| `questions.total_answers` | integer | How many respondents answered it. |
| `questions.options` | array of objects | For choice questions: each option with its count. Absent for other types. |
| `questions.options.id` | string | Option id. |
| `questions.options.label` | string | Option text. |
| `questions.options.count` | integer | Respondents who chose it. |
| `questions.options.pct` | number | Share of answers, as a percentage. |
| `questions.rating` | object | For rating questions: the average and the distribution. Absent for other types. |
| `questions.rating.average` | number | Mean rating. |
| `questions.rating.distribution` | array of objects | Each rating with its count: `{ rating, count }`. |

**Errors**

- `404`: No survey with this id belongs to your brand.

**Example request**

```bash
curl 'https://api.rendezvu.co/api/brand/v1/surveys/c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f/results' \
  -H "Authorization: Bearer $RENDEZVU_BRAND_API_KEY"
```

**Example response**

```json
{
  "success": true,
  "data": {
    "survey_id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "total_responses": 18,
    "questions": [
      {
        "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
        "type": "RATING",
        "title": "How comfortable is the pack after 3 hours?",
        "position": 1,
        "total_answers": 18,
        "rating": {
          "average": 4.4,
          "distribution": [
            {
              "rating": 3,
              "count": 2
            },
            {
              "rating": 4,
              "count": 6
            },
            {
              "rating": 5,
              "count": 10
            }
          ]
        }
      },
      {
        "id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
        "type": "FREE_TEXT",
        "title": "What would you change?",
        "position": 2,
        "total_answers": 15
      }
    ]
  },
  "_timing": {
    "duration_ms": 42
  }
}
```

## Related

- [Gifts](https://www.rendezvu.co/docs/api/gifts.md): The products you sent to hosts, where each gift stands, the store order behind it, and the feedback the host wrote after using it.

---

Source: https://www.rendezvu.co/docs/api/surveys (Rendezvu docs, Markdown view). Every page: https://www.rendezvu.co/llms.txt