openapi: 3.0.3
info:
  title: Survicate Data Export Personal Data Respondents 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: Respondents
  description: Operations related to survey respondents
paths:
  /v2/respondents/{respondentId}/attributes:
    get:
      operationId: listRespondentAttributes
      summary: List respondent attributes
      description: Returns all attributes (traits) associated with a specific respondent.
      tags:
      - Respondents
      parameters:
      - $ref: '#/components/parameters/respondentId'
      responses:
        '200':
          description: Respondent attributes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespondentAttributes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/respondents/{respondentId}/responses:
    get:
      operationId: listRespondentResponses
      summary: List respondent responses
      description: Returns all survey responses submitted by a specific respondent.
      tags:
      - Respondents
      parameters:
      - $ref: '#/components/parameters/respondentId'
      - 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
      responses:
        '200':
          description: A list of respondent responses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseList'
        '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
    RespondentAttributes:
      type: object
      properties:
        respondent_id:
          type: string
          description: Unique identifier for the respondent
        attributes:
          type: object
          additionalProperties: true
          description: Key-value pairs of respondent traits/attributes
          example:
            email: user@example.com
            name: Jane Doe
            plan: pro
            user_id: '12345'
    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:
    respondentId:
      name: respondentId
      in: path
      required: true
      description: The unique identifier of the respondent
      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}}`

        '