> ## 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 a payer

> Resolves a stored `payer_id` back to its directory entry. **Exact match only**: aliases and other ids do not resolve, and letter case must match.

**A 404 for an id that used to resolve means the payer is gone.** A payer that leaves the payer network, or whose id changes, stops resolving under the old id after the next daily refresh. Search for it again with `GET /payers`.

The 403 and 502 rules of `GET /payers` apply here too.

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.

**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/{payer_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:
  /payers/{payer_id}:
    get:
      tags:
        - Payer Directory
      summary: Retrieve a payer
      description: >-
        Resolves a stored `payer_id` back to its directory entry. **Exact match
        only**: aliases and other ids do not resolve, and letter case must
        match.


        **A 404 for an id that used to resolve means the payer is gone.** A
        payer that leaves the payer network, or whose id changes, stops
        resolving under the old id after the next daily refresh. Search for it
        again with `GET /payers`.


        The 403 and 502 rules of `GET /payers` apply here too.


        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.


        **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: payer_id
          in: path
          required: true
          schema:
            type: string
          description: An entry's `payer_id`, exactly as `GET /payers` returned it.
          example: '60054'
      responses:
        '200':
          description: The payer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PayerDirectoryEntry'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
              example:
                data:
                  payer_id: '60054'
                  name: Aetna
                  names:
                    - Aetna Affordable Health Choices (SM) SRC
                    - Aetna Insurance Company
                    - Aetna Medicare Advantage
                  states:
                    - NATIONAL
                  eligibility_support: SUPPORTED
                  programs: []
                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
        '404':
          description: >-
            No entry has this `payer_id`. Aliases and other ids do not resolve,
            and a payer that left the payer network is gone after the next daily
            refresh.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: No Payer in the directory has this payer_id.
                  error_code: NOT_FOUND
                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:
    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
    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
  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.