Full Contract Lookup

Overview

The Full Contract Lookup endpoint retrieves detailed contract information including pricing, network tier, effective dates, and bundle configurations. This endpoint should only be called after a successful Blind Contract Lookup match to retrieve the contract_id. It returns all negotiated rates, Medicare multipliers, and bundle type classifications needed for claims processing and financial verification.

info

Full Lookup requires the contract_id from a prior Blind Lookup call. It returns complete pricing and terms information.

Endpoint

POST /v1/contract-lookup/full/

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

---

Request

Schema

Field	Type	Required	Description
contract_id	string	Yes	Opaque contract ID returned from Blind Lookup
npi	string	Yes	National Provider Identifier for verification
group_id	string	Yes	TPA network identifier
cpt_code	string	Yes	Specific CPT code for rate lookup
admit_type	string	No	Admission type (INPATIENT, OUTPATIENT, EMERGENCY). Defaults to OUTPATIENT

Request Example

{
  "contract_id": "ct_1a2b3c4d5e6f7g8h",
  "npi": "1234567890",
  "group_id": "SHARP_HEALTHCARE_NW",
  "cpt_code": "45378",
  "admit_type": "OUTPATIENT"
}

---

Response

Success Response (200 OK)

Field	Type	Description
contract_id	string	Opaque contract identifier
contract_number	string	Human-readable contract reference
effective_date	string	ISO 8601 date contract becomes active
termination_date	string	ISO 8601 date contract ends (null if active indefinitely)
network_tier	string	Network classification (TIER_1, TIER_2, PREFERRED, etc.)
rate_type	string	Pricing model (PERCENT_OF_CHARGES, FLAT_RATE, CASE_RATE, BUNDLE)
negotiated_rate	number	Negotiated rate for the specified CPT code (if rate_type is fixed)
medicare_multiplier	number	Multiplier of Medicare fee schedule (if rate_type is percentage)
bundle_type	string	Bundle classification (SINGLE, DOUBLE_HEADER, PACKAGE, null if unbundled)
anesthesia_included	boolean	Whether anesthesia is bundled in the rate

{
  "contract_id": "ct_1a2b3c4d5e6f7g8h",
  "contract_number": "SHP-2024-001",
  "effective_date": "2024-01-01",
  "termination_date": null,
  "network_tier": "TIER_1",
  "rate_type": "CASE_RATE",
  "negotiated_rate": 2500.00,
  "medicare_multiplier": null,
  "bundle_type": "DOUBLE_HEADER",
  "anesthesia_included": true
}

Not Found Response (404 Not Found)

{
  "error": "Contract not found or has expired",
  "contract_id": "ct_1a2b3c4d5e6f7g8h"
}

Invalid Contract ID (400 Bad Request)

{
  "errors": [
    {
      "field": "contract_id",
      "message": "Invalid or expired contract identifier"
    }
  ]
}

---

Examples

cURL

curl -X POST https://api.turquoise.health/tpa-api/v1/contract-lookup/full/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "ct_1a2b3c4d5e6f7g8h",
    "npi": "1234567890",
    "group_id": "SHARP_HEALTHCARE_NW",
    "cpt_code": "45378",
    "admit_type": "OUTPATIENT"
  }'

Python

import requests
from datetime import datetime

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

# Assume contract_id came from blind lookup
contract_id = "ct_1a2b3c4d5e6f7g8h"

payload = {
    "contract_id": contract_id,
    "npi": "1234567890",
    "group_id": "SHARP_HEALTHCARE_NW",
    "cpt_code": "45378",
    "admit_type": "OUTPATIENT"
}

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

if response.status_code == 200:
    contract = response.json()
    print(f"Contract: {contract['contract_number']}")
    print(f"Rate Type: {contract['rate_type']}")

    if contract["rate_type"] == "CASE_RATE":
        rate = contract["negotiated_rate"]
        print(f"Negotiated Rate: ${rate:.2f}")
    elif contract["rate_type"] == "PERCENT_OF_CHARGES":
        mult = contract["medicare_multiplier"]
        print(f"Medicare Multiplier: {mult}x")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

---

Rate Type Interpretation

tip

Use the rate_type field to determine how to calculate expected reimbursement:

• FLAT_RATE / CASE_RATE: Use negotiated_rate directly
• PERCENT_OF_CHARGES: Multiply submitted charges by medicare_multiplier
• BUNDLE: Multiple service lines rolled into single case rate

Bundle Types

The bundle_type field indicates how multiple procedures are priced:

• SINGLE — Individual procedure pricing
• DOUBLE_HEADER — Two primary procedures (e.g., colonoscopy + EGD) at bundled rate
• PACKAGE — Multi-day or multi-procedure package with per-diem or inclusive rate
• null — Not bundled

For bundles, the negotiated_rate applies to the entire bundle, not per-procedure.