Blind Contract Lookup

Overview

The Blind Contract Lookup is the first stage of the contract discovery workflow. This endpoint allows a TPA to submit minimal provider and service metadata to verify whether a direct contract exists with the health plan, without revealing any pricing or financial terms. This approach minimizes data exposure and enables safe pre-flight validation.

info

This is a read-only verification endpoint. It returns only a match result and opaque contract identifier, never pricing data.

Endpoint

POST /v1/contract-lookup/blind/

Authentication Required: Yes (X-API-Key header) Content-Type: application/json Rate Limit: 1000 requests per minute

---

Request

Schema

Field	Type	Required	Description
npi	string	Yes	National Provider Identifier (NPI) of the facility or provider group
group_id	string	Yes	TPA network or group identifier (e.g., "SHARP_HEALTHCARE_NW")
cpt_codes	array[string]	Yes	List of CPT codes being checked (e.g., ["43235", "45378"])

Request Example

{
  "npi": "1234567890",
  "group_id": "SHARP_HEALTHCARE_NW",
  "cpt_codes": ["45378", "43235"]
}

---

Response

Success Response (200 OK)

Field	Type	Description
match_found	boolean	True if a contract covering these CPT codes exists
contract_id	string	Opaque contract identifier (only returned if match_found is true)
message	string	Human-readable confirmation message

{
  "match_found": true,
  "contract_id": "ct_1a2b3c4d5e6f7g8h",
  "message": "Contract found for NPI 1234567890 covering CPT codes 45378, 43235"
}

No Match Response (404 Not Found)

{
  "match_found": false,
  "message": "No active contract found for the specified NPI and CPT codes"
}

Validation Error (400 Bad Request)

{
  "errors": [
    {
      "field": "npi",
      "message": "NPI must be a 10-digit string"
    }
  ]
}

---

Examples

cURL

curl -X POST https://api.turquoise.health/tpa-api/v1/contract-lookup/blind/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "npi": "1234567890",
    "group_id": "SHARP_HEALTHCARE_NW",
    "cpt_codes": ["45378", "43235"]
  }'

Python

import requests

api_key = "YOUR_API_KEY"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

payload = {
    "npi": "1234567890",
    "group_id": "SHARP_HEALTHCARE_NW",
    "cpt_codes": ["45378", "43235"]
}

response = requests.post(
    "https://api.turquoise.health/tpa-api/v1/contract-lookup/blind/",
    json=payload,
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    if data["match_found"]:
        contract_id = data["contract_id"]
        print(f"Contract found: {contract_id}")
        # Proceed to full lookup
    else:
        print("No contract found")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

---

Workflow Integration

tip

Always call Blind Lookup before Full Contract Lookup. If this endpoint returns match_found: false, skip Full Lookup to save API calls and processing time.

The Blind Lookup is designed to fit into a two-stage contract verification flow:

1. Stage 1 (Blind Lookup) — Submit provider NPI, group ID, and CPT codes
2. Stage 2 (Full Lookup) — If match found, call Full Lookup with contract_id to retrieve pricing and terms

This approach ensures that pricing queries are only made for contracts that actually exist, reducing unnecessary data requests.