openapi: 3.0.3
info:
  title: WTW HR Portal Benefits Employees API
  description: Willis Towers Watson HR Portal API for delivering personalized digital employee experiences. Enables HR teams to manage employee content, benefits communications, total rewards statements, case management, and targeted workforce messaging.
  version: 1.0.0
  contact:
    name: Willis Towers Watson
    url: https://www.wtwco.com/en-us/solutions/products/hr-portal-software
servers:
- url: https://api.wtwco.com/hrportal/v1
  description: WTW HR Portal API
security:
- bearerAuth: []
tags:
- name: Employees
  description: Employee profile and engagement management
paths:
  /employees:
    get:
      operationId: listEmployees
      summary: List Employees
      description: Returns a paginated list of employee records in the HR portal.
      tags:
      - Employees
      parameters:
      - name: department
        in: query
        schema:
          type: string
        description: Filter by department
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - inactive
          - leave
        description: Filter by employment status
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: Employee list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}:
    get:
      operationId: getEmployee
      summary: Get Employee
      description: Retrieve HR portal profile for a specific employee.
      tags:
      - Employees
      parameters:
      - name: employeeId
        in: path
        required: true
        schema:
          type: string
        description: Employee identifier
      responses:
        '200':
          description: Employee profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '404':
          $ref: '#/components/responses/NotFound'
  /employees/{employeeId}/total-rewards:
    get:
      operationId: getEmployeeTotalRewards
      summary: Get Employee Total Rewards
      description: Returns the total compensation and rewards summary for an employee.
      tags:
      - Employees
      parameters:
      - name: employeeId
        in: path
        required: true
        schema:
          type: string
      - name: year
        in: query
        schema:
          type: integer
        description: Plan year (defaults to current year)
      responses:
        '200':
          description: Total rewards statement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotalRewards'
        '404':
          $ref: '#/components/responses/NotFound'
  /employees/{employeeId}/benefits:
    get:
      operationId: getEmployeeBenefits
      summary: Get Employee Benefits
      description: Returns current benefits enrollment summary for an employee.
      tags:
      - Employees
      parameters:
      - name: employeeId
        in: path
        required: true
        schema:
          type: string
      - name: planYear
        in: query
        schema:
          type: integer
        description: Benefits plan year
      responses:
        '200':
          description: Benefits summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitsSummary'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    BenefitsSummary:
      type: object
      properties:
        employeeId:
          type: string
        planYear:
          type: integer
        enrollments:
          type: array
          items:
            type: object
            properties:
              planType:
                type: string
                enum:
                - medical
                - dental
                - vision
                - life
                - disability
                - hsa
                - 401k
                - other
              planName:
                type: string
              status:
                type: string
                enum:
                - active
                - waived
                - pending
              coverageLevel:
                type: string
              employeeContribution:
                type: number
                format: float
              employerContribution:
                type: number
                format: float
              effectiveDate:
                type: string
                format: date
    Employee:
      type: object
      properties:
        id:
          type: string
        employeeNumber:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        department:
          type: string
        jobTitle:
          type: string
        location:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
          - leave
        hireDate:
          type: string
          format: date
        manager:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
    TotalRewards:
      type: object
      properties:
        employeeId:
          type: string
        planYear:
          type: integer
        baseSalary:
          type: number
          format: float
        bonus:
          type: number
          format: float
        equity:
          type: number
          format: float
        benefits:
          type: object
          properties:
            healthInsurance:
              type: number
              format: float
            dental:
              type: number
              format: float
            vision:
              type: number
              format: float
            retirement:
              type: number
              format: float
            other:
              type: number
              format: float
        totalCompensation:
          type: number
          format: float
        currency:
          type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    EmployeeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT