Skip to navigation
API ReferenceQualification Sessions

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.

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

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.

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.
Allowed values:

Errors

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