List Survey Templates
=====================

Survey Templates are reusable, predefined sets of survey steps that can be applied to SURVEY-type campaigns.
Each template stores a voice, a length factor, and an ordered list of steps with optional audio files.

**Base path:** ``/api/v1/survey-templates/``

**Permissions required:**

- User must be a company user (``IsCompanyUser``)
- User must have survey access (``HasSurveyAccess``)
- Write operations are blocked when user is impersonated by a business (``BlockWriteWhenImpersonatedByBusiness``)

.. rubric:: List

+-----------------------------------------------------------------------+-------------------+-----------------+
| URL                                                                   | Required Values   | HTTP Methods    |
+=======================================================================+===================+=================+
| https://app.tingting.io/api/v1/survey-templates/                      |                   |      GET        |
+-----------------------------------------------------------------------+-------------------+-----------------+

Returns a paginated list of the authenticated user's survey templates, ordered newest first.

**Query Parameters:**

+------------+--------+----------------------------------+
| Parameter  | Type   | Description                      |
+============+========+==================================+
| search     | string | Filter by name or content.       |
+------------+--------+----------------------------------+
| page       | integer| Page number.                     |
+------------+--------+----------------------------------+
| page_size  | integer| Results per page.                |
+------------+--------+----------------------------------+

Sample Request:

.. code-block:: http

    GET /api/v1/survey-templates/
    Authorization: Token <token>

Sample Response (200 OK):

.. code-block:: json

    {
      "count": 2,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 2,
          "name": "Customer Feedback Survey",
          "voice": {
            "id": 5,
            "voice_display_name": "Rijan",
            "voice_internal_name": "np_rijan",
            "is_premium": false,
            "is_beta": false
          },
          "length_factor": "1.20",
          "content": [
            {
              "order": 0,
              "content_type": "say",
              "response_type": "dtmf",
              "input_name": "satisfaction",
              "audio_file": null
            }
          ],
          "created_at": "2026-05-20T10:00:00Z"
        },
        {
          "id": 1,
          "name": "Product Review Survey",
          "voice": {
            "id": 3,
            "voice_display_name": "Anita",
            "voice_internal_name": "np_anita",
            "is_premium": true,
            "is_beta": false
          },
          "length_factor": "1.00",
          "content": [
            {
              "order": 0,
              "content_type": "play",
              "response_type": "raw_record",
              "input_name": "feedback",
              "audio_file": "https://example.com/media/survey_templates/audio/step_0_a1b2c3d4.mp3"
            }
          ],
          "created_at": "2026-04-10T08:30:00Z"
        }
      ]
    }

With ``search`` query parameter:

.. code-block:: http

    GET /api/v1/survey-templates/?search=Customer

Returns only templates whose name or content contains "Customer".

.. rubric:: Retrieve

+-----------------------------------------------------------------------+-------------------+-----------------+
| URL                                                                   | Required Values   | HTTP Methods    |
+=======================================================================+===================+=================+
| https://app.tingting.io/api/v1/survey-templates/<id>/                 | Template ID       |      GET        |
+-----------------------------------------------------------------------+-------------------+-----------------+

Returns a single survey template by ID. Replace ``<id>`` with the template ID.

Sample Request:

.. code-block:: http

    GET /api/v1/survey-templates/3/
    Authorization: Token <token>

Sample Response (200 OK):

.. code-block:: json

    {
      "id": 3,
      "name": "Simple DTMF Survey",
      "voice": {
        "id": 5,
        "voice_display_name": "Rijan",
        "voice_internal_name": "np_rijan",
        "is_premium": false,
        "is_beta": false
      },
      "length_factor": "1.00",
      "content": [
        {
          "order": 0,
          "content_type": "say",
          "response_type": "dtmf",
          "input_name": "rating",
          "audio_file": null
        }
      ],
      "created_at": "2026-06-02T12:00:00Z"
    }

**Error Response (404 Not Found):**

.. code-block:: json

    { "detail": "No SurveyTemplate matches the given query." }