FAQ

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; 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):

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

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. See the Overview for access, credentials, and incremental-pull guidance.