> ## 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 eligibility verification

> Asks a payer whether a patient's coverage is active and what it covers. The check runs out of band: this call answers 202 with an `id`, and the answer arrives on `GET /eligibility-verifications/{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.

No provider identifier is accepted: `subscriber.address.state` selects the OpenLoop entity the inquiry is submitted under.

`payer_id` must use the payer-id vocabulary your account uses. Ask your OpenLoop contact which one that is.

**Repeat submissions are absorbed for five minutes.** An identical check from your organization inside that window answers 200 with the original `id` and `deduplicated: true` rather than asking the payer again. The window matches the whole question — subscriber, payer, state, date of service, specialty and place of service — and only against a check that is still `PENDING` or already `COMPLETE`; a `FAILED` or `TIMEOUT` check never blocks a resubmission. Two identical submissions sent at once are serialized: one is answered 200 with the other's `id`, or 409 if that one is not recorded yet.

A check here writes to no OpenLoop clinical record and starts no scheduling. If you need the result in a patient's chart, that is a separate integration.

**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 /eligibility-verifications
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:
    post:
      tags:
        - Eligibility
      summary: Submit an eligibility verification
      description: >-
        Asks a payer whether a patient's coverage is active and what it covers.
        The check runs out of band: this call answers 202 with an `id`, and the
        answer arrives on `GET /eligibility-verifications/{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.


        No provider identifier is accepted: `subscriber.address.state` selects
        the OpenLoop entity the inquiry is submitted under.


        `payer_id` must use the payer-id vocabulary your account uses. Ask your
        OpenLoop contact which one that is.


        **Repeat submissions are absorbed for five minutes.** An identical check
        from your organization inside that window answers 200 with the original
        `id` and `deduplicated: true` rather than asking the payer again. The
        window matches the whole question — subscriber, payer, state, date of
        service, specialty and place of service — and only against a check that
        is still `PENDING` or already `COMPLETE`; a `FAILED` or `TIMEOUT` check
        never blocks a resubmission. Two identical submissions sent at once are
        serialized: one is answered 200 with the other's `id`, or 409 if that
        one is not recorded yet.


        A check here writes to no OpenLoop clinical record and starts no
        scheduling. If you need the result in a patient's chart, that is a
        separate integration.


        **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/EligibilityVerificationRequest'
      responses:
        '200':
          description: >-
            An identical check from your organization was submitted inside the
            last five minutes. Its `id` is returned and no payer call was made.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EligibilityVerificationDeduplicated'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
        '202':
          description: >-
            Accepted. The check runs out of band; poll the `id` for the result.
            This body carries no interval, because the first poll is never
            refused — a pending read reports `retry_after_ms`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EligibilityVerificationAccepted'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
        '400':
          description: >-
            Request validation failed, or the organization could not be
            resolved. No payer has been asked at this point. A payer rejection
            is not reported here — it reaches you as a `FAILED` status, or as an
            `error.*` `result.status`, on the retrieve call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: 'Invalid request: subscriber.member_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:write` permission.
          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:
    EligibilityVerificationRequest:
      type: object
      additionalProperties: false
      required:
        - subscriber
        - payer_id
      properties:
        subscriber:
          $ref: '#/components/schemas/EligibilityVerificationSubscriber'
        payer_id:
          type: string
          maxLength: 80
          description: >-
            The payer to ask. Find it with `GET /payers` and send its `payer_id`
            unchanged.
          example: '61101'
        date_of_service:
          type: string
          format: date
          description: >-
            ISO `YYYY-MM-DD`; defaults to today. Send a past date for an earlier
            encounter or a future one for a scheduled visit — neither is
            refused. The answer is the coverage in force on the date you asked
            about.
          example: '2026-08-28'
        specialty_code:
          type: string
          enum:
            - ABA
            - IOP
            - OCT
            - PCH
            - PHT
            - PRC
            - PSY
            - SLP
            - SUD
            - UGC
            - WMT
          description: >-
            The encounter's specialty. An unrecognised value is a 400 rather
            than a silently dropped field.
          example: PSY
        place_of_service_code:
          type: string
          description: Two-digit CMS place-of-service code.
          example: '02'
    EligibilityVerificationDeduplicated:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - deduplicated
      properties:
        id:
          type: string
          format: uuid
          description: The id of the check that was already submitted. Poll it as usual.
        status:
          type: string
          enum:
            - PENDING
            - COMPLETE
          description: >-
            State of the matched check. `COMPLETE` means its answer is already
            available from the retrieve call.
        deduplicated:
          type: boolean
          enum:
            - true
          description: >-
            Always `true` here, and absent from the 202, so you can tell a
            matched check from a newly accepted one.
    EligibilityVerificationAccepted:
      type: object
      additionalProperties: false
      required:
        - id
        - status
      properties:
        id:
          type: string
          format: uuid
          description: >-
            The check id, and the only way to reach the answer. Distinct from
            the envelope's `request_id`, which identifies this one HTTP call.
        status:
          type: string
          enum:
            - PENDING
          description: Always `PENDING` — the check has been accepted, not answered.
    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
    EligibilityVerificationSubscriber:
      type: object
      additionalProperties: false
      required:
        - first_name
        - last_name
        - date_of_birth
        - member_id
        - address
      description: >-
        The person whose coverage is being checked. The same field name is used
        on every endpoint here.
      properties:
        first_name:
          type: string
          maxLength: 60
          example: Phillip
        last_name:
          type: string
          maxLength: 60
          example: Mozee
        date_of_birth:
          type: string
          format: date
          description: ISO `YYYY-MM-DD`.
          example: '1957-11-10'
        member_id:
          type: string
          maxLength: 80
          description: The id on the insurance card.
          example: H77465998
        address:
          type: object
          additionalProperties: false
          required:
            - state
          description: >-
            `state` only on this endpoint; any other address field is a 400. It
            selects the licensed OpenLoop entity the inquiry is submitted under
            as well as reaching the payer, so send the state the encounter takes
            place in.
          properties:
            state:
              type: string
              minLength: 2
              maxLength: 2
              example: WI
  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.