Ledger Entry Detail
Overview
The Ledger Entry Detail endpoint returns complete historical information for a single encounter, including all status transitions, complete financial breakdowns, service line details, and provider/payer metadata. This is the authoritative source for understanding the full financial lifecycle of a claim from submission through settlement.
info
This endpoint provides complete transaction history for an encounter. Use it for reconciliation, audits, and detailed financial reporting.
Endpoint
GET /v1/ledger/entries/{encounter_id}/
Authentication Required: Yes (X-API-Key header) Rate Limit: 200 requests per minute per API key
Request
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
encounter_id | string | Yes | Unique encounter identifier (e.g., ENC-2024-098765) |
Example Request
GET /v1/ledger/entries/ENC-2024-098765/
Response
Success Response (200 OK)
Complete encounter structure with full financial and status details.
{
"encounter": {
"id": "ENC-2024-098765",
"encounter_number": "SHP-2024-098765",
"service_date": "2024-02-15",
"submission_date": "2024-02-16",
"patient": {
"member_id": "SHP123456789",
"name": "Jane Doe",
"dob": "1980-03-15"
},
"provider": {
"npi": "1234567890",
"name": "Dr. John Smith",
"role": "SURGEON",
"facility_npi": "1111111111",
"facility_name": "Sharp Healthcare Facility"
},
"payer": {
"name": "Sharp Health Plan",
"id": "SHPLAN"
}
},
"entries": [
{
"sequence": 1,
"type": "SUBMISSION",
"timestamp": "2024-02-16T10:30:00Z",
"reference": "sub_1a2b3c4d5e6f7g8h",
"description": "Claim submitted",
"financial_impact": null
},
{
"sequence": 2,
"type": "VALIDATION",
"timestamp": "2024-02-16T10:35:00Z",
"reference": null,
"description": "Claim validated against contract",
"financial_impact": null
},
{
"sequence": 3,
"type": "ADJUDICATION",
"timestamp": "2024-02-17T14:32:10Z",
"reference": "RESP-098765",
"description": "Claim adjudicated - APPROVED",
"financial_impact": {
"benefit_amount": 1900.00,
"copay_applied": 25.00,
"coinsurance_applied": 25.00
}
},
{
"sequence": 4,
"type": "FUNDING_APPROVED",
"timestamp": "2024-02-18T08:00:00Z",
"reference": "AUTH-20240217-TPA-SHARP-001",
"description": "Funding approved by TPA",
"financial_impact": {
"transfer_amount": 1900.00
}
},
{
"sequence": 5,
"type": "SETTLEMENT_INITIATED",
"timestamp": "2024-02-18T09:15:00Z",
"reference": "tr_1Oz9rZA1g7yLGa7e0xYzFxVK",
"description": "Stripe transfer initiated",
"financial_impact": null
},
{
"sequence": 6,
"type": "SETTLEMENT_COMPLETED",
"timestamp": "2024-02-19T18:30:00Z",
"reference": "SETTLE-2024-098765-001",
"description": "Funds settled to provider account",
"financial_impact": {
"settled_amount": 1900.00
}
}
],
"financial_summary": {
"service_date": "2024-02-15",
"submitted_charges": 2000.00,
"allowed_amount": 1950.00,
"adjustments": {
"contractual_adjustment": 50.00,
"other_adjustments": 0.00
},
"deductible": {
"plan_deductible": 1000.00,
"deductible_met_prior": 1000.00,
"deductible_applied": 0.00
},
"copay": {
"plan_copay": 25.00,
"copay_applied": 25.00
},
"coinsurance": {
"plan_coinsurance_percentage": 10.0,
"coinsurance_applied": 25.00
},
"patient_responsibility": {
"total": 50.00,
"copay": 25.00,
"coinsurance": 25.00,
"deductible": 0.00,
"non_covered": 0.00
},
"payer_responsibility": {
"total": 1900.00,
"benefit_amount": 1900.00
},
"balance": {
"running_balance": 0.00,
"status": "SETTLED"
}
},
"service_lines": [
{
"sequence": 1,
"cpt_code": "45378",
"cpt_description": "Colonoscopy with removal of lesion",
"quantity": 1,
"submitted_charge": 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,
"status": "ALLOWED"
}
],
"reconciliation": {
"claim_match_status": "MATCHED",
"aeob_reference": "AEOB-2024-098765",
"stripe_trace_id": "tr_1Oz9rZA1g7yLGa7e0xYzFxVK",
"settlement_record_id": "SETTLE-2024-098765-001",
"external_claim_id": "CLM-2024-098765"
}
}
Not Found Response (404 Not Found)
{
"error": "Encounter not found",
"encounter_id": "ENC-INVALID"
}
Entry Types
The entries array is chronologically ordered with standardized type values:
| Type | Description | Reference |
|---|---|---|
SUBMISSION | Claim submitted via API | submission_id |
VALIDATION | Contract and coverage validation | contract_id |
ADJUDICATION | Claim processed and adjudicated | ClaimResponse ID |
FUNDING_APPROVED | TPA authorized fund release | authorization_code |
SETTLEMENT_INITIATED | Stripe transfer created | stripe_transfer_id |
SETTLEMENT_COMPLETED | Funds received by provider | settlement_record_id |
RECONCILIATION | Claim matched to payer systems | AEOB reference |
PENDED | Claim waiting for additional info | pend_reason |
DENIED | Claim denied | denial_code |
Examples
cURL
curl -X GET "https://api.turquoise.health/tpa-api/v1/ledger/entries/ENC-2024-098765/" \
-H "X-API-Key: YOUR_API_KEY"
Python (Basic Retrieval)
import requests
import json
api_key = "YOUR_API_KEY"
encounter_id = "ENC-2024-098765"
response = requests.get(
f"https://api.turquoise.health/tpa-api/v1/ledger/entries/{encounter_id}/",
headers={"X-API-Key": api_key}
)
if response.status_code == 200:
data = response.json()
encounter = data["encounter"]
print(f"Encounter: {encounter['encounter_number']}")
print(f"Patient: {encounter['patient']['name']}")
print(f"Provider: {encounter['provider']['name']} (NPI: {encounter['provider']['npi']})")
summary = data["financial_summary"]
print(f"\nCharges: ${summary['submitted_charges']:.2f}")
print(f"Allowed: ${summary['allowed_amount']:.2f}")
print(f"Benefit: ${summary['payer_responsibility']['total']:.2f}")
print(f"Patient Resp: ${summary['patient_responsibility']['total']:.2f}")
print(f"\nStatus: {summary['balance']['status']}")
else:
print(f"Error: {response.status_code}")
Python (Print Chronological Timeline)
import requests
from datetime import datetime
api_key = "YOUR_API_KEY"
encounter_id = "ENC-2024-098765"
response = requests.get(
f"https://api.turquoise.health/tpa-api/v1/ledger/entries/{encounter_id}/",
headers={"X-API-Key": api_key}
)
if response.status_code == 200:
data = response.json()
print("Claim Lifecycle Timeline")
print("=" * 60)
for entry in data["entries"]:
timestamp = datetime.fromisoformat(entry["timestamp"].replace("Z", "+00:00"))
formatted_time = timestamp.strftime("%Y-%m-%d %H:%M:%S")
print(f"\n{formatted_time} | {entry['type']}")
print(f" {entry['description']}")
if entry["reference"]:
print(f" Reference: {entry['reference']}")
if entry["financial_impact"]:
for key, value in entry["financial_impact"].items():
if isinstance(value, (int, float)):
print(f" {key}: ${value:.2f}")
else:
print(f" {key}: {value}")
Python (Reconciliation Verification)
import requests
def verify_encounter_reconciliation(encounter_id, api_key):
"""
Verify that an encounter is fully reconciled with matching AEOB and settlement.
"""
response = requests.get(
f"https://api.turquoise.health/tpa-api/v1/ledger/entries/{encounter_id}/",
headers={"X-API-Key": api_key}
)
if response.status_code != 200:
print(f"Error: {response.status_code}")
return False
data = response.json()
recon = data["reconciliation"]
summary = data["financial_summary"]
print(f"Encounter: {data['encounter']['encounter_number']}")
print(f"\nReconciliation Status:")
print(f" Claim Match: {recon['claim_match_status']}")
print(f" AEOB Reference: {recon['aeob_reference']}")
print(f" Stripe Trace: {recon['stripe_trace_id']}")
print(f" Settlement Record: {recon['settlement_record_id']}")
print(f"\nFinancial Balance:")
print(f" Current Balance: ${summary['balance']['running_balance']:.2f}")
print(f" Status: {summary['balance']['status']}")
# Check all reconciliation fields are populated
is_reconciled = all([
recon["claim_match_status"] == "MATCHED",
recon["aeob_reference"],
recon["stripe_trace_id"],
recon["settlement_record_id"],
summary["balance"]["running_balance"] == 0.00,
summary["balance"]["status"] == "SETTLED"
])
if is_reconciled:
print("\n✓ Encounter is fully reconciled and settled")
else:
print("\n✗ Encounter is NOT fully reconciled")
return is_reconciled
# Usage
verify_encounter_reconciliation("ENC-2024-098765", "YOUR_API_KEY")
Python (Export for Audit)
import requests
import csv
from datetime import datetime
api_key = "YOUR_API_KEY"
encounter_id = "ENC-2024-098765"
response = requests.get(
f"https://api.turquoise.health/tpa-api/v1/ledger/entries/{encounter_id}/",
headers={"X-API-Key": api_key}
)
if response.status_code == 200:
data = response.json()
# Export to CSV for audit trail
with open(f"{encounter_id}_audit.csv", "w", newline="") as csvfile:
writer = csv.writer(csvfile)
# Header with encounter info
writer.writerow(["Encounter Audit Log"])
writer.writerow(["Encounter ID", data["encounter"]["encounter_number"]])
writer.writerow(["Service Date", data["encounter"]["service_date"]])
writer.writerow(["Provider", data["encounter"]["provider"]["name"]])
writer.writerow([])
# Timeline
writer.writerow(["Timestamp", "Type", "Description", "Reference", "Financial Impact"])
for entry in data["entries"]:
impact = ""
if entry["financial_impact"]:
impact = "; ".join(
[f"{k}: ${v:.2f}" if isinstance(v, (int, float)) else f"{k}: {v}"
for k, v in entry["financial_impact"].items()]
)
writer.writerow([
entry["timestamp"],
entry["type"],
entry["description"],
entry["reference"] or "",
impact
])
# Summary
writer.writerow([])
writer.writerow(["Financial Summary"])
summary = data["financial_summary"]
writer.writerow(["Submitted Charges", f"${summary['submitted_charges']:.2f}"])
writer.writerow(["Allowed Amount", f"${summary['allowed_amount']:.2f}"])
writer.writerow(["Patient Responsibility", f"${summary['patient_responsibility']['total']:.2f}"])
writer.writerow(["Payer Responsibility", f"${summary['payer_responsibility']['total']:.2f}"])
print(f"Audit log exported to {encounter_id}_audit.csv")
Financial Formula Verification
tip
Verify claim math by checking this fundamental formula:
Allowed Amount = Patient Responsibility + Payer Responsibility
For the example above:
1950.00 = 50.00 + 1900.00 ✓
If this formula doesn't hold, contact support for reconciliation.
Use Cases
- Dispute Resolution — Review complete entry history to resolve payment discrepancies
- Audit Trail — Export entries for compliance and internal audit requirements
- Reconciliation — Verify AEOB and Stripe trace IDs match payer systems
- Patient Billing — Use patient_responsibility breakdown for statement generation
- Financial Reporting — Aggregate financial_summary fields across multiple encounters