> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joincandidhealth.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.joincandidhealth.com/_mcp/server.

# Agent & LLM Guide

> How to point an AI coding agent (Claude Code, Cursor, etc.) at the Candid Data Share docs

This page is an [AGENTS.md](https://agents.md)-style guide for using an AI coding agent — Claude Code, Cursor, Copilot, or any LLM — to explore and query **Candid Data Share**. It's a router: it tells the agent which docs to read and how to reason about the data, without duplicating the per-table schemas that already live in this section.

> **Point your agent here**
>
> Give your agent a link to this page or its Markdown version — append `.md` to the URL:
>
> `https://docs.joincandidhealth.com/data-share/agents.md`
>
> Every page in these docs has a `.md` twin, so an agent can fetch clean Markdown for any table reference below.

## What Candid Data Share is

Candid Data Share gives you direct BigQuery access to a set of `export_*` tables describing encounters, service lines, claims, and the financial transaction ledger behind them. It is documentation-and-data only: these docs describe schema and structure; the dataset itself is your organization's own data in BigQuery. Access is via service-account credentials (usable directly or through tools like Fivetran/Airbyte) — see the [Overview](/data-share/overview).

## Read these first

1. **[Data Model & Grain](/data-share/data-model-and-grain)** — the entity hierarchy (Encounter → Service Line → Charge → Transaction), the grain of every table (current-state, version history, or transaction ledger), void handling, and join paths. Read this before writing any aggregation.
2. **[FAQ](/data-share/faq)** — the interpretation gotchas (claim status vs. X12 status code, payments vs. adjustments, diagnosis representation, CARC/RARC codes, patient credits, external IDs, refresh cadence).
3. **Per-table column references** — the tables below, for exact column names, types, and meanings.

## How an agent should work with this data

* **Ground every column and join in the reference pages** below — do not invent column names. If a column isn't documented, say so rather than guessing.
* **Respect grain before aggregating.** `export_transaction` is the only table with amounts to aggregate: sum `amount_cents` per `charge_id`, `service_line_id`, or `encounter_id`, optionally split by `counter_party_type`. The detail tables (`export_charge_details`, `export_payment_details`, `export_adjustment_details`) annotate ledger rows and carry no amounts to sum. Current-state tables (`export_encounter`, `export_service_line`, the financial summaries) have one row per entity — don't dedupe by `updated_at`. Version history tables (`export_patient_insurance_history`, `export_patient_non_insurance_payer_history`, `export_patient_note_history`) have one row per version — filter on the latest-record flag for current state.
* **Exclude voids** when computing live financials: `voids_transaction_id IS NULL AND voided_by_transaction_id IS NULL`.
* **Don't treat any table as append-only.** Existing rows can change — for example, `voided_by_transaction_id` is filled in on a transaction after it's voided. For incremental ingestion, pull rows by `updated_at` daily and run a full refresh weekly.
* **This dataset is not real-time and not for invoicing.** It is refreshed on a nightly cadence. For patient balances/invoicing use the [patient invoicing integration guide](https://docs.joincandidhealth.com/api-reference/patient-collections/patient-invoicing-integration-guide).
* **Handle PHI carefully.** Many tables carry patient identifiers (name, DOB, address, member IDs). When helping a user query their own live data, keep example output minimal and relevant — do not dump full rows or PHI-heavy columns into chat unless the user specifically needs them for their own debugging.
* **Escalate the unknowns.** Exact enum values (plan/insurance type), CARC/RARC descriptor text, and access requests are not derivable from these docs — direct the user to [support@joincandidhealth.com](mailto:support@joincandidhealth.com).

## Table map

### Encounters & Service Lines

| Table                                      | Grain                                                     | Reference                                                                             |
| ------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `export_encounter`                         | one row per `encounter_id` (claim flattened on)           | [docs](/data-share/encounters-service-lines/export-encounter)                         |
| `export_service_line`                      | one row per `service_line_id` (claim procedure line item) | [docs](/data-share/encounters-service-lines/export-service-line)                      |
| `export_financial_summary`                 | one row per `encounter_id` (computed rollup)              | [docs](/data-share/encounters-service-lines/export-financial-summary)                 |
| `export_claim_submission_history`          | one row per `claim_submission_id` (many per claim)        | [docs](/data-share/encounters-service-lines/export-claim-submission-history)          |
| `export_service_line_financial_summary`    | one row per `service_line_id` (computed rollup)           | [docs](/data-share/encounters-service-lines/export-service-line-financial-summary)    |
| `export_service_line_projected_financials` | one row per `service_line_id` (projected)                 | [docs](/data-share/encounters-service-lines/export-service-line-projected-financials) |

### Financial Transactions

| Table                                     | Grain                                                              | Reference                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `export_transaction`                      | one row per `transaction_id` (the ledger — carries `amount_cents`) | [docs](/data-share/financial-transactions/export-transaction)                      |
| `export_charge_details`                   | one row per `transaction_id` (`CHARGE` details)                    | [docs](/data-share/financial-transactions/export-charge-details)                   |
| `export_payment_details`                  | one row per `transaction_id` (`PAYMENT` details)                   | [docs](/data-share/financial-transactions/export-payment-details)                  |
| `export_adjustment_details`               | one row per `transaction_id` (`ADJUSTMENT` details)                | [docs](/data-share/financial-transactions/export-adjustment-details)               |
| `export_informational_adjustment_details` | one row per `adjustment_detail_id` (non-balance-impacting)         | [docs](/data-share/financial-transactions/export-informational-adjustment-details) |
| `export_batch_details`                    | one row per `batch_id` (accounting period)                         | [docs](/data-share/financial-transactions/export-batch-details)                    |

### Patients & Payers

| Table                                        | Grain                                                                                         | Reference                                                                      |
| -------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `export_patient`                             | one row per `patient_id` (current state; join to encounters on `mrn = patient_external_id`)   | [docs](/data-share/patients-payers/export-patient)                             |
| `export_patient_insurance_history`           | one row per `patient_insurance_history_pk` (coverage version; `is_latest_record` for current) | [docs](/data-share/patients-payers/export-patient-insurance-history)           |
| `export_patient_non_insurance_payer_history` | one row per `patient_non_insurance_payer_history_pk` (patient version × non-insurance payer)  | [docs](/data-share/patients-payers/export-patient-non-insurance-payer-history) |
| `export_patient_note_history`                | one row per `patient_note_history_pk` (note version)                                          | [docs](/data-share/patients-payers/export-patient-note-history)                |
| `export_patient_appointments`                | one row per `appointment_id` (includes deactivated)                                           | [docs](/data-share/patients-payers/export-patient-appointments)                |
| `export_patient_referrals`                   | one row per `referral_id`                                                                     | [docs](/data-share/patients-payers/export-patient-referrals)                   |
| `export_patient_authorizations`              | one row per `authorization_id`                                                                | [docs](/data-share/patients-payers/export-patient-authorizations)              |
| `export_patient_merge`                       | one row per `patient_merge_id` (MRN mapping)                                                  | [docs](/data-share/patients-payers/export-patient-merge)                       |
| `export_payer`                               | one row per `payer_uuid` (reference)                                                          | [docs](/data-share/patients-payers/export-payer)                               |

## A minimal, grain-correct example

Current balance per service line — starts from the service line and sums every live ledger row (charges, payments, adjustments, balance transfers) against it:

```sql
SELECT
  sl.service_line_id,
  sl.procedure_code,
  SUM(t.amount_cents) AS balance_cents
FROM export_service_line sl
LEFT JOIN export_transaction t
  ON t.service_line_id = sl.service_line_id
  AND t.voids_transaction_id IS NULL
  AND t.voided_by_transaction_id IS NULL
GROUP BY 1, 2
```

* The void filter sits in the `ON` clause so service lines with no live transactions still return a row. Their balance is NULL, which distinguishes them from settled service lines (balance 0).
* Add `t.counter_party_type` to the `SELECT` and `GROUP BY` to split the balance by who owes it (`PAYER`, `PATIENT`, or `THIRD_PARTY_PAYER`). Balance transfers move amounts between counterparties and net to zero across them.
* Transactions posted at the claim level (`target_type = 'CLAIM'` — mostly payments and balance transfers) have no `service_line_id` or `charge_id`, so they don't appear here. Roll up by `encounter_id` to include them.