> ## 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 insurance discovery

> Returns the discovery's current state, and once it has finished either the coverages found or the reason the payer network could not answer. **The two shapes never mix.**

A finished discovery with `coverages_found: 0` is a normal answer — the patient may have no coverage to find.

Wait `retry_after_ms` between polls. Polling sooner while the check can still change answers 429; a check that has since finished returns 200 with its answer instead. The first poll is never refused.

Each entry in `coverages` is a coverage in the same shape a verification's `result` publishes, so one parser reads both answers.

**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 /insurance-discoveries/{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:
  /insurance-discoveries/{id}:
    get:
      tags:
        - Eligibility
      summary: Retrieve an insurance discovery
      description: >-
        Returns the discovery's current state, and once it has finished either
        the coverages found or the reason the payer network could not answer.
        **The two shapes never mix.**


        A finished discovery with `coverages_found: 0` is a normal answer — the
        patient may have no coverage to find.


        Wait `retry_after_ms` between polls. Polling sooner while the check can
        still change answers 429; a check that has since finished returns 200
        with its answer instead. The first poll is never refused.


        Each entry in `coverages` is a coverage in the same shape a
        verification's `result` publishes, so one parser reads both answers.


        **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 discovery's current state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InsuranceDiscovery'
                  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'
        '403':
          description: >-
            Missing the `eligibility:read` permission, or insurance discovery is
            disabled. Read `error.message` to tell the two apart.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: 'Discovery not found: 1a9f0b7c-8e4d-4f6a-9d3b-2c5e7a8f1b04'
                  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:
    InsuranceDiscovery:
      type: object
      required:
        - id
        - status
      description: >-
        A discovery and, once it has finished, either the coverages found or the
        reason the payer network could not answer. **The two shapes never mix**:
        an answered discovery carries `coverages` and no failure, a refused one
        carries `failure_status` and nothing about coverage.


        Quote `id`, or the envelope's `request_id`, when you ask us about a
        check.
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - PENDING
            - COMPLETE
            - TIMEOUT
            - FAILED
          description: >-
            The same four states the verification endpoint reports, with the
            same meanings. `FAILED` means resubmitting the same check cannot
            help; `TIMEOUT` means it may.
        retry_after_ms:
          type: integer
          description: >-
            Milliseconds to wait before polling again, present only while the
            check can still change. 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
        coverages_found:
          type: integer
          description: >-
            How many coverages the payer network returned. `0` is a normal
            answer — the patient may have none to find.
          example: 1
        coverages:
          type: array
          description: >-
            Each entry is a coverage in the same shape a verification's `result`
            publishes, so one parser reads both.
          items:
            $ref: '#/components/schemas/EligibilityCoverage'
        failure_status:
          type: string
          description: >-
            Present only when the payer network could not answer. Same
            vocabulary as a verification's `result.status`, so branch on the
            family before the first `.`.
          example: error.member.name
        failure_reason:
          type: string
          description: >-
            Finer than `failure_status`, and drawn from the same closed set a
            verification's `status_reason` uses.
          example: error.member.not_found
    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
    EligibilityCoverage:
      type: object
      required:
        - benefits
      description: >-
        One coverage. An insurance discovery returns an array of these, and a
        verification's `result` carries the same `payer` / `plan` / `group` /
        `benefits` fields with the same meanings, so one parser reads both
        answers.
      properties:
        payer:
          type: object
          properties:
            name:
              type: string
              example: Aetna
        plan:
          $ref: '#/components/schemas/EligibilityPlan'
        group:
          type: object
          properties:
            number:
              type: string
            name:
              type: string
        benefits:
          type: array
          items:
            $ref: '#/components/schemas/EligibilityBenefit'
        subscriber:
          allOf:
            - $ref: '#/components/schemas/EligibilityCoveragePerson'
          description: >-
            The policyholder on the coverage that was found, who is not always
            the patient: a discovery turns up policies held by a spouse or a
            parent. `member_id` sits on whoever holds the policy.
        dependent:
          allOf:
            - $ref: '#/components/schemas/EligibilityCoveragePerson'
          description: >-
            Present when the payer matched the patient as a dependent on the
            policy above. Its absence means the patient is the subscriber — the
            difference between billing under their own member id and someone
            else's.
        confidence:
          type: object
          required:
            - level
          description: An assessment of how well the patient matched this coverage.
          properties:
            level:
              type: string
              example: HIGH
            reason:
              type: string
    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
    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'
    EligibilityCoveragePerson:
      type: object
      additionalProperties: false
      description: >-
        A person on a coverage that was found. No `ssn`: the discovery response
        carries none, and an SSN you send is never echoed back.
      properties:
        first_name:
          type: string
          example: Erica
        middle_name:
          type: string
        last_name:
          type: string
          example: McDaniel
        date_of_birth:
          type: string
          example: '1991-04-27'
        gender:
          type: string
          example: F
        member_id:
          type: string
          example: W123456789
        relation_to_subscriber:
          type: string
          example: Spouse
        relation_to_subscriber_code:
          type: string
          example: '01'
    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.