Building an Integration

Integration Partners sync data between Hint and your system so practices can work in the right place at the right time while seeing relevent data from each system and without re-entering the same information twice.

This guide explains the path to a reliable, user-friendly integration: define source of truth, activate safely, establish a clean baseline, keep data current via webhooks, and make the sync observable with deep links and errors.

Best Practices

The following decisions reduce or prevent the most common sources of workflow issues, misaligned value, duplicates, and support needs.

Define data that will sync and direction

Pick which system is authoritative for each type of data. Determine which direction(s) the data will flow.

You will also want to decide which attributes for each object will be synced. Which system is authoritative and wins in a data conflict, etc.

Store your system's unqiue ids in the integration_record_id field to ensure idempotency and uniqueness.

Make sync observable for staff

When things go wrong (and they will), practice staff need to self-serve. Use integration metadata to make status and remediation obvious:

• integration_record_id: your identifier for the corresponding record
• integration_web_link: deep link into your record in your app
• integration_error_message: actionable reason the record is not synced

Also consider surfacing provider_web_link in your UI so staff can jump back and forth from your system to Hint.

Prefer webhooks over polling

Use Webhooks for event-driven updates, retry-safe processing, and better time-to-sync. Store the payloads, return a successful response, and then process them later in the background.

Building

Step 1: Determine the data that will sync & direction

Before writing any code, define which system is authoritative for each type of data domain, the direction it will sync, and which attributes are included.

If data already exists in both systems you will need logic for handling matching & conflicts. Hint supports a way to Match Patients.

Step 2: Implement activation (one practice at a time)

Each practice must enable your integration and authorize access to practice-scoped data. We recommend implementing our automatic activation logic for a scalable, self-serve activation experience.

Deep dive: Integration Activation

Step 3: Establish a clean baseline (initial sync)

Initial sync is where most duplicate records and long-term drift begin. Build it to be safe to re-run and explicit about matching rules.

Deep dive: Initial Data Sync

Step 4: Keep data current with webhooks (avoid polling)

Use Webhooks to receive lifecycle events and update your system in near real-time. This reduces load on both sides and improves time-to-sync compared to polling.

At a minimum:

• subscribe to the events you need for the objects you surface in your product
• treat webhook handling as a durable pipeline (idempotent, retry-safe, monitored)

Step 5: Make sync status obvious with integration records and deep links

When practice staff are looking at a record, they should be able to see whether it is connected and jump to the corresponding record in the other system.

Integration records (IDs, deep links, and errors)

Hint supports integration metadata on many objects (for example Patient and CustomerInvoice):

• integration_record_id: your system's identifier for the corresponding record
• integration_web_link: a deep link from Hint into the record in your app
• integration_error_message: a human-readable reason a record is not synced (and what to do next)

Hint uses these fields to derive meaningful sync status in the UI and to help staff resolve issues quickly.

Deep links back into Hint (provider web links)

Hint also provides provider_web_link on certain resources (for example Patient and CustomerInvoice). Partners can store and surface this URL in their UI to deep link users back into Hint.

Step 6: Surface the "high value" fields in your UI

Most Integration Partners get the most leverage by making these fields obvious in the partner product:

• membership status (active, inactive, pending, unconfirmed)
• plan name
• balance owed
• employer (if applicable)
• practitioner / provider or location (if it exists in your product)
• deep links back into Hint (provider_web_link)