> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.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://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Update a qualification session

> How to attach a user_id, update metadata, or adjust redirect URLs on an existing qualification session.

Keep a qualification session in sync with your own records after you've created it. Attach your
internal user identifier, store free-form metadata, and adjust the redirect URLs a customer returns
to once they finish qualifying—without touching the qualification itself.

This is most useful when you create a qualification session before you know who the shopper is. If
the customer qualifies through an ungated entry point, the session may start without your
`user_id`. Once you've resolved the shopper on your side—typically by matching their email
to an account—you can attach that identifier to the existing session so future visits reuse the
qualification instead of starting over.

## Why this matters

* **Backfill your user identifier.** Resolve a shopper to one of your accounts after the fact and
  attach your `user_id`, so the next time they check out Truemed recognizes them and they
  can skip re-qualifying.
* **Keep attribution current.** Store updated `metadata` against the session as your own records
  evolve.
* **Adjust the customer's return path.** Update the `success_url` or `failure_url` a customer is
  redirected to while the session is still in progress. Truemed sends the customer to `failure_url`
  when they opt out of HSA/FSA or do not qualify in the survey.
  Omitting the field leaves the stored URL unchanged; a session with none stored sends the customer
  to your website URL.

## How to implement

You'll need the `qualification_session_id` Truemed returned when the session was created and a valid
API key passed in the `x-truemed-api-key` header.

#### Resolve the shopper on your side

Map the customer to one of your accounts—usually by matching the email on the qualification
session to your user records—and determine the `user_id` you want to attach. You own
this resolution: Truemed never infers the identifier for you.

#### Call the update endpoint

Send a `POST` to
[`update_qualification_session`](/api-reference/qualification-sessions/update-qualification-session)
with the fields you want to change and a unique `idempotency_key`. Only the fields you supply are
updated; omitted fields are left untouched.

```bash
curl -X POST https://api.truemed.com/api/v1/qualification_session/$QUALIFICATION_SESSION_ID/update \
  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "idempotency_key": "your-unique-key-123",
    "user_id": "your-internal-user-id"
  }'
```

#### Read the response

A `200` echoes the `qualification_session_id` and the current `status` summary. The status is a
read-only passthrough—this endpoint never changes it.

```json
{
  "qualification_session_id": "qs_abc123",
  "status": "approved"
}
```

## `user_id` is set-when-null

You can attach an `user_id` only while the qualification session doesn't already have one.
Attempting to overwrite an existing value returns the `user_id_already_set` error code with
a `409` status.

> **Warning**
>
> This endpoint never overwrites an `user_id` that's already set. If you need to correct a
> previously set value, contact Truemed support—it can't be changed through this endpoint.

## Safe retries with idempotency

Every request requires an `idempotency_key`, scoped to the qualification session. A duplicate `POST`
with the same key against the same session is deduplicated and returns the original response, so
retries after a network blip are safe. Reusing a key with a different payload returns a `400`
validation error.

> **Note**
>
> Send a fresh `idempotency_key` for each distinct change you want to make to the same session.

## Notes and caveats

* **Status is never mutable here.** Qualification-session status changes only through the
  survey-submission and clinical-review flows, never through this endpoint.
* **Redirect URLs are stored but inert after a terminal status.** `success_url` and `failure_url`
  are still saved when supplied, but have no effect once the session reaches a terminal status
  (`approved` or `rejected`)—the customer has already completed the flow and won't be redirected
  again.
* **`metadata` is a JSON-encoded string** following the same convention as the create endpoint.