Get Claim Response

Overview

After submitting a claim via the Submit Claim endpoint, use this endpoint to poll for the adjudicated ClaimResponse. The response includes allowed amounts, benefit determinations, patient responsibility, AEOB reference, and Stripe settlement trace ID for financial reconciliation.

info

Claims are processed asynchronously. Poll this endpoint to check processing status and retrieve adjudication details.

Endpoint

GET /v1/claims/{submission_id}/response/

Authentication Required: Yes (X-API-Key header) Rate Limit: 100 requests per minute per API key

---

Request

Path Parameters

Parameter	Type	Required	Description
submission_id	string	Yes	Submission ID from Submit Claim response (e.g., sub_1a2b3c4d5e6f7g8h)

Query Parameters

Parameter	Type	Required	Description
include_raw_response	boolean	No	Include raw FHIR ClaimResponse JSON (default: false)

Example Request

GET /v1/claims/sub_1a2b3c4d5e6f7g8h/response/?include_raw_response=true

---

Response

Completed Response (200 OK)

Field	Type	Description
submission_id	string	Original submission identifier
status	string	ACKNOWLEDGED, PROCESSING, or ADJUDICATED
claim_response	object	Adjudicated FHIR ClaimResponse resource
adjudication	object	Financial summary with allowed/benefit/responsibility amounts
aeob_reference	string	AEOB document identifier for patient explanation
stripe_trace_id	string	Stripe transfer ID for settlement tracking
disposition	string	Final disposition (APPROVED, DENIED, PARTIAL_APPROVAL, PENDING_REVIEW)
completed_at	string	ISO 8601 timestamp when adjudication completed

{
  "submission_id": "sub_1a2b3c4d5e6f7g8h",
  "status": "ADJUDICATED",
  "adjudication": {
    "service_date": "2024-02-15",
    "total_charges": 2000.00,
    "allowed_amount": 1950.00,
    "deductible_applied": 0.00,
    "copay_applied": 25.00,
    "coinsurance_applied": 25.00,
    "patient_responsibility": 50.00,
    "benefit_amount": 1900.00,
    "payer_responsibility": 1900.00
  },
  "aeob_reference": "AEOB-2024-098765",
  "stripe_trace_id": "tr_1Oz9rZA1g7yLGa7e0xYzFxVK",
  "disposition": "APPROVED",
  "completed_at": "2024-02-17T14:32:10Z",
  "claim_response": {
    "resourceType": "ClaimResponse",
    "id": "RESP-098765",
    "status": "active",
    "type": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/claim-type",
          "code": "professional"
        }
      ]
    },
    "use": "claim",
    "patient": {
      "reference": "Patient/P12345"
    },
    "created": "2024-02-17",
    "insurer": {
      "reference": "Organization/SHPLAN"
    },
    "request": {
      "reference": "Claim/CLM-2024-098765"
    },
    "outcome": "complete",
    "disposition": "Claim processed successfully",
    "item": [
      {
        "itemSequence": 1,
        "adjudication": [
          {
            "category": {
              "coding": [
                {
                  "code": "submitted"
                }
              ]
            },
            "amount": {
              "value": 2000.00,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "code": "allowable"
                }
              ]
            },
            "amount": {
              "value": 1950.00,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "code": "benefit"
                }
              ]
            },
            "amount": {
              "value": 1900.00,
              "currency": "USD"
            }
          }
        ]
      }
    ]
  }
}

Processing Response (202 Accepted)

Claim is still being adjudicated. Check back later.

{
  "submission_id": "sub_1a2b3c4d5e6f7g8h",
  "status": "PROCESSING",
  "message": "Claim is being adjudicated",
  "estimated_completion": "2024-02-17T16:00:00Z"
}

Not Found Response (404 Not Found)

{
  "error": "Claim submission not found",
  "submission_id": "sub_invalid123"
}

Denied Response (200 OK)

{
  "submission_id": "sub_1a2b3c4d5e6f7g8h",
  "status": "ADJUDICATED",
  "disposition": "DENIED",
  "denial_reason": "Service not covered under plan",
  "denial_code": "NOT_COVERED",
  "aeob_reference": "AEOB-2024-098765",
  "completed_at": "2024-02-17T14:15:00Z"
}

---

Examples

cURL

# Check processing status
curl -X GET "https://api.turquoise.health/tpa-api/v1/claims/sub_1a2b3c4d5e6f7g8h/response/" \
  -H "X-API-Key: YOUR_API_KEY"

# Include raw FHIR response
curl -X GET "https://api.turquoise.health/tpa-api/v1/claims/sub_1a2b3c4d5e6f7g8h/response/?include_raw_response=true" \
  -H "X-API-Key: YOUR_API_KEY"

Python (Poll Until Adjudicated)

import requests
import time

api_key = "YOUR_API_KEY"
submission_id = "sub_1a2b3c4d5e6f7g8h"

headers = {
    "X-API-Key": api_key
}

max_wait = 300  # 5 minutes
elapsed = 0
poll_interval = 5  # Start with 5 seconds

while elapsed < max_wait:
    response = requests.get(
        f"https://api.turquoise.health/tpa-api/v1/claims/{submission_id}/response/",
        headers=headers
    )

    if response.status_code == 200:
        data = response.json()
        status = data.get("status")

        if status == "ADJUDICATED":
            print("Claim adjudicated!")
            print(f"Disposition: {data['disposition']}")
            print(f"Benefit Amount: ${data['adjudication']['benefit_amount']:.2f}")
            print(f"Patient Responsibility: ${data['adjudication']['patient_responsibility']:.2f}")
            print(f"Stripe Trace ID: {data['stripe_trace_id']}")
            break
        elif status == "PROCESSING":
            print(f"Still processing... Estimated completion: {data['estimated_completion']}")
            time.sleep(poll_interval)
            poll_interval = min(poll_interval + 5, 30)  # Back off to 30 seconds max
            elapsed += poll_interval
    else:
        print(f"Error: {response.status_code}")
        print(response.json())
        break

if elapsed >= max_wait:
    print("Timeout waiting for adjudication")

Python (Check with Raw FHIR)

import requests

api_key = "YOUR_API_KEY"
submission_id = "sub_1a2b3c4d5e6f7g8h"

response = requests.get(
    f"https://api.turquoise.health/tpa-api/v1/claims/{submission_id}/response/",
    params={"include_raw_response": "true"},
    headers={"X-API-Key": api_key}
)

if response.status_code == 200:
    data = response.json()

    if data["status"] == "ADJUDICATED":
        # Access adjudication details
        adj = data["adjudication"]
        print(f"Allowed: ${adj['allowed_amount']:.2f}")
        print(f"Benefit: ${adj['benefit_amount']:.2f}")

        # Access raw FHIR ClaimResponse
        claim_resp = data["claim_response"]
        print(f"Claim Response ID: {claim_resp['id']}")
        print(f"Outcome: {claim_resp['outcome']}")
else:
    print(f"Error: {response.status_code}")

---

Polling Strategy

tip

Recommended Polling Intervals:

1. Initial poll: 2-5 seconds after submission
2. Subsequent polls: 10 seconds (back off if 202 received)
3. Maximum backoff: 30 seconds
4. Total timeout: 5-10 minutes depending on volume

Most claims adjudicate within 30 seconds for primary processing.

Adjudication Fields Explained

Field	Meaning
allowed_amount	Amount the plan recognizes for payment (after contractual adjustments)
deductible_applied	Portion of deductible met by this claim
copay_applied	Fixed copay amount subtracted from benefit
coinsurance_applied	Percentage-based cost share after deductible
patient_responsibility	Total copay + coinsurance + any other member obligations
benefit_amount	Amount plan will pay to provider (allowed - member responsibility)
payer_responsibility	Same as benefit_amount; amount from plan perspective

info

Formula: allowed_amount = benefit_amount + patient_responsibility

Disposition Values

• APPROVED — Claim fully adjudicated and approved for payment
• DENIED — Claim rejected; no payment issued
• PARTIAL_APPROVAL — Some service lines approved, others denied
• PENDING_REVIEW — Requires manual review; check back later
• PENDED — Missing information requested from provider