aflac Enrollment API

openapi: 3.0.3
info:
  title: Aflac Enterprise Connect Claims Enrollment API
  description: The Aflac Enterprise Connect (AEC) API enables benefits administrators, HR platforms, and third-party enrollment systems to integrate with Aflac's supplemental insurance platform. It provides REST API access to benefits enrollment, policy management, claims status, and eligibility verification for group and individual supplemental insurance products.
  version: '1.0'
  contact:
    name: Aflac Enterprise Connect Support
    url: https://docs.enterprise-connect.aflac.com
  x-generated-from: documentation
servers:
- url: https://api.enterprise-connect.aflac.com/v1
  description: Production Server
- url: https://sandbox.enterprise-connect.aflac.com/v1
  description: Sandbox Server
security:
- oauth2: []
tags:
- name: Enrollment
  description: Benefits enrollment operations for supplemental insurance products.
paths:
  /enrollments:
    get:
      operationId: listEnrollments
      summary: Aflac List Enrollments
      description: Retrieve a list of benefit enrollments for a group or employee.
      tags:
      - Enrollment
      parameters:
      - name: group_id
        in: query
        description: Filter enrollments by employer group ID.
        schema:
          type: string
        example: GRP-123456
      - name: employee_id
        in: query
        description: Filter enrollments by employee ID.
        schema:
          type: string
        example: EMP-789012
      - name: status
        in: query
        description: Filter by enrollment status (active, pending, terminated).
        schema:
          type: string
          enum:
          - active
          - pending
          - terminated
        example: active
      - name: limit
        in: query
        description: Maximum number of results to return.
        schema:
          type: integer
        example: 50
      - name: offset
        in: query
        description: Number of results to skip for pagination.
        schema:
          type: integer
        example: 0
      responses:
        '200':
          description: A list of enrollments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrollmentList'
              examples:
                listEnrollments200Example:
                  summary: Default listEnrollments 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - {}
                    total: 1
                    limit: 1
                    offset: 1
        '401':
          description: Unauthorized — invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listEnrollments401Example:
                  summary: Default listEnrollments 401 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
        '403':
          description: Forbidden — insufficient permissions for the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listEnrollments403Example:
                  summary: Default listEnrollments 403 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createEnrollment
      summary: Aflac Create Enrollment
      description: Submit a new benefit enrollment for an employee into a supplemental insurance product.
      tags:
      - Enrollment
      requestBody:
        required: true
        description: Enrollment submission payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollmentRequest'
            examples:
              createEnrollmentRequestExample:
                summary: Default createEnrollment request
                x-microcks-default: true
                value:
                  employee_id: '500123'
                  group_id: '500123'
                  product_type: accident
                  coverage_level: employee_only
                  effective_date: '2025-03-15'
                  dependents:
                  - {}
      responses:
        '201':
          description: Enrollment created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enrollment'
              examples:
                createEnrollment201Example:
                  summary: Default createEnrollment 201 response
                  x-microcks-default: true
                  value:
                    enrollment_id: '500123'
                    employee_id: '500123'
                    group_id: '500123'
                    policy_id: '500123'
                    product_type: accident
                    coverage_level: employee_only
                    status: active
                    effective_date: '2025-03-15'
                    termination_date: '2025-03-15'
                    monthly_premium: 99.99
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '400':
          description: Bad request — invalid enrollment data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createEnrollment400Example:
                  summary: Default createEnrollment 400 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createEnrollment401Example:
                  summary: Default createEnrollment 401 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /enrollments/{enrollment_id}:
    get:
      operationId: getEnrollment
      summary: Aflac Get Enrollment
      description: Retrieve a specific enrollment record by ID.
      tags:
      - Enrollment
      parameters:
      - name: enrollment_id
        in: path
        required: true
        description: Unique enrollment identifier.
        schema:
          type: string
        example: ENR-500123
      responses:
        '200':
          description: Enrollment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enrollment'
              examples:
                getEnrollment200Example:
                  summary: Default getEnrollment 200 response
                  x-microcks-default: true
                  value:
                    enrollment_id: '500123'
                    employee_id: '500123'
                    group_id: '500123'
                    policy_id: '500123'
                    product_type: accident
                    coverage_level: employee_only
                    status: active
                    effective_date: '2025-03-15'
                    termination_date: '2025-03-15'
                    monthly_premium: 99.99
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '404':
          description: Enrollment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                getEnrollment404Example:
                  summary: Default getEnrollment 404 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateEnrollment
      summary: Aflac Update Enrollment
      description: Update an existing enrollment record (e.g., change coverage level or dependents).
      tags:
      - Enrollment
      parameters:
      - name: enrollment_id
        in: path
        required: true
        description: Unique enrollment identifier.
        schema:
          type: string
        example: ENR-500123
      requestBody:
        required: true
        description: Updated enrollment data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollmentRequest'
            examples:
              updateEnrollmentRequestExample:
                summary: Default updateEnrollment request
                x-microcks-default: true
                value:
                  employee_id: '500123'
                  group_id: '500123'
                  product_type: accident
                  coverage_level: employee_only
                  effective_date: '2025-03-15'
                  dependents:
                  - {}
      responses:
        '200':
          description: Enrollment updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enrollment'
              examples:
                updateEnrollment200Example:
                  summary: Default updateEnrollment 200 response
                  x-microcks-default: true
                  value:
                    enrollment_id: '500123'
                    employee_id: '500123'
                    group_id: '500123'
                    policy_id: '500123'
                    product_type: accident
                    coverage_level: employee_only
                    status: active
                    effective_date: '2025-03-15'
                    termination_date: '2025-03-15'
                    monthly_premium: 99.99
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '404':
          description: Enrollment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                updateEnrollment404Example:
                  summary: Default updateEnrollment 404 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: terminateEnrollment
      summary: Aflac Terminate Enrollment
      description: Terminate an active enrollment for an employee (e.g., upon employment termination).
      tags:
      - Enrollment
      parameters:
      - name: enrollment_id
        in: path
        required: true
        description: Unique enrollment identifier.
        schema:
          type: string
        example: ENR-500123
      responses:
        '204':
          description: Enrollment terminated successfully.
        '404':
          description: Enrollment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                terminateEnrollment404Example:
                  summary: Default terminateEnrollment 404 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Enrollment:
      type: object
      description: A supplemental insurance enrollment record for an employee.
      properties:
        enrollment_id:
          type: string
          description: Unique enrollment identifier.
          example: ENR-500123
        employee_id:
          type: string
          description: Employee identifier.
          example: EMP-789012
        group_id:
          type: string
          description: Employer group identifier.
          example: GRP-123456
        policy_id:
          type: string
          description: Associated policy identifier assigned upon enrollment.
          example: POL-987654
        product_type:
          type: string
          description: Type of supplemental insurance product.
          enum:
          - accident
          - critical_illness
          - cancer
          - hospital_indemnity
          - disability
          - life
          example: accident
        coverage_level:
          type: string
          description: Coverage level selected by the employee.
          enum:
          - employee_only
          - employee_spouse
          - employee_children
          - family
          example: family
        status:
          type: string
          description: Current enrollment status.
          enum:
          - active
          - pending
          - terminated
          example: active
        effective_date:
          type: string
          format: date
          description: Date the coverage became effective.
          example: '2025-01-01'
        termination_date:
          type: string
          format: date
          description: Date the coverage was terminated, if applicable.
          example: '2025-12-31'
        monthly_premium:
          type: number
          description: Monthly premium amount in USD.
          example: 18.5
        created_at:
          type: string
          format: date-time
          description: Timestamp when the enrollment was created.
          example: '2024-11-01T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the enrollment was last updated.
          example: '2025-01-01T00:00:00Z'
    EnrollmentList:
      type: object
      description: Paginated list of enrollment records.
      properties:
        items:
          type: array
          description: Array of enrollment records.
          items:
            $ref: '#/components/schemas/Enrollment'
          example:
          - example_value
        total:
          type: integer
          description: Total number of matching enrollments.
          example: 150
        limit:
          type: integer
          description: Maximum number of results returned.
          example: 50
        offset:
          type: integer
          description: Number of results skipped.
          example: 0
    EnrollmentRequest:
      type: object
      description: Request payload for creating or updating an enrollment.
      required:
      - employee_id
      - group_id
      - product_type
      - coverage_level
      - effective_date
      properties:
        employee_id:
          type: string
          description: Employee identifier.
          example: EMP-789012
        group_id:
          type: string
          description: Employer group identifier.
          example: GRP-123456
        product_type:
          type: string
          description: Type of supplemental insurance product to enroll in.
          enum:
          - accident
          - critical_illness
          - cancer
          - hospital_indemnity
          - disability
          - life
          example: accident
        coverage_level:
          type: string
          description: Coverage level for the enrollment.
          enum:
          - employee_only
          - employee_spouse
          - employee_children
          - family
          example: employee_only
        effective_date:
          type: string
          format: date
          description: Requested effective date for coverage.
          example: '2025-01-01'
        dependents:
          type: array
          description: List of dependents to include in family coverage.
          items:
            $ref: '#/components/schemas/Dependent'
          example:
          - example_value
    Error:
      type: object
      description: API error response.
      properties:
        error:
          type: string
          description: Error code.
          example: not_found
        message:
          type: string
          description: Human-readable error description.
          example: The requested resource was not found.
        request_id:
          type: string
          description: Unique request ID for support reference.
          example: req-a1b2c3d4e5
    Dependent:
      type: object
      description: A dependent to be covered under a family enrollment.
      properties:
        first_name:
          type: string
          description: Dependent's first name.
          example: Jane
        last_name:
          type: string
          description: Dependent's last name.
          example: Smith
        date_of_birth:
          type: string
          format: date
          description: Dependent's date of birth.
          example: '1990-06-15'
        relationship:
          type: string
          description: Relationship to the employee.
          enum:
          - spouse
          - child
          example: spouse
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow for server-to-server API access.
      flows:
        clientCredentials:
          tokenUrl: https://auth.enterprise-connect.aflac.com/oauth/token
          scopes:
            enrollment:read: Read enrollment records
            enrollment:write: Create and update enrollments
            claims:read: Read claim records
            claims:write: Submit claims
            eligibility:read: Verify eligibility
            groups:read: Read group records