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

# List or search payers

> Lists the payers whose `payer_id` an eligibility verification and a coordination check accept. Send an entry's `payer_id` unchanged, character for character.

The directory is OpenLoop's copy of the payer network's list, refreshed daily. A request reads that copy and never contacts a payer, so an entry can be up to a day old.

Without parameters the response carries every payer in one response, ordered by `name`, then `payer_id`, with `next_cursor: null`.

**`search` matches names only**: the `name` and the other `names`, never an id. The best match ranks first: an exact name, then a name prefix, then an exact other name, then a substring of any name. Inside each of these, national payers come first, then `name`, then `payer_id`. Only when none of these match does a typo-tolerant match run, ordered by how close the name is.

**`state` keeps payers that operate in that state, and national payers.** `state=NATIONAL` keeps only national payers. A payer with no state data never passes a state filter.

**`programs` keeps payers that have any of the listed programs.** A payer whose `programs` is empty never passes a program filter, though the unfiltered list has it.

All given parameters combine: search, then state, then programs. **No match is a 200** with an empty `payers`, not a 404.

**Paging is off unless you send `limit`.** With `limit`, each page returns `next_cursor`, or `null` on the last page. Send the same `search`, `state`, `programs` and `limit` with the cursor: it does not remember them, so changing one between pages returns the wrong page rather than an error. A cursor stops working when the directory refreshes; the 400 tells you to restart.

**A listed payer says nothing about network status, contracting or billability.** The directory is also not a list of the payer ids `POST /network-status` accepts.

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

Responses of 1 KB or more are gzip-compressed when you send `Accept-Encoding: gzip`.

**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`. `eligibility:write` is not accepted in its place.



## OpenAPI

````yaml /openapi.json get /payers
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:
  /payers:
    get:
      tags:
        - Payer Directory
      summary: List or search payers
      description: >-
        Lists the payers whose `payer_id` an eligibility verification and a
        coordination check accept. Send an entry's `payer_id` unchanged,
        character for character.


        The directory is OpenLoop's copy of the payer network's list, refreshed
        daily. A request reads that copy and never contacts a payer, so an entry
        can be up to a day old.


        Without parameters the response carries every payer in one response,
        ordered by `name`, then `payer_id`, with `next_cursor: null`.


        **`search` matches names only**: the `name` and the other `names`, never
        an id. The best match ranks first: an exact name, then a name prefix,
        then an exact other name, then a substring of any name. Inside each of
        these, national payers come first, then `name`, then `payer_id`. Only
        when none of these match does a typo-tolerant match run, ordered by how
        close the name is.


        **`state` keeps payers that operate in that state, and national
        payers.** `state=NATIONAL` keeps only national payers. A payer with no
        state data never passes a state filter.


        **`programs` keeps payers that have any of the listed programs.** A
        payer whose `programs` is empty never passes a program filter, though
        the unfiltered list has it.


        All given parameters combine: search, then state, then programs. **No
        match is a 200** with an empty `payers`, not a 404.


        **Paging is off unless you send `limit`.** With `limit`, each page
        returns `next_cursor`, or `null` on the last page. Send the same
        `search`, `state`, `programs` and `limit` with the cursor: it does not
        remember them, so changing one between pages returns the wrong page
        rather than an error. A cursor stops working when the directory
        refreshes; the 400 tells you to restart.


        **A listed payer says nothing about network status, contracting or
        billability.** The directory is also not a list of the payer ids `POST
        /network-status` accepts.


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


        Responses of 1 KB or more are gzip-compressed when you send
        `Accept-Encoding: gzip`.


        **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`. `eligibility:write` is not accepted
        in its place.
      parameters:
        - name: search
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 100
          description: >-
            A payer name or part of one, 1 to 100 characters after trimming, in
            any letter case. Matches names only, never an id.
          example: aetna
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: >-
            One of the 50 states, `DC`, `PR`, `GU`, `VI`, `AS` or `MP`, or
            `NATIONAL`, in any letter case. Keeps payers that operate in that
            state, and national payers; `NATIONAL` keeps only national payers.
            An entry's `states` can carry a code this parameter refuses, for
            example `FM`.
          example: CA
        - name: programs
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PayerProgram'
          description: >-
            Comma-separated programs, in any letter case. Keeps payers that have
            any of them. An unknown program is a 400.
          example:
            - COMMERCIAL
            - MEDICARE_ADVANTAGE
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
          description: >-
            Page size, from 1 to 200. Without it, every match comes in one
            response and paging is off.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            The `next_cursor` of the previous page, passed back unchanged with
            the same `search`, `state`, `programs` and `limit`. Only valid with
            `limit`, and only until the directory next refreshes: an expired
            cursor is a 400 that tells you to restart without one.
      responses:
        '200':
          description: The matching payers. No match is a 200 with an empty `payers`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PayerDirectoryPage'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
              example:
                data:
                  payers:
                    - payer_id: '06603'
                      name: ASA GEHA
                      names:
                        - Aetna Signature Administrators GEHA
                      states:
                        - NATIONAL
                      eligibility_support: SUPPORTED
                      programs:
                        - COMMERCIAL
                    - payer_id: HLPAE
                      name: Hill Physicians Aetna Preferred Provider Organization
                      names: []
                      states:
                        - CA
                      eligibility_support: SUPPORTED
                      programs:
                        - COMMERCIAL
                  next_cursor: eyJ2IjoiMjAyNi0wOS0zMFQwNjowMDowMFoiLCJvIjoyfQ
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '400':
          description: >-
            A query parameter failed validation: an unknown parameter, a
            `search` outside 1 to 100 characters, an unknown `state` or program,
            a `limit` outside 1 to 200, or a `cursor` without `limit`. Also an
            expired or malformed `cursor`: restart without one. `error.message`
            names the cause.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: >-
                    Unknown program. Allowed values: COMMERCIAL, MEDICARE,
                    MEDICAID, MEDICARE_ADVANTAGE, TRICARE, VETERANS_AFFAIRS,
                    WORKERS_COMPENSATION, AUTOMOBILE_MEDICAL.
                  error_code: BAD_REQUEST
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '401':
          description: >-
            Missing or invalid access token, or a token that carries no
            organization claim.
          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. A token that holds only
            `eligibility:write` lands here too.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: insufficient_permissions
                  error_code: FORBIDDEN
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '429':
          description: 'Too many requests: the request was throttled. 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
        '502':
          description: The directory has no data yet. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: The Payer Directory is not ready. Try again later.
                  error_code: NETWORK_ERROR
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
      security:
        - serviceToken:
            - eligibility:read
components:
  schemas:
    PayerProgram:
      type: string
      enum:
        - COMMERCIAL
        - MEDICARE
        - MEDICAID
        - MEDICARE_ADVANTAGE
        - TRICARE
        - VETERANS_AFFAIRS
        - WORKERS_COMPENSATION
        - AUTOMOBILE_MEDICAL
      description: >-
        A program as the payer network reports it. The list is not published,
        and this enum grows when a new value appears.
    PayerDirectoryPage:
      type: object
      additionalProperties: false
      required:
        - payers
        - next_cursor
      properties:
        payers:
          type: array
          items:
            $ref: '#/components/schemas/PayerDirectoryEntry'
          description: >-
            The matching payers: best match first when you search, otherwise by
            `name`, then `payer_id`. Empty when nothing matches.
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Send as `cursor`, with the same parameters, for the next page.
            `null` on the last page, and always `null` without `limit`.
          example: eyJ2IjoiMjAyNi0wOS0zMFQwNjowMDowMFoiLCJvIjoyfQ
    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
    PayerDirectoryEntry:
      type: object
      additionalProperties: false
      required:
        - payer_id
        - name
        - names
        - states
        - eligibility_support
        - programs
      description: >-
        One payer in the directory. A listed payer says nothing about network
        status, contracting or billability.
      properties:
        payer_id:
          type: string
          description: >-
            The value to send as `payer_id` to an eligibility verification or a
            coordination check, unchanged.
          example: '06603'
        name:
          type: string
          example: ASA GEHA
        names:
          type: array
          items:
            type: string
          description: >-
            Other names of the payer, never ids. Empty when there are none.
            `search` matches these as well as `name`.
          example:
            - Aetna Signature Administrators GEHA
        states:
          type: array
          items:
            type: string
          description: >-
            Two-letter codes as the payer network reports them, or `NATIONAL`
            for a national payer. A code can be outside the `state` parameter's
            list, for example `FM`. Empty when the payer network reports none,
            and then no state filter returns the payer.
          example:
            - NATIONAL
        eligibility_support:
          type: string
          enum:
            - SUPPORTED
            - NOT_SUPPORTED
            - ENROLLMENT_REQUIRED
          description: >-
            The payer network's current eligibility status for the payer. Only
            `SUPPORTED` payers are expected to answer an eligibility check now.
            `ENROLLMENT_REQUIRED` payers can fail until OpenLoop enrolls with
            them. `NOT_SUPPORTED` payers will fail.
          example: SUPPORTED
        programs:
          type: array
          items:
            type: string
          description: >-
            Programs, upper case as the payer network reports them. Empty when
            it reports none, and then no program filter returns the payer. Can
            carry a value the `programs` parameter does not accept yet.
          example:
            - COMMERCIAL
  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.