Fast FHIR ClaimResponse

Complete JSON schema and reference for Fast FHIR ClaimResponse resources returned by Turquoise after claim adjudication.

Overview

ClaimResponse is the Turquoise adjudication decision. It includes allowed amounts, benefit determinations, and settlement metadata including the opaque Stripe trace ID.

Field Reference

Field	Type	Required	Description
`resourceType`	string	✓	Always `"ClaimResponse"`
`id`	string	✓	Unique response ID (e.g., `"CLMR-2024-001"`)
`status`	string	✓	Response status: `"active"`, `"cancelled"`
`use`	string	✓	Always `"claim"`
`claim`	object	✓	Reference to original claim: `{ "reference": "Claim/CLM-2024-001" }`
`created`	timestamp	✓	ISO 8601 adjudication timestamp
`outcome`	string	✓	Adjudication outcome: `"complete"`, `"partial"`, `"error"`
`item`	array	✗	Array of adjudicated line items
`adjudication`	array	✗	Top-level adjudication summary
`extension`	array	✗	Custom extensions (stripe-trace-id, aeob-reference, etc.)
`payment`	object	✗	Payment details object (see below)

Adjudication Categories

Each adjudication entry has a category that classifies the claim component:

Category	Code	Description	Example
Allowed Amount	`allowedamount`	Negotiated rate	$1,200.00
Benefit	`benefit`	Plan's payment amount	$1,100.00
Member Coinsurance	`coinsurance`	Member's % responsibility	$100.00 (EOB)
Member Deductible	`deductible`	Deductible applied	$0.00 (met)
Network Determination	`network`	In-network status	`"in_network"`
AEOB Reference	`aeob-reference`	Link to AEOB document	`"AEOB-2024-001"`

Extensions

stripe-trace-id

Unique opaque identifier for Stripe settlement tracking (no PHI):

{
  "url": "https://turquoise.health/stripe-trace-id",
  "valueString": "trace_0310_abc123xyz"
}

Use this to reconcile bank deposits to claim adjudications.

aeob-reference

Reference to Advance Explanation of Benefits:

{
  "url": "https://turquoise.health/aeob-reference",
  "valueString": "AEOB-2024-001"
}

network-status

Network determination:

{
  "url": "https://turquoise.health/network-status",
  "valueCode": "in_network|out_of_network|unknown"
}

Complete Example

Full ClaimResponse for institutional colonoscopy claim:

{
  "resourceType": "ClaimResponse",
  "id": "CLMR-2024-001",
  "status": "active",
  "use": "claim",
  "claim": {
    "reference": "Claim/CLM-2024-001"
  },
  "created": "2024-03-11T10:30:00Z",
  "outcome": "complete",
  "extension": [
    {
      "url": "https://turquoise.health/stripe-trace-id",
      "valueString": "trace_0310_abc123xyz"
    },
    {
      "url": "https://turquoise.health/aeob-reference",
      "valueString": "AEOB-2024-001"
    },
    {
      "url": "https://turquoise.health/network-status",
      "valueCode": "in_network"
    }
  ],
  "adjudication": [
    {
      "category": {
        "coding": [
          {
            "code": "allowedamount",
            "display": "Allowed Amount"
          }
        ]
      },
      "amount": {
        "value": 1500.00,
        "currency": "USD"
      }
    },
    {
      "category": {
        "coding": [
          {
            "code": "benefit",
            "display": "Benefit"
          }
        ]
      },
      "amount": {
        "value": 1400.00,
        "currency": "USD"
      }
    },
    {
      "category": {
        "coding": [
          {
            "code": "coinsurance",
            "display": "Member Coinsurance"
          }
        ]
      },
      "amount": {
        "value": 100.00,
        "currency": "USD"
      }
    }
  ],
  "item": [
    {
      "itemSequence": 1,
      "adjudication": [
        {
          "category": {
            "coding": [
              {
                "code": "allowedamount",
                "display": "Allowed Amount"
              }
            ]
          },
          "amount": {
            "value": 1500.00,
            "currency": "USD"
          }
        },
        {
          "category": {
            "coding": [
              {
                "code": "benefit",
                "display": "Benefit"
              }
            ]
          },
          "amount": {
            "value": 1400.00,
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "payment": {
    "type": {
      "coding": [
        {
          "code": "stripe_ach",
          "display": "Stripe ACH Transfer"
        }
      ]
    },
    "amount": {
      "value": 1400.00,
      "currency": "USD"
    },
    "date": "2024-03-12",
    "note": "Settlement initiated. Expected arrival 48 hours."
  }
}

Item Adjudication Structure

For multi-item claims, each item is adjudicated separately:

{
  "item": [
    {
      "itemSequence": 1,
      "adjudication": [
        {
          "category": { "coding": [{ "code": "allowedamount" }] },
          "amount": { "value": 1500.00, "currency": "USD" }
        },
        {
          "category": { "coding": [{ "code": "benefit" }] },
          "amount": { "value": 1400.00, "currency": "USD" }
        }
      ]
    },
    {
      "itemSequence": 2,
      "adjudication": [
        {
          "category": { "coding": [{ "code": "allowedamount" }] },
          "amount": { "value": 250.00, "currency": "USD" }
        },
        {
          "category": { "coding": [{ "code": "benefit" }] },
          "amount": { "value": 250.00, "currency": "USD" }
        }
      ]
    }
  ]
}

Payment Object

Settlement information in the payment field:

{
  "payment": {
    "type": {
      "coding": [
        {
          "code": "stripe_ach",
          "display": "Stripe ACH Transfer"
        }
      ]
    },
    "amount": {
      "value": 1400.00,
      "currency": "USD"
    },
    "date": "2024-03-12",
    "note": "Settlement initiated via Stripe Connect. Check webhook for completion."
  }
}

Field	Type	Description
`type.coding[0].code`	string	`"stripe_ach"` (always)
`amount.value`	decimal	Amount to be paid (after deductible, copay)
`date`	date	Expected settlement date
`note`	string	Settlement status message

Extracting Payout Instructions

To extract settlement information from ClaimResponse:

def extract_settlement_info(claim_response):
    return {
        'claim_response_id': claim_response['id'],
        'claim_id': claim_response['claim']['reference'].split('/')[-1],
        'outcome': claim_response['outcome'],
        'stripe_trace_id': next(
            (ext['valueString'] for ext in claim_response.get('extension', [])
             if ext['url'] == 'https://turquoise.health/stripe-trace-id'),
            None
        ),
        'allowed_amount': next(
            (adj['amount']['value'] for adj in claim_response['adjudication']
             if adj['category']['coding'][0]['code'] == 'allowedamount'),
            0
        ),
        'benefit_amount': next(
            (adj['amount']['value'] for adj in claim_response['adjudication']
             if adj['category']['coding'][0]['code'] == 'benefit'),
            0
        ),
        'settlement_amount': claim_response['payment']['amount']['value'],
        'expected_date': claim_response['payment']['date']
    }

Adjudication Outcomes

Outcome: complete

Claim fully adjudicated with no issues:

{
  "outcome": "complete",
  "adjudication": [
    { "category": { "coding": [{ "code": "allowedamount" }] }, "amount": { "value": 1500.00 } },
    { "category": { "coding": [{ "code": "benefit" }] }, "amount": { "value": 1400.00 } }
  ]
}

Outcome: partial

Claim partially adjudicated (e.g., some items disputed):

{
  "outcome": "partial",
  "adjudication": [
    { "category": { "coding": [{ "code": "allowedamount" }] }, "amount": { "value": 1500.00 } },
    { "category": { "coding": [{ "code": "benefit" }] }, "amount": { "value": 0.00 } }
  ],
  "processNote": [
    {
      "number": 1,
      "type": "display",
      "text": "Member not eligible for this procedure. Prior authorization required."
    }
  ]
}

Outcome: error

Claim rejected (e.g., invalid member, contract not found):

{
  "outcome": "error",
  "processNote": [
    {
      "number": 1,
      "type": "display",
      "text": "Member ID 'INVALID-ID' not found in SHARP-HMO-2024 plan."
    }
  ]
}

Network Status Determination

{
  "extension": [
    {
      "url": "https://turquoise.health/network-status",
      "valueCode": "in_network"
    }
  ]
}

Status	Meaning	Example
`in_network`	Provider is contracted	Allowed: $1,500 (full direct contract)
`out_of_network`	Provider not contracted	Allowed: $900 (emergency-only rate)
`unknown`	Network status indeterminate	Allowed: $0 (pending verification)

warning

Out-of-network claims may be adjusted or denied. Plan sponsor determines coverage.

Deductible & Copay Handling

Deductible Applied

If member has remaining deductible, it's applied first:

{
  "adjudication": [
    { "category": { "coding": [{ "code": "allowedamount" }] }, "amount": { "value": 1500.00 } },
    { "category": { "coding": [{ "code": "deductible" }] }, "amount": { "value": 500.00 } },
    { "category": { "coding": [{ "code": "benefit" }] }, "amount": { "value": 1000.00 } },
    { "category": { "coding": [{ "code": "coinsurance" }] }, "amount": { "value": 0.00 } }
  ]
}

Interpretation:

Allowed: $1,500
Deductible applied: $500
Plan pays (benefit): $1,000
Member pays: $500 (deductible)

Copay Structure

Copay after deductible is met:

{
  "adjudication": [
    { "category": { "coding": [{ "code": "allowedamount" }] }, "amount": { "value": 1500.00 } },
    { "category": { "coding": [{ "code": "deductible" }] }, "amount": { "value": 0.00 } },
    { "category": { "coding": [{ "code": "copayment" }] }, "amount": { "value": 100.00 } },
    { "category": { "coding": [{ "code": "benefit" }] }, "amount": { "value": 1400.00 } }
  ]
}

Interpretation:

Allowed: $1,500
Deductible: $0 (met)
Copay: $100 (member pays)
Plan pays (benefit): $1,400

Reconciliation Example

Map ClaimResponse back to claim for reconciliation:

def reconcile_claim(claim, claim_response):
    """Verify claim matches adjudicated response."""

    claimed_amount = sum(item['net']['value'] for item in claim['item'])
    allowed_amount = next(
        (adj['amount']['value'] for adj in claim_response['adjudication']
         if adj['category']['coding'][0]['code'] == 'allowedamount'),
        0
    )

    if claimed_amount != allowed_amount:
        print(f"WARNING: Claim amount ${claimed_amount} != allowed ${allowed_amount}")

    benefit_amount = next(
        (adj['amount']['value'] for adj in claim_response['adjudication']
         if adj['category']['coding'][0]['code'] == 'benefit'),
        0
    )

    print(f"Claim: ${claimed_amount} → Allowed: ${allowed_amount} → Benefit: ${benefit_amount}")

    return {
        'claim_id': claim['id'],
        'claimed': claimed_amount,
        'allowed': allowed_amount,
        'benefit': benefit_amount,
        'status': 'matched' if claimed_amount == allowed_amount else 'mismatched'
    }

Error Responses

Invalid Member

{
  "outcome": "error",
  "processNote": [{
    "type": "display",
    "text": "Member ID 'INVALID' not found in plan SHARP-HMO-2024"
  }]
}

Contract Not Found

{
  "outcome": "error",
  "processNote": [{
    "type": "display",
    "text": "No direct contract found for CPT 99999 under SHARP-HMO-2024"
  }]
}

Invalid Claim Format

{
  "outcome": "error",
  "processNote": [{
    "type": "display",
    "text": "Claim missing required field: item[0].net"
  }]
}

Polling for ClaimResponse

If ClaimResponse isn't returned immediately, poll for it:

# Poll every 5 seconds
CLAIM_ID="CLM-2024-001"
for i in {1..12}; do
  curl -X GET \
    https://api.turquoise.health/tpa-api/v1/claims/$CLAIM_ID/response \
    -H "X-API-Key: $TURQUOISE_API_KEY"
  sleep 5
done

info

Most claims adjudicate within 5 seconds. Complex claims may take up to 60 seconds.

Best Practices

Check outcome first: Verify outcome is "complete" before using adjudication data
Use trace IDs: Store stripe-trace-id for settlement reconciliation
Handle partial responses: Some claims may adjudicate partially; check processNote for details
Reconcile to claims: Compare ClaimResponse amounts back to original Claim
Monitor for errors: Track rejected claims and investigate reasons

Overview​

Field Reference​

Adjudication Categories​

Extensions​

stripe-trace-id​

aeob-reference​

network-status​

Complete Example​

Item Adjudication Structure​

Payment Object​

Extracting Payout Instructions​

Adjudication Outcomes​

Outcome: complete​

Outcome: partial​

Outcome: error​

Network Status Determination​

Deductible & Copay Handling​

Deductible Applied​

Copay Structure​

Reconciliation Example​

Error Responses​

Invalid Member​

Contract Not Found​

Invalid Claim Format​

Polling for ClaimResponse​

Best Practices​

Next Steps​