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

# Resolve a Medicare Beneficiary Identifier

> Resolves a Medicare Beneficiary Identifier from a patient's demographics, with a minimal coverage summary. **Answered inline** — there is nothing to poll, and the identifier is at `data.member_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 on every request, the SSN-bearing variant included: it selects the OpenLoop entity that submits the lookup. The SSN alone chooses the variant — supplying one selects the higher-matching `MBILU`, omitting it selects `MBILUNOSSN`. Whichever answered comes back as `variant`.

**A repeat inside four hours returns the stored answer** with `deduplicated: true`. The window is longer than the five minutes the other endpoints use, because a Medicare identifier does not change hour to hour.

**A 404 means no match, and no match is a normal outcome rather than a fault.** It covers a payer no-match, a mismatch on date of birth or name, and Medicare Advantage patients, for whom no identifier exists to find. Retrying an unchanged 404 returns 404 again.

**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 /medicare-id-lookups
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:
  /medicare-id-lookups:
    post:
      tags:
        - Eligibility
      summary: Resolve a Medicare Beneficiary Identifier
      description: >-
        Resolves a Medicare Beneficiary Identifier from a patient's
        demographics, with a minimal coverage summary. **Answered inline** —
        there is nothing to poll, and the identifier is at `data.member_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 on every request, the SSN-bearing
        variant included: it selects the OpenLoop entity that submits the
        lookup. The SSN alone chooses the variant — supplying one selects the
        higher-matching `MBILU`, omitting it selects `MBILUNOSSN`. Whichever
        answered comes back as `variant`.


        **A repeat inside four hours returns the stored answer** with
        `deduplicated: true`. The window is longer than the five minutes the
        other endpoints use, because a Medicare identifier does not change hour
        to hour.


        **A 404 means no match, and no match is a normal outcome rather than a
        fault.** It covers a payer no-match, a mismatch on date of birth or
        name, and Medicare Advantage patients, for whom no identifier exists to
        find. Retrying an unchanged 404 returns 404 again.


        **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`
      parameters:
        - name: X-Forwarded-For
          in: header
          required: false
          schema:
            type: string
          description: >-
            Optional. Forwarded upstream with the lookup when present; you are
            not required to set it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MedicareIdLookupRequest'
      responses:
        '200':
          description: The identifier resolved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MedicareIdLookup'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
        '400':
          description: >-
            The request body failed validation: a missing or unknown field, an
            absent or invalid `subscriber.address.state`, an SSN that is not
            nine digits after hyphen stripping, or a date of birth that is not a
            real calendar date.


            Also where a forwarded chain carrying an address outside the United
            States lands — the chain is part of the request. Read
            `error.message` to tell the two apart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: >-
                    An address in the forwarded chain is outside the United
                    States, so the request was refused
                  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
        '404':
          description: >-
            No match. The payer could not identify a beneficiary from the
            demographics supplied. A normal outcome, not a fault — retrying it
            unchanged returns 404 again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: No Medicare beneficiary matched the demographics supplied
                  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
        '504':
          description: >-
            The request timed out before an answer arrived. Try again. The
            message names no hop: which one ran out of time is not something you
            can act on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: The request timed out. Try again.
                  error_code: REQUEST_TIMEOUT
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
      security:
        - serviceToken:
            - eligibility:write
components:
  schemas:
    MedicareIdLookupRequest:
      type: object
      additionalProperties: false
      required:
        - subscriber
      description: >-
        Nothing outside `subscriber` is accepted — no service type, place of
        service, date of service or key of your own.
      properties:
        subscriber:
          $ref: '#/components/schemas/MedicareIdLookupSubscriber'
    MedicareIdLookup:
      type: object
      required:
        - member_id
        - member_id_status
        - variant
        - deduplicated
        - plan
        - payer
      properties:
        member_id:
          type: string
          description: The Medicare Beneficiary Identifier.
          example: 1EG4TE5MK73
        member_id_status:
          type: string
          enum:
            - CURRENT
            - POSSIBLY_OUTDATED
          description: >-
            Always present. `POSSIBLY_OUTDATED` means the payer returned this
            identifier alongside a rotation warning, so it may have been
            superseded. It is still the best available value and there is no way
            to obtain the newer one.
          example: CURRENT
        variant:
          type: string
          enum:
            - MBILU
            - MBILUNOSSN
          description: >-
            Which lookup answered. `MBILU` is the SSN-bearing variant, chosen
            whenever an SSN was supplied; `MBILUNOSSN` is the state-only
            variant.
          example: MBILU
        deduplicated:
          type: boolean
          description: >-
            `true` when the four-hour result cache answered instead of a live
            call.
          example: false
        plan:
          allOf:
            - $ref: '#/components/schemas/EligibilityPlan'
          required:
            - active
          description: >-
            A coverage summary, **not a benefits answer** — use a verification
            if you need cost shares. `active` says whether the plan reports
            active coverage. The payer reports its window in `CCYYMMDD` and it
            is converted to `YYYY-MM-DD` so every date on this surface reads the
            same way; a value in neither form is passed through as received.
            `name`, `number`, `insurance_type_code` and `network_id` are not
            reported by this operation.
        payer:
          allOf:
            - $ref: '#/components/schemas/EligibilityPayer'
          description: 'Always CMS, so no `id` is reported: there was no payer to choose.'
    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
    MedicareIdLookupSubscriber:
      type: object
      additionalProperties: false
      required:
        - first_name
        - last_name
        - date_of_birth
        - address
      description: >-
        The person whose Medicare identifier is being resolved. No `member_id`:
        resolving one is what this operation does.
      properties:
        first_name:
          type: string
          minLength: 1
          description: As printed on the card, punctuation included.
          example: Jane
        last_name:
          type: string
          minLength: 1
          description: >-
            As printed on the card. **Must not contain a name suffix** — use
            `suffix`.
          example: Doe
        suffix:
          type: string
          minLength: 1
          description: Generational suffix, where one exists. The only correct home for it.
          example: Jr
        date_of_birth:
          type: string
          description: >-
            Calendar date (`YYYY-MM-DD`). A full ISO datetime is accepted and
            truncated to its date part. An impossible date is a 400.
          example: '1955-05-05'
        ssn:
          type: string
          description: >-
            Nine digits; **hyphens are accepted and stripped** here, unlike the
            coordination check. Supplying one selects the higher-matching
            `MBILU` variant. Never echoed in a response.
          example: 123-45-6789
        address:
          type: object
          additionalProperties: false
          required:
            - state
          description: >-
            `state` only; any other address field is a 400. Required on every
            request, **including the SSN-bearing one that never sends it to
            CMS**: it selects the OpenLoop entity that submits the lookup.
          properties:
            state:
              type: string
              minLength: 2
              maxLength: 2
              example: WI
    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
    EligibilityPayer:
      type: object
      description: >-
        A payer. `id` is the payer id you sent, under the spelling you sent it.
        An operation with no payer to choose reports `name` alone.
      properties:
        id:
          type: string
          example: '61101'
        name:
          type: string
          example: Aetna
  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.