--- title: "Get History" method: GET path: "/patients/v1/{id}/history" tags: ["v1"] --- # Get History `GET /patients/v1/{id}/history` ## Request - Base URL: `https://pre-api.joincandidhealth.com` - URL: `https://pre-api.joincandidhealth.com/patients/v1/{id}/history` - Auth: HTTP bearer Gets a patient along with it's full history. The return list is ordered by version ascending. ## Path parameters - `id` string, required: The unique identifier for a Patient ## Response `200` Response with status 200 - PreEncounterPatientsV1Patient[] - `organization_id` string, required: The unique identifier for an Organization in the database - `deactivated` boolean, required: True if the object is deactivated. Deactivated objects are not returned in search results but are returned in all other endpoints including scan. - `version` integer, required: The version of the object. Any update to any property of an object object will create a new version. - `updated_at` string, date-time, required - `updating_user_id` string, required: The unique identifier for a User in the database - `name` PreEncounterCommonHumanName, required - `family` string, required - `given` string[], required - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `suffix` string - `other_names` PreEncounterCommonHumanName[], required: Other names for the patient. - `family` string, required - `given` string[], required - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `suffix` string - `other_identifiers` PreEncounterCommonExternalIdentifier[]: Other identifiers for the patient. - `value` string, required - `system` string, required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `gender` 'MAN' | 'WOMAN' | 'NON_BINARY' | 'TWO_SPIRIT' | 'FEMALE_TO_MALE' | 'MALE_TO_FEMALE' | 'OTHER' | 'UNKNOWN' | 'REFUSED' - `birth_date` string, date, required - `social_security_number` string - `biological_sex` 'FEMALE' | 'MALE' | 'UNKNOWN' | 'REFUSED', required - `sexual_orientation` 'HETEROSEXUAL' | 'HOMOSEXUAL' | 'BISEXUAL' | 'TWO_SPIRIT' | 'OTHER' | 'UNKNOWN' | 'REFUSED' - `pronouns` string[]: The pronouns of the patient. - `race` 'AMERICAN_INDIAN_OR_ALASKA_NATIVE' | 'WHITE' | 'BLACK' | 'ASIAN' | 'NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLANDER' | 'MIDDLE_EASTERN_OR_NORTH_AFRICAN' | 'OTHER' | 'UNKNOWN' | 'REFUSED' - `ethnicity` 'HISPANIC_OR_LATINO' | 'NOT_HISPANIC_OR_LATINO' | 'UNKNOWN' | 'REFUSED' - `disability_status` 'DISABLED' | 'NON_DISABLED' - `marital_status` 'ANNULLED' | 'DIVORCED' | 'INTERLOCUTORY' | 'SEPARATED' | 'MARRIED' | 'COMMON_LAW' | 'POLYGAMOUS' | 'DOMESTIC_PARTNER' | 'UNMARRIED' | 'NEVER_MARRIED' | 'WIDOWED' | 'UNKNOWN' - `deceased` string, date-time: Time of death for the patient. Leave unset if the patient is not deceased. - `multiple_birth` integer: The number of siblings the patient was born with. Leave unset if the patient was not part of a multiple birth. - `primary_address` PreEncounterCommonAddress, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required - `line` string[], required - `city` string, required - `state` string, required - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `postal_code` string, required - `country` string, required - `county` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `other_addresses` PreEncounterCommonAddress[], required: Other addresses for the patient. - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required - `line` string[], required - `city` string, required - `state` string, required - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `postal_code` string, required - `country` string, required - `county` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `primary_telecom` PreEncounterCommonContactPoint - `value` string, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `other_telecoms` PreEncounterCommonContactPoint[], required: Other phone numbers for the patient. - `value` string, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `email` string - `electronic_communication_opt_in` boolean: Use electronic_communication_consent for granular channel-level consent. This field is kept in sync automatically but should not be used for new integrations. - `electronic_communication_consent` PreEncounterPatientsV1ElectronicCommunicationConsent: Granular consent for electronic communication channels. - `text_communication_consent` boolean: Consent for text/SMS communication. - `email_communication_consent` boolean: Consent for email communication. - `photo` string - `language` string - `external_provenance` PreEncounterPatientsV1ExternalProvenance: Information about the upstream system that owns this patient data. - `external_id` string, required - `system_name` string, required - `contacts` PreEncounterPatientsV1Contact[], required: Contacts for the patient. - `relationship` PreEncounterCommonRelationship[], required - `name` PreEncounterCommonHumanName, required - `family` string, required - `given` string[], required - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `suffix` string - `telecoms` PreEncounterCommonContactPoint[], required - `value` string, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `addresses` PreEncounterCommonAddress[], required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required - `line` string[], required - `city` string, required - `state` string, required - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `postal_code` string, required - `country` string, required - `county` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `hipaa_authorization` boolean - `general_practitioners` PreEncounterCommonExternalProvider[], required - `name` PreEncounterCommonHumanName, required - `family` string, required - `given` string[], required - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `suffix` string - `type` 'PRIMARY' | 'REFERRING' | 'ATTENDING' - `npi` string - `telecoms` PreEncounterCommonContactPoint[], required - `value` string, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `addresses` PreEncounterCommonAddress[] - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required - `line` string[], required - `city` string, required - `state` string, required - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `postal_code` string, required - `country` string, required - `county` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `canonical_id` string: The unique identifier for a provider configured in the Candid system - `fax` string - `other_fax_numbers` string[] - `emails` string[] - `service_facilities` PreEncounterCommonPatientServiceFacility[]: Associated service facilities for this provider. - `service_facility_id` string, required: The unique identifier for a service facility configured in the Candid system - `filing_order` PreEncounterPatientsV1FilingOrder, required: The patient's active coverages, in order of primary, secondary, etc. - `coverages` PreEncounterCommonCoverageId[], required - `coverages_for_related_causes` PreEncounterPatientsV1CoveragesForRelatedCauses: Additional coverages for the patient applicable to related causes such as Auto or Workers Comp - `coverages` PreEncounterCommonCoverageId[], required - `non_insurance_payers` PreEncounterCommonCanonicalNonInsurancePayerId[] - `non_insurance_payer_associations` PreEncounterCommonCanonicalNonInsurancePayerAssociation[] - `id` string, required: The unique identifier for a non-insurance payer configured in the Candid system - `member_id` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `clinical_trial_info` PreEncounterCommonCanonicalClinicalTrialAssociation[]: A patient cannot be associated with a given trial more than once - `id` string, required: The unique identifier for a clinical trial configured in the Candid system - `clinical_trial_arm` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `guarantor` PreEncounterPatientsV1Guarantor - `name` PreEncounterCommonHumanName, required - `family` string, required - `given` string[], required - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `suffix` string - `telecom` PreEncounterCommonContactPoint - `value` string, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `email` string - `birth_date` string, date - `address` PreEncounterCommonAddress, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required - `line` string[], required - `city` string, required - `state` string, required - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `postal_code` string, required - `country` string, required - `county` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `self_pay` boolean - `authorizations` PreEncounterPatientsV1Authorization[] - `payer_id` string, required: The unique identifier for a Payer in the database - `payer_name` string, required - `additional_payer_information` PreEncounterCommonAdditionalPayerInformation - `availity_eligibility_id` string - `availity_payer_id` string - `availity_payer_name` string - `availity_remittance_payer_id` string - `authorization_number` string, required - `cpt_code` string, required - `apply_for_all_cpt_codes` boolean: If true, then the authorization will apply for all claims for the payer that fall in range the `period`. - `no_prior_authorization_required` boolean: If true, indicates that prior authorization is not required and prior authorization number will not be set on the claim for this authorization. - `units` 'VISIT' | 'UNIT', required - `quantity` integer - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `notes` string - `billing_provider_npi` string: The NPI of the billing provider for which this authorization applies. - `service_facility` PreEncounterCommonPatientServiceFacility: Represents a canonical service facility attached to a patient or patient dependent object - `service_facility_id` string, required: The unique identifier for a service facility configured in the Candid system - `dx_codes` string[]: When set, the authorization will only apply when at least one of these diagnosis codes is found on the claim/service lines (in addition to other criteria). - `referrals` PreEncounterPatientsV1Referral[] - `provider` PreEncounterCommonExternalProvider, required - `name` PreEncounterCommonHumanName, required - `family` string, required - `given` string[], required - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `suffix` string - `type` 'PRIMARY' | 'REFERRING' | 'ATTENDING' - `npi` string - `telecoms` PreEncounterCommonContactPoint[], required - `value` string, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `addresses` PreEncounterCommonAddress[] - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required - `line` string[], required - `city` string, required - `state` string, required - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `postal_code` string, required - `country` string, required - `county` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `canonical_id` string: The unique identifier for a provider configured in the Candid system - `fax` string - `other_fax_numbers` string[] - `emails` string[] - `service_facilities` PreEncounterCommonPatientServiceFacility[]: Associated service facilities for this provider. - `service_facility_id` string, required: The unique identifier for a service facility configured in the Candid system - `referral_number` string, required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `notes` string - `serviceFacility` PreEncounterCommonPatientServiceFacility: Represents a canonical service facility attached to a patient or patient dependent object - `service_facility_id` string, required: The unique identifier for a service facility configured in the Candid system - `units` 'VISIT' | 'UNIT' - `quantity` integer - `cptCodes` string[] - `applyForAllCptCodes` boolean - `payer_id` string: The unique identifier for a Payer in the database - `payer_name` string - `primary_service_facility_id` string - `service_facilities` PreEncounterCommonPatientServiceFacility[]: Associated service facilities for this patient. - `service_facility_id` string, required: The unique identifier for a service facility configured in the Candid system - `do_not_invoice_reason` 'BANKRUPTCY' | 'DECEASED' | 'HARDSHIP' | 'OTHER' | 'COLLECTIONS' | 'BAD_ADDRESS' | 'PROFESSIONAL_COURTESY' - `note_ids` PreEncounterCommonNoteId[] - `tag_ids` PreEncounterCommonTagId[] - `origination_detail` PreEncounterPatientsV1OriginationDetail - `referral_source` 'HOSPITAL' | 'REFERRING_MD' | 'SELF' | 'OTHER', required - `referring_provider` PreEncounterCommonExternalProvider - `name` PreEncounterCommonHumanName, required - `family` string, required - `given` string[], required - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `suffix` string - `type` 'PRIMARY' | 'REFERRING' | 'ATTENDING' - `npi` string - `telecoms` PreEncounterCommonContactPoint[], required - `value` string, required - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `addresses` PreEncounterCommonAddress[] - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required - `line` string[], required - `city` string, required - `state` string, required - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `postal_code` string, required - `country` string, required - `county` string - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `period` PreEncounterCommonPeriod - `start` string, date - `end` string, date - `canonical_id` string: The unique identifier for a provider configured in the Candid system - `fax` string - `other_fax_numbers` string[] - `emails` string[] - `service_facilities` PreEncounterCommonPatientServiceFacility[]: Associated service facilities for this provider. - `service_facility_id` string, required: The unique identifier for a service facility configured in the Candid system - `specialization_categories` PreEncounterPatientsV1SpecializationCategory[] - `referral_type` 'DIRECTED' | 'ROTATION' | 'OVERNIGHT' - `inferred_patient_metadata` PreEncounterPatientsV1InferredPatientMetadata - `inferred_encounter_id` string, required - `inferred_encounter_latest_date_of_service` string, date, required - `orcon` boolean: ORCON (Originator Controlled) - When set to true, the Candid system will hide this patient from downstream integrations. Updates made in the Candid UI will unset this flag. Defaults to false. - `advanced_directives` PreEncounterPatientsV1AdvancedDirective[] - `hipaa_code` string - `custom_metadata` PreEncounterPatientsV1CustomMetadataEntry[]: Custom key/value metadata attached to this patient, grouped by the MetadataSchema that defines the keys' types. Configure schemas via the metadata-schemas API. Values are validated against the referenced schema on write. - `metadata_schema_id` string, uuid, required: The unique identifier for a custom MetadataSchema. - `key_value_pairs` object, required: The custom values. Each key must be a field defined on the referenced MetadataSchema and each value must match that field's declared type. - `id` string, required: The unique identifier for a Patient - `mrn` string, required: The medical record number for the patient. Human-friendly Candid generated MRNs are of the form "YYMMDDXXXX", where "YYMMDD" is the date of patient creation and "XXXX" is a zero-padded incrementing integer. ## Other responses - `404`: Error response with status 404 ## Changes - **2026-10-29** `d8b0a61873e2`: 2 info - added the optional property `items/referrals/items/payer_id` to the response with the `200` status - added the optional property `items/referrals/items/payer_name` to the response with the `200` status - **2026-09-19** `72fc5ca65ba5`: 7 info - added the optional property `items/contacts/items/addresses/items/administrative_area` to the response with the `200` status - added the optional property `items/general_practitioners/items/addresses/items/administrative_area` to the response with the `200` status - added the optional property `items/guarantor/address/administrative_area` to the response with the `200` status - added the optional property `items/origination_detail/referring_provider/addresses/items/administrative_area` to the response with the `200` status - …3 more - **2026-09-17** `24b2d80d577a`: 2 breaking, 1 warning, 57 info - the `content` response's property type changed from no type to `object` for status `404` - the `items/` response's property type changed from no type to `object` for status `200` - deleted the `header` request parameter `Authorization` - the endpoint scheme security `OAuthScheme` was added to the API - …56 more - **2026-09-12** `3a81ee81d4ed`: 1 info - api operation id `get_history` removed and replaced with `v1_get_history_3` [Operation history](https://skmtc.dev/joincandidhealth/apis/api-reference/changes/patients/v1/:id/history/get.md) --- [API](https://skmtc.dev/joincandidhealth/apis/api-reference.md) - [All operations](https://skmtc.dev/joincandidhealth/apis/api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/joincandidhealth/apis/api-reference/revisions/d8b0a61873e2?raw)