openapi: 3.0.3
info:
  title: Aflac Enterprise Connect Claims Groups 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: Groups
  description: Employer group management operations.
paths:
  /groups:
    get:
      operationId: listGroups
      summary: Aflac List Groups
      description: Retrieve a list of employer groups associated with the authenticated partner.
      tags:
      - Groups
      parameters:
      - 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.
        schema:
          type: integer
        example: 0
      responses:
        '200':
          description: A list of employer groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
              examples:
                listGroups200Example:
                  summary: Default listGroups 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - {}
                    total: 1
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listGroups401Example:
                  summary: Default listGroups 401 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /groups/{group_id}:
    get:
      operationId: getGroup
      summary: Aflac Get Group
      description: Retrieve a specific employer group record.
      tags:
      - Groups
      parameters:
      - name: group_id
        in: path
        required: true
        description: Unique employer group identifier.
        schema:
          type: string
        example: GRP-123456
      responses:
        '200':
          description: Employer group details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                getGroup200Example:
                  summary: Default getGroup 200 response
                  x-microcks-default: true
                  value:
                    group_id: '500123'
                    name: Example Name
                    employer_name: Example Name
                    status: active
                    employee_count: 1
                    effective_date: '2025-03-15'
        '404':
          description: Group not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                getGroup404Example:
                  summary: Default getGroup 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:
    Group:
      type: object
      description: An employer group record.
      properties:
        group_id:
          type: string
          description: Unique employer group identifier.
          example: GRP-123456
        name:
          type: string
          description: Employer group name.
          example: Example Corp Benefits Group
        employer_name:
          type: string
          description: Legal employer name.
          example: Example Corporation
        status:
          type: string
          description: Group status.
          enum:
          - active
          - inactive
          example: active
        employee_count:
          type: integer
          description: Number of enrolled employees.
          example: 250
        effective_date:
          type: string
          format: date
          description: Group effective date.
          example: '2025-01-01'
    GroupList:
      type: object
      description: Paginated list of employer groups.
      properties:
        items:
          type: array
          description: Array of group records.
          items:
            $ref: '#/components/schemas/Group'
          example:
          - example_value
        total:
          type: integer
          description: Total number of groups.
          example: 10
    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
  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