> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.truemed.com/_mcp/server.

# Retrieve Token Eligibility

GET https://dev-api.truemed.com/api/v1/eligibility/token/{token_id}

Returns the items *this* customer can charge to their HSA/FSA card, and when that stops being true.

This is **customer eligibility** — a property of the person rather than the product. It is catalog eligibility
narrowed to one customer: an item appears here only when they hold a verified, unexpired Letter of Medical
Necessity covering its eligibility category, or when that category is pre-approved and needs no letter at all.

`eligibility_status` and `lmn_expires_at` answer for the payment token you name, not for whoever holds it.
They count the letters reachable through the token together with the letters the holder earned on your sales
channel. A customer who answers our health survey under a second email address earns their letter on that
address while the token stays where it was minted, and counting both is what keeps that letter visible here.
The `payment_token.updated` webhook counts the same letters, so a token reads the same way on both surfaces.
The provision-request form answers for a customer who holds no token yet, and is keyed on the customer.

`eligibility_status` is a statement of fact, not an instruction, and each value earns a different response from
you — the per-value meanings are listed on the enum. In short: `approved` is the steady state; `expired` is your
renewal trigger, while every item keeps charging to the backup card meanwhile; `never_requested` calls for a
first-time qualification prompt rather than a renewal one; `rejected` means suppress the prompt rather than
sending the customer round again, since we have already emailed them the outcome; and `pending` means wait.

`pending` is rare on this form, because a payment token is normally minted only once a letter has been decided.
It appears when a customer who is not currently covered has a survey under review — a requalification in
flight, most often.

An empty `items` list under `approved` is worth reporting to us rather than to your customer: it means a live
qualification exists but nothing in your catalog falls under it any more, which a re-survey cannot fix.

Read it on whatever schedule suits you; the answer is stable through `lmn_expires_at` (inclusive, UTC).

Reference: https://docs.truemed.com/api-reference/eligibility/retrieve-token-eligibility

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Path parameters

- `token_id` (string, required) — The payment token returned by create_payment_token, in its prefixed form

## Response

### 200

Successful response

- `items` (list of string, required) — The catalog items that can be charged to an HSA/FSA card, each identified exactly as it is in order_items when you charge.
- `eligibility_status` (enum, optional, nullable) — Where this customer's clinical eligibility stands. Named apart from the payment `status` on other Truemed payloads, which is a different vocabulary. Per-value meanings are listed on the enum. Null for catalog eligibility, which identifies no customer. One of: - `approved` — A verified, unexpired letter stands for this customer. - `pending` — A survey is with a clinician; the outcome is not decided yet. - `expired` — The letter that covered this customer has lapsed and not been renewed. - `rejected` — A clinician reviewed this customer's most recent survey and declined it. - `never_requested` — No letter has ever been requested for this customer here.
  - Allowed values: `approved`, `pending`, `expired`, `rejected`, `never_requested`
- `lmn_expires_at` (date, optional, nullable) — When the letter determining this customer's coverage expires (inclusive, UTC). Null for catalog eligibility, which identifies no customer.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Examples

**Response**

```json
{
  "items": [
    "string"
  ],
  "eligibility_status": "approved",
  "lmn_expires_at": "2023-01-15"
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/api/v1/eligibility/token/token_id"

headers = {"x-truemed-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/api/v1/eligibility/token/token_id';
const options = {method: 'GET', headers: {'x-truemed-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```