Fast FHIR Claim

Complete JSON schema and reference for Fast FHIR Claim resources submitted to Turquoise.

Overview

Fast FHIR is a simplified subset of the FHIR Claim resource optimized for healthcare pricing workflows. It captures essential claim data without unnecessary complexity.

Field Reference

Field	Type	Required	Description
resourceType	string	✓	Must be "Claim"
id	string	✓	Unique claim identifier (e.g., "CLM-2024-001")
status	string	✓	Claim status: "active", "cancelled", "draft"
type	object	✓	Claim type: { "coding": [{ "code": "institutional" | "professional" }] }
use	string	✓	Claim use: "claim" or "preauthorization"
patient	object	✓	Patient identifier: { "identifier": { "value": "MEMBER_ID" } }
created	timestamp	✓	ISO 8601 creation timestamp (e.g., "2024-03-10T10:00:00Z")
provider	object	✓	Provider NPI: { "identifier": { "value": "1234567890" } }
facility	object	✗	Facility NPI (institutional claims): { "identifier": { "value": "9876543210" } }
insurer	object	✓	Plan/insurer ID: { "identifier": { "value": "PLAN_ID" } }
servicedDate	date	✗	Service date (YYYY-MM-DD format)
item	array	✓	Array of claim line items (see below)
extension	array	✗	Custom extensions (guarantee ID, admit type, etc.)

Item Structure

Each claim must include at least one item:

{
  "sequence": 1,
  "productOrService": {
    "coding": [{ "code": "43235" }]
  },
  "servicedDate": "2024-03-10",
  "quantity": { "value": 1 },
  "unitPrice": { "value": 1200.00, "currency": "USD" },
  "net": { "value": 1200.00, "currency": "USD" },
  "extension": [
    {
      "url": "https://turquoise.health/admit-type",
      "valueCode": "emergency"
    }
  ]
}

Field	Type	Required	Description
sequence	integer	✓	Line item number (1, 2, 3...)
productOrService	object	✓	CPT/HCPCS code: { "coding": [{ "code": "43235" }] }
servicedDate	date	✗	Service date (YYYY-MM-DD)
quantity	object	✗	Quantity: { "value": 1 } (default: 1)
unitPrice	object	✗	Price per unit: { "value": 1200.00, "currency": "USD" }
net	object	✗	Total item amount: { "value": 1200.00, "currency": "USD" }
extension	array	✗	Item-level extensions

Extensions

admit-type (Institutional Claims)

Specify the admission type for facility claims:

{
  "url": "https://turquoise.health/admit-type",
  "valueCode": "emergency|urgent|scheduled|newborn|trauma|other"
}

guarantee-id (Pre-Service Guarantees)

Reference a pre-service guarantee:

{
  "url": "https://turquoise.health/guarantee-id",
  "valueString": "GUAR-20240310-001"
}

modifier-codes (Line Item Modifiers)

Add CPT modifiers (e.g., bilateral, reduced services):

{
  "url": "https://turquoise.health/modifier-codes",
  "valueCode": "RT|LT|50|52|59"
}

Professional Claim Example

EGD performed by gastroenterologist:

{
  "resourceType": "Claim",
  "id": "CLM-PROF-001",
  "status": "active",
  "type": { "coding": [{ "code": "professional" }] },
  "use": "claim",
  "patient": { "identifier": { "value": "SHP00123456" } },
  "provider": { "identifier": { "value": "1234567890" } },
  "insurer": { "identifier": { "value": "SHARP-HMO-2024" } },
  "created": "2024-03-11T10:00:00Z",
  "servicedDate": "2024-03-10",
  "item": [
    {
      "sequence": 1,
      "productOrService": { "coding": [{ "code": "43235" }] },
      "servicedDate": "2024-03-10",
      "unitPrice": { "value": 1200.00, "currency": "USD" },
      "net": { "value": 1200.00, "currency": "USD" }
    }
  ]
}

Institutional Claim Example

Facility charge for colonoscopy at hospital:

{
  "resourceType": "Claim",
  "id": "CLM-INST-001",
  "status": "active",
  "type": { "coding": [{ "code": "institutional" }] },
  "use": "claim",
  "patient": { "identifier": { "value": "SHP00123456" } },
  "provider": { "identifier": { "value": "1234567890" } },
  "facility": { "identifier": { "value": "9876543210" } },
  "insurer": { "identifier": { "value": "SHARP-HMO-2024" } },
  "created": "2024-03-11T10:00:00Z",
  "servicedDate": "2024-03-10",
  "extension": [
    {
      "url": "https://turquoise.health/admit-type",
      "valueCode": "scheduled"
    }
  ],
  "item": [
    {
      "sequence": 1,
      "productOrService": { "coding": [{ "code": "45378" }] },
      "servicedDate": "2024-03-10",
      "quantity": { "value": 1 },
      "unitPrice": { "value": 1500.00, "currency": "USD" },
      "net": { "value": 1500.00, "currency": "USD" }
    }
  ]
}

Bundle Claim Example (Multiple Items)

Claim with multiple services (e.g., EGD + biopsy):

{
  "resourceType": "Claim",
  "id": "CLM-BUNDLE-001",
  "status": "active",
  "type": { "coding": [{ "code": "professional" }] },
  "use": "claim",
  "patient": { "identifier": { "value": "SHP00123456" } },
  "provider": { "identifier": { "value": "1234567890" } },
  "insurer": { "identifier": { "value": "SHARP-HMO-2024" } },
  "created": "2024-03-11T10:00:00Z",
  "servicedDate": "2024-03-10",
  "item": [
    {
      "sequence": 1,
      "productOrService": { "coding": [{ "code": "43235" }] },
      "servicedDate": "2024-03-10",
      "unitPrice": { "value": 1200.00, "currency": "USD" },
      "net": { "value": 1200.00, "currency": "USD" },
      "description": "EGD - esophagogastroduodenoscopy"
    },
    {
      "sequence": 2,
      "productOrService": { "coding": [{ "code": "43239" }] },
      "servicedDate": "2024-03-10",
      "unitPrice": { "value": 250.00, "currency": "USD" },
      "net": { "value": 250.00, "currency": "USD" },
      "description": "Biopsy of stomach"
    }
  ]
}

Claim with Pre-Service Guarantee

Reference a guarantee to eliminate pricing disputes:

{
  "resourceType": "Claim",
  "id": "CLM-GUAR-001",
  "status": "active",
  "type": { "coding": [{ "code": "institutional" }] },
  "use": "claim",
  "patient": { "identifier": { "value": "SHP00123456" } },
  "provider": { "identifier": { "value": "1234567890" } },
  "facility": { "identifier": { "value": "9876543210" } },
  "insurer": { "identifier": { "value": "SHARP-HMO-2024" } },
  "created": "2024-03-11T10:00:00Z",
  "servicedDate": "2024-03-10",
  "extension": [
    {
      "url": "https://turquoise.health/guarantee-id",
      "valueString": "GUAR-20240310-001"
    },
    {
      "url": "https://turquoise.health/admit-type",
      "valueCode": "scheduled"
    }
  ],
  "item": [
    {
      "sequence": 1,
      "productOrService": { "coding": [{ "code": "43235" }] },
      "servicedDate": "2024-03-10",
      "unitPrice": { "value": 1200.00, "currency": "USD" },
      "net": { "value": 1200.00, "currency": "USD" }
    }
  ]
}

Validation Rules

Turquoise validates claims before adjudication:

Required Fields

• resourceType: Must equal "Claim"
• id: Unique per TPA (within 1 year)
• status: "active" required for processing
• use: "claim" required
• patient.identifier.value: Valid member ID
• provider.identifier.value: Valid NPI
• insurer.identifier.value: Valid plan ID
• created: Valid ISO 8601 timestamp
• item: At least one item required

Conditional Requirements

• Institutional claims: Require facility.identifier.value
• Professional claims: facility is optional
• Items with modifiers: Add extension with modifier-codes

Data Validation

def validate_claim(claim):
    # resourceType
    assert claim['resourceType'] == 'Claim', "Invalid resourceType"

    # IDs
    assert claim['id'], "Claim ID required"
    assert len(claim['id']) <= 64, "Claim ID too long (max 64 chars)"

    # Status & use
    assert claim['status'] in ['active', 'cancelled', 'draft'], "Invalid status"
    assert claim['use'] == 'claim', "Invalid use (must be 'claim')"

    # Identifiers
    assert claim['patient']['identifier']['value'], "Member ID required"
    assert claim['provider']['identifier']['value'], "Provider NPI required"
    assert claim['insurer']['identifier']['value'], "Plan ID required"

    # Type
    assert claim['type']['coding'][0]['code'] in ['professional', 'institutional'], \
        "Type must be professional or institutional"

    # Items
    assert len(claim['item']) > 0, "At least one item required"
    for item in claim['item']:
        assert item['sequence'] > 0, "Item sequence must be > 0"
        assert item['productOrService']['coding'][0]['code'], "CPT code required"
        assert item.get('net', {}).get('value', 0) > 0, "Item amount must be > 0"

    return True

Common Errors

Error: Missing member ID

{
  "error": "validation_error",
  "message": "Missing required field: patient.identifier.value",
  "field": "patient.identifier.value"
}

Fix: Include member ID in claim submission.

Error: Invalid CPT code

{
  "error": "validation_error",
  "message": "CPT code '99999' not recognized",
  "field": "item[0].productOrService.coding[0].code"
}

Fix: Use valid CPT/HCPCS codes. Check against Turquoise contract codes.

Error: Missing facility for institutional claim

{
  "error": "validation_error",
  "message": "Institutional claims require facility NPI",
  "field": "facility.identifier.value"
}

Fix: For type.code = "institutional", include facility NPI.

Error: Item amount mismatch

{
  "error": "validation_error",
  "message": "Item net amount (1500.00) does not match unitPrice × quantity (1200.00 × 1)",
  "field": "item[0].net"
}

Fix: Ensure net = unitPrice × quantity.

Testing Claims

Sandbox Test Cases

Use these test member IDs in sandbox to trigger specific behaviors:

Member ID	Plan	Behavior
TEST-APPROVED	SHARP-HMO-2024	Claim approved without changes
TEST-DEDUCTIBLE	SHARP-HMO-2024	Remaining deductible: $500
TEST-NOT-ELIGIBLE	SHARP-HMO-2024	Member not eligible for procedure
TEST-INACTIVE	SHARP-HMO-2024	Member coverage inactive

Example:

curl -X POST \
  https://sandbox.api.turquoise.health/tpa-api/v1/claims/submit \
  -H "X-API-Key: $TURQUOISE_API_KEY" \
  -d '{
    "resourceType": "Claim",
    "id": "TEST-CLM-001",
    ...
    "patient": { "identifier": { "value": "TEST-DEDUCTIBLE" } }
    ...
  }'

Batch Submission (NDJSON)

For high-volume submissions, send multiple claims in newline-delimited JSON:

POST /claims/batch-submit
Content-Type: application/x-ndjson

{"resourceType":"Claim","id":"CLM-001",...}
{"resourceType":"Claim","id":"CLM-002",...}
{"resourceType":"Claim","id":"CLM-003",...}

Best Practices

1. Use guarantee IDs: Reference pre-service guarantees when available
2. Unique IDs: Ensure claim IDs are unique per TPA for 1+ year
3. Accurate amounts: Match billed amounts to actual charges
4. Complete items: Include all line items in single submission
5. Timely submission: Submit claims within 3-5 days of service
6. Idempotency: Include Idempotency-Key header to prevent duplicates

Next Steps

• ClaimResponse Schema
• TPA Integration Guide
• Sandbox Testing