Initial Data Sync

Initial sync is the one-time backfill that establishes the baseline between Hint and your system. It should avoid creating duplicates, preserve each system's source-of-truth decisions, and leave a clear audit trail for the practice.

Recommended approach

1. Define matching rules up front

Decide how you will detect "the same record" across systems for each object (patients, practitioners, invoices, etc.). Common patterns:

Prefer stable external IDs if you already have them
If you must match on attributes, document precedence and tie-breakers (and assume attributes can be missing)

To reconcile against existing Hint records, the List All Patients endpoint accepts search filters you can use as a pre-import check:

import_id to confirm the external IDs you plan to import already resolve to the expected patient
first_name, last_name, and dob for exact-match lookups (string matches are case-insensitive)
q for a broader, case-insensitive partial-match search across name and email

For a single "does this person already exist?" check before creating a record, prefer the purpose-built Match Patients endpoint, which applies deterministic primary and secondary matching rather than raw filtering.

2. Make the sync idempotent

Your initial sync should be safe to re-run without creating duplicates:

Create/update operations should be idempotent on your side
Store integration_record_id as soon as you establish a match so both systems converge

3. Avoid duplicates intentionally

For each object type, define what happens when a match is found:

Skip and link (most common)
Merge (rare; requires clear dominance rules)
Prompt the admin (if human decision is required)

4. Surface failures clearly

If a record cannot sync, make it obvious:

Update integration_error_message on the corresponding Hint object with the actionable reason
Consider linking to remediation steps via integration_web_link where appropriate

Checklist

Matching rules documented and implemented
Re-runs do not create duplicates
Integration record fields are written consistently (integration_record_id, integration_web_link, integration_error_message)
Practice admins can understand and fix failures (in Hint and/or in your product)