openapi: 3.0.3
info:
  title: Aflac Enterprise Connect Claims 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: Claims
  description: Claims submission and status retrieval operations.
paths:
  /claims:
    get:
      operationId: listClaims
      summary: Aflac List Claims
      description: Retrieve a list of supplemental insurance claims for a policyholder or group.
      tags:
      - Claims
      parameters:
      - name: policy_id
        in: query
        description: Filter claims by policy ID.
        schema:
          type: string
        example: POL-987654
      - name: employee_id
        in: query
        description: Filter claims by employee ID.
        schema:
          type: string
        example: EMP-789012
      - name: status
        in: query
        description: Filter by claim status.
        schema:
          type: string
          enum:
          - submitted
          - in_review
          - approved
          - denied
          - paid
        example: approved
      responses:
        '200':
          description: A list of claims.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimList'
              examples:
                listClaims200Example:
                  summary: Default listClaims 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - {}
                    total: 1
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listClaims401Example:
                  summary: Default listClaims 401 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: submitClaim
      summary: Aflac Submit Claim
      description: Submit a new supplemental insurance claim for review and payment.
      tags:
      - Claims
      requestBody:
        required: true
        description: Claim submission payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimRequest'
            examples:
              submitClaimRequestExample:
                summary: Default submitClaim request
                x-microcks-default: true
                value:
                  policy_id: '500123'
                  claim_type: accident
                  incident_date: '2025-03-15'
                  description: Example description
      responses:
        '201':
          description: Claim submitted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
              examples:
                submitClaim201Example:
                  summary: Default submitClaim 201 response
                  x-microcks-default: true
                  value:
                    claim_id: '500123'
                    policy_id: '500123'
                    employee_id: '500123'
                    claim_type: accident
                    status: submitted
                    incident_date: '2025-03-15'
                    submission_date: '2025-03-15T14:30:00Z'
                    benefit_amount: 99.99
                    denial_reason: example_value
        '400':
          description: Invalid claim data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                submitClaim400Example:
                  summary: Default submitClaim 400 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    message: example_value
                    request_id: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /claims/{claim_id}:
    get:
      operationId: getClaim
      summary: Aflac Get Claim
      description: Retrieve a specific claim record and its processing status.
      tags:
      - Claims
      parameters:
      - name: claim_id
        in: path
        required: true
        description: Unique claim identifier.
        schema:
          type: string
        example: CLM-112233
      responses:
        '200':
          description: Claim details and status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
              examples:
                getClaim200Example:
                  summary: Default getClaim 200 response
                  x-microcks-default: true
                  value:
                    claim_id: '500123'
                    policy_id: '500123'
                    employee_id: '500123'
                    claim_type: accident
                    status: submitted
                    incident_date: '2025-03-15'
                    submission_date: '2025-03-15T14:30:00Z'
                    benefit_amount: 99.99
                    denial_reason: example_value
        '404':
          description: Claim not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                getClaim404Example:
                  summary: Default getClaim 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:
    ClaimList:
      type: object
      description: Paginated list of claims.
      properties:
        items:
          type: array
          description: Array of claim records.
          items:
            $ref: '#/components/schemas/Claim'
          example:
          - example_value
        total:
          type: integer
          description: Total number of matching claims.
          example: 30
    ClaimRequest:
      type: object
      description: Request payload for submitting a new claim.
      required:
      - policy_id
      - claim_type
      - incident_date
      properties:
        policy_id:
          type: string
          description: Policy against which to file the claim.
          example: POL-987654
        claim_type:
          type: string
          description: Type of claim event.
          enum:
          - accident
          - critical_illness
          - cancer_diagnosis
          - hospitalization
          - disability
          example: accident
        incident_date:
          type: string
          format: date
          description: Date of the qualifying event.
          example: '2025-02-10'
        description:
          type: string
          description: Description of the incident or diagnosis.
          example: Employee sustained a broken arm in a workplace accident.
    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
    Claim:
      type: object
      description: A supplemental insurance claim record.
      properties:
        claim_id:
          type: string
          description: Unique claim identifier.
          example: CLM-112233
        policy_id:
          type: string
          description: Policy associated with the claim.
          example: POL-987654
        employee_id:
          type: string
          description: Claimant employee identifier.
          example: EMP-789012
        claim_type:
          type: string
          description: Type of claim event.
          enum:
          - accident
          - critical_illness
          - cancer_diagnosis
          - hospitalization
          - disability
          example: accident
        status:
          type: string
          description: Current claim processing status.
          enum:
          - submitted
          - in_review
          - approved
          - denied
          - paid
          example: approved
        incident_date:
          type: string
          format: date
          description: Date of the qualifying event.
          example: '2025-02-10'
        submission_date:
          type: string
          format: date-time
          description: Timestamp when the claim was submitted.
          example: '2025-02-15T09:30:00Z'
        benefit_amount:
          type: number
          description: Approved benefit payment amount in USD.
          example: 1500.0
        denial_reason:
          type: string
          description: Reason for denial if the claim was denied.
          example: Condition not covered under policy terms.
  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