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

# 200 OK
# {
#   "object": "list",
#   "items": [
#     {
#       "id": "prc_9f2a7c",
#       "provider": { "id": "21929", "name": "Example Imaging Center" },
#       "total": { "amount": "482.00", "minor_units": 48200, "currency": "USD" }
#     }
#   ],
#   "page": { "size": 25, "total": 37, "next_cursor": "eyJ..." }
# }

# 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":"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}}'

# 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": "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,
        },
    },
)
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

Choose your integration

For developers

REST API

Query prices, providers, networks, and personalized member estimates from your own backend.

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