Scan
Scans up to 1000 patient updates. The since query parameter is inclusive, and the result list is ordered by updatedAt ascending.
**Polling Pattern:**
To continuously poll for updates without gaps:
1. Make your initial request with a `since` timestamp (e.g., `since=2020-01-01T13:00:00.000Z`)
2. The API returns 100 by default and up to 1000 patient records, sorted by `updated_at` ascending
3. Find the `updated_at` value from the last record in the response
4. Use that `updated_at` value as the `since` parameter in your next request
5. Repeat steps 2-4 to ingest updates until you receive an empty list
**Important Notes:**
- The `since` parameter is inclusive, so you may receive the last record from the previous batch again (you can deduplicate by ID and version)
- All patient records include `updated_at`, `id`, `version`, `deactivated`, and `updating_user` fields for tracking changes
- Timestamps have millisecond resolution for precise ordering
Authentication
AuthorizationBearer
OAuth authentication of the form <token>.
Query parameters
since
maxResults
Response
This endpoint returns a list of objects.
biological_sex
The biological sex of the patient. This corresponds to the HL7 AdministrativeGender https://www.hl7.org/fhir/valueset-administrative-gender.html
Allowed values:
birth_date
contacts
Contacts for the patient.
deactivated
True if the object is deactivated. Deactivated objects are not returned in search results but are returned in all other endpoints including scan.
filing_order
The patient's active coverages, in order of primary, secondary, etc.
general_practitioners
id
The unique UUID identifier for a Patient. Patient ID is used in machine contexts.
mrn
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.
name
organization_id
The organization that owns this object.
other_addresses
Other addresses for the patient.
other_names
Other names for the patient.
other_telecoms
Other phone numbers for the patient.
primary_address
The primary address for the patient.
updated_at
updating_user_id
The user ID of the user who last updated the object.
version
The version of the object. Any update to any property of an object object will create a new version.
deceased
Time of death for the patient. Leave unset if the patient is not deceased.
disability_status
Allowed values:
do_not_invoice_reason
If this value is defined, the customer will not be invoiced.
electronic_communication_opt_in
email
ethnicity
Allowed values:
external_provenance
Information about the upstream system that owns this patient data. Leave unset if Candid owns patient data.
gender
guarantor
inferred_patient_metadata
Metadata for the patient used for patient inference from encounters.
language
marital_status
multiple_birth
The number of siblings the patient was born with. Leave unset if the patient was not part of a multiple birth.
non_insurance_payer_associations
note_ids
orcon
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.
origination_detail
Information about the patient source, if applicable.
other_identifiers
Other identifiers for the patient.
photo
primary_service_facility_id
primary_telecom
The primary phone number for the patient.
pronouns
The pronouns of the patient.
race
referrals
self_pay
service_facilities
Associated service facilities for this patient.
sexual_orientation
The sexual orientation of the patient.
tag_ids
non_insurance_payersDeprecated
