List Ledger Entries

Overview

The List Ledger Entries endpoint returns a paginated collection of all encounter ledger entries for the TPA's contracted network. Each entry represents a single encounter (claim) with metadata, status progression, and financial summary. Use this endpoint to monitor claim volumes, track financial flows, and audit claim status across your network.

info

This is a read-only list endpoint with pagination support. Use filters and date ranges to narrow results for performance.

Endpoint

GET /v1/ledger/entries/

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

Request

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	No	ISO 8601 start date (inclusive) — filters by service_date
`end_date`	string	No	ISO 8601 end date (inclusive) — filters by service_date
`provider_npi`	string	No	Filter by rendering/billing provider NPI
`status`	string	No	Filter by claim status (SUBMITTED, ADJUDICATED, FUNDED, DENIED, PENDED)
`limit`	integer	No	Results per page (default: 20, max: 100)
`offset`	integer	No	Pagination offset (default: 0)

Example Requests

GET /v1/ledger/entries/?start_date=2024-02-01&end_date=2024-02-29&limit=50

GET /v1/ledger/entries/?provider_npi=1234567890&status=ADJUDICATED

GET /v1/ledger/entries/?status=PENDED&limit=100&offset=100

Response

Success Response (200 OK)

Field	Type	Description
`count`	integer	Total number of entries matching filters (across all pages)
`next`	string	URL to next page of results (null if no next page)
`previous`	string	URL to previous page of results (null if no previous page)
`results`	array	Array of ledger entry objects

Ledger Entry Object

Field	Type	Description
`id`	string	Unique ledger entry identifier
`encounter_id`	string	Clinical encounter reference (unique per service date/provider)
`encounter_number`	string	Human-readable encounter number
`ssp_code`	string	Service/Service-line identifier (e.g., CPT 45378)
`ssp_name`	string	Human-readable service name
`provider`	object	Provider NPI, name, role (FACILITY, SURGEON, ANESTHESIA, PATHOLOGY)
`payer`	object	Payer name and ID
`service_date`	string	ISO 8601 date service was rendered
`status_progression`	array	Chronological list of status transitions with timestamps
`financial_summary`	object	Aggregate financial amounts (charges, allowed, benefit, patient_resp)

Example Response

{
  "count": 245,
  "next": "https://api.turquoise.health/tpa-api/v1/ledger/entries/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": "LE-2024-098765",
      "encounter_id": "ENC-2024-098765",
      "encounter_number": "SHP-2024-098765",
      "ssp_code": "45378",
      "ssp_name": "Colonoscopy",
      "provider": {
        "npi": "1234567890",
        "name": "Dr. John Smith",
        "role": "SURGEON"
      },
      "payer": {
        "name": "Sharp Health Plan",
        "id": "SHPLAN"
      },
      "service_date": "2024-02-15",
      "status_progression": [
        {
          "status": "SUBMITTED",
          "timestamp": "2024-02-16T10:30:00Z"
        },
        {
          "status": "ADJUDICATED",
          "timestamp": "2024-02-17T14:32:10Z"
        },
        {
          "status": "FUNDED",
          "timestamp": "2024-02-18T09:15:00Z"
        }
      ],
      "financial_summary": {
        "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
      }
    },
    {
      "id": "LE-2024-098764",
      "encounter_id": "ENC-2024-098764",
      "encounter_number": "SHP-2024-098764",
      "ssp_code": "43235",
      "ssp_name": "EGD with Biopsy",
      "provider": {
        "npi": "1234567890",
        "name": "Dr. John Smith",
        "role": "SURGEON"
      },
      "payer": {
        "name": "Sharp Health Plan",
        "id": "SHPLAN"
      },
      "service_date": "2024-02-14",
      "status_progression": [
        {
          "status": "SUBMITTED",
          "timestamp": "2024-02-15T11:00:00Z"
        },
        {
          "status": "PENDED",
          "timestamp": "2024-02-16T16:45:00Z"
        }
      ],
      "financial_summary": {
        "charges": 1200.00,
        "allowed_amount": null,
        "patient_responsibility": null,
        "benefit_amount": null,
        "payer_responsibility": null
      }
    }
  ]
}

Examples

cURL

# List all adjudicated claims in February 2024
curl -X GET "https://api.turquoise.health/tpa-api/v1/ledger/entries/?start_date=2024-02-01&end_date=2024-02-29&status=ADJUDICATED&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

# List all claims for a specific provider
curl -X GET "https://api.turquoise.health/tpa-api/v1/ledger/entries/?provider_npi=1234567890&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

Python (Basic Listing)

import requests
from datetime import datetime, timedelta

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

# List claims from the last 7 days
end_date = datetime.now().date()
start_date = end_date - timedelta(days=7)

params = {
    "start_date": start_date.isoformat(),
    "end_date": end_date.isoformat(),
    "limit": 50
}

response = requests.get(
    "https://api.turquoise.health/tpa-api/v1/ledger/entries/",
    params=params,
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"Total entries: {data['count']}")

    for entry in data["results"]:
        print(f"\n{entry['encounter_number']}")
        print(f"  Service: {entry['ssp_name']} ({entry['ssp_code']})")
        print(f"  Date: {entry['service_date']}")
        print(f"  Status: {entry['status_progression'][-1]['status']}")
        summary = entry["financial_summary"]
        if summary["benefit_amount"] is not None:
            print(f"  Benefit: ${summary['benefit_amount']:.2f}")
else:
    print(f"Error: {response.status_code}")

Python (Paginate Through All Results)

import requests

def list_all_ledger_entries(api_key, **filters):
    """
    Generator that yields all ledger entries, handling pagination automatically.
    """
    headers = {"X-API-Key": api_key}
    url = "https://api.turquoise.health/tpa-api/v1/ledger/entries/"

    params = {
        "limit": 100,
        "offset": 0,
        **filters
    }

    while True:
        response = requests.get(url, params=params, headers=headers)

        if response.status_code != 200:
            print(f"Error: {response.status_code}")
            break

        data = response.json()

        for entry in data["results"]:
            yield entry

        # Check if there are more pages
        if not data["next"]:
            break

        params["offset"] += params["limit"]

# Usage: List all funded claims from February
for entry in list_all_ledger_entries(
    "YOUR_API_KEY",
    start_date="2024-02-01",
    end_date="2024-02-29",
    status="FUNDED"
):
    encounter = entry["encounter_number"]
    amount = entry["financial_summary"]["benefit_amount"]
    print(f"{encounter}: ${amount:.2f}")

Python (Filter and Aggregate)

import requests
from collections import defaultdict

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

# Aggregate benefit amounts by provider
provider_totals = defaultdict(float)

params = {
    "start_date": "2024-02-01",
    "end_date": "2024-02-29",
    "status": "FUNDED",
    "limit": 100
}

while True:
    response = requests.get(
        "https://api.turquoise.health/tpa-api/v1/ledger/entries/",
        params=params,
        headers=headers
    )

    if response.status_code != 200:
        break

    data = response.json()

    for entry in data["results"]:
        npi = entry["provider"]["npi"]
        benefit = entry["financial_summary"]["benefit_amount"]
        if benefit:
            provider_totals[npi] += benefit

    if not data["next"]:
        break

    params["offset"] = params.get("offset", 0) + params["limit"]

# Print summary
for npi in sorted(provider_totals.keys()):
    total = provider_totals[npi]
    print(f"NPI {npi}: ${total:.2f}")

Status Values

Status	Meaning
`SUBMITTED`	Claim submitted to payer, awaiting adjudication
`PROCESSING`	Claim being adjudicated
`ADJUDICATED`	Claim processed; approved or denied
`PENDED`	Claim pending additional information from provider
`FUNDED`	Benefit amount transferred to provider
`DENIED`	Claim denied; no payment issued
`RECONCILED`	Claim fully settled and reconciled

tip

Use status filter to monitor claim lifecycle:

SUBMITTED or PROCESSING — Claims in-flight
PENDED — Claims needing action
FUNDED — Successfully paid claims
DENIED — Rejected claims to investigate

Performance Tips

Use date ranges — Always filter by start_date and end_date for faster queries
Use status filters — Narrow by claim status to focus on specific workflows
Paginate efficiently — Use limit=100 and iterate via next URL rather than offset-based pagination for large datasets
Cache results locally — Consider caching ledger data for reporting to reduce API calls

Overview​

Endpoint​

Request​

Query Parameters​

Example Requests​

Response​

Success Response (200 OK)​

Ledger Entry Object​

Example Response​

Examples​

cURL​

Python (Basic Listing)​

Python (Paginate Through All Results)​

Python (Filter and Aggregate)​

Status Values​

Performance Tips​