> 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 Qualification Session

POST https://dev-api.truemed.com/api/v1/qualification_session/{qualification_session_id}/update
Content-Type: application/json

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.

## Request Notes

- `idempotency_key` makes retries safe: a duplicate POST with the same key against the same qualification session is deduplicated and returns the original response, while reusing a key with a different payload returns a `400` validation error.
- `user_id` is set-when-null only: you can supply it while the qualification session has no `user_id` yet, but attempting to overwrite a non-null value returns the documented `user_id_already_set` error code. Stale-value corrections must route through Truemed support, not this endpoint.
- `metadata` is a JSON-encoded string echoing the same convention used by the create endpoint.
- `success_url` and `failure_url` are still stored when supplied, but have no effect once the qualification session reaches a terminal status (`approved` / `rejected`) — the customer has already completed the flow and won't be redirected again.

## Response Notes

- `status` is a read-only passthrough — qualification-session status is never mutable via this endpoint. Status changes occur through the survey-submission and LMN-clinical-review flows.

Reference: https://developers.truemed.com/api-reference/qualification-sessions/update-qualification-session

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

- `qualification_session_id` (string, required) — The qualification session ID from the URL path.

### Body (application/json)

This endpoint expects an UpdateQualificationSessionRequest.

- `idempotency_key` (string, required) — A unique key for safely retrying the request, scoped to this qualification session. Duplicate POSTs with the same key against the same qualification session are deduplicated and return the original response.
- `failure_url` (string, optional, nullable) — Where Truemed sends the customer when they opt out of HSA/FSA or do not qualify in the survey. If omitted, the current failure URL is unchanged. In an iframe, Truemed returns this URL in the completion message instead of navigating. Has no effect once the qualification session reaches a terminal status.
- `metadata` (string, optional, nullable) — Optional metadata string (JSON-encoded by convention).
- `success_url` (string, optional, nullable) — Optional success redirect URL. Has no effect once the qualification session reaches a terminal status.
- `user_id` (string, optional, nullable) — Your stable, opaque identifier for the shopper. Can only be set when the qualification session does not already have one — attempting to overwrite an existing value returns the `user_id_already_set` error. To correct a previously set value, contact Truemed support.

## Response

### 200

Successful response

- `qualification_session_id` (string, required) — The qualification_session_id that was updated (echoed from the path param).
- `status` (enum, required) — Current status summary of the qualification session. This endpoint does not change the status. One of: - `pending` — The session was created; the shopper hasn't completed the survey yet. - `processing` — The shopper completed the survey and it is under review. - `approved` — The shopper holds a valid Letter of Medical Necessity covering the items in this order. - `rejected` — The shopper is ineligible for a Letter of Medical Necessity for the items in this order.
  - Allowed values: `pending`, `processing`, `approved`, `rejected`

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `BadRequest`, `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

**Request**

```json
{
  "idempotency_key": "string"
}
```

**Response**

```json
{
  "qualification_session_id": "string",
  "status": "pending"
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/api/v1/qualification_session/qualification_session_id/update"

payload = { "idempotency_key": "string" }
headers = {
    "x-truemed-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/api/v1/qualification_session/qualification_session_id/update';
const options = {
  method: 'POST',
  headers: {'x-truemed-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"idempotency_key":"string"}'
};

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