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)

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)