openapi: 3.0.3
info:
  title: Survicate Data Export Personal Data Responses API
  description: 'The Survicate Data Export API (v2) allows retrieval of survey data collected in your Survicate account. It exposes resources for surveys, responses, respondents, and personal data management to integrate feedback into databases, CRMs, and custom solutions.

    '
  version: '2'
  contact:
    name: Survicate Developer Documentation
    url: https://developers.survicate.com/data-export/
  termsOfService: https://survicate.com/terms/
  license:
    name: Proprietary
    url: https://survicate.com/terms/
servers:
- url: https://data.survicate.com
  description: Survicate Data Export API base URL
security:
- BasicAuth: []
tags:
- name: Responses
  description: Operations related to survey responses
paths:
  /v2/surveys/{surveyId}/responses:
    get:
      operationId: listResponses
      summary: List all responses for a survey
      description: Returns a paginated list of all responses collected for a specific survey.
      tags:
      - Responses
      parameters:
      - $ref: '#/components/parameters/surveyId'
      - name: page
        in: query
        description: Page number for pagination
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: per_page
        in: query
        description: Number of responses per page
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: from
        in: query
        description: Filter responses from this date (ISO 8601)
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: Filter responses up to this date (ISO 8601)
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: A list of survey responses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/surveys/{surveyId}/responses/{responseId}:
    get:
      operationId: getResponse
      summary: Retrieve a response
      description: Returns detailed information about a specific survey response.
      tags:
      - Responses
      parameters:
      - $ref: '#/components/parameters/surveyId'
      - $ref: '#/components/parameters/responseId'
      responses:
        '200':
          description: Survey response details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Response:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the response
        survey_id:
          type: string
          description: Identifier of the survey this response belongs to
        respondent_id:
          type: string
          description: Identifier of the respondent who submitted this response
        completed_at:
          type: string
          format: date-time
          description: Date and time when the response was completed
        answers:
          type: array
          description: Answers submitted for each question
          items:
            $ref: '#/components/schemas/Answer'
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        per_page:
          type: integer
          description: Number of items per page
        total:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages
    ResponseList:
      type: object
      allOf:
      - $ref: '#/components/schemas/Pagination'
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Response'
    Answer:
      type: object
      properties:
        question_id:
          type: string
          description: Identifier of the question being answered
        value:
          oneOf:
          - type: string
          - type: number
          - type: array
            items:
              type: string
          description: The answer value (string for text, number for ratings/NPS, array for multi-select)
        answer_ids:
          type: array
          description: IDs of selected answer options (for closed-ended questions)
          items:
            type: string
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
        code:
          type: string
          description: An error code identifier
  parameters:
    surveyId:
      name: surveyId
      in: path
      required: true
      description: The unique identifier of the survey
      schema:
        type: string
    responseId:
      name: responseId
      in: path
      required: true
      description: The unique identifier of the response
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication failed or API key is missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 'Rate limit exceeded. Survicate allows up to 5 concurrent requests and up to 1000 requests per minute per workspace.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Use your Survicate API key as the value for Basic authentication. The API key can be found in the Survicate panel under Surveys Settings > Access Keys. Format: `Basic {{apiKey}}`

        '