For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomeGuidesAPI Reference
HomeGuidesAPI Reference
  • Payment Sessions
    • Payments Overview
    • Manual/Delayed Capture
    • Itemized Fees and Discounts
  • Implementation
    • Stripe Custom Payment Method
    • iFrame Payment Session
  • Product Catalog
    • Overview
    • Managing Your Catalog
  • Qualification Sessions
    • Update a Qualification Session
  • Direct Substantiation
    • Overview
    • TPA Guide
    • Employers Guide
    • Platforms Guide
  • Subscriptions
    • Overview
    • Create a Subscription (New Subscriber)
    • Create a Subscription (Existing Subscriber)
    • Subsequent Billing Periods
    • Partner Administrative Operations
  • Resources
    • Webhooks
    • Developer Tools
LogoLogo
On this page
  • Why this matters
  • How to implement
  • user_id is set-when-null
  • Safe retries with idempotency
  • Notes and caveats
Qualification Sessions

Update a Qualification Session

Was this page helpful?
Previous

Overview

Next
Built with

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.

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.

1

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.

2

Call the update endpoint

Send a POST to 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.

$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"
>  }'
3

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.

1{
2  "qualification_session_id": "qs_abc123",
3  "status": "approved"
4}

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.

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.

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.