> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an eligibility check

> Runs a real-time insurance eligibility and benefits check (X12 270/271) with the payer and stores the result in your organization's benefits history, where it also shows in the HealOS dashboard. Either pass `patient_id` for a patient already in HealOS, or pass `member_id`, `first_name`, `last_name` and `date_of_birth`. Requires the `benefits:write` scope. Each check is a billable payer request, so this endpoint is limited to 10 requests per minute per API key on top of the global limit. Responses usually take a few seconds; allow up to a minute when the payer is slow.



## OpenAPI

````yaml /openapi/ext-api-v1.json post /benefits/eligibility-checks
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), and running insurance eligibility checks.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /benefits/eligibility-checks:
    post:
      tags:
        - Benefits
      summary: Run an eligibility check
      description: >-
        Runs a real-time insurance eligibility and benefits check (X12 270/271)
        with the payer and stores the result in your organization's benefits
        history, where it also shows in the HealOS dashboard. Either pass
        `patient_id` for a patient already in HealOS, or pass `member_id`,
        `first_name`, `last_name` and `date_of_birth`. Requires the
        `benefits:write` scope. Each check is a billable payer request, so this
        endpoint is limited to 10 requests per minute per API key on top of the
        global limit. Responses usually take a few seconds; allow up to a minute
        when the payer is slow.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EligibilityCheckBody'
      responses:
        '200':
          description: >-
            Check completed (the payer may still report inactive coverage or
            issues)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityCheckResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitsError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Patient or linked check not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitsError'
        '422':
          description: The payer rejected the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitsError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '502':
          description: Eligibility service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitsError'
        '503':
          description: Eligibility checking unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitsError'
        '504':
          description: Payer did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitsError'
components:
  schemas:
    EligibilityCheckBody:
      type: object
      properties:
        payer_id:
          type: string
          minLength: 1
          description: Payer id from `GET /benefits/payers/search`.
          example: '60054'
        payer_name:
          type: string
          description: Payer display name, stored on the check for your records.
          example: Aetna
        provider_name:
          type: string
          minLength: 1
          description: Name of the requesting provider or practice.
          example: Riverside Family Medicine
        provider_npi:
          type: string
          pattern: ^\d{10}$
          description: 10-digit NPI of the requesting provider or practice.
          example: '1234567893'
        patient_id:
          type: string
          pattern: ^\d+$
          description: >-
            A HealOS patient in your organization. When set, the patient's name,
            date of birth, gender and the member id of their active insurance
            for this payer are used, and the member fields below are not
            required.
          example: '481926357104938271'
        member_id:
          type: string
          minLength: 1
          description: Insurance member id. Required without `patient_id`.
          example: W123456789
        first_name:
          type: string
          minLength: 1
          description: Required without `patient_id`.
          example: Jordan
        last_name:
          type: string
          minLength: 1
          description: Required without `patient_id`.
          example: Rivera
        date_of_birth:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: YYYY-MM-DD. Required without `patient_id`.
          example: '1984-03-12'
        middle_name:
          type: string
        gender:
          type: string
          example: F
        service_type:
          type: string
          description: >-
            X12 service type code. Defaults to 30 (health benefit plan
            coverage).
          example: '30'
        insurance_type:
          type: string
          enum:
            - primary
            - secondary
          description: Defaults to primary.
        linked_check_id:
          type: string
          description: 'For a secondary check: the id of the primary check it belongs to.'
      required:
        - payer_id
        - provider_name
        - provider_npi
    EligibilityCheckResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EligibilityCheck'
      required:
        - data
    BenefitsError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: Machine-readable reason, when known.
          example: PAYER_VALIDATION_ERROR
      required:
        - error
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
      required:
        - error
    EligibilityCheck:
      type: object
      properties:
        id:
          type: string
          example: 3f2b9c1e-6a7d-4e1f-9b0a-2c4d5e6f7a8b
        status:
          type: string
          description: Coverage status as reported by the payer (e.g. Active, Inactive).
          example: Active
        patient_name:
          type: string
          example: Jordan Rivera
        payer_name:
          type: string
          example: Aetna
        member_id:
          type: string
          example: W123456789
        patient_id:
          type: string
          nullable: true
          description: The HealOS patient, when the check was run for one.
        insurance_type:
          type: string
          enum:
            - primary
            - secondary
        linked_check_id:
          type: string
          nullable: true
        checked_at:
          type: string
          description: When the check was first run (ISO 8601).
        last_checked_at:
          type: string
          description: When the check last ran (ISO 8601).
        result:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
          description: >-
            The payer's normalized eligibility response: `subscriber`, `payer`,
            `provider`, `plan` (plan names, group, coverage dates), `benefits`
            (one entry per benefit: type, coverage level, network, amount or
            percentage, time period, auth required), plus any `issues` /
            `warnings` the payer returned.
      required:
        - id
        - status
        - patient_name
        - payer_name
        - member_id
        - patient_id
        - insurance_type
        - linked_check_id
        - checked_at
        - last_checked_at
        - result
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.