Best Practices
Object Field Mapping
Partners should have a clear understanding of what objects will be mapped between our systems, and how object mappings will be made obvious to the practice within your app. For example if you have a provider, coach, or practitioner object in your system, this should probably be mapped to our our practitioner object.
During the initial integration activation process, there should be a workflow that supports the configuration of the mapping between objects between Partner and Hint. Ideally this mapping will exist in some kind of integration admin screen.
Integration Record ID, Weblink, & Status
Our API supports the ability for our Partners to post object level integration record ID's (integration_record_id), error messages (integration_error_message), and weblinks (integration_web_link) on all Hint API objects.
Integration Record ID's
The Hint API will accept Integration Record ID (integration_record_id) as an additional parameter for create and update calls on all objects within our system. This field is where Partners should add the ID of the corresponding record in their database. We strongly recommend at the very least syncing Integration Record ID's on patients (and practitioners if you are syncing these objects).
Integration Record Weblinks
Our API supports the ability to post an Integration Weblink (integration_web_link) to our patient endpoint. This will allow a Hint user to click a link on a patient profile which will deeplink the user directly into the corresponding chart within the Partner application. In order to enable this functionality, Partners should post a URL to integration_web_link that brings the Hint user directly into the correct place within the Partner app.
Integration Record Status/Error Messages
Within the patient record in Hint, there is an integration status (errored/synced/unsynced/enabled) and an error message if there is some action required to resolve a conflict with the integration.
Hint has a flag denoting whether or not we believe the partner is using the integration_record_id or integration_web_link field and this flag let's us give more meaningful statuses to the Hint user. As the partner you do not touch sync status, we show it based on whether or not we have:
- An Integration Record ID
- An Integration Record Weblink
- A recent successful webhooks and/or there is an error message present
If we have an Integration Record ID, and there are no errors, the integration record is marked as "synced" on our side.
For example, if we believe you are using the integration_record_id fields, and a record does have an ID, we say "synced". If it does not have the ID from you, then we can confidently say it is "not synced" (as in purposefully ignored). For that same record, if we believe you are not using the integration_record_id fields, then we would simply say the integration is "enabled". Which is our way of saying... "we have no reason to believe the integration is broken, but we don't really have any info on whether or not there is a corresponding record on the Partner's side".
If there is an error preventing the record from being synced, we expect partners to update the "integration_error_message" field for that record (using the corresponding Update endpoint). For example, if a patient cannot be synced to your system because they don't have an email address, which is required on your system, we would expect you to update the "integration_error_message" property on the patient with a message saying "Missing email address" or something like that.
Hint Web Links
Similar to Integration Record Weblink, where we provide a link back to a patient record in your system, on our Patient and CustomerInvoice objects we provide a Hint Weblink (provider_web_link), which is a URL that directly links back to Hint for that object.
At a minimum, we strongly recommend that you provide a link back to Hint patient records using the weblink. This streamlines the interactions between our systems.
Bi-directional Data Sync
When a new patient is added to Hint, a corresponding record should be created in the partner app and vice-versa. When patient information is updated in Hint, the updates should push to the partner app and vice-versa.
We strongly recommend bi-directional data sync is part of your integration, and unless there are extenuating circumstance, we will not publicly publish an integration without this functionality enabled.
Initial data sync process
This process should be set up with the goal of pulling and/or pushing over all relevant information while avoiding the creation of duplicates.
There should be clear rules about what happens if a match is found. Will the records be skipped? Will they be merged? If they are merged which will be the dominate record?
If a record fails in the initial data sync, it should be obvious that the record failed. An error message either on in the partner app and/or in ours should be surfaced.
Data to Surface in Partner App
Some or all of the following information should be made available within Partner applications:
- Hint Web Link
- Membership status (active, inactive, pending, unconfirmed)
- Plan name (eg: Bronze, Silver, Gold)
- Balance
- Employer name
- Practitioner (if this is a native concept in your app)
Integration Activation Process
This guide is designed to help you plan out and design your integration with Hint. With all of our Hint Connect partners we recommend that at a minimum the following is completed.
To make the integration process seamless for our mutual clients, partners should take advantage of InstantOn (via OAuth). Below you can see an example of how this process streamlines the process of setting up and configuring the integration.
To ensure it is obvious how to activate the integration, partners should have a link to their Hint integration page within their app.
Joint documentation / knowledge doc *
In order to ensure integrations are well documented, we will work with your team to jointly develop integration documentation. Documentation should include instructions for how to configure the integration, what to expect from the integration, and how to troubleshoot key issues with the integration.
Here is an example of a knowledge doc from Spruce
Updated almost 3 years ago