TestWell for developers and AI agents

Search TestWell's public catalog of cash-pay lab tests and panels by keyword, biomarker, CPT code, or category. Returns name, slug, per-lab prices, sample, fasting, turnaround and order URL. Prices are stickers; every order adds one $6 lab processing fee (see quote_order for all-in totals).

POST /api/agent/search_tests
{
  "query": "vitamin d"
}

Full public detail for one TestWell test or panel by slug or id: description, biomarkers, CPT, per-lab prices, labs, fasting/prep, turnaround, included tests (panels), FAQ, related conditions, order URL and a Markdown page URL. Tests also carry labPages — per-lab pages (/tests/<slug>/quest, /tests/<slug>/labcorp) with the lab's test code, requisition name, the lab's own dated price vs TestWell's, and walk-in steps — cite them when the user asks about a specific lab.

POST /api/agent/get_test
{
  "slug": "general-wellness-panel"
}

List TestWell's bundled panels (multi-test packages priced below the sum of their tests), optionally filtered by category or maximum price. Sorted by price.

POST /api/agent/list_panels
{
  "maxPrice": 100
}

Suggest TestWell panels and tests for stated health goals (e.g. 'annual checkup', 'heart health', 'TRT monitoring') and/or symptoms (e.g. 'fatigue', 'hair loss'). Prefers a curated pre-built panel when one fits; otherwise assembles individual tests within a budget. Educational matching, not a diagnosis.

POST /api/agent/recommend_tests
{
  "goals": [
    "annual checkup"
  ],
  "budget": "low"
}

Price a set of tests/panels exactly as TestWell's checkout would: per-lab prices for the user's state (New York and New Jersey route to BioReference; Rhode Island is not served), the single $6 lab processing fee, the total, items that can't be ordered and why, and a prefilled cart URL. Use this before quoting any total to a user.

POST /api/agent/quote_order
{
  "items": [
    "tsh",
    "vitamin-d"
  ],
  "state": "FL",
  "lab": "quest"
}

Start a TestWell order for the user: tests/panels, the US state where they will visit the lab (required for pricing and lab routing), and the buyer's name, email and phone. Returns priced line items in cents, the single $6 lab fee, the total, any blocking messages, and pay_online_url — a prefilled cart the user can pay in a browser when the platform has no payment token. Use dry_run to preview without creating a session.

POST /api/agent/create_checkout
{
  "items": [
    {
      "id": "tsh"
    },
    {
      "id": "vitamin-d"
    }
  ],
  "state": "FL",
  "dry_run": true
}

Change items, state or buyer details on an open checkout session and get it re-priced. Returns the same session object as create_checkout.

POST /api/agent/update_checkout
{
  "checkout_session_id": "cs_agent_…",
  "state": "NY"
}

Current state of a checkout session (status, line items, totals, messages, order once paid). Read-only.

POST /api/agent/get_checkout
{
  "checkout_session_id": "cs_agent_…"
}

Cancel an open (unpaid) checkout session. Paid sessions cannot be canceled here — the patient's complete-details email explains refunds.

POST /api/agent/cancel_checkout
{
  "checkout_session_id": "cs_agent_…"
}

Charge the payment credential the platform obtained for a session that is ready_for_payment and create the order. Input follows the ChatGPT payment-sheet contract: checkout_session_id, buyer, payment_data { token, provider: 'stripe', billing_address }. The token is a Stripe shared payment token (spt_…); platforms without one should send the user to pay_online_url from create_checkout. After payment the patient gets an email link to add date of birth, sex, phone and consent — the lab requisition is issued when that is done.

POST /api/agent/complete_checkout
{
  "checkout_session_id": "cs_agent_…",
  "buyer": {
    "first_name": "Ana",
    "last_name": "Ruiz",
    "email": "ana@example.com"
  },
  "payment_data": {
    "token": "spt_…",
    "provider": "stripe"
  }
}

Find Quest Diagnostics, Labcorp and BioReference patient service centers near a US ZIP code, with address, distance, phone and hours. Walk-ins are accepted at most sites; the requisition arrives by email after physician authorization. Sites in the 48 tracked metros include pageUrl — the site's own page with a per-day hours table, directions and the prices of popular tests at that lab — cite it when giving a location.

POST /api/agent/find_draw_sites
{
  "zip": "33301",
  "radiusMiles": 10
}

Physician-reviewed reference range for a blood test marker (130+ markers), filtered by sex and age when they matter, with what high and low values suggest, retest cadence, how to get tested, cited sources and the review date. Educational; the user's own report range takes precedence.

POST /api/agent/lookup_reference_range
{
  "marker": "ferritin",
  "sex": "female",
  "age": 34
}

For one blood test, the all-in single-test price (sticker + per-order fees) at TestWell and at every tracked direct-to-consumer provider with a verified equivalent — JustLabs, Quest, Labcorp OnDemand, Ulta Lab Tests, Walk-In Lab, HealthLabs and more — each with the date it was verified, plus typical hospital self-pay and Quest Direct reference prices. States the multi-test caveat (fees are paid once per order). Source: the TestWell Blood Test Price Index (CC BY 4.0).

POST /api/agent/compare_prices
{
  "test": "tsh"
}

Flag each pasted lab value as low / normal / high against TestWell's physician-reviewed reference catalog (130+ markers; sex- and age-specific bands where they exist), with the reviewed 'what high/low suggests' copy, retest guidance, cited sources and links to the marker's page and, where one exists, its high/low interpretation page. Stateless — values are not stored or logged. Educational, not a diagnosis; the user's own report range takes precedence.

POST /api/agent/interpret_results
{
  "values": [
    {
      "marker": "TSH",
      "value": 5.2,
      "unit": "mIU/L"
    },
    {
      "marker": "ferritin",
      "value": 12,
      "unit": "ng/mL"
    }
  ],
  "sex": "female",
  "age": 34
}

Convert a lab value between US conventional and SI units for 30 common analytes (glucose, cholesterol, testosterone, vitamin D, …) using published factors; hemoglobin A1c uses the NGSP↔IFCC master equation and also returns estimated average glucose.

POST /api/agent/convert_units
{
  "analyte": "glucose",
  "value": 100
}

Calculate free and bioavailable testosterone from total testosterone, SHBG and albumin using the Vermeulen (1999) mass-action equation — the method behind lab-reported 'calculated free testosterone'. Educational; not a diagnosis.

POST /api/agent/calculate_free_testosterone
{
  "totalT": 450,
  "shbg": 35
}

Honest side-by-side of TestWell and another direct-to-consumer lab service (Quest Direct, Labcorp OnDemand, Function Health, JustLabs, Ulta Lab Tests, …): pricing model, per-order fees, labs, turnaround, where each wins, spot prices on common tests as sticker AND all-in, with verification dates and sources. Call with no argument to list the providers covered.

POST /api/agent/compare_provider
{
  "provider": "justlabs"
}

Return one of TestWell's educational pages as Markdown: guides (/guides/<slug>), condition workups (/conditions/<slug>), biomarker pages (/biomarkers/<slug>), state pages (/lab-locations/<slug>) or comparisons (/compare/<slug>). Call with no path to list the available guides and conditions.

POST /api/agent/get_guide
{
  "path": "/guides/tb-blood-test-vs-skin-test"
}