Start Building

Get started with our API or MCP in a few easy steps.

Quickstart

The Consumer Pricing API and MCP server share an OAuth 2.0 Client Credentials flow for authentication, which is designed for server-to-server requests. The same token authenticates both the REST API and the MCP server.

Get your credentials

You’ll need a client_id, client_secret, and organization_id.

Get an access token

Exchange your credentials for a short-lived bearer token via the OAuth 2.0 client-credentials flow.

curl --request POST \
  --url https://api.turquoise.health/oauth/token \
  --header "Content-Type: application/json" \
  --data '{"grant_type":"client_credentials","client_id":"<clientID>","client_secret":"<clientSecret>","organization_id":"<organizationID>"}'

# pip install requests
import requests

response = requests.post(
    "https://api.turquoise.health/oauth/token",
    headers={"Content-Type": "application/json"},
    json={
        "grant_type": "client_credentials",
        "client_id": "<clientID>",
        "client_secret": "<clientSecret>",
        "organization_id": "<organizationID>",
    },
)
token = response.json()["access_token"]

const response = await fetch("https://api.turquoise.health/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: "<clientID>",
    client_secret: "<clientSecret>",
    organization_id: "<organizationID>",
  }),
});
const { access_token: token } = await response.json();

A successful response returns a JSON object:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Field	Description
`access_token`	Bearer token to send on every request.
`token_type`	Always `Bearer`.
`expires_in`	Seconds until expiry (e.g. `3600` = 1 hour).

Token expiration

Tokens expire after the number of seconds indicated by expires_in. When a token expires, your requests will receive a 401 Unauthorized response. At that point, repeat the token request above to obtain a new one. We recommend proactively refreshing tokens before expiry rather than waiting for a 401.

Make your first call

Search for prices on a knee MRI near Denver. Include the access token from the previous step in the Authorization header of every request, whether you’re using cURL, Python, TypeScript, or any other HTTP client.

curl --request POST \
  --url https://api.turquoise.health/v3/prices/query \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{"package_id":"RA005","pricing":{"type":"cash"},"location":{"zip":"80202"}}'

# pip install requests
import requests

response = requests.post(
    "https://api.turquoise.health/v3/prices/query",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "package_id": "RA005",
        "pricing": {"type": "cash"},
        "location": {"zip": "80202"},
    },
)
prices = response.json()
print(prices)

const response = await fetch("https://api.turquoise.health/v3/prices/query", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    package_id: "RA005",
    pricing: { type: "cash" },
    location: { zip: "80202" },
  }),
});
const prices = await response.json();
console.log(prices);

Get a personalized out-of-pocket estimate

The call above returns the rate. To get what a specific member actually pays, add their eligibility and hit the personalized-estimates endpoint:

curl --request POST \
  --url https://api.turquoise.health/v3/personalized-estimates \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{"package_id":"RA005","pricing":{"type":"negotiated","network_id":"-3776001016975145508"},"location":{"zip":"80202"},"member_eligibility":{"first_name":"Jane","last_name":"Doe","date_of_birth":"1990-01-01","member_id":"MBR-000-EXAMPLE","consent_attested":true}}'

# pip install requests
import requests

response = requests.post(
    "https://api.turquoise.health/v3/personalized-estimates",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "package_id": "RA005",
        "pricing": {"type": "negotiated", "network_id": "-3776001016975145508"},
        "location": {"zip": "80202"},
        "member_eligibility": {
            "first_name": "Jane",
            "last_name": "Doe",
            "date_of_birth": "1990-01-01",
            "member_id": "MBR-000-EXAMPLE",
            "consent_attested": True,
        },
    },
)
estimate = response.json()
print(estimate)

const response = await fetch("https://api.turquoise.health/v3/personalized-estimates", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    package_id: "RA005",
    pricing: { type: "negotiated", network_id: "482910" },
    location: { zip: "80202" },
    member_eligibility: {
      first_name: "Jane",
      last_name: "Doe",
      date_of_birth: "1990-01-01",
      member_id: "MBR-000-EXAMPLE",
      consent_attested: true,
    },
  }),
});
const estimate = await response.json();
console.log(estimate);

Personalized Estimates

Use an official client library

Prefer a typed client over raw HTTP? Official libraries for Python, TypeScript, and C# wrap the OAuth flow above behind an APIAuthHandler utility and give you typed request/response models for every endpoint.

Building with an AI coding assistant? Point it at github.com/turquoisehealth/turquoise-api-client. The README and examples/ directory contain the same authentication and request patterns below in complete, runnable form.

Install

pip install turquoisehealth-api

npm install @turquoisehealth/api

dotnet add package TurquoiseHealth.Api

Initialize the client

Set the three credentials as environment variables, then create the auth handler once to reuse it across your application. The handler caches the token in memory and refreshes it before it expires.

Important: Reuse the auth handler after creation

Each handler maintains an in-memory token cache with automatic refresh. Creating new instances for every request will bypass the cache and unnecessarily refetch tokens from the OAuth server, leading to performance degradation and rate limiting errors.

# export TURQUOISE_CLIENT_ID, TURQUOISE_CLIENT_SECRET, TURQUOISE_ORGANIZATION_ID
from turquoise_health import TurquoiseHealth, APIAuthHandler

auth = APIAuthHandler.from_client_credentials()
client = TurquoiseHealth(
    base_url="https://api.turquoise.health",
    token=auth.as_callable()
)

// export TURQUOISE_CLIENT_ID, TURQUOISE_CLIENT_SECRET, TURQUOISE_ORGANIZATION_ID
import { TurquoiseHealthApiClient, lib } from "@turquoisehealth/api";

const auth = lib.APIAuthHandler.fromClientCredentials();
const client = new TurquoiseHealthApiClient({
  environment: "https://api.turquoise.health",
  token: auth.asSupplier(),
});

// export TURQUOISE_CLIENT_ID, TURQUOISE_CLIENT_SECRET, TURQUOISE_ORGANIZATION_ID
using TurquoiseHealth.Api;
using TurquoiseHealth.Api.Lib;

var auth = APIAuthHandler.FromClientCredentials();
var client = new TurquoiseHealthApiClient(auth.GetToken(), new ClientOptions
{
    BaseUrl = "https://api.turquoise.health"
});

Query prices

The same knee MRI search from step 3 above, through the client:

prices = client.consumer_pricing.v3query_prices(
    package_id="RA005",
    pricing={"type": "cash"},
    location={"zip": "80202"},
)
for price in prices.items:
    print(price.provider.name, price.total.amount)

const prices = await client.consumerPricing.v3QueryPrices({
  package_id: "RA005",
  pricing: { type: "cash" },
  location: { zip: "80202" },
});
for (const price of prices.items) {
  console.log(price.provider.name, price.total.amount);
}

var prices = await client.ConsumerPricing.V3QueryPricesAsync(new V3PricesQueryRequest
{
    PackageId = "RA005",
    Pricing = new V3PricesQueryRequestPricing(new V3PricesQueryRequestPricing.Cash(new V3PricingCash())),
    Location = new V3Location { Zip = "80202" },
});

foreach (var price in prices.Items)
{
    Console.WriteLine($"{price.Provider.Name} {price.Total.Amount}");
}

View source, README, and examples on GitHub

Choose your integration

For developers

REST API

Query prices, providers, networks, and personalized member estimates from your own backend, either directly over HTTP or through an official client library.

Go to API reference

For AI agents

MCP server

Connect our server to Claude Code, Claude Desktop, Codex, or Cursor and query our pricing data conversationally. No code required.

Go to MCP reference