generated: '2026-08-14'
method: derived
source: openapi/_original/candid-health-openapi.yml
docs: https://docs.joincandidhealth.com/api-reference
name: Candid Health Data Model
description: Entity-relationship graph derived from Candid Health's OpenAPI. Candid's 805 component schemas
  are dominated by request/response wrappers, enums and union members; the entities below are the durable,
  id-bearing business objects an integrator actually stores. Relationships were computed from typed id-reference
  fields (<entity>_id) — Candid rarely uses $ref to link entities, it links by id, so an id-field walk
  is the only accurate way to read the graph.
id_convention: Every entity carries either a bare `id` (all pre-encounter services) or a self-named `<entity>_id`
  (all post-encounter/billing services). Ids are UUIDs with no type prefix, so an id is not self-describing
  — the field name is the only type information. Client-supplied `external_id` / `<entity>_external_id`
  fields sit alongside them as the caller's own key into their EMR.
total_schemas: 805
entity_count: 48
relationship_count: 20
entities:
- name: Encounter
  schema: type_encounters/v4:Encounter
  primary_key: encounter_id
  field_count: 76
  required_fields: 22
- name: ServiceLine
  schema: type_service-lines/v2:ServiceLine
  primary_key: service_line_id
  field_count: 43
  required_fields: 8
- name: Claim
  schema: type_claims:Claim
  primary_key: claim_id
  field_count: 8
  required_fields: 4
- name: Diagnosis
  schema: type_diagnoses:Diagnosis
  primary_key: diagnosis_id
  field_count: 8
  required_fields: 6
- name: Patient
  schema: type_pre-encounter/patients/v1:Patient
  primary_key: id
  field_count: 52
  required_fields: 17
- name: Coverage
  schema: type_pre-encounter/coverages/v1:Coverage
  primary_key: id
  field_count: 18
  required_fields: 12
- name: Appointment
  schema: type_pre-encounter/appointments/v1:Appointment
  primary_key: id
  field_count: 24
  required_fields: 10
- name: Image
  schema: type_pre-encounter/images/v1:Image
  primary_key: id
  field_count: 13
  required_fields: 11
- name: Note
  schema: type_pre-encounter/notes/v1:Note
  primary_key: id
  field_count: 11
  required_fields: 8
- name: Tag
  schema: type_pre-encounter/tags/v1:Tag
  primary_key: id
  field_count: 9
  required_fields: 7
- name: PatientMerge
  schema: type_pre-encounter/patientMerges/v1:PatientMerge
  primary_key: id
  field_count: 8
  required_fields: 8
- name: OrganizationExternalProvider
  schema: type_pre-encounter/organizationExternalProviders/v1:OrganizationExternalProvider
  primary_key: id
  field_count: 18
  required_fields: 8
- name: EligibilityRecommendation
  schema: type_pre-encounter/eligibilityChecks/v1:EligibilityRecommendation
  primary_key: id
  field_count: 11
  required_fields: 9
- name: EligibilityTimelineEvent
  schema: type_pre-encounter/patients/v1:EligibilityTimelineEvent
  primary_key: id
  field_count: 9
  required_fields: 7
- name: InsuranceCard
  schema: type_insurance-cards/v2:InsuranceCard
  primary_key: insurance_card_id
  field_count: 15
  required_fields: 4
- name: Payer
  schema: type_payers/v3:Payer
  primary_key: payer_id
  field_count: 8
  required_fields: 3
- name: PayerPlanGroup
  schema: type_payer-plan-groups/v1:PayerPlanGroup
  primary_key: payer_plan_group_id
  field_count: 7
  required_fields: 7
- name: NonInsurancePayer
  schema: type_non-insurance-payers/v1:NonInsurancePayer
  primary_key: non_insurance_payer_id
  field_count: 7
  required_fields: 4
- name: ChargeCapture
  schema: type_charge-capture/v1:ChargeCapture
  primary_key: id
  field_count: 13
  required_fields: 6
- name: ChargeCaptureClaimCreation
  schema: type_charge-capture-bundles/v1:ChargeCaptureClaimCreation
  primary_key: id
  field_count: 6
  required_fields: 4
- name: ChargeCaptureError
  schema: type_charge-capture/v1:ChargeCaptureError
  primary_key: id
  field_count: 8
  required_fields: 3
- name: OrganizationProvider
  schema: type_organization-providers/v2:OrganizationProvider
  primary_key: organization_provider_id
  field_count: 17
  required_fields: 7
- name: OrganizationServiceFacility
  schema: type_organization-service-facilities/v2:OrganizationServiceFacility
  primary_key: organization_service_facility_id
  field_count: 16
  required_fields: 5
- name: ProviderCredentialingSpan
  schema: type_credentialing/v2:ProviderCredentialingSpan
  primary_key: provider_credentialing_span_id
  field_count: 13
  required_fields: 8
- name: FacilityCredentialingSpan
  schema: type_credentialing/v2:FacilityCredentialingSpan
  primary_key: facility_credentialing_span_id
  field_count: 10
  required_fields: 6
- name: Contract
  schema: type_contracts/v2:Contract
  primary_key: contract_id
  field_count: 12
  required_fields: 9
- name: ContractServiceFacility
  schema: type_contracts/v3:ContractServiceFacility
  primary_key: contract_service_facility_id
  field_count: 4
  required_fields: 4
- name: Rate
  schema: type_fee-schedules/v3:Rate
  primary_key: rate_id
  field_count: 6
  required_fields: 6
- name: InsuranceAdjudication
  schema: type_insurance-adjudications/v1:InsuranceAdjudication
  primary_key: insurance_adjudication_id
  field_count: 7
  required_fields: 4
- name: ServiceLineAdjudication
  schema: type_insurance-adjudications/v1:ServiceLineAdjudication
  primary_key: service_line_adjudication_id
  field_count: 9
  required_fields: 3
- name: InsuranceRefund
  schema: type_insurance-refunds/v1:InsuranceRefund
  primary_key: insurance_refund_id
  field_count: 7
  required_fields: 4
- name: PatientPayment
  schema: type_patient-payments/v4:PatientPayment
  primary_key: patient_payment_id
  field_count: 11
  required_fields: 6
- name: PatientRefund
  schema: type_patient-refunds/v1:PatientRefund
  primary_key: patient_refund_id
  field_count: 11
  required_fields: 6
- name: NonInsurancePayerPayment
  schema: type_non-insurance-payer-payments/v1:NonInsurancePayerPayment
  primary_key: non_insurance_payer_payment_id
  field_count: 8
  required_fields: 4
- name: NonInsurancePayerRefund
  schema: type_non-insurance-payer-refunds/v1:NonInsurancePayerRefund
  primary_key: non_insurance_payer_refund_id
  field_count: 9
  required_fields: 4
- name: Invoice
  schema: type_invoices:Invoice
  primary_key: id
  field_count: 13
  required_fields: 10
- name: ImportInvoice
  schema: type_import-invoice/v1:ImportInvoice
  primary_key: id
  field_count: 12
  required_fields: 10
- name: Guarantor
  schema: type_guarantor/v1:Guarantor
  primary_key: guarantor_id
  field_count: 11
  required_fields: 9
- name: Superbill
  schema: type_superbills/v1:Superbill
  primary_key: superbill_id
  field_count: 6
  required_fields: 6
- name: BillingNote
  schema: type_billing-notes/v2:BillingNote
  primary_key: billing_note_id
  field_count: 8
  required_fields: 4
- name: Task
  schema: type_tasks/v3:Task
  primary_key: task_id
  field_count: 20
  required_fields: 15
- name: TaskNote
  schema: type_tasks/v3:TaskNote
  primary_key: task_note_id
  field_count: 5
  required_fields: 5
- name: Allocation
  schema: type_financials:Allocation
  primary_key: allocation_id
  field_count: 5
  required_fields: 2
- name: BalanceEarmark
  schema: type_financials:BalanceEarmark
  primary_key: id
  field_count: 4
  required_fields: 2
- name: Event
  schema: type_events/v1:Event
  primary_key: id
  field_count: 6
  required_fields: 6
- name: Schema
  schema: type_custom-schemas/v1:Schema
  primary_key: id
  field_count: 4
  required_fields: 3
- name: SupplementalInformation
  schema: type_encounter-supplemental-information/v1:SupplementalInformation
  primary_key: supplemental_information_id
  field_count: 7
  required_fields: 5
- name: ClinicalTrial
  schema: type_clinical-trials/v1:ClinicalTrial
  primary_key: clinical_trial_id
  field_count: 6
  required_fields: 5
relationships:
- from: ServiceLine
  to: Claim
  type: belongs_to
  via: claim_id
  required: true
- from: Diagnosis
  to: Encounter
  type: belongs_to
  via: encounter_id
  required: true
- from: InsuranceCard
  to: PayerPlanGroup
  type: belongs_to
  via: payer_plan_group_id
  required: false
- from: InsuranceCard
  to: Payer
  type: belongs_to
  via: payer_id
  required: true
- from: ContractServiceFacility
  to: Contract
  type: belongs_to
  via: contract_id
  required: true
- from: BillingNote
  to: Encounter
  type: belongs_to
  via: encounter_id
  required: true
- from: Task
  to: Encounter
  type: belongs_to
  via: encounter_id
  required: true
- from: Task
  to: Payer
  type: belongs_to
  via: payer_id
  required: false
- from: SupplementalInformation
  to: Encounter
  type: belongs_to
  via: encounter_id
  required: true
- from: ClinicalTrial
  to: NonInsurancePayer
  type: belongs_to
  via: non_insurance_payer_id
  required: true
- from: Claim
  to: ServiceLine
  type: has_many
  via: claim_id
- from: Encounter
  to: Diagnosis
  type: has_many
  via: encounter_id
- from: PayerPlanGroup
  to: InsuranceCard
  type: has_many
  via: payer_plan_group_id
- from: Payer
  to: InsuranceCard
  type: has_many
  via: payer_id
- from: Contract
  to: ContractServiceFacility
  type: has_many
  via: contract_id
- from: Encounter
  to: BillingNote
  type: has_many
  via: encounter_id
- from: Encounter
  to: Task
  type: has_many
  via: encounter_id
- from: Payer
  to: Task
  type: has_many
  via: payer_id
- from: Encounter
  to: SupplementalInformation
  type: has_many
  via: encounter_id
- from: NonInsurancePayer
  to: ClinicalTrial
  type: has_many
  via: non_insurance_payer_id
domains:
- name: Pre-Encounter
  host: https://pre-api.joincandidhealth.com
  entities:
  - Patient
  - Coverage
  - Appointment
  - Image
  - Note
  - Tag
  - PatientMerge
  - OrganizationExternalProvider
  - EligibilityRecommendation
  - EligibilityTimelineEvent
  note: Versioned, optimistic-concurrency resources. Writes take a {version} path segment and return 409
    VersionConflictError on a stale write.
- name: Encounter & Claims
  host: https://api.joincandidhealth.com
  entities:
  - Encounter
  - ServiceLine
  - Claim
  - Diagnosis
  - BillingNote
  - SupplementalInformation
  - Guarantor
  - Superbill
- name: Charge Capture
  host: https://api.joincandidhealth.com
  entities:
  - ChargeCapture
  - ChargeCaptureClaimCreation
  - ChargeCaptureError
- name: Payers & Contracts
  host: https://api.joincandidhealth.com
  entities:
  - Payer
  - PayerPlanGroup
  - NonInsurancePayer
  - InsuranceCard
  - Contract
  - ContractServiceFacility
  - Rate
- name: Providers & Credentialing
  host: https://api.joincandidhealth.com
  entities:
  - OrganizationProvider
  - OrganizationServiceFacility
  - ProviderCredentialingSpan
  - FacilityCredentialingSpan
- name: Financials
  host: https://api.joincandidhealth.com
  entities:
  - InsuranceAdjudication
  - ServiceLineAdjudication
  - InsuranceRefund
  - PatientPayment
  - PatientRefund
  - NonInsurancePayerPayment
  - NonInsurancePayerRefund
  - Invoice
  - ImportInvoice
  - Allocation
  - BalanceEarmark
- name: Workflow & Platform
  host: https://api.joincandidhealth.com
  entities:
  - Task
  - TaskNote
  - Event
  - Schema
  - ClinicalTrial
notes:
- 'Encounter is the hub: it is the anchor for ServiceLine, Diagnosis, BillingNote, SupplementalInformation
  and every health-care-code-information record.'
- The financial entities form a second cluster around Allocation/BalanceEarmark, which move money between
  an Invoice, an Encounter and a ServiceLine.
- Candid also publishes these shapes as a warehouse schema (Candid Data Share, BigQuery) with export_*
  table names that mirror the entities here.