Retrieve Token Eligibility

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. The payment token is only how you name the customer; the provision-request form of this endpoint answers the same question for a customer who does not hold a token yet. `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 is eligible under it any more, which a re-survey cannot fix. Read it on whatever schedule suits you; the answer is stable until `lmn_expires_at`.

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Path parameters

token_idstringRequired

The payment token returned by create_payment_token, in its prefixed form

Response

Successful response
itemslist of strings

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_statusenum or nullOptional

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.
lmn_expires_atdatetime or nullOptional

When the letter determining this customer’s coverage expires: in the future while approved, in the past once expired. Null for catalog eligibility, which identifies no customer.

Errors

400
Bad Request Error
404
Not Found Error
405
Method Not Allowed Error
500
Internal Server Error
501
Not Implemented Error