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

# Retrieve an eligibility verification

> Returns the check's current state, and its `result` once the payer has answered. This route reads what was stored and never calls a payer, so a `PENDING` answer means the check is still running.

**Read both statuses.** The top-level `status` says whether the check ran. `result.status` says what the payer said. A `COMPLETE` check whose `result.status` is `error.member.name` ran normally — the payer could not match the patient on the name you sent. Only `complete.eligible` and `complete.ineligible` are answers about coverage.

Wait `retry_after_ms` between polls. Polling sooner while the check is still pending answers 429; a check that has since been answered returns 200 with its result instead. The first poll is never refused, so no interval is reported until a pending read tells you to wait.

Scoped to the submitting organization: a check belonging to another one answers 404, the same as an id that never existed.

A check is kept for 48 hours; after that the id answers 404.

**Not yet enabled on the production edge.** This path appears in the reference but answers 404 against the production server, and there is no committed enablement date. Do not sequence a launch behind it — confirm status with your OLH implementation contact before designing against it.

**Permissions:** `eligibility:read`



## OpenAPI

````yaml /openapi.json get /eligibility-verifications/{id}
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /eligibility-verifications/{id}:
    get:
      tags:
        - Eligibility
      summary: Retrieve an eligibility verification
      description: >-
        Returns the check's current state, and its `result` once the payer has
        answered. This route reads what was stored and never calls a payer, so a
        `PENDING` answer means the check is still running.


        **Read both statuses.** The top-level `status` says whether the check
        ran. `result.status` says what the payer said. A `COMPLETE` check whose
        `result.status` is `error.member.name` ran normally — the payer could
        not match the patient on the name you sent. Only `complete.eligible` and
        `complete.ineligible` are answers about coverage.


        Wait `retry_after_ms` between polls. Polling sooner while the check is
        still pending answers 429; a check that has since been answered returns
        200 with its result instead. The first poll is never refused, so no
        interval is reported until a pending read tells you to wait.


        Scoped to the submitting organization: a check belonging to another one
        answers 404, the same as an id that never existed.


        A check is kept for 48 hours; after that the id answers 404.


        **Not yet enabled on the production edge.** This path appears in the
        reference but answers 404 against the production server, and there is no
        committed enablement date. Do not sequence a launch behind it — confirm
        status with your OLH implementation contact before designing against it.


        **Permissions:** `eligibility:read`
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            The id returned when the check was submitted. Distinct from
            `request_id`, which identifies a single HTTP call.
      responses:
        '200':
          description: The check's current state, with the result once it has one.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EligibilityVerification'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
        '400':
          description: The path carried no id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Missing `id`
                  error_code: BAD_REQUEST
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: the token carries no organization
                  error_code: AUTHENTICATION_ERROR
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '403':
          description: Missing the `eligibility:read` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: insufficient_permissions
                  error_code: FORBIDDEN
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '404':
          description: >-
            Unknown check id, a check belonging to another organization, or a
            check older than 48 hours — all three are deliberately
            indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Check not found.
                  error_code: NOT_FOUND
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '429':
          description: >-
            Too many requests: a poll inside the interval the previous read
            reported, a throttled request, or exhausted shared real-time
            capacity. The message is the same on every eligibility endpoint and
            names no duration, because the window behind each of those differs.
            Back off and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Too many requests. Retry later.
                  error_code: TOO_MANY_REQUESTS
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '500':
          description: >-
            Something failed that names no cause. `error_code` is always
            `UNHANDLED_EXCEPTION` and the message is fixed prose — quote
            `request_id` to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Internal server error
                  error_code: UNHANDLED_EXCEPTION
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
      security:
        - serviceToken:
            - eligibility:read
components:
  schemas:
    EligibilityVerification:
      type: object
      required:
        - id
        - status
      description: A submitted check and, once the payer has answered, its result.
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - PENDING
            - COMPLETE
            - TIMEOUT
            - FAILED
          description: >-
            Whether the check ran — **not** what the payer said, which is
            `result.status`. `PENDING`: still running, poll again. `COMPLETE`:
            an answer was stored in `result`, so read `result.status`.
            `TIMEOUT`: nothing usable arrived in time, and asking again may do
            better. `FAILED`: an answer arrived and is unusable, so resubmitting
            the same check cannot change it.
        retry_after_ms:
          type: integer
          description: >-
            Milliseconds to wait before polling again, present only while
            `PENDING`. It backs off 500, 1000, 2000, 4000 then 5000, and it is
            enforced rather than advised: a poll inside the interval is a 429.
            It appears on no submit response, because the first poll is never
            refused.
          example: 500
        result:
          allOf:
            - $ref: '#/components/schemas/EligibilityVerificationResult'
          description: Present once the check has completed.
        reason:
          type: string
          description: >-
            Why a `TIMEOUT` or `FAILED` check produced no answer. Absent on a
            `COMPLETE` check.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            error_code:
              type: string
          required:
            - message
            - error_code
        request_id:
          type: string
      required:
        - error
        - request_id
    EligibilityVerificationResult:
      type: object
      additionalProperties: false
      required:
        - status
        - benefits
      description: >-
        The payer's answer. Every property except `status` and `benefits` is
        present only when it is known. **Absent means not reported — never zero
        and never false.**
      properties:
        status:
          type: string
          pattern: ^(complete|error)\.
          description: >-
            The payer's verdict. Only `complete.eligible` and
            `complete.ineligible` are statements about coverage; every `error.*`
            value is a completed check whose answer names why the patient could
            not be matched. A transport failure is not reported here — it
            surfaces as the enclosing `status` of `FAILED` or `TIMEOUT`.


            The values produced today are `complete.eligible`,
            `complete.ineligible`, `error.member.id`, `error.member.dob`,
            `error.member.name`, `error.member.not_found`, `error.member.data`,
            `error.provider`, `error.payer` and `error.request`.


            `error.provider` is the one to read differently: it means OpenLoop's
            provider identity was rejected or is not enrolled with that payer.
            No request carries a provider identifier — ours is resolved from the
            subscriber's state — so correcting the request cannot clear it.
            Contact us.


            **Branch on the family, not the whole string.** This is a pattern
            rather than a closed enum on purpose: an unrecognised member of
            either family is passed through rather than reshaped into a verdict
            we cannot justify, so a value outside the list above can appear.
            Read the prefix before the first `.` and treat an unrecognised
            `error.*` as a match failure.
          example: complete.eligible
        status_reason:
          type: string
          description: >-
            A finer code for the same verdict. Two reasons can share one status
            where the coarser value is accurate for both.


            On an `error.*` status it is one of `error.member.id`,
            `error.member.dob`, `error.member.name`, `error.member.not_found`,
            `error.member.data`, `error.provider.enrollment`,
            `error.provider.identity`, `error.payer.out_of_network`,
            `error.payer.not_configured`, `error.request` or `error.payer`.


            On `complete.ineligible` it is one of `coverage.inactive`,
            `coverage.ended` or `coverage.not_yet_effective`, and it is absent
            where the payer gave a reason we have no code for — so **an absent
            value means "not stated", never "coverage is fine"**.


            It is always absent on `complete.eligible`.
          example: error.provider.enrollment
        patient:
          $ref: '#/components/schemas/EligibilityVerificationPatient'
        plan:
          allOf:
            - $ref: '#/components/schemas/EligibilityPlan'
          description: >-
            The plan the payer named. No `active` here — the verdict is
            `status`, not a field of the plan.
        payer:
          $ref: '#/components/schemas/EligibilityPayer'
        group:
          type: object
          properties:
            number:
              type: string
            name:
              type: string
        benefits:
          type: array
          description: >-
            Always present. **Empty on any non-eligible verdict**, and empty
            when the payer quoted no cost shares — which is a real answer, not a
            missing one.
          items:
            $ref: '#/components/schemas/EligibilityBenefit'
    EligibilityVerificationPatient:
      type: object
      description: >-
        Who the check was about, which is not always the policyholder. Some of
        this block may be the request echoed back rather than anything the payer
        stated.
      properties:
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          description: >-
            Normally `YYYY-MM-DD`. A value that will not parse is passed through
            as received, so this is a plain string.
          example: '1957-11-10'
        member_id:
          type: string
        gender:
          type: string
        address:
          $ref: '#/components/schemas/EligibilityAddress'
    EligibilityPlan:
      type: object
      description: >-
        A plan and its coverage window. `active` is reported only where the
        operation establishes it — on a verification the verdict is `status`,
        not a field of the plan.
      properties:
        active:
          type: boolean
        name:
          type: string
          example: PPO Gold
        number:
          type: string
        insurance_type_code:
          type: string
          description: X12 insurance type, such as `HM`, `PR` or `MA`.
        start_date:
          type: string
          description: >-
            Start of the coverage window. Normally `YYYY-MM-DD`. A value the
            payer reports in some other form — `ONGOING`, say — is passed
            through as received rather than dropped, so this is a plain string
            rather than a date: check it before parsing it.
          example: '2026-01-01'
        end_date:
          type: string
          description: End of the coverage window. See `start_date`.
          example: '2026-12-31'
        network_id:
          type: string
    EligibilityPayer:
      type: object
      description: >-
        A payer. `id` is the payer id you sent, under the spelling you sent it.
        An operation with no payer to choose reports `name` alone.
      properties:
        id:
          type: string
          example: '61101'
        name:
          type: string
          example: Aetna
    EligibilityBenefit:
      type: object
      required:
        - network_status
        - copay
        - coinsurance
        - deductible
        - out_of_pocket
      description: >-
        The cost shares for one network. One entry per network; a network the
        payer quoted nothing for has no entry at all.
      properties:
        network_status:
          type: string
          enum:
            - IN NETWORK
            - OUT OF NETWORK
          description: Whether the cost shares below apply in or out of network.
        copay:
          type:
            - number
            - 'null'
          description: Dollar amount per visit.
          example: 25
        coinsurance:
          type:
            - number
            - 'null'
          description: '**A fraction, not a percentage** — `0.1` is 10%.'
          example: 0.1
        deductible:
          $ref: '#/components/schemas/EligibilityAccumulatorScopes'
        out_of_pocket:
          $ref: '#/components/schemas/EligibilityAccumulatorScopes'
    EligibilityAddress:
      type: object
      additionalProperties: false
      required:
        - state
      description: >-
        A postal address, nested under the person it belongs to. Only the
        insurance discovery request accepts more than `state`; the other three
        take the state alone and reject any other address field with a 400.
      properties:
        state:
          type: string
          minLength: 2
          maxLength: 2
          description: >-
            Two-letter US state code, case-insensitive. The state the care takes
            place in, not a mailing address: it selects the OpenLoop entity that
            submits the inquiry.
          example: WI
        line_1:
          type: string
        line_2:
          type: string
        city:
          type: string
        zip:
          type: string
          example: '53703'
    EligibilityAccumulatorScopes:
      type: object
      required:
        - individual
        - family
      description: >-
        The same accumulator at both scopes the payer quotes it at. Both keys
        are always present and either may be all `null`, so you never read a
        coverage-level code to work out which of the two a number belongs to.
      properties:
        individual:
          $ref: '#/components/schemas/EligibilityAccumulator'
        family:
          $ref: '#/components/schemas/EligibilityAccumulator'
    EligibilityAccumulator:
      type: object
      required:
        - total
        - remaining
      description: >-
        A running total the payer quoted. `null` means the payer did not report
        it, which is not the same as zero.
      properties:
        total:
          type:
            - number
            - 'null'
          example: 1500
        remaining:
          type:
            - number
            - 'null'
          example: 400
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}

````

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