> ## 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.

# Submit an insurance discovery

> Finds coverage a patient may have when you do not know their payer or member id, from demographics alone. Queued rather than answered inline: this call answers 202 with an `id` and `status: PENDING`, and the result arrives on `GET /insurance-discoveries/{id}`.

The organization comes from your access token's organization claim; there is no body field or query parameter for it. A token carrying no claim is a 401.

`subscriber.address.state` is required, and is the state of care rather than a mailing address: it narrows the search and selects the OpenLoop entity the inquiry is submitted under. The rest of the address is optional and improves matching, as does `subscriber.ssn`, which is never echoed back.

**Repeat submissions are absorbed for five minutes.** An identical submission inside that window answers 200 instead of 202, carrying the original `id` and `deduplicated: true`, and queues nothing new. The window matches the whole question, so a corrected submission is a new search.

**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:write`



## OpenAPI

````yaml /openapi.json post /insurance-discoveries
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:
    post:
      tags:
        - Eligibility
      summary: Submit an insurance discovery
      description: >-
        Finds coverage a patient may have when you do not know their payer or
        member id, from demographics alone. Queued rather than answered inline:
        this call answers 202 with an `id` and `status: PENDING`, and the result
        arrives on `GET /insurance-discoveries/{id}`.


        The organization comes from your access token's organization claim;
        there is no body field or query parameter for it. A token carrying no
        claim is a 401.


        `subscriber.address.state` is required, and is the state of care rather
        than a mailing address: it narrows the search and selects the OpenLoop
        entity the inquiry is submitted under. The rest of the address is
        optional and improves matching, as does `subscriber.ssn`, which is never
        echoed back.


        **Repeat submissions are absorbed for five minutes.** An identical
        submission inside that window answers 200 instead of 202, carrying the
        original `id` and `deduplicated: true`, and queues nothing new. The
        window matches the whole question, so a corrected submission is a new
        search.


        **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:write`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsuranceDiscoveryRequest'
      responses:
        '200':
          description: >-
            An identical submission from the last five minutes was matched; its
            `id` is returned with `deduplicated: true` and nothing new was
            queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InsuranceDiscoveryDeduplicated'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
        '202':
          description: >-
            Accepted. The discovery is worked out of band; poll the `id` for the
            result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InsuranceDiscoveryAccepted'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
        '400':
          description: >-
            The request body was absent or not valid JSON, or it failed
            validation: a missing or unknown field, a `subscriber.address.state`
            that is not a valid US state code, or a `subscriber.date_of_birth`
            or `date_of_service` that is not `YYYY-MM-DD`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Invalid request
                  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:write` 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
        '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:write
components:
  schemas:
    InsuranceDiscoveryRequest:
      type: object
      additionalProperties: false
      required:
        - subscriber
      properties:
        subscriber:
          $ref: '#/components/schemas/InsuranceDiscoverySubscriber'
        date_of_service:
          type: string
          format: date
          description: >-
            ISO `YYYY-MM-DD`; anything else is a 400. It decides which cost
            shares the retrieve call reports as in force. Omit it and the date
            is chosen for you.
          example: '2026-06-23'
    InsuranceDiscoveryDeduplicated:
      type: object
      additionalProperties: false
      required:
        - id
        - deduplicated
      properties:
        id:
          type: string
          format: uuid
          description: >-
            The id of the submission already in flight. Poll it rather than
            treating this as a new search.
        deduplicated:
          type: boolean
          enum:
            - true
          description: >-
            Always `true` here, and absent from a fresh acceptance. **Branch on
            this field, not on the status code**, which is 200 either way.
    InsuranceDiscoveryAccepted:
      type: object
      additionalProperties: false
      required:
        - id
        - status
      properties:
        id:
          type: string
          format: uuid
          description: >-
            The check id, to be polled. Distinct from the envelope's
            `request_id`, which identifies this one HTTP call.
        status:
          type: string
          enum:
            - PENDING
          description: >-
            Always `PENDING` — the same word the verification endpoint uses for
            the same fact. How we schedule the work is not published.
    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
    InsuranceDiscoverySubscriber:
      type: object
      additionalProperties: false
      required:
        - first_name
        - last_name
        - date_of_birth
        - address
      description: >-
        The person to find coverage for. No `member_id`: finding the coverage is
        the point.
      properties:
        first_name:
          type: string
          example: Erica
        last_name:
          type: string
          example: McDaniel
        date_of_birth:
          type: string
          format: date
          description: ISO `YYYY-MM-DD`.
          example: '1991-04-27'
        gender:
          type: string
          description: The patient's gender as the payer records it.
        ssn:
          type: string
          description: Optional, and it sharpens the match.
        address:
          allOf:
            - $ref: '#/components/schemas/EligibilityAddress'
          description: >-
            The one endpoint of the four that accepts more than `state`. The
            rest of the address improves matching.
    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'
  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.