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

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.

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.

Authentication

x-truemed-api-keystring

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

Path parameters

qualification_session_idstringRequired

The qualification session ID from the URL path.

Request

Request body for UpdateQualificationSessionRequest

idempotency_keystringRequired<=255 characters

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_urlstring or nullOptional<=2048 characters

Optional failure redirect URL. Has no effect once the qualification session reaches a terminal status.

metadatastring or nullOptional<=4096 characters

Optional metadata string (JSON-encoded by convention).

success_urlstring or nullOptional<=2048 characters

Optional success redirect URL. Has no effect once the qualification session reaches a terminal status.

user_idstring or nullOptional<=255 characters

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

Successful response

qualification_session_idstring

The qualification_session_id that was updated (echoed from the path param).

statusenum

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.

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error

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.

$	curl -X POST https://dev-api.truemed.com/api/v1/qualification_session/qualification_session_id/update \
>	-H "x-truemed-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"idempotency_key": "string"
>	}'