openapi: 3.0.0
info:
  title: Simplesat API (v1)
  description: |
    Welcome to the Simplesat API reference!


    The public endpoints are stable but still a work in progress. If you have
    any questions or see any issues, please reach out to us at
    support@simplesat.io.

    ## Previous API Versions

    - [API v0](https://documenter.getpostman.com/view/457268/SVfRt7WJ?version=latest) (deprecated)


    ## Authentication


    You need a Simplesat account with an API key to make requests. 
    You can manage API keys from the [API keys page](https://app.simplesat.io/settings/api-keys/).
    Your API key needs to have the appropriate scopes to access the endpoints you want to use.


    To authenticate, use an API key with the required scopes in a `X-Simplesat-Token` header.


    <table>
      <tr>
        <th>Key</th>
        <th>Value</th>
      </tr>
      <tr>
        <td><code>X-Simplesat-Token</code></td>
        <td>Your access token</td>
      </tr>
    </table>


    ## Content Type

    All requests and responses use JSON format. Ensure your `Content-Type` header
    is set correctly:

    ```http
    Content-Type: application/json
    ```

    ## Date and Time Format

    Dates and times in Simplesat's API follow the ISO 8601 standard, formatted as:

    ```
    YYYY-MM-DDTHH:MM:SSZ
    ```

    - `T` separates the date and time.
    - `Z` indicates UTC time.

    Example: `2024-08-08T14:30:00Z`


    ## Pagination

    By default, most list endpoints return a maximum of 100 records per page.
    You can change the number of records on a per-request basis by passing a
    `page_size` parameter in the request URL parameters. Example:
    `page_size=50`.


    When the response exceeds the per-page maximum, you can paginate through the
    records by incrementing the page parameter. Example: `page=3`. List results
    include `next` and `previous` URLs in the response body for easier
    navigation:


    ```

    {
        "answers" [...],
        "count": 106,
        "next": "https://api.simplesat.io/api/answers/?page=2",
        "previous": null,
    }

     ```

    Stop paging when the `next` attribute is `null`.


    ## Rate Limiting

    Public v1 API requests are rate limited per account.

    ### How it works

    - The limit is enforced in rolling 1‑minute windows.
    - All requests for the same account share the same quota.
    - If you exceed the limit, further requests in that window will return HTTP `429 Too Many Requests`.

    ### Rate limit headers

    Every public v1 API response includes the following headers:

    - `X-RateLimit-Limit` – the maximum number of requests allowed per 1‑minute window.
    - `X-RateLimit-Remaining` – how many requests you have left in the current window.
    - `X-RateLimit-Reset` – Unix timestamp (seconds) when the current window resets.
    - `Retry-After` – only sent on HTTP `429 Too Many Requests`; number of seconds until you can retry.

    <table>
      <tr>
        <th>Header</th>
        <th>Example</th>
      </tr>
      <tr>
        <td><code>X-RateLimit-Limit</code></td>
        <td><code>300</code></td>
      </tr>
      <tr>
        <td><code>X-RateLimit-Remaining</code></td>
        <td><code>42</code></td>
      </tr>
      <tr>
        <td><code>X-RateLimit-Reset</code></td>
        <td><code>1737642000</code></td>
      </tr>
      <tr>
        <td><code>Retry-After</code></td>
        <td><code>15</code></td>
      </tr>
    </table>

  version: 1.0.0
  contact:
    name: Simplesat Support
    email: support@simplesat.io
    url: https://help.simplesat.io
  termsOfService: https://simplesat.io/terms
servers:
  - url: https://api.simplesat.io
    description: "Simplesat"
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Simplesat-Token
      description: "All API endpoints require an API key with the appropriate scopes for access. You can manage API keys and scopes from https://app.simplesat.io/settings/api-keys/."
  schemas:
    Answer:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the answer, defined by Simplesat.
          example: 1
        created:
          type: string
          format: date-time
          description: The date and time the answer was created.
          example: "2024-01-01T00:00:00Z"
        modified:
          type: string
          format: date-time
          description: The date and time the answer was last modified.
          example: "2024-01-01T00:00:00Z"
        question:
          type: object
          description: Information about the question the answer is associated with.
          properties:
            id:
              type: integer
              example: 1
            text:
              type: string
              example: "How did we do?"
            metric:
              type: string
              example: "csat"
          example:
            id: 1
            text: "How did we do?"
            metric: "csat"
        choice:
          type: string
          description: The choice selected by the customer for the question.
          example: "3"
        choice_label:
          type: string
          description: The label for the choice selected by the customer.
          example: "Okay, but not great"
        choices:
          type: array
          items:
            type: string
          description: The selected choices for the question.
          example: ["Option1", "Option2", "Option3"]
        sentiment:
          type: string
          description: The sentiment associated with the answer.
          example: "neutral"
        comment:
          type: string
          description: Any comment provided by the customer for the question.
          example: "Very slow!"
        follow_up_answer:
          type: string
          description: Any follow-up answer provided by the customer.
          example: "Thank you!"
        follow_up_answer_choice:
          type: string
          description: The choice selected by the customer for the follow-up question.
          example: "yes"
        follow_up_answer_choices:
          type: array
          items:
            type: string
          description: The selected choices for the follow-up question.
          example: ["Option1", "Option2", "Option3"]
        survey:
          type: object
          description: Information about the survey the answer is associated with.
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: "Follow-up CSAT"
          example:
            id: 1
            name: "Follow-up CSAT"
        published_as_testimonial:
          type: boolean
          description: Whether the answer was published as a testimonial.
          example: false
        response_id:
          type: integer
          description: The unique identifier of the response associated with the answer.
          example: 1

    Customer:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the customer, defined by Simplesat.
          example: 1
        external_id:
          type: string
          description: The unique identifier of the customer from an external system.
          example: "1"
        created:
          type: string
          format: date-time
          description: The date and time the customer was created.
          example: "2024-01-01T00:00:00Z"
        modified:
          type: string
          format: date-time
          description: The date and time the customer was last modified.
          example: "2024-01-01T00:00:00Z"
        name:
          type: string
          description: Full name (first and last) of the customer.
          example: "Tester McTestFace"
        email:
          type: string
          format: email
          description: Email address of the customer.
          example: "tester@example.com"
        company:
          type: string
          description: The company associated with the customer.
          example: "Simplesat"
        custom_attributes:
          type: object
          description: Custom attributes associated with the customer.
          example:
            Country: "United States"
            City: "San Francisco"
            Channels: ["Web", "Mobile App"]

    TeamMember:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier representing the team member, assigned by Simplesat.
          example: 1
        external_id:
          type: string
          description: The unique identifier of the team member from an external system.
          example: "1"
        created:
          type: string
          format: date-time
          description: The date and time when the team member was created.
          example: "2024-01-01T00:00:00Z"
        modified:
          type: string
          format: date-time
          description: The date and time when the team member was last modified.
          example: "2024-01-01T00:00:00Z"
        name:
          type: string
          description: Full name (first and last) of the team member.
          example: "Tester McTestFace"
        email:
          type: string
          format: email
          description: Email address associated with the team member.
          example: "tester@example.com"
        custom_attributes:
          type: object
          description: Custom attributes associated with the team member.
          example:
            Level: "Senior"
            Department: "Support"

    Response:
      type: object
      properties:
        survey_id:
          type: integer
          description: The unique identifier of the survey for which the responses are recorded.
          example: 1
        tags:
          type: array
          items:
            type: string
          description: A list of tags associated with the survey.
          example: ["tag1", "tag2"]
        answers:
          type: array
          items:
            $ref: "#/components/schemas/Answer"
          description: A list of answers provided by the customer to the survey questions.
        team_members:
          type: array
          items:
            $ref: "#/components/schemas/TeamMember"
          description: A list of team members involved in handling the ticket.
        ticket:
          description: The ticket details from and external system.
          type: object
          properties:
            id:
              type: integer
              description: Unique identifier for the ticket, defined by Simplesat.
              example: 1
            external_id:
              type: string
              description: The unique identifier of the ticket from an external system.
              example: "1"
            subject:
              type: string
              description: The subject or title of the ticket.
              example: "Coffee machine broken!"
            custom_attributes:
              type: object
              description: Custom attributes associated with the ticket (e.g., priority, type).
              example:
                Priority: "Medium"
                Category: "Support"
        customer:
          type: object
          $ref: "#/components/schemas/Customer"
          description: The customer who responded to the survey.

    Survey:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the survey, defined by Simplesat.
          example: 1
        name:
          type: string
          description: The name of the survey.
          example: "Customer Satisfaction Survey"
        metric:
          type: string
          description: The metric associated with the survey.
          example: "csat"
        survey_token:
          type: string
          description: Randomly generated token for the survey.
          example: "z_3OxYijnEkfZSt6hLKxCRxBlu4CPQ9feLUAW4Eaen4"
        survey_type:
          type: string
          description: The type of survey (e.g., generic_embed, or an external platform).
          example: "generic_embed"
        brand_name:
          type: string
          description: The brand name associated with the survey.
          example: "Simplesat"
security:
  - api_key: []
paths:
  /api/v1/answers/{answer_id}:
    get:
      operationId: getAnswerById
      tags:
        - Answers
      summary: Get answer by ID
      description: |
        Get an answer by ID.

        Required scopes: `read answers`
      parameters:
        - name: answer_id
          description: The ID of the answer to retrieve
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  question:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      text:
                        type: string
                        example: "How did we do?"
                      metric:
                        type: string
                        example: "csat"
                  choice:
                    type: string
                    example: "3"
                  choice_label:
                    type: string
                    example: "Okay, but not great"
                  choices:
                    type: array
                    items:
                      type: string
                    example: ["Option1", "Option2", "Option3"]
                  sentiment:
                    type: string
                    example: "neutral"
                  comment:
                    type: string
                    example: "Very slow!"
                  follow_up_answer:
                    type: string
                    example: "Thank you!"
                  follow_up_answer_choice:
                    type: string
                    example: "yes"
                  follow_up_answer_choices:
                    type: array
                    items:
                      type: string
                    example: ["Option1", "Option2", "Option3"]
                  survey:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: "Follow-up CSAT"
                  created:
                    type: string
                    format: date-time
                    example: "2024-01-01T00:00:00"
                  modified:
                    type: string
                    format: date-time
                    example: "2024-01-01T00:00:00"
                  published_as_testimonial:
                    type: boolean
                    example: false
                  response_id:
                    type: integer
                    example: 1
                example:
                  id: 1
                  choice: "3"
                  choice_label: "Okay, but not great"
                  choices: null
                  comment: null
                  follow_up_answer: null
                  follow_up_answer_choice: "yes"
                  follow_up_answer_choices: null
                  published_as_testimonial: false
                  created: "2024-01-01T00:00:00Z"
                  modified: "2024-01-01T00:00:00Z"
                  question:
                    id: 1
                    text: "How did we do?"
                    metric: "csat"
                  sentiment: "neutral"
                  survey:
                    id: 1
                    name: "Follow-up CSAT"
                  response_id: 1
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No Answer matches the given query."
    put:
      operationId: updateAnswerById
      tags:
        - Answers
      summary: Update answer by ID
      description: |
        Update an answer by ID.

        One of `choice`, `choices`, or `comment` is required.

        Required scopes: `write answers`
      parameters:
        - name: answer_id
          description: The ID of the answer to update
          in: path
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                choice:
                  type: string
                  example: "2"
                choices:
                  type: array
                  items:
                    type: string
                  example: ["1", "2", "3"]
                comment:
                  type: string
                  nullable: true
                  example: "Very slow!"
                follow_up_answer:
                  type: string
                  nullable: true
                  example: "Thank you!"
                follow_up_answer_choice:
                  type: string
                  nullable: true
                  example: "yes"
                follow_up_answer_choices:
                  type: array
                  items:
                    type: string
                  example: ["Option1", "Option2", "Option3"]
              example:
                choice: "4"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  choice:
                    type: string
                    example: "2"
                  choice_label:
                    type: string
                    example: "Bad, I'm unsatisfied"
                  choices:
                    type: array
                    items:
                      type: string
                      nullable: true
                    example: ["Option1", "Option2", "Option3"]
                  comment:
                    type: string
                    nullable: true
                    example: "Very slow!"
                  follow_up_answer:
                    type: string
                    nullable: true
                    example: "Thank you!"
                  follow_up_answer_choice:
                    type: string
                    nullable: true
                    example: "yes"
                  follow_up_answer_choices:
                    type: array
                    items:
                      type: string
                      nullable: true
                    example: ["Choice 1", "Choice 2"]
                  published_as_testimonial:
                    type: boolean
                    example: false
                  created:
                    type: string
                    format: date-time
                    example: "2024-01-01T00:00:00Z"
                  modified:
                    type: string
                    format: date-time
                    example: "2024-01-02T00:00:00.000000Z"
                  question:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      text:
                        type: string
                        example: "How did we do?"
                      metric:
                        type: string
                        example: "csat"
                  sentiment:
                    type: string
                    example: "neutral"
                  survey:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: "Customer Satisfaction Survey"
                  response_id:
                    type: integer
                    example: 12345
                example:
                  id: 1
                  choice: "2"
                  choice_label: "Bad, I'm unsatisfied"
                  choices: null
                  comment: null
                  follow_up_answer: "Very slow!"
                  follow_up_answer_choice: "yes"
                  follow_up_answer_choices: null
                  published_as_testimonial: false
                  created: "2024-01-01T00:00:000000Z"
                  modified: "2024-01-01T00:00:000000Z"
                  question:
                    id: 1
                    text: "How did we do?"
                    metric: "csat"
                  sentiment: "negative"
                  survey:
                    id: 1
                    name: "Generic"
                  response_id: 1
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No Answer matches the given query."
                example:
                  detail: "No Answer matches the given query."
  /api/v1/answers/search:
    post:
      operationId: searchAnswers
      parameters:
        - description: The page number to retrieve
          in: query
          name: page
          required: false
          schema:
            type: integer
        - description: The number of records per page
          in: query
          name: page_size
          required: false
          schema:
            type: integer
      tags:
        - Answers
      summary: Search answers
      description: |
        Search for answers.

        Required scopes: `read answers`

        Accepted `operator` values are:
        - `and`
        - `or`

        Accepted `comparison` values are:
        - `is`
        - `is_not`
        - `contains`
        - `does_not_contain`
        - `is_unknown`
        - `has_any_value`

        Accepted `key` values are:
        - `choice_value`
        - `comment`
        - `metric`
        - `sentiment`
        - `survey` (token)

      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                  format: date-time
                  example: "2024-01-01T00:00:00Z"
                end_date:
                  type: string
                  format: date-time
                  example: "2024-12-31T23:59:59.000000Z"
                operator:
                  type: string
                  example: "and"
                filters:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        example: "sentiment"
                      values:
                        type: array
                        items:
                          type: string
                        example: ["positive"]
                      comparison:
                        type: string
                        example: "is"
              example:
                start_date: "2024-01-01T00:00:00"
                end_date: "2024-12-31T23:59:59Z"
                operator: "and"
                filters:
                  - key: "sentiment"
                    values: ["positive"]
                    comparison: "is"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    example: "https://api.simplesat.io/api/v1/answers/search?page=2&page_size=50"
                  previous:
                    type: string
                    nullable: true
                    example: null
                  count:
                    type: integer
                    example: 65
                  answers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        choice:
                          type: string
                          example: "3"
                        choice_label:
                          type: string
                          example: "Okay, but not great"
                        choices:
                          type: array
                          items:
                            type: string
                          example: ["Option1", "Option2", "Option3"]
                        comment:
                          type: string
                          example: "Very slow!"
                        follow_up_answer:
                          type: string
                          example: "Thank you!"
                        follow_up_answer_choice:
                          type: string
                          example: "yes"
                        follow_up_answer_choices:
                          type: array
                          items:
                            type: string
                          example: ["Option1", "Option2", "Option3"]
                        published_as_testimonial:
                          type: boolean
                          example: false
                        created:
                          type: string
                          format: date-time
                          example: "2024-10-11T05:38:19.000000Z"
                        modified:
                          type: string
                          format: date-time
                          example: "2024-11-12T03:17:13.000000Z"
                        question:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 219977
                            text:
                              type: string
                              example: "How did we do?"
                            metric:
                              type: string
                              example: "csat"
                        sentiment:
                          type: string
                          example: "neutral"
                        survey:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: "Follow-up CSAT"
                        response_id:
                          type: integer
                          example: 1
                  id:
                    type: integer
                    example: 1
                  choice:
                    type: string
                    example: "3"
                  choice_label:
                    type: string
                    example: "Okay, but not great"
                  choices:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example: ["Option1", "Option2", "Option3"]
                  comment:
                    type: string
                    nullable: true
                    example: "Very slow!"
                  follow_up_answer:
                    type: string
                    nullable: true
                    example: "Thank you!"
                  follow_up_answer_choice:
                    type: string
                    nullable: true
                    example: "yes"
                  follow_up_answer_choices:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example: ["Option1", "Option2", "Option3"]
                  published_as_testimonial:
                    type: boolean
                    example: false
                  created:
                    type: string
                    format: date-time
                    example: "2024-01-01T00:00:00Z"
                  modified:
                    type: string
                    format: date-time
                    example: "2024-01-01T00:00:00Z"
                  question:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      text:
                        type: string
                        example: "How did we do?"
                      metric:
                        type: string
                        example: "csat"
                  sentiment:
                    type: string
                    example: "neutral"
                  survey:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: "Follow-up CSAT"
                  response_id:
                    type: integer
                    example: 1
                example:
                  next: null
                  previous: null
                  count: 65
                  answers:
                    - id: 1
                      choice: "3"
                      choice_label: "Okay, but not great"
                      choices: null
                      comment: null
                      follow_up_answer: null
                      follow_up_answer_choice: "yes"
                      follow_up_answer_choices: null
                      published_as_testimonial: false
                      created: "2024-10-11T05:38:19Z"
                      modified: "2024-11-12T03:17:13.413332Z"
                  question:
                    id: 1
                    text: "How did we do?"
                    metric: "csat"
                  sentiment: "neutral"
                  survey:
                    - id: 1
                      name: "Generic"
                  response_id: 1
  /api/v1/customers/{customer_id}:
    put:
      operationId: updateCustomerById
      tags:
        - Customers
      summary: Update customer by ID
      description: |
        Update a customer by ID.

        Updating the `custom_attributes` or `tags` fields will overwrite any existing values.

        Customers accept arrays in `custom_attributes`.

        Required scopes: `write customers`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_id:
                  type: string
                  example: "1"
                name:
                  type: string
                  example: "Tester McTestFace"
                company:
                  type: string
                  example: "Simplesat"
                language:
                  type: string
                  example: "en"
                tags:
                  type: array
                  items:
                    type: string
                  example: ["tag1", "tag2"]
                custom_attributes:
                  type: object
                  example:
                    Country: "United States"
                    City: "San Francisco"
                    Channels: ["Web", "Mobile App"]
              example:
                external_id: "1"
                name: "Tester McTestFace"
                company: "Simplesat"
                language: "en"
                tags: ["tag1", "tag2"]
                custom_attributes:
                  Country: "United States"
                  City: "San Francisco"
                  Channels: ["Web", "Mobile App"]
      parameters:
        - name: customer_id
          description: The ID of the customer to update
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  external_id:
                    type: string
                    example: "12345"
                  name:
                    type: string
                    example: "Tester McTestFace"
                  email:
                    type: string
                    example: "tester@simplesat.io"
                  company:
                    type: string
                    example: "Simplesat"
                  language:
                    type: string
                    example: "en"
                  tags:
                    type: array
                    items:
                      type: string
                      example: "tag1"
                    example: ["tag1", "tag2"]
                  custom_attributes:
                    type: object
                    example:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                example:
                  id: 25754952
                  external_id: "1"
                  name: "Tester McTestFace"
                  email: "tester@simplesat.io"
                  company: "Simplesat"
                  language: "en"
                  tags: ["tag1", "tag2"]
                  custom_attributes:
                    Country: "United States"
                    City: "San Francisco"
                    Channels: ["Web", "Mobile App"]
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No Customer matches the given query."
                example:
                  detail: "No Customer matches the given query."
    get:
      operationId: getCustomerById
      tags:
        - Customers
      summary: Get customer by ID
      description: |
        Get a customer by ID.

        Required scopes: `read customers`
      parameters:
        - name: customer_id
          description: The ID of the customer to retrieve
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  external_id:
                    type: string
                    example: "12345"
                  name:
                    type: string
                    example: "Tester McTestFace"
                  email:
                    type: string
                    example: "tester@simplesat.io"
                  company:
                    type: string
                    example: "Simplesat"
                  language:
                    type: string
                    example: "en"
                  tags:
                    type: array
                    items:
                      type: string
                    example: ["tag1", "tag2"]
                  custom_attributes:
                    type: object
                    example:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                example:
                  id: 1
                  external_id: "1"
                  name: "Tester McTestFace"
                  email: "tester@simplesat.io"
                  company: "Simplesat"
                  language: "en"
                  tags: ["tag1", "tag2"]
                  custom_attributes:
                    Country: "United States"
                    City: "San Francisco"
                    Channels: ["Web", "Mobile App"]
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No Customer matches the given query."
                example:
                  detail: "No Customer matches the given query."
  /api/v1/customers:
    post:
      operationId: createOrUpdateCustomer
      summary: Create or update customer
      description: |
        Create or update a customer. 

        If the customer with the specified email address already exists, the
        existing customer will be updated.

        Updating the `custom_attributes` or `tags` fields will overwrite any existing values.

        Customers accept arrays in `custom_attributes`.

        Required scopes: `write customers`
      tags:
        - Customers
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_id:
                  type: string
                  example: "12345"
                email:
                  type: string
                  example: "tester@simplesat.io"
                name:
                  type: string
                  example: "Tester McTestFace"
                company:
                  type: string
                  example: "Simplesat"
                language:
                  type: string
                  example: "en"
                tags:
                  type: array
                  items:
                    type: string
                  example: ["tag1", "tag2"]
                custom_attributes:
                  type: object
                  example:
                    Country: "United States"
                    City: "San Francisco"
                    Channels: ["Web", "Mobile App"]
              example:
                email: "tester@simplesat.io"
                name: "Tester McTestFace"
                company: "Simplesat"
                language: "en"
                tags: ["tag1", "tag2"]
                custom_attributes:
                  Country: "United States"
                  City: "San Francisco"
                  Channels: ["Web", "Mobile App"]
      responses:
        "201":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  external_id:
                    type: string
                    example: "12345"
                  email:
                    type: string
                    example: "tester@simplesat.io"
                  name:
                    type: string
                    example: "Tester McTestFace"
                  tags:
                    type: array
                    items:
                      type: string
                    example:
                      - "tag1"
                      - "tag2"
                  custom_attributes:
                    type: object
                    example:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                  company:
                    type: string
                    example: "Simplesat"
                  language:
                    type: string
                    example: "en"
                example:
                  id: 1
                  external_id: 1
                  name: "Tester McTestFace"
                  email: "tester@simplesat.io"
                  company: "Simplesat"
                  language: "en"
                  tags: ["tag1", "tag2"]
                  custom_attributes:
                    City: "San Francisco"
                    Channels: ["Web", "Mobile App"]
                    Country: "United States"
    get:
      operationId: listCustomers
      summary: List customers
      description: |
        Get a paginated list of customers with optional filtering by creation/modification dates and subscription status.

        Required scopes: `read customers`
      tags:
        - Customers
      parameters:
        - name: page
          description: The page number to retrieve
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          description: The number of records per page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 250
            default: 50
        - name: created_after
          description: Filter customers created after this date (ISO 8601 format)
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: "2025-01-01T00:00:00Z"
        - name: created_before
          description: Filter customers created before this date (ISO 8601 format)
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: "2025-12-31T23:59:59Z"
        - name: modified_after
          description: Filter customers modified after this date (ISO 8601 format)
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: "2025-01-01T00:00:00Z"
        - name: modified_before
          description: Filter customers modified before this date (ISO 8601 format)
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: "2025-12-31T23:59:59Z"
        - name: subscribed
          description: Filter customers by subscription status
          in: query
          required: false
          schema:
            type: boolean
            example: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    description: URL for the next page of results
                    example: "https://api.simplesat.io/api/v1/customers?page=2&page_size=50"
                  previous:
                    type: string
                    nullable: true
                    description: URL for the previous page of results
                    example: null
                  count:
                    type: integer
                    description: Total number of customers matching the query
                    example: 1
                  customers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        external_id:
                          type: string
                          example: "1"
                        name:
                          type: string
                          example: "Tester McTestFace"
                        email:
                          type: string
                          example: "tester@simplesat.io"
                        company:
                          type: string
                          example: "Simplesat"
                        language:
                          type: string
                          example: "en"
                        tags:
                          type: array
                          items:
                            type: string
                          example: ["tag1", "tag2"]
                        custom_attributes:
                          type: object
                          example:
                            Country: "United States"
                            City: "San Francisco"
                            Channels: ["Web", "Mobile App"]
                        created:
                          type: string
                          format: date-time
                          example: "2025-01-01T00:00:00.000000Z"
                        modified:
                          type: string
                          format: date-time
                          example: "2025-09-26T10:28:57.000000Z"
                        subscribed:
                          type: boolean
                          example: true
              example:
                next: null
                previous: null
                count: 1
                customers:
                  - id: 1
                    external_id: "1"
                    name: "Tester McTestFace"
                    email: "tester@simplesat.io"
                    company: "Simplesat"
                    language: "en"
                    tags: ["tag1", "tag2"]
                    custom_attributes:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                    created: "2025-01-01T00:00:00.000000Z"
                    modified: "2025-01-01T00:00:00.000000Z"
                    subscribed: true
  /api/v1/customers/bulk:
    post:
      operationId: bulkUpsertCustomers
      tags:
        - Customers
      summary: Bulk upsert customers
      description: |
        Bulk upsert customers, creating or updating multiple customers at once.

        Maximum 1000 customers per request.

        Updating the `custom_attributes` or `tags` fields will overwrite any existing values.

        Customers accept arrays in `custom_attributes`.

        Customers with invalid data will be ignored.

        Required scopes: `write customers`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customers:
                  type: array
                  items:
                    type: object
                    properties:
                      external_id:
                        type: string
                        example: "12345"
                      email:
                        type: string
                        example: "tester@simplesat.io"
                      name:
                        type: string
                        example: "Tester McTestFace"
                      tags:
                        type: array
                        items:
                          type: string
                        example: ["tag1", "tag2"]
                      custom_attributes:
                        type: object
                        example:
                          Country: "United States"
                          City: "San Francisco"
                          Channels: ["Web", "Mobile App"]
                      company:
                        type: string
                        example: "Simplesat"
              example:
                customers:
                  - external_id: 1
                    email: "tester@simplesat.io"
                    name: "Tester McTestFace"
                    company: "Simplesat"
                    tags: ["tag1", "tag2"]
                    custom_attributes:
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                      Country: "United States"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    example: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                  detail:
                    type: string
                    example: "Customer(s) successfully scheduled to be updated or created."
                example:
                  request_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                  detail: "Customer(s) successfully scheduled to be updated or created."
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      type: string
                      example: "This field is required."
                example:
                  customers:
                    - "This field is required."
  /api/v1/team-members/{team_member_id}:
    get:
      operationId: getTeamMemberById
      tags:
        - Team members
      summary: Get team member by ID
      description: |
        Get a team member by ID.

        Required scopes: `read team members`
      parameters:
        - name: team_member_id
          description: The ID of the team member to retrieve
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  external_id:
                    type: string
                    example: "1"
                  name:
                    type: string
                    example: "Tester McTestFace"
                  email:
                    type: string
                    example: "tester@simplesat.io"
                  custom_attributes:
                    type: object
                    example:
                      Department: "Support"
                      Level: "Senior"
                example:
                  id: 1
                  external_id: "1"
                  name: "Tester McTestFace"
                  email: "tester@simplesat.io"
                  custom_attributes:
                    Department: "Support"
                    Level: "Senior"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No TeamMember matches the given query."
                example:
                  detail: "No TeamMember matches the given query."
  /api/v1/team-members:
    post:
      operationId: createOrUpdateTeamMember
      tags:
        - Team members
      summary: Create or update team member
      description: |
        Create or update a team member.

        If the team member with the specified email address already exists, the existing team member will be updated.

        Updating the `custom_attributes` field will overwrite any existing custom attributes.

        Required scopes: `write team members`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_id:
                  type: string
                  example: "12345"
                name:
                  type: string
                  example: "Tester McTestFace"
                email:
                  type: string
                  example: "tester@simplesat.io"
                custom_attributes:
                  type: object
                  example:
                    Department: "Support"
                    Level: "Senior"
              example:
                external_id: "1"
                name: "Tester McTestFace"
                email: "tester@simplesat.io"
                custom_attributes:
                  Department: "Support"
                  Level: "Senior"
      responses:
        "201":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  external_id:
                    type: string
                    example: "12345"
                  name:
                    type: string
                    example: "Tester McTestFace"
                  email:
                    type: string
                    example: "tester@simplesat.io"
                  custom_attributes:
                    type: object
                    example:
                      Department: "Support"
                      Level: "Senior"
                example:
                  id: 1
                  external_id: "1"
                  name: "Tester McTestFace"
                  email: "tester@simplesat.io"
                  custom_attributes:
                    Department: "Support"
                    Level: "Senior"
  /api/v1/responses/{response_id}:
    get:
      operationId: getResponseById
      tags:
        - Responses
      summary: Get response by ID
      description: |
        Get a response by ID.

        Required scopes: `read responses`
      parameters:
        - name: response_id
          description: The ID of the response to retrieve
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  survey:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: "Follow-up CSAT"
                    example:
                      id: 1
                      name: "Follow-up CSAT"
                  tags:
                    type: array
                    items:
                      type: string
                      example: "tag1"
                    example:
                      - "tag1"
                      - "tag2"
                  created:
                    type: string
                    format: date-time
                    example: "2024-01-01T00:00:00Z"
                  modified:
                    type: string
                    format: date-time
                    example: "2024-01-02T00:00:00.000000Z"
                  ip_address:
                    type: string
                    example: "192.168.1.1"
                  language:
                    type: string
                    example: "en"
                  ticket:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 100
                      external_id:
                        type: string
                        example: "12345"
                      subject:
                        type: string
                        example: "Issue with product"
                      custom_attributes:
                        type: object
                        example:
                          Priority: "Medium"
                          Category: "Support"
                    example:
                      id: 100
                      external_id: "12345"
                      subject: "Issue with product"
                      custom_attributes:
                        Priority: "Medium"
                        Category: "Support"
                  team_members:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        role:
                          type: string
                          example: "Assignee"
                        is_primary:
                          type: boolean
                          example: true
                        external_id:
                          type: string
                          example: "1"
                        name:
                          type: string
                          example: "Tester McTestFace"
                        email:
                          type: string
                          example: "tester@simplesat.io"
                      example:
                        id: 1
                        role: "Assignee"
                        is_primary: true
                        external_id: "1"
                        name: "Tester McTestFace"
                        email: "tester@simplesat.io"
                    example:
                      - id: 1
                        role: "Assignee"
                        is_primary: true
                        external_id: "1"
                        name: "Tester McTestFace"
                        email: "tester@simplesat.io"
                      - id: 1
                        role: "Closed by"
                        is_primary: false
                        external_id: "1"
                        name: "Tester McTestFace"
                        email: "tester@simplesat.io"
                  customer:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      external_id:
                        type: string
                        example: "1"
                      name:
                        type: string
                        example: "Tester McTestFace"
                      email:
                        type: string
                        example: "tester@simplesat.io"
                      company:
                        type: string
                        example: "Simplesat"
                      tags:
                        type: array
                        items:
                          type: string
                          example: "premium"
                        example:
                          - "premium"
                          - "beta"
                      custom_attributes:
                        type: object
                        example:
                          Country: "United States"
                          City: "San Francisco"
                          Channels: ["Web", "Mobile App"]
                    example:
                      id: 1
                      external_id: "1"
                      name: "Tester McTestFace"
                      email: "tester@simplesat.io"
                      company: "Simplesat"
                      tags:
                        - "premium"
                        - "beta"
                      custom_attributes:
                        Country: "United States"
                        City: "San Francisco"
                        Channels: ["Web", "Mobile App"]
                  answers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        question:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            text:
                              type: string
                              example: "How satisfied are you?"
                            metric:
                              type: string
                              example: "csat"
                          example:
                            id: 1
                            text: "How satisfied are you?"
                            metric: "csat"
                        choice:
                          type: string
                          example: "4"
                        choices:
                          type: array
                          items:
                            type: string
                            example: "1"
                          example:
                            - "1"
                            - "2"
                            - "3"
                        comment:
                          type: string
                          example: "Great service!"
                        sentiment:
                          type: string
                          example: "positive"
                        follow_up_answer:
                          type: string
                          example: "Thank you!"
                        choice_label:
                          type: string
                          example: "Absolutely amazing!"
                        follow_up_answer_choice:
                          type: string
                          example: "yes"
                        follow_up_answer_choices:
                          type: array
                          items:
                            type: string
                            example: "Option A"
                          example:
                            - "Option A"
                            - "Option B"
                        follow_up_question:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 2
                            text:
                              type: string
                              example: "Would you recommend us to your friends?"
                            metric:
                              type: string
                              example: "custom"
                          example:
                            id: 2
                            text: "Would you recommend us to your friends?"
                            metric: "csat"
                        source:
                          type: string
                          example: "generic_embed"
                      example:
                        id: 1000
                        question:
                          id: 1
                          text: "How satisfied are you?"
                          metric: "satisfaction"
                        choice: "5"
                        choices:
                          - "1"
                          - "2"
                          - "3"
                        comment: "Great service!"
                        sentiment: "positive"
                        follow_up_answer: "Thank you!"
                        choice_label: "Absolutely amazing!"
                        follow_up_answer_choice: "yes"
                        follow_up_answer_choices:
                          - "Option A"
                          - "Option B"
                        follow_up_question:
                          id: 2
                          text: "Would you recommend us to your friends?"
                          metric: "custom"
                        source: "generic_embed"
                  source:
                    type: string
                    example: "generic_embed"
                example:
                  id: 1
                  survey:
                    id: 1
                    name: "Survey name"
                  tags: []
                  created: "2024-01-01T00:00:00Z"
                  modified: "2024-01-01T00:00:00Z"
                  ip_address: "192.168.1.1"
                  ticket:
                    id: 1
                    external_id: "1"
                    subject: "Ticket subject"
                    custom_attributes:
                      Priority: "Medium"
                      Category: "Support"
                  team_members:
                    - id: 1
                      role: "Team member"
                      is_primary: true
                      external_id: "1"
                      name: "Tester McTestFace"
                      email: "tester@simplesat.io"
                  customer:
                    id: 1
                    external_id: "1"
                    name: "Tester McTestFace"
                    email: "tester@simplesat.io"
                    company: "Simplesat"
                    tags: ["tag1", "tag2"]
                    custom_attributes:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                  answers:
                    - id: 1
                      question:
                        id: 1
                        text: "How did we do?"
                        metric: "csat"
                      choice: "4"
                      choices: null
                      comment: null
                      sentiment: "positive"
                      follow_up_answer: "Great!"
                      choice_label: "Great, I'm satisfied"
                      follow_up_answer_choice: "yes"
                      follow_up_answer_choices: null
                      follow_up_question:
                        id: 1
                        text: "Was there anything in particular we did that delighted you?"
                        metric: "custom"
                  source: "generic_embed"
                  language: "en"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No Response matches the given query."
                example:
                  detail: "No Session matches the given query."
  /api/v1/responses/search:
    post:
      operationId: searchResponses
      tags:
        - Responses
      summary: Search for responses
      description: |
        Search for responses.

        Required scopes: `read responses`

        Accepted date filters are:
          - `created_start_date`
          - `created_end_date`
          - `modified_start_date`
          - `modified_end_date`

        Accepted `operator` values are:
          - `and`
          - `or`

        Accepted `comparison` values are:
          - `is`
          - `is_not`
          - `contains`
          - `does_not_contain`
          - `is_unknown`
          - `has_any_value`

        Accepted `key` values are:
          - `choice_value`
          - `collaborator`
          - `company`
          - `comment`
          - `customer` (name)
          - `customer.email`
          - `ip`
          - `metric`
          - `sentiment`
          - `source`
          - `survey` (token)
          - `tag`
          - `team_member` (name)
          - `team_member.email`
          - `team_member.id` (external_id)
          - `ticket_id` (external_id)
          - `customer.attribute` (add the `attribute` field to the filter to specify the attribute to filter on)
          - `ticket.attribute` (add the `attribute` field to the filter to specify the attribute to filter on)

      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                  format: date-time
                  example: "2024-01-01T00:00:00Z"
                created_start_date:
                  type: string
                  format: date-time
                  example: "2024-01-01T00:00:00Z"
                end_date:
                  type: string
                  format: date-time
                  example: "2024-01-31T23:59:59Z"
                created_end_date:
                  type: string
                  format: date-time
                  example: "2024-01-31T23:59:59Z"
                modified_start_date:
                  type: string
                  format: date-time
                  example: "2024-01-01T00:00:00Z"
                modified_end_date:
                  type: string
                  format: date-time
                  example: "2024-01-31T23:59:59Z"
                operator:
                  type: string
                  example: "and"
                filters:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        example: "customer.email"
                      values:
                        type: array
                        items:
                          type: string
                        example: ["tester@simplesat.io"]
                      attribute:
                        type: string
                        example: "city"
                      comparison:
                        type: string
                        example: "is"
              example:
                created_start_date: "2024-01-01T00:00:00Z"
                created_end_date: "2024-12-31T23:59:59Z"
                operator: "and"
                filters:
                  - key: "customer.email"
                    values:
                      - "tester@simplesat.io"
                    comparison: "is"
      parameters:
        - name: page_size
          description: The number of responses to return per page
          in: query
          schema:
            type: integer
          example: 50
        - name: page
          description: The page number to return
          in: query
          schema:
            type: integer
          example: 1
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    example: "https://api.simplesat.io/api/v1/responses/search?page=2&page_size=50"
                  previous:
                    type: string
                    nullable: true
                    example: null
                  count:
                    type: integer
                    example: 100
                  responses:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        survey:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: "Follow-up CSAT"
                        tags:
                          type: array
                          items:
                            type: string
                          example: ["tag1", "tag2"]
                        created:
                          type: string
                          format: date-time
                          example: "2024-01-01T00:00:00Z"
                        modified:
                          type: string
                          format: date-time
                          example: "2024-01-01T00:00:00Z"
                        ip_address:
                          type: string
                          example: "192.168.1.1"
                        language:
                          type: string
                          example: "en"
                        ticket:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            external_id:
                              type: string
                              example: "1"
                            subject:
                              type: string
                              example: "Ticket subject"
                            custom_attributes:
                              type: object
                              example:
                                Priority: "Medium"
                                Category: "Support"
                        team_members:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              role:
                                type: string
                                example: "Agent"
                              is_primary:
                                type: boolean
                                example: true
                              external_id:
                                type: string
                                example: "1"
                              name:
                                type: string
                                example: "Tester McTestFace"
                              email:
                                type: string
                                example: "tester@simplesat.io"
                        customer:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            external_id:
                              type: string
                              example: "1"
                            name:
                              type: string
                              example: "Tester McTestFace"
                            email:
                              type: string
                              example: "tester@simplesat.io"
                            company:
                              type: string
                              example: "Simplesat"
                            tags:
                              type: array
                              items:
                                type: string
                              example: ["tag1", "tag2"]
                            custom_attributes:
                              type: object
                              example:
                                Country: "United States"
                                City: "San Francisco"
                                Channels: ["Web", "Mobile App"]
                        answers:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              question:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                    example: 1
                                  text:
                                    type: string
                                    example: "How did we do?"
                                  metric:
                                    type: string
                                    example: "csat"
                              choice:
                                type: string
                                example: "4"
                              choices:
                                type: array
                                items:
                                  type: string
                                nullable: true
                                example: ["1", "2", "3"]
                              comment:
                                type: string
                                nullable: true
                                example: "Thank you!"
                              sentiment:
                                type: string
                                example: "positive"
                              follow_up_answer:
                                type: string
                                example: "Great!"
                              choice_label:
                                type: string
                                example: "Great, I'm satisfied"
                              follow_up_answer_choice:
                                type: string
                                nullable: true
                                example: "yes"
                              follow_up_answer_choices:
                                type: array
                                items:
                                  type: string
                                nullable: true
                                example: ["Option A", "Option B"]
                              follow_up_question:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                    example: 1
                                  text:
                                    type: string
                                    example: "Was there anything in particular we did that delighted you?"
                                  metric:
                                    type: string
                                    example: "custom"
                              language:
                                type: string
                                example: "en"
                        source:
                          type: string
                          example: "generic_embed"
                example:
                  next: null
                  previous: null
                  count: 1
                  responses:
                    - id: 1
                      survey:
                        id: 1
                        name: "CSAT Survey"
                      language: "en"
                      tags: ["tag1", "tag2"]
                      created: "2024-01-01T00:00:00Z"
                      modified: "2024-01-01T00:00:00Z"
                      ip_address: "192.168.1.1"
                      ticket:
                        id: 1
                        external_id: "1"
                        subject: "Ticket subject"
                        custom_attributes:
                          Priority: "Medium"
                          Category: "Support"
                      team_members:
                        - id: 1
                          role: "Agent"
                          is_primary: true
                          external_id: "1"
                          name: "Tester McTestFace"
                          email: "tester@simplesat.io"
                      customer:
                        id: 1
                        external_id: "1"
                        name: "Tester McTestFace"
                        email: "tester@simplesat.io"
                        company: "Simplesat"
                        tags: ["tag1", "tag2"]
                        custom_attributes:
                          Country: "United States"
                          City: "San Francisco"
                          Channels: ["Web", "Mobile App"]
                      answers:
                        - id: 1
                          question:
                            id: 1
                            text: "How did we do?"
                            metric: "csat"
                          choice: "4"
                          choices: ["Option1", "Option2"]
                          comment: "Great!"
                          sentiment: "positive"
                          follow_up_answer: "Great!"
                          follow_up_answer_choice: "yes"
                          follow_up_answer_choices: ["Option A", "Option B"]
                          follow_up_question:
                            id: 1
                            text: "Was there anything in particular we did that delighted you?"
                            metric: "custom"
                          source: "generic_embed"
                          language: "en"
  /api/v1/responses/create-or-update:
    post:
      operationId: createOrUpdateResponse
      tags:
        - Responses
      summary: Create or update response
      description: |
        Create or update a response.

        If the response with the specified external ID already exists, the existing response will be updated.

        When creating a new response, the `survey_id` and `answers` fields are required. The `answers` array should have at least one item with the `question_id` and either a `choice` or `choices` field.

        The customer and team members will be created if they do not already exist with the specified email address. Otherwise, the response will be linked to the existing customer and team member.
        Team members and customers without emails will be ignored.

        Updating any `tags` or `custom_attributes` field will overwrite any existing values.

        When updating a response none of the fields are required, but at least one field must be provided.

        Required scopes: `write responses`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - survey_id
              properties:
                survey_id:
                  type: integer
                  example: 1
                language:
                  type: string
                  example: "en"
                created:
                  type: string
                  format: date-time
                  description: Optional date and time to set as the response creation timestamp (for example when importing or syncing historical responses).
                  example: "2024-01-01T00:00:00Z"
                tags:
                  type: array
                  items:
                    type: string
                    example: "asset"
                  example: ["asset", "issue"]
                answers:
                  type: array
                  items:
                    type: object
                    required:
                      - question_id
                    properties:
                      question_id:
                        type: integer
                        example: 1
                      choice:
                        type: string
                        example: "4"
                      choices:
                        type: array
                        items:
                          type: string
                          example: "Option1"
                        example: ["Option1", "Option2"]
                      comment:
                        type: string
                        example: "Great!"
                      sentiment:
                        type: string
                        example: "positive"
                      follow_up_answer:
                        type: string
                        example: "Thank you!"
                      follow_up_answer_choice:
                        type: string
                        example: "yes"
                      follow_up_answer_choices:
                        type: array
                        items:
                          type: string
                          example: "Option A"
                        example: ["Option A", "Option B"]
                    example:
                      survey_id: 1
                      answers:
                        - question_id: 1
                          choice: "4"
                      customer:
                        email: tester@simplesat.io
                team_members:
                  type: array
                  items:
                    type: object
                    required:
                      - email
                      - role
                      - is_primary
                    properties:
                      external_id:
                        type: string
                        example: "1"
                      name:
                        type: string
                        example: "Tester McTestFace"
                      email:
                        type: string
                        example: "tester@simplesat.io"
                      custom_attributes:
                        type: object
                        example:
                          Level: "Senior"
                          Group: "Support"
                      role:
                        type: string
                        example: "Closed by"
                      is_primary:
                        type: boolean
                        example: true
                    example:
                      - external_id: "1"
                        name: "Tester McTestFace"
                        email: "tester@simplesat.io"
                        custom_attributes:
                          Level: "Senior"
                          Group: "Support"
                        role: "Closed by"
                        is_primary: true
                ticket:
                  type: object
                  properties:
                    external_id:
                      type: string
                      example: "1"
                    subject:
                      type: string
                      example: "Coffee machine broken!"
                    custom_attributes:
                      type: object
                      example:
                        Priority: "Medium"
                        Category: "Support"
                  example:
                    external_id: "1"
                    subject: "Coffee machine broken!"
                    custom_attributes:
                      Priority: "Medium"
                      Category: "Support"
                customer:
                  type: object
                  required:
                    - email
                  properties:
                    external_id:
                      type: string
                      example: "1"
                    name:
                      type: string
                      example: "Tester McTestFace"
                    email:
                      type: string
                      example: "tester@simplesat.io"
                    tags:
                      type: array
                      items:
                        type: string
                        example: "asset"
                      example: ["asset", "issue"]
                    company:
                      type: string
                      example: "Simplesat"
                    custom_attributes:
                      type: object
                      example:
                        Country: "United States"
                        City: "San Francisco"
                        Channels: ["Web", "Mobile App"]
                  example:
                    external_id: "1"
                    name: "Tester McTestFace"
                    email: "tester@simplesat.io"
                    tags: ["asset", "issue"]
                    company: "Simplesat"
                    custom_attributes:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
              example:
                survey_id: 1
                created: "2024-01-01T00:00:00Z"

      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  survey_id:
                    type: integer
                    example: 1
                  language:
                    type: string
                    example: "en"
                  ticket:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      external_id:
                        type: string
                        example: "1"
                      subject:
                        type: string
                        example: "Issue with product"
                      custom_attributes:
                        type: object
                        example:
                          Priority: "Medium"
                          Category: "Support"
                  team_members:
                    type: array
                    items:
                      type: object
                      properties:
                        external_id:
                          type: string
                          example: "1"
                        name:
                          type: string
                          example: "Tester McTestFace"
                        email:
                          type: string
                          example: "tester@simplesat.io"
                        custom_attributes:
                          type: object
                          example:
                            Group: "Support"
                            Level: "Senior"
                        role:
                          type: string
                          example: "Developer"
                        is_primary:
                          type: boolean
                          example: true
                  customer:
                    type: object
                    properties:
                      external_id:
                        type: string
                        example: "1"
                      name:
                        type: string
                        example: "Simplesat"
                      email:
                        type: string
                        example: "tester@simplesat.io"
                      tags:
                        type: array
                        items:
                          type: string
                        example: ["premium", "beta"]
                      company:
                        type: string
                        example: "Simplesat"
                      custom_attributes:
                        type: object
                        example:
                          Country: "United States"
                          City: "San Francisco"
                          Channels: ["Web", "Mobile App"]
                  answers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        question:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            text:
                              type: string
                              example: "How did we do?"
                            metric:
                              type: string
                              example: "csat"
                          example:
                            id: 1
                            text: "How did we do?"
                            metric: "csat"
                        choice:
                          type: string
                          example: "4"
                        choices:
                          type: array
                          items:
                            type: string
                          example: ["Option A", "Option B"]
                        comment:
                          type: string
                          example: "Great service!"
                        sentiment:
                          type: string
                          example: "positive"
                        follow_up_answer:
                          type: string
                          example: "Thank you!"
                        choice_label:
                          type: string
                          example: "Absolutely amazing!"
                        follow_up_answer_choice:
                          type: string
                          example: "yes"
                        follow_up_answer_choices:
                          type: array
                          items:
                            type: string
                          example: ["Option A", "Option B"]
                        follow_up_question:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 2
                            text:
                              type: string
                              example: "Was there anything in particular we did that delighted you?"
                            metric:
                              type: string
                              example: "custom"
                          example:
                            id: 2
                            text: "Was there anything in particular we did that delighted you?"
                            metric: "custom"
                  id:
                    type: integer
                    example: 1
                  tags:
                    type: array
                    items:
                      type: string
                    example: ["tag1", "tag2"]
                  created:
                    type: string
                    format: date-time
                    example: "2024-01-01T01:00:00Z"
                  modified:
                    type: string
                    format: date-time
                    example: "2024-01-01T01:00:00Z"
                  ip_address:
                    type: string
                    example: "192.168.1.1"
                example:
                  survey_id: 1
                  ticket:
                    id: 1
                    external_id: "1"
                    subject: "Coffee machine broken!"
                    custom_attributes:
                      Priority: "Medium"
                      Category: "Support"
                  team_members:
                    - external_id: "1"
                      name: "Tester McTestFace"
                      email: "tester@simplesat.io"
                      custom_attributes:
                        Level: "Senior"
                        Group: "Support"
                      role: "Closed by"
                      is_primary: true
                  customer:
                    external_id: "1"
                    name: "Tester McTestFace"
                    email: "tester@simplesat.io"
                    tags: ["asset", "issue"]
                    company: "Simplesat"
                    custom_attributes:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                  answers:
                    - id: 1
                      question:
                        id: 1
                        text: "How did we do?"
                        metric: "csat"
                      choice: "4"
                      choices: null
                      comment: null
                      sentiment: "positive"
                      follow_up_answer: "Great!"
                      choice_label: "Great, I'm satisfied"
                      follow_up_answer_choice: "yes"
                      follow_up_answer_choices: null
                      follow_up_question:
                        id: 2
                        text: "Was there anything in particular we did that delighted you?"
                        metric: "custom"
                  id: 1
                  tags: ["tag1", "tag2"]
                  created: "2024-01-01T01:00:00Z"
                  modified: "2024-01-01T01:00:00Z"
                  ip_address: "192.168.1.1"
                  survey:
                    id: 1
                    name: "CSAT Survey"
                  language: "en"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  survey_id:
                    type: array
                    items:
                      type: string
                    example: ["This field is required."]
                  answers:
                    type: array
                    items:
                      type: string
                    example: ["This field is required."]
                example:
                  survey_id:
                    - "This field is required."
                  answers:
                    - "This field is required."
  /api/v1/responses/{response_id}/update:
    put:
      operationId: updateResponseById
      tags:
        - Responses
      summary: Update response by ID
      description: |
        Update a response by ID.

        Updating the `tags` field, or any of the `custom_attributes` fields will overwrite any existing values.

        Required scopes: `write responses`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - survey_id
              properties:
                survey_id:
                  type: integer
                  example: 1
                language:
                  type: string
                  example: "en"
                created:
                  type: string
                  format: date-time
                  example: "2024-01-01T00:00:00Z"
                tags:
                  type: array
                  items:
                    type: string
                  example: ["tag1", "tag2"]
                answers:
                  type: array
                  items:
                    type: object
                    required:
                      - question_id
                    properties:
                      question_id:
                        type: integer
                        example: 1
                      choice:
                        type: string
                        example: "4"
                      choices:
                        type: array
                        items:
                          type: string
                        example: ["1", "2", "3", "4", "5"]
                      comment:
                        type: string
                        example: "Excellent service!"
                      sentiment:
                        type: string
                        example: "positive"
                      follow_up_answer:
                        type: string
                        example: "Thank you!"
                      follow_up_answer_choice:
                        type: string
                        example: "yes"
                      follow_up_answer_choices:
                        type: array
                        items:
                          type: string
                        example: ["Option A", "Option B"]
                team_members:
                  type: array
                  items:
                    type: object
                    required:
                      - email
                    properties:
                      external_id:
                        type: string
                        example: "1"
                      name:
                        type: string
                        example: "Tester McTestFace"
                      email:
                        type: string
                        example: "tester@simplesat.io"
                      custom_attributes:
                        type: object
                        example:
                          Group: "Support"
                          Level: "Senior"
                      role:
                        type: string
                        example: "Assignee"
                      is_primary:
                        type: boolean
                        example: true
                ticket:
                  type: object
                  properties:
                    external_id:
                      type: string
                      example: "1"
                    subject:
                      type: string
                      example: "Issue with product installation."
                    custom_attributes:
                      type: object
                      example:
                        Priority: "Medium"
                        Category: "Support"
                customer:
                  type: object
                  required:
                    - email
                  properties:
                    external_id:
                      type: string
                      example: "1"
                    name:
                      type: string
                      example: "Tester McTestFace"
                    email:
                      type: string
                      example: "tester@simplesat.io"
                    tags:
                      type: array
                      items:
                        type: string
                      example: ["premium", "newsletter"]
                    company:
                      type: string
                      example: "Simplesat"
                    custom_attributes:
                      type: object
                      example:
                        Country: "United States"
                        City: "San Francisco"
                        Channels: ["Web", "Mobile App"]
              example:
                survey_id: 1
                created: "2024-01-01T00:00:00Z"
                answers:
                  - question_id: 1
                    choice: "4"
      parameters:
        - name: response_id
          description: The ID of the response to update
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  survey_id:
                    type: integer
                    example: 1
                  language:
                    type: string
                    example: "en"
                  ticket:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 100
                      external_id:
                        type: string
                        example: "1"
                      subject:
                        type: string
                        example: "Issue with product installation."
                      custom_attributes:
                        type: object
                        example:
                          Priority: "Medium"
                          Category: "Support"
                  team_members:
                    type: array
                    items:
                      type: object
                      properties:
                        external_id:
                          type: string
                          example: "1"
                        name:
                          type: string
                          example: "Tester McTestFace"
                        email:
                          type: string
                          example: "tester@simplesat.io"
                        custom_attributes:
                          type: object
                          example:
                            Group: "Support"
                            Level: "Senior"
                        role:
                          type: string
                          example: "Developer"
                        is_primary:
                          type: boolean
                          example: true
                  customer:
                    type: object
                    properties:
                      external_id:
                        type: string
                        example: "1"
                      name:
                        type: string
                        example: "Tester McTestFace"
                      email:
                        type: string
                        example: "tester@simplesat.io"
                      tags:
                        type: array
                        items:
                          type: string
                        example: ["premium", "newsletter"]
                      company:
                        type: string
                        example: "Simplesat"
                      custom_attributes:
                        type: object
                        example:
                          Country: "United States"
                          City: "San Francisco"
                          Channels: ["Web", "Mobile App"]
                  answers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        question:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 101
                            text:
                              type: string
                              example: "How satisfied are you with our service?"
                            metric:
                              type: string
                              example: "satisfaction"
                          example:
                            id: 101
                            text: "How satisfied are you with our service?"
                            metric: "satisfaction"
                        choice:
                          type: string
                          example: "4"
                        choices:
                          type: array
                          items:
                            type: string
                          example: ["1", "2", "3", "4", "5"]
                        comment:
                          type: string
                          example: "Excellent service!"
                        sentiment:
                          type: string
                          example: "positive"
                        follow_up_answer:
                          type: string
                          example: "Thank you for your feedback!"
                        choice_label:
                          type: string
                          example: "Absolutely amazing!"
                        follow_up_answer_choice:
                          type: string
                          example: "yes"
                        follow_up_answer_choices:
                          type: array
                          items:
                            type: string
                          example: ["Option A", "Option B"]
                        follow_up_question:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 202
                            text:
                              type: string
                              example: "Would you recommend us to your friends?"
                            metric:
                              type: string
                              example: "custom"
                          example:
                            id: 202
                            text: "Would you recommend us to your friends?"
                            metric: "custom"
                  id:
                    type: integer
                    example: 1
                  tags:
                    type: array
                    items:
                      type: string
                    example: ["tag1", "tag2"]
                  created:
                    type: string
                    format: date-time
                    example: "2024-01-01T01:00:00Z"
                  modified:
                    type: string
                    format: date-time
                    example: "2024-01-01T01:00:00Z"
                  ip_address:
                    type: string
                    example: "192.168.1.1"
                example:
                  survey_id: 1
                  ticket:
                    id: 1
                    external_id: "1"
                    subject: null
                    custom_attributes:
                      Priority: "Medium"
                      Category: "Support"
                  team_members:
                    - id: 1
                      external_id: "1"
                      name: "Tester McTestFace"
                      email: "tester@simplesat.io"
                      custom_attributes:
                        Group: "Support"
                        Level: "Senior"
                      role: "Team member"
                      is_primary: true
                  customer:
                    id: 1
                    external_id: "1"
                    name: "Tester McTestFace"
                    email: "tester@simplesat.io"
                    company: "Simplesat"
                    tags: ["tag1", "tag2"]
                    custom_attributes:
                      Country: "United States"
                      City: "San Francisco"
                      Channels: ["Web", "Mobile App"]
                  answers:
                    - id: 1
                      question:
                        id: 1
                        text: "How did we do?"
                        metric: "csat"
                      choice: "4"
                      choices: null
                      comment: null
                      sentiment: "positive"
                      follow_up_answer: "Great!"
                      choice_label: "Great, I'm satisfied"
                      follow_up_answer_choice: "yes"
                      follow_up_answer_choices: null
                      follow_up_question:
                        id: 1
                        text: "Was there anything in particular we did that delighted you?"
                        metric: "custom"
                  id: 1
                  tags: []
                  created: "2024-01-01T01:00:00Z"
                  modified: "2024-01-01T01:00:00Z"
                  ip_address: "192.168.1.1"
                  survey:
                    id: 1
                    name: "CSAT Survey"
                  language: "en"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No Session matches the given query."
  /api/v1/surveys:
    get:
      operationId: listSurveys
      tags:
        - Surveys
      summary: List surveys
      description: |
        List surveys.

        Required scopes: `read surveys`
      parameters:
        - description: The number of surveys to return per page
          example: 10
          in: query
          name: page_size
          schema:
            type: integer
        - example: 1
          in: query
          name: page
          schema:
            type: integer
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    example: "https://api.simplesat.io/api/v1/surveys?page=2&page_size=10"
                  previous:
                    type: string
                    nullable: true
                    example: null
                  count:
                    type: integer
                    example: 25
                  surveys:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: "Follow-up CSAT Survey"
                        metric:
                          type: string
                          example: "CSAT"
                        survey_token:
                          type: string
                          example: "z_3OxYijnEkfZSt6hLKxCRxBlu4CPQ9feLUAW4Eaen4"
                        survey_type:
                          type: string
                          example: "generic_embed"
                        brand_name:
                          type: string
                          example: "Simplesat"
                example:
                  next: "https://api.simplesat.io/api/v1/surveys?page=2&page_size=10"
                  previous: null
                  count: 25
                  surveys:
                    - id: 1
                      name: "Follow-up CSAT Survey"
                      metric: "CSAT"
                      survey_token: "z_3OxYijnEkfZSt6hLKxCRxBlu4CPQ9feLUAW4Eaen4"
                      survey_type: "generic_embed"
                      brand_name: "Simplesat"
  /api/v1/surveys/{survey_token}/email:
    post:
      operationId: sendSurveyByEmail
      tags:
        - Surveys
      summary: Send survey by email
      description: |
        Send a survey email.

        Only survey tokens of surveys with survey type `event_based_email` are accepted.

        Required scopes: `write surveys`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer:
                  type: object
                  required:
                    - email
                  properties:
                    id:
                      type: string
                      example: "1"
                    email:
                      type: string
                      example: "tester@simplesat.io"
                    name:
                      type: string
                      example: "Tester McTestFace"
                    company:
                      type: string
                      example: "Simplesat"
                    language:
                      type: string
                      example: "en"
                    custom_attributes:
                      type: object
                      example:
                        Country: "United States"
                        City: "San Francisco"
                team_member:
                  type: object
                  properties:
                    id:
                      type: string
                      example: "1"
                    email:
                      type: string
                      example: "tester@simplesat.io"
                    name:
                      type: string
                      example: "Tester McTestFace"
                    custom_attributes:
                      type: object
                      example:
                        Department: "Support"
                        Level: "Senior"
                ticket:
                  type: object
                  properties:
                    id:
                      type: string
                      example: "1"
                    subject:
                      type: string
                      example: "Issue with product installation."
                    custom_attributes:
                      type: object
                      example:
                        Priority: "Medium"
                        Category: "Support"
              example:
                customer:
                  id: "1"
                  email: "tester@simplesat.io"
                  name: "Tester McTestFace"
                  company: "Simplesat"
                  language: "en"
                  custom_attributes:
                    Country: "United States"
                    City: "San Francisco"
                team_member:
                  id: "1"
                  email: "tester@simplesat.io"
                  name: "Tester McTestFace"
                  custom_attributes:
                    Department: "Support"
                    Level: "Senior"
                ticket:
                  id: "1"
                  subject: "Ticket subject"
                  custom_attributes:
                    Priority: "Medium"
                    Category: "Support"
      parameters:
        - name: survey_token
          description: The token of the survey to send
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "Survey is scheduled to be sent"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer:
                    type: array
                    items:
                      type: string
                    example:
                      - "This field is required."
                example:
                  customer:
                    - "This field is required."
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "No Survey matches the given query."
  /api/v1/questions:
    get:
      operationId: listQuestions
      tags:
        - Questions
      parameters:
        - name: survey_id
          description: Filter questions by survey ID
          in: query
          schema:
            type: integer
          example: "1"
        - name: metric
          description: Filter questions by metric
          in: query
          schema:
            type: string
          example: "csat"
        - name: page_size
          description: The number of questions to return per page
          in: query
          schema:
            type: integer
          example: "10"
        - name: page
          in: query
          schema:
            type: integer
          example: "1"
      summary: List questions
      description: |
        List questions.

        Required scopes: `read questions`
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    example: "https://api.simplesat.io/api/v1/questions?page=2&page_size=10"
                  previous:
                    type: string
                    nullable: true
                    example: null
                  count:
                    type: integer
                    example: 79
                  questions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        survey:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: "CSAT Survey"
                        order:
                          type: integer
                          example: 1
                        metric:
                          type: string
                          example: "csat"
                        text:
                          type: string
                          example: "How did we do?"
                        rating_scale:
                          type: boolean
                          example: true
                        required:
                          type: boolean
                          example: true
                        choices:
                          type: array
                          items:
                            type: string
                            example: "2"
                          example: ["2", "3", "4"]
                        rules:
                          type: array
                          items:
                            type: object
                            example:
                              conditions: ["positive"]
                              action: "display_follow_up_question"
                              question:
                                id: 3
                                text: "Was there anything in particular we did that delighted you?"
                                required: false
                                choices: []
                                rules: []
                example:
                  next: "https://api.simplesat.io/api/v1/questions?page=2&page_size=10"
                  previous: null
                  count: 79
                  questions:
                    - id: 1
                      survey:
                        id: 1
                        name: "CSAT Survey"
                      order: 1
                      metric: "csat"
                      text: "How did we do?"
                      rating_scale: true
                      required: true
                      choices: ["2", "3", "4"]
                      rules:
                        - conditions: ["negative"]
                          action: "display_follow_up_question"
                          question:
                            id: 1
                            text: "We're sorry to have let you down, how could we improve?"
                            required: false
                            choices: []
                            rules: []
                        - conditions: ["neutral"]
                          action: "display_follow_up_question"
                          question:
                            id: 2
                            text: "Can you share your experience and how we could have done a little better?"
                            required: false
                            choices: []
                            rules: []
                        - conditions: ["positive"]
                          action: "display_follow_up_question"
                          question:
                            id: 3
                            text: "Was there anything in particular we did that delighted you?"
                            required: false
                            choices: []
                            rules: []
