Submit Claim (Fast FHIR)

Overview

The Submit Claim endpoint accepts healthcare claims in FHIR R4 format. It supports both professional claims (provider services) and institutional claims (facility-based services). The endpoint performs validation against contracted rates and returns an acknowledgment with a unique submission ID for tracking and polling responses.

info

All claims are submitted as FHIR R4 Claim resources. The API auto-detects claim type based on type.coding.code (professional vs. institutional).

Endpoint

POST /v1/claims/submit/

Authentication Required: Yes (X-API-Key header) Content-Type: application/fhir+json Rate Limit: 100 claims per minute per API key

Request

Schema Overview

Submit a complete FHIR R4 Claim resource. Key sections:

Section	Purpose	Example
`type`	Claim classification	professional, institutional
`patient`	Member demographics	name, DOB, member ID
`provider`	Rendering provider NPI	Surgeon or facility
`insurer`	Health plan OID/ID	Sharp Health Plan
`item[]`	Service lines	CPT code, units, charges
`supportingInfo[]`	Authorization, diagnosis	preauth refs, ICD-10 codes

Professional Claim Example (Colonoscopy)

{
  "resourceType": "Claim",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "professional"
      }
    ]
  },
  "use": "claim",
  "patient": {
    "reference": "Patient/P12345"
  },
  "billablePeriod": {
    "start": "2024-02-15",
    "end": "2024-02-15"
  },
  "created": "2024-02-16",
  "provider": {
    "reference": "Practitioner/PROV9876543210",
    "identifier": {
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "1234567890"
    }
  },
  "priority": {
    "coding": [
      {
        "code": "normal"
      }
    ]
  },
  "insurer": {
    "reference": "Organization/SHPLAN"
  },
  "item": [
    {
      "sequence": 1,
      "careTeamSequence": [1],
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "45378"
          }
        ]
      },
      "servicedDate": "2024-02-15",
      "quantity": {
        "value": 1
      },
      "unitPrice": {
        "value": 2000.00,
        "currency": "USD"
      },
      "net": {
        "value": 2000.00,
        "currency": "USD"
      }
    }
  ],
  "careTeam": [
    {
      "sequence": 1,
      "provider": {
        "reference": "Practitioner/PROV9876543210"
      },
      "role": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/claimcareteamrole",
            "code": "surgeon"
          }
        ]
      }
    }
  ],
  "diagnosis": [
    {
      "sequence": 1,
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "Z12.11"
          }
        ]
      }
    }
  ]
}

Institutional Claim Example (Facility)

{
  "resourceType": "Claim",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "institutional"
      }
    ]
  },
  "use": "claim",
  "patient": {
    "reference": "Patient/P54321"
  },
  "billablePeriod": {
    "start": "2024-02-15",
    "end": "2024-02-15"
  },
  "created": "2024-02-16",
  "provider": {
    "reference": "Organization/FACILITY",
    "identifier": {
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "1111111111"
    }
  },
  "insurer": {
    "reference": "Organization/SHPLAN"
  },
  "item": [
    {
      "sequence": 1,
      "revenue": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/ex-revenue-center",
            "code": "0360"
          }
        ]
      },
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "45378"
          }
        ]
      },
      "servicedDate": "2024-02-15",
      "quantity": {
        "value": 1
      },
      "unitPrice": {
        "value": 1500.00,
        "currency": "USD"
      },
      "net": {
        "value": 1500.00,
        "currency": "USD"
      }
    }
  ],
  "diagnosis": [
    {
      "sequence": 1,
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "Z12.11"
          }
        ]
      }
    }
  ]
}

Response

Success Response (201 Created)

Field	Type	Description
`submission_id`	string	Unique API submission identifier for polling
`external_claim_id`	string	Claim ID for external systems (EDI, payer systems)
`status`	string	Current status (ACKNOWLEDGED, PROCESSING, ADJUDICATED)
`message`	string	Confirmation message

{
  "submission_id": "sub_1a2b3c4d5e6f7g8h",
  "external_claim_id": "CLM-2024-098765",
  "status": "ACKNOWLEDGED",
  "message": "Claim received and queued for processing"
}

Validation Error (400 Bad Request)

{
  "errors": [
    {
      "field": "item[0].productOrService.coding[0].code",
      "message": "Invalid CPT code format. Must be 5 digits."
    },
    {
      "field": "provider.identifier.value",
      "message": "NPI must be 10 digits"
    }
  ]
}

No Contract (404 Not Found)

{
  "error": "No active contract found for provider NPI and CPT codes",
  "provider_npi": "1234567890",
  "cpt_codes": ["45378"]
}

Examples

cURL (Professional Claim)

curl -X POST https://api.turquoise.health/tpa-api/v1/claims/submit/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d @claim.json

Python (Institutional Claim)

import requests
import json

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

claim = {
    "resourceType": "Claim",
    "type": {
        "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/claim-type",
                "code": "institutional"
            }
        ]
    },
    "use": "claim",
    "patient": {"reference": "Patient/P54321"},
    "billablePeriod": {
        "start": "2024-02-15",
        "end": "2024-02-15"
    },
    "created": "2024-02-16",
    "provider": {
        "reference": "Organization/FACILITY",
        "identifier": {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "1111111111"
        }
    },
    "insurer": {"reference": "Organization/SHPLAN"},
    "item": [
        {
            "sequence": 1,
            "revenue": {
                "coding": [{"code": "0360"}]
            },
            "productOrService": {
                "coding": [
                    {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "45378"
                    }
                ]
            },
            "servicedDate": "2024-02-15",
            "quantity": {"value": 1},
            "unitPrice": {"value": 1500.00, "currency": "USD"},
            "net": {"value": 1500.00, "currency": "USD"}
        }
    ]
}

response = requests.post(
    "https://api.turquoise.health/tpa-api/v1/claims/submit/",
    json=claim,
    headers=headers
)

if response.status_code == 201:
    result = response.json()
    submission_id = result["submission_id"]
    print(f"Claim submitted: {submission_id}")
    # Use submission_id to poll for response
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Important Notes

warning

Contract Verification Required: Before submitting a claim, verify the provider NPI and CPT codes via Blind/Full Contract Lookup. Claims for non-contracted services will be rejected with a 404 error.

tip

Async Processing: Claims are processed asynchronously. Use the submission_id from the response to poll the Get Claim Response endpoint for adjudication results.

Supported Provider Roles

SURGEON — CPT 45378, 43235
FACILITY — Institutional revenue codes (0360, 0750, etc.)
ANESTHESIA — Anesthesia codes bundled or separate
PATHOLOGY — Pathology/lab service codes

Claim Type Detection

The endpoint auto-detects claim type from type.coding.code:

professional → Professional claim workflow
institutional → Institutional claim workflow (with revenue codes)

Overview​

Endpoint​

Request​

Schema Overview​

Professional Claim Example (Colonoscopy)​

Institutional Claim Example (Facility)​

Response​

Success Response (201 Created)​

Validation Error (400 Bad Request)​

No Contract (404 Not Found)​

Examples​

cURL (Professional Claim)​

Python (Institutional Claim)​

Important Notes​

Supported Provider Roles​

Claim Type Detection​