Smart Routings — Surveys — Smart Analytics & Integrations for Business Phone Systems

Manage satisfaction surveys, record caller answers from your call flows, and list or export survey results.

Surveys collect post-call satisfaction scores from callers. See 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.

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

{
  "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

{
  "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

{ "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

{
  "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

{
  "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

{
  "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

{ "response": "element deleted" }

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