---
title: Smart Routings — Surveys
excerpt: Manage satisfaction surveys, record caller answers from your call flows, and list or export survey results.
order: 13
---

Surveys collect post-call satisfaction scores from callers. See [Smart Routings](/en/docs/cx-api/smart-routings) for the concepts shared by every Smart Routings endpoint.

All endpoints in this section are **workspace-scoped** and require the `client` OAuth scope. Recording an answer (`POST /api/smart-routings/survey-records`) also accepts the `cfd` scope.

**Headers:** `Authorization: Bearer {workspace-token}`

**Required query parameter:** `customer_account` — the customer account to act on. See [Selecting the customer account](/en/docs/cx-api/smart-routings#selecting-the-customer-account).

| Permission | Required for |
|---|---|
| `survey.view` | Listing and reading surveys, listing and exporting records |
| `survey.create` | Creating surveys |
| `survey.edit` | Updating surveys, updating and deleting records |
| `survey.delete` | Deleting surveys |
| `survey.lookup` or `survey.edit` | Recording an answer |

---

## Surveys

### GET /api/smart-routings/surveys

Returns a paginated list of the customer's surveys.

**Query parameters**

| Parameter | Description |
|---|---|
| `filter[name]` | Filter by name |
| `sort` | Sort field: `id`, `name`, `created_at`, `updated_at`. Prefix with `-` for descending. Default: `-updated_at` |
| `per_page` | Results per page (default: 20) |
| `page` | Page number |

**Response `200`** — paginated response

```json
{
  "data": [
    {
      "id": 3,
      "customer_id": 12,
      "name": "After-sales satisfaction",
      "created_at": "2024-05-10T08:00:00.000000Z",
      "updated_at": "2024-05-10T08:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}
```

---

### GET /api/smart-routings/surveys/{id}

Returns a single survey, including its `customer` object.

**Response `200`**

```json
{
  "id": 3,
  "customer_id": 12,
  "name": "After-sales satisfaction",
  "created_at": "2024-05-10T08:00:00.000000Z",
  "updated_at": "2024-05-10T08:00:00.000000Z",
  "customer": { "id": 12, ... }
}
```

**Response `403`** — the survey belongs to another customer, or the permission is missing

---

### POST /api/smart-routings/surveys

Creates a survey for the customer.

**Request body**

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Survey name |

**Response `201`** — the created survey object

---

### PUT /api/smart-routings/surveys/{id}

Renames a survey. `PATCH` is also accepted.

**Request body**

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | no | Survey name |

**Response `201`** — the updated survey object

---

### DELETE /api/smart-routings/surveys/{id}

Deletes a survey.

**Response `200`**

```json
{ "response": "element deleted" }
```

---

## Survey Records

A record is one caller's answer to a survey: the caller number, one to three scores, the agent who handled the call, and the date and time.

### POST /api/smart-routings/survey-records

Records a caller's answers. This is the endpoint a 3CX call flow calls at the end of a survey. Accepts the `client` or `cfd` scope.

**Request body**

| Field | Type | Required | Description |
|---|---|---|---|
| `survey_id` | integer | yes | ID of the survey |
| `caller` | string | yes | Caller's phone number |
| `score_1` | string | yes | Answer to the first question (numeric value) |
| `score_2` | string | no | Answer to the second question (numeric value) |
| `score_3` | string | no | Answer to the third question (numeric value) |
| `datetime` | string | yes | Date and time of the answer, in 3CX format: `MM/DD/YYYY hh:mm:ss AM` or `PM` (e.g. `10/08/2026 2:35:12 PM`) |
| `agent_extension` | string | no | Extension of the agent who handled the call |
| `agent_name` | string | no | Name of the agent who handled the call |

```json
{
  "survey_id": 3,
  "caller": "+33612345678",
  "score_1": "4",
  "score_2": "5",
  "datetime": "10/08/2026 2:35:12 PM",
  "agent_extension": "201",
  "agent_name": "Alice Martin"
}
```

**Response `201`**

```json
{
  "survey_id": 3,
  "caller": "+33612345678",
  "score_1": "4",
  "score_2": "5",
  "datetime": "2026-10-08T14:35:12.000000Z",
  "agent_extension": "201",
  "agent_name": "Alice Martin",
  "updated_at": "2026-10-08T14:35:13.000000Z",
  "created_at": "2026-10-08T14:35:13.000000Z",
  "id": 981
}
```

**Response `400`** — validation failure

---

### GET /api/smart-routings/survey-records

Returns a paginated list of a survey's records.

**Query parameters**

| Parameter | Description |
|---|---|
| `survey_id` | **Required.** ID of the survey |
| `filter[caller]` | Filter by caller number |
| `filter[agent_name]` | Filter by agent name |
| `filter[search]` | Search in caller number, agent name and agent extension |
| `sort` | Sort field: `id`, `caller`, `datetime`. Prefix with `-` for descending. Default: `-datetime` |
| `per_page` | Results per page (default: 20) |
| `page` | Page number |

**Response `200`** — paginated response

```json
{
  "data": [
    {
      "id": 981,
      "survey_id": 3,
      "caller": "+33612345678",
      "score_1": 4,
      "score_2": 5,
      "score_3": null,
      "agent_extension": "201",
      "agent_name": "Alice Martin",
      "datetime": "2026-10-08T14:35:12.000000Z",
      "created_at": "2026-10-08T14:35:13.000000Z",
      "updated_at": "2026-10-08T14:35:13.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}
```

---

### GET /api/smart-routings/survey-records/export

Downloads all records of a survey as a file.

**Query parameters**

| Parameter | Description |
|---|---|
| `survey_id` | **Required.** ID of the survey |
| `format` | `csv` (default), `xlsx` or `xls` |

**Response `200`** — file download named `survey_records.{format}`, with the columns `id`, `survey_id`, `caller`, `score_1`, `score_2`, `score_3`, `datetime`, `agent_extension`, `agent_name`.

---

### PUT /api/smart-routings/survey-records/{id}

Updates a record. All fields from the create endpoint are accepted and optional. When sent, `datetime` uses the same 3CX format. Requires the `survey.edit` permission.

**Response `200`** — the updated record object

**Response `403`** — the survey belongs to another customer, or the permission is missing

---

### DELETE /api/smart-routings/survey-records/{id}

Deletes a record. Requires the `survey.edit` permission (`survey.delete` only applies to surveys themselves).

**Response `200`**

```json
{ "response": "element deleted" }
```

**Response `403`** — the survey belongs to another customer, or the permission is missing