openapi: 3.0.3
info:
  title: Unum HR Connect Authentication Eligibility API
  description: The Unum HR Connect API provides a secure, real-time connection between Unum benefits and major HR platforms including Workday, ADP, and UKG. It automates eligibility checks, evidence of insurability (EOI) processing, premium billing calculations, leave and absence management, and enrollment data synchronization for employers and HR technology partners.
  version: '1.0'
  contact:
    name: Unum Developer Support
    url: https://developer.unum.com/s/
  termsOfService: https://www.unum.com/legal
servers:
- url: https://api.unum.com/v1
  description: Unum Production API
security:
- OAuth2:
  - eligibility:read
  - enrollment:read
  - leave:read
  - eoi:read
  - billing:read
tags:
- name: Eligibility
  description: Member eligibility management and verification
paths:
  /eligibility/members:
    get:
      operationId: listEligibleMembers
      summary: List Eligible Members
      description: Retrieve a list of eligible members for a given employer group.
      tags:
      - Eligibility
      parameters:
      - name: groupId
        in: query
        required: true
        schema:
          type: string
        description: Employer group identifier
      - name: effectiveDate
        in: query
        schema:
          type: string
          format: date
        description: Effective date for eligibility check (YYYY-MM-DD)
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number for pagination
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
          maximum: 500
        description: Number of records per page
      responses:
        '200':
          description: List of eligible members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: submitMemberEligibility
      summary: Submit Member Eligibility
      description: Submit or update member eligibility information for a group.
      tags:
      - Eligibility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberEligibilityRequest'
      responses:
        '201':
          description: Member eligibility created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /eligibility/members/{memberId}:
    get:
      operationId: getMemberEligibility
      summary: Get Member Eligibility
      description: Retrieve eligibility details for a specific member.
      tags:
      - Eligibility
      parameters:
      - name: memberId
        in: path
        required: true
        schema:
          type: string
        description: Unique member identifier
      responses:
        '200':
          description: Member eligibility details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateMemberEligibility
      summary: Update Member Eligibility
      description: Update eligibility information for an existing member.
      tags:
      - Eligibility
      parameters:
      - name: memberId
        in: path
        required: true
        schema:
          type: string
        description: Unique member identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberEligibilityRequest'
      responses:
        '200':
          description: Member eligibility updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: terminateMemberEligibility
      summary: Terminate Member Eligibility
      description: Terminate eligibility for a member (life event, termination, etc.).
      tags:
      - Eligibility
      parameters:
      - name: memberId
        in: path
        required: true
        schema:
          type: string
        description: Unique member identifier
      - name: terminationDate
        in: query
        required: true
        schema:
          type: string
          format: date
        description: Effective termination date
      - name: terminationReason
        in: query
        schema:
          type: string
        description: Reason for termination
      responses:
        '204':
          description: Member eligibility terminated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Member:
      type: object
      properties:
        memberId:
          type: string
          description: Unique member identifier
        groupId:
          type: string
          description: Employer group identifier
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        employeeId:
          type: string
          description: Employer-assigned employee ID
        hireDate:
          type: string
          format: date
        employmentStatus:
          type: string
          enum:
          - active
          - terminated
          - on-leave
        coverages:
          type: array
          items:
            $ref: '#/components/schemas/Coverage'
        effectiveDate:
          type: string
          format: date
        terminationDate:
          type: string
          format: date
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    MemberEligibilityRequest:
      type: object
      required:
      - groupId
      - firstName
      - lastName
      - dateOfBirth
      - employeeId
      - hireDate
      - employmentStatus
      - effectiveDate
      properties:
        groupId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        employeeId:
          type: string
        hireDate:
          type: string
          format: date
        employmentStatus:
          type: string
          enum:
          - active
          - terminated
          - on-leave
        effectiveDate:
          type: string
          format: date
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    Coverage:
      type: object
      properties:
        productType:
          type: string
          enum:
          - disability
          - life
          - dental
          - vision
          - critical-illness
          - accident
        planCode:
          type: string
        benefitAmount:
          type: number
          format: double
        effectiveDate:
          type: string
          format: date
        terminationDate:
          type: string
          format: date
        status:
          type: string
          enum:
          - active
          - pending
          - terminated
    MemberList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.unum.com/v1/oauth/token
          scopes:
            eligibility:read: Read member eligibility
            eligibility:write: Write member eligibility
            enrollment:read: Read enrollment elections
            enrollment:write: Write enrollment elections
            leave:read: Read leave requests
            leave:write: Write leave requests
            eoi:read: Read EOI submissions
            eoi:write: Write EOI submissions
            billing:read: Read billing invoices