WTW HR Portal

openapi: 3.0.3
info:
  title: WTW HR Portal
  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
tags:
  - name: Employees
    description: Employee profile and engagement management
  - name: Content
    description: HR content and communications management
  - name: Benefits
    description: Benefits summary and enrollment status
  - name: Cases
    description: HR service case management
  - name: Total Rewards
    description: Total compensation and rewards statements
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:
        - Total Rewards
        - 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'
  /content:
    get:
      operationId: listContent
      summary: List Content
      description: Returns a list of HR content articles and communications.
      tags:
        - Content
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [article, announcement, policy, form, video]
          description: Filter by content type
        - name: audience
          in: query
          schema:
            type: string
          description: Filter by target audience segment
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Content list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentList'
    post:
      operationId: createContent
      summary: Create Content
      description: Create a new HR content item or communication.
      tags:
        - Content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentInput'
      responses:
        '201':
          description: Content created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Content'
        '400':
          $ref: '#/components/responses/BadRequest'
  /content/{contentId}:
    get:
      operationId: getContent
      summary: Get Content
      description: Retrieve a specific content item.
      tags:
        - Content
      parameters:
        - name: contentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Content item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Content'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateContent
      summary: Update Content
      description: Update an existing content item.
      tags:
        - Content
      parameters:
        - name: contentId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentInput'
      responses:
        '200':
          description: Content updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Content'
  /cases:
    get:
      operationId: listCases
      summary: List Cases
      description: Returns a list of HR service cases.
      tags:
        - Cases
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [open, pending, resolved, closed]
          description: Filter by case status
        - name: category
          in: query
          schema:
            type: string
          description: Filter by case category
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Case list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseList'
    post:
      operationId: createCase
      summary: Create Case
      description: Submit a new HR service case or inquiry.
      tags:
        - Cases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseInput'
      responses:
        '201':
          description: Case created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
  /cases/{caseId}:
    get:
      operationId: getCase
      summary: Get Case
      description: Retrieve a specific HR service case.
      tags:
        - Cases
      parameters:
        - name: caseId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Case details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCase
      summary: Update Case
      description: Update an existing HR service case.
      tags:
        - Cases
      parameters:
        - name: caseId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseUpdate'
      responses:
        '200':
          description: Case updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
  /employees/{employeeId}/benefits:
    get:
      operationId: getEmployeeBenefits
      summary: Get Employee Benefits
      description: Returns current benefits enrollment summary for an employee.
      tags:
        - Benefits
        - 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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    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
    EmployeeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    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
    Content:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        type:
          type: string
          enum: [article, announcement, policy, form, video]
        body:
          type: string
        audience:
          type: array
          items:
            type: string
        status:
          type: string
          enum: [draft, published, archived]
        publishedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ContentInput:
      type: object
      required:
        - title
        - type
        - body
      properties:
        title:
          type: string
        type:
          type: string
          enum: [article, announcement, policy, form, video]
        body:
          type: string
        audience:
          type: array
          items:
            type: string
        status:
          type: string
          enum: [draft, published]
    ContentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Content'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    Case:
      type: object
      properties:
        id:
          type: string
        caseNumber:
          type: string
        employeeId:
          type: string
        category:
          type: string
        subject:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [open, pending, resolved, closed]
        priority:
          type: string
          enum: [low, medium, high, urgent]
        assignedTo:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
    CaseInput:
      type: object
      required:
        - employeeId
        - category
        - subject
      properties:
        employeeId:
          type: string
        category:
          type: string
        subject:
          type: string
        description:
          type: string
        priority:
          type: string
          enum: [low, medium, high, urgent]
    CaseUpdate:
      type: object
      properties:
        status:
          type: string
          enum: [open, pending, resolved, closed]
        assignedTo:
          type: string
        notes:
          type: string
    CaseList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Case'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    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
security:
  - bearerAuth: []