> 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.

# FAQ

> Answers to common data-model and interpretation questions about Candid Data Share

Direct answers to the questions that come up most often when interpreting Candid Data Share. Every answer here is grounded in the published table schemas linked from the [Overview](/data-share/overview); where a value is populated from upstream source data and not documented, that is called out explicitly rather than guessed.

## Grain & aggregation

**Do I get a new row every time an amount is updated?**

It depends on the table's grain (see [Data Model & Grain](/data-share/data-model-and-grain)):

* **`export_transaction`**: yes. A new payment or adjustment is a **new row** — sum across rows per `charge_id` or rolled up to `encounter_id` for a current total, and filter out voids.
* **`export_financial_summary` / `export_service_line_financial_summary`**: no. These are single computed rollup rows (one per `encounter_id` / `service_line_id`). Check `is_persisted_financial_summary_record_stale` before trusting the summary against the very latest transactions. Note that `updated_at` recalculates on any claim-status change even when no balance-impacting transaction occurred.

**Is `export_transaction` really one row per transaction?**

Yes — one row per `transaction_id`. Voids and re-adjudications add **new, linked** rows (`voids_transaction_id` / `voided_by_transaction_id`) rather than changing the original amount, so aggregate across rows and exclude voided pairs to get the live picture. The original row does still change — its `voided_by_transaction_id` is filled in — so don't treat the table as append-only when ingesting incrementally.

## Transactions, payments & adjustments

**What's the difference between `export_payment_details` and `export_adjustment_details`?**

Detail tables for different transaction types, both keyed by `transaction_id` (amounts live on `export_transaction`):

* `export_payment_details` — money **received/posted** (`payment_type` is `ERA`, `PATIENT PAYMENT`, or `NON-INSURANCE PAYMENT`).
* `export_adjustment_details` — balance-impacting **adjustments** / write-offs (`source` is `ERA`, `ERA Provider Adjustment`, `Manual Insurance Balance Adjustment`, `Patient Balance Adjustment`, or `Non-Insurance Payer Balance Adjustment`).

A single claim typically has rows in both.

**What is a "Non-Insurance Payment"?**

`export_payment_details.payment_type = 'NON-INSURANCE PAYMENT'` marks a payment from a third-party payer that is not an insurance company (e.g. a grant program or other funding source), as opposed to `ERA` (insurance-sourced) or `PATIENT PAYMENT` (patient-sourced). Non-insurance payer context is also flattened onto `export_encounter` (`non_insurance_payer_id`, `non_insurance_payer_name`, `non_insurance_payer_category`, `non_insurance_payer_member_id`).

**How is a patient prepayment / account credit represented?**

As `PAYMENT` rows on `export_transaction` with `counter_party_type = 'PATIENT'`. `target_type` shows where the money currently sits:

1. When the money is collected before it's applied to a visit, the payment row has `target_type = 'ORGANIZATION'` and no `encounter_id`, `service_line_id`, or `charge_id`.
2. When the credit is later applied, that organization-level row is voided (its `voided_by_transaction_id` is filled in and a reversing row is added) and a new `PAYMENT` row is written against the claim or service line (`target_type = 'CLAIM'` or `'SERVICE_LINE'`).

A credit can be applied in part, leaving the remainder at the organization level. A voided organization-level row can also mean the payment itself was voided rather than applied — in that case no live row remains for it.

After filtering out voids, each credit appears only where it currently sits. Balance transfers (`transaction_type = 'BALANCE_TRANSFER'`) are a different mechanism: they move liability for a charge from one counterparty to another (for example, from a payer to the patient) and always come in pairs so the ledger stays balanced.

**How is `adjustment_reason` populated?**

`export_adjustment_details.adjustment_reason` is set when the adjustment is created. For ERA-driven adjustments it derives from the remittance; for manual insurance/patient/non-insurance balance adjustments it's entered at the time of the manual action. The `carc` column is the raw ERA-sourced Claim Adjustment Reason Code and is only populated for ERA-sourced adjustments.

## Codes & their meanings

**Claim status — is there one status field, and is there a mapping table?**

There are **three separate code systems**; they come from different sources and can't be joined to one another:

1. `export_encounter.claim_status` — Candid's internal claim lifecycle state (a string, e.g. `submitted_to_payer`/`finalized_paid`/`denied`).
2. `claim_status_code` on `export_payment_details` / `export_adjustment_details` / `export_informational_adjustment_details` — the **X12 835 (ERA)** claim status code reported by the payer at adjudication (integer; NULL for non-ERA rows).
3. `claim_status_category_code` / `claim_status_code` on `export_claim_submission_history` — codes from the latest **payer 277 acknowledgement** for that submission (strings).

The data share doesn't include description tables for these codes. The 835 and 277 codes are standard X12 code lists, so descriptions can be sourced from the published X12 lists.

**Can I get the descriptor text for CARC / RARC codes, not just the code?**

No. `export_adjustment_details` and `export_informational_adjustment_details` expose the raw `carc`, `claim_adjustment_group_code`, `adjustment_reason_code`, and `remark_codes` values only. There is no descriptor-lookup table in the data share — these are standard X12 codes, so a translation table must be sourced on your side. See Candid's [Understanding Remit Codes (CARCs & RARCs)](https://support.joincandidhealth.com/hc/en-us/articles/17352381560852-Understanding-Remit-Codes-CARCs-RARCs).

**Is there a Medicaid vs. Commercial vs. Military distinction?**

Insurance/plan-type fields exist on `export_encounter` (`subscriber_{primary,secondary,tertiary}_insurance_card_plan_type` and `..._insurance_card_insurance_type`). The exact enum values are populated from upstream source data and are **not enumerated in the schema** — confirm the value list with your Candid contact rather than assuming a fixed Medicaid/Commercial/Military mapping.

## Fields & representations

**Diagnosis 1 vs. 2 — why do codes seem to overlap between encounter and service line?**

Two representations at two grains, by design:

* `export_encounter.diagnosis_codes` — a single comma-joined string of **every** diagnosis code on the encounter.
* `export_service_line.diagnosis_{zero,one,two,three}_code` (with `_name`, `_code_type`, `_position`) — up to **four positional diagnosis pointers per service line** indicating which encounter diagnoses apply to that line and in what order (matching the 837 diagnosis-pointer concept).

Seeing the same code at the encounter level and in several service-line pointer slots is expected, not a data-quality problem.

**Where do modifiers live, and what's `modifiers` vs `modifiers_string`?**

`export_service_line` exposes both `modifiers` (an `ARRAY<STRING>`) and `modifiers_string` (the same values as a comma-separated string for convenience). `export_charge_details.modifiers` carries the modifier array at the charge grain.

**Where are revenue codes?**

On the service line: `export_service_line.revenue_code` (also on `export_service_line_projected_financials`). Revenue codes are institutional-claim attributes and are not on `export_charge_details`.

**Where are external mapping identifiers stored?**

* **Encounter:** `export_encounter.external_id`.
* **Patient / guarantor:** `export_encounter.patient_external_id`, `guarantor_external_id` (patient identity is flattened onto each encounter row). `export_patient_merge` maps a `primary_patient_mrn` (target) to an `alternative_patient_mrn` (source) when records are merged.
* **Service line:** `export_service_line.external_id`.
* **Organization:** `external_organization_id` is present on most tables.
* **Payer:** `export_payer.payer_uuid` is Candid-internal; `primary_payer_id` is the clearinghouse-recognized payer ID.

## Access & freshness

**How fresh is the data? Can I use it for patient invoicing?**

Tables are refreshed nightly. It is **not** real-time and **must not** be used for patient invoicing — use the [patient invoicing integration guide](https://docs.joincandidhealth.com/api-reference/patient-collections/patient-invoicing-integration-guide). See the [Overview](/data-share/overview) for access, credentials, and incremental-pull guidance.

> **Note**
>
> For anything not answerable from these docs — exact enum values, code descriptors, or access requests — email [support@joincandidhealth.com](mailto:support@joincandidhealth.com).