openapi: 3.0.3
info:
  title: Allianz Engagement Survey Action Plans Responses API
  description: REST API for managing the full lifecycle of employee engagement surveys at Allianz. Supports survey creation, participant management, response collection, analytics reporting, and action plan tracking across global business units.
  version: 1.0.0
  contact:
    name: Allianz HR Technology
    url: https://www.allianz.com/en/careers/working-at-allianz.html
  x-generated-from: documentation
servers:
- url: https://api.allianz.com/engagement/v1
  description: Allianz Engagement Survey API production server
security:
- OAuth2: []
tags:
- name: Responses
  description: Survey response submission and retrieval operations
paths:
  /surveys/{survey_id}/responses:
    get:
      operationId: listResponses
      summary: Allianz Engagement Survey List Responses
      description: Retrieve anonymized survey responses for analysis. Individual responses are never linked to specific employees.
      tags:
      - Responses
      parameters:
      - name: survey_id
        in: path
        required: true
        description: Unique identifier of the survey
        schema:
          type: string
        example: survey-500123
      - name: business_unit
        in: query
        required: false
        description: Filter responses by business unit code
        schema:
          type: string
        example: BU-DE-001
      - name: limit
        in: query
        required: false
        description: Maximum number of responses to return
        schema:
          type: integer
          default: 50
        example: 50
      responses:
        '200':
          description: Responses retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseList'
              examples:
                ListResponses200Example:
                  summary: Default listResponses 200 response
                  x-microcks-default: true
                  value:
                    total: 876
                    items:
                    - response_id: resp-500789
                      survey_id: survey-500123
                      submitted_at: '2026-05-03T14:22:00Z'
                      answers:
                      - question_id: q-001
                        score: 4
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard error response
      properties:
        error:
          type: string
          description: Error code
          example: invalid_request
        message:
          type: string
          description: Human-readable error description
          example: The specified survey_id does not exist
        request_id:
          type: string
          description: Request identifier for support reference
          example: req-500999
    SurveyResponse:
      title: SurveyResponse
      type: object
      description: An anonymized survey response submission
      properties:
        response_id:
          type: string
          description: Unique identifier for the response
          example: resp-500789
        survey_id:
          type: string
          description: Survey this response belongs to
          example: survey-500123
        submitted_at:
          type: string
          format: date-time
          description: Timestamp when the response was submitted
          example: '2026-05-03T14:22:00Z'
        answers:
          type: array
          description: List of question answers
          items:
            $ref: '#/components/schemas/Answer'
    Answer:
      title: Answer
      type: object
      description: An individual question answer within a survey response
      properties:
        question_id:
          type: string
          description: Identifier of the question being answered
          example: q-001
        score:
          type: integer
          description: Numeric score on a 1-5 Likert scale
          minimum: 1
          maximum: 5
          example: 4
        text_response:
          type: string
          description: Open text response for free-text questions
          example: The team culture is very collaborative
    ResponseList:
      title: ResponseList
      type: object
      description: Paginated list of anonymized survey responses
      properties:
        total:
          type: integer
          description: Total number of responses
          example: 876
        items:
          type: array
          description: List of anonymized response records
          items:
            $ref: '#/components/schemas/SurveyResponse'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 client credentials for Allianz internal API access
      flows:
        clientCredentials:
          tokenUrl: https://api.allianz.com/oauth2/token
          scopes:
            surveys:read: Read survey definitions and configurations
            surveys:write: Create and manage surveys
            responses:read: Read anonymized survey responses
            analytics:read: Access survey analytics and reporting
            action_plans:write: Create and manage action plans