Quickstart

Get your first API call working in 5 minutes using our sandbox environment.

Prerequisites

• API key (request from Turquoise support)
• curl or Python 3.7+
• Sandbox credentials for Sharp HealthCare demo

Step 1: Set Up Your API Key

Export your API key as an environment variable:

export TURQUOISE_API_KEY="your-sandbox-api-key-here"

info

Keep your API key secure. Never commit it to version control or share it publicly. Rotate keys regularly.

Step 2: Verify Sandbox Access

Test your authentication with a health check:

curl -X GET \
  https://sandbox.api.turquoise.health/tpa-api/v1/health \
  -H "X-API-Key: $TURQUOISE_API_KEY"

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "environment": "sandbox"
}

Step 3: Make Your First Contract Lookup

Perform a blind contract lookup for a GI procedure:

curl -X POST \
  https://sandbox.api.turquoise.health/tpa-api/v1/contracts/lookup \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_npi": "1234567890",
    "plan_id": "SHARP-HMO-2024",
    "service_code": "43235",
    "member_id": "SHP00123456"
  }'

Expected response (< 200ms):

{
  "contract_id": "DIR-2024-001",
  "negotiated_rate": 1200.00,
  "service_code": "43235",
  "member_responsibility": 100.00,
  "plan_pays": 1100.00,
  "expires_at": "2025-12-31T23:59:59Z"
}

Step 4: Submit a Test Claim

Submit a FHIR Claim for pricing verification:

curl -X POST \
  https://sandbox.api.turquoise.health/tpa-api/v1/claims/submit \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Claim",
    "id": "DEMO-CLM-001",
    "status": "active",
    "type": { "coding": [{ "code": "institutional" }] },
    "patient": { "identifier": { "value": "SHP00123456" } },
    "provider": { "identifier": { "value": "1234567890" } },
    "insurer": { "identifier": { "value": "SHARP-HMO-2024" } },
    "created": "2024-03-10T10:00:00Z",
    "item": [{
      "sequence": 1,
      "productOrService": { "coding": [{ "code": "43235" }] },
      "servicedDate": "2024-03-15",
      "unitPrice": { "value": 1200.00, "currency": "USD" },
      "net": { "value": 1200.00, "currency": "USD" }
    }]
  }'

Step 5: Check the Response

The API returns a ClaimResponse with adjudication details:

{
  "resourceType": "ClaimResponse",
  "id": "DEMO-CLMR-001",
  "status": "active",
  "use": "claim",
  "claim": { "reference": "Claim/DEMO-CLM-001" },
  "outcome": "complete",
  "adjudication": [{
    "category": { "coding": [{ "code": "allowedamount" }] },
    "amount": { "value": 1200.00, "currency": "USD" }
  }],
  "extension": [{
    "url": "https://turquoise.health/stripe-trace-id",
    "valueString": "trace_abc123xyz"
  }]
}

tip

Use the stripe-trace-id extension to track payments through Stripe Connect without exposing PHI.

Next Steps

• Read the Authentication Guide for production setup
• Explore TPA Integration for batch processing
• Review the FHIR Claim Schema for advanced fields
• Join our Developer Community for support

Sandbox Test Data

The sandbox includes pre-configured test data:

Provider	NPI	Plan	Service	Rate
Sharp HealthCare	1234567890	SHARP-HMO-2024	EGD (43235)	$1,200
Sharp HealthCare	1234567890	SHARP-HMO-2024	Colonoscopy (45378)	$1,500
Sharp HealthCare	1234567890	SHARP-HMO-2024	GI Double Header	$2,400

warning

Sandbox data resets daily. Do not rely on stored state across sessions.