openapi: 3.0.3
info:
  title: Allianz Engagement Survey Action Plans Analytics 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: Analytics
  description: Survey analytics, reporting, and insights operations
paths:
  /surveys/{survey_id}/analytics:
    get:
      operationId: getSurveyAnalytics
      summary: Allianz Engagement Survey Get Survey Analytics
      description: Retrieve aggregated engagement analytics and insights for a survey, including participation rates, question scores, and trend comparisons.
      tags:
      - Analytics
      parameters:
      - name: survey_id
        in: path
        required: true
        description: Unique identifier of the survey
        schema:
          type: string
        example: survey-500123
      - name: segment_by
        in: query
        required: false
        description: Segment analytics by this dimension
        schema:
          type: string
          enum:
          - business_unit
          - region
          - role_level
          - tenure
        example: business_unit
      responses:
        '200':
          description: Analytics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyAnalytics'
              examples:
                GetSurveyAnalytics200Example:
                  summary: Default getSurveyAnalytics 200 response
                  x-microcks-default: true
                  value:
                    survey_id: survey-500123
                    participation_rate: 70.1
                    engagement_score: 76.3
                    favorable_percentage: 74.8
                    question_scores:
                    - question_id: q-001
                      question: I am proud to work for Allianz
                      score: 4.2
                      favorable: 84.0
        '404':
          description: Survey not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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
    SurveyAnalytics:
      title: SurveyAnalytics
      type: object
      description: Aggregated analytics and insights for an engagement survey
      properties:
        survey_id:
          type: string
          description: Survey being analyzed
          example: survey-500123
        participation_rate:
          type: number
          format: double
          description: Percentage of invited employees who responded
          example: 70.1
        engagement_score:
          type: number
          format: double
          description: Overall engagement score out of 100
          example: 76.3
        favorable_percentage:
          type: number
          format: double
          description: Percentage of favorable responses across all questions
          example: 74.8
        question_scores:
          type: array
          description: Per-question score breakdown
          items:
            $ref: '#/components/schemas/QuestionScore'
    QuestionScore:
      title: QuestionScore
      type: object
      description: Score summary for a single survey question
      properties:
        question_id:
          type: string
          description: Question identifier
          example: q-001
        question:
          type: string
          description: The survey question text
          example: I am proud to work for Allianz
        score:
          type: number
          format: double
          description: Average score on a 1-5 scale
          example: 4.2
        favorable:
          type: number
          format: double
          description: Percentage of favorable responses (4-5 on Likert scale)
          example: 84.0
  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