Institutions, Syncs and Locations

An institution represents a group of practices belonging to the same parent organization. Institutions have syncs, which map to an instance of a health record system (e.g. a server running Dentrix). Syncs may have one or many locations.

Institutions

An institution represents a logical grouping of practices and their syncs. Institutions represent the highest level of the hierarchy. You can think of an institution as a parent organization or practice umbrella organization.

In the NexHealth API, institution data is identified with a subdomain. As such, almost all endpoints require that the subdomain parameter is specified (i.e. ?subdomain=example-subdomain). You may only query one subdomain at a time. If you attempt to access an institution/subdomain that your API key does not have access to, you will receive a 403 Forbidden response.

Syncs

After creating an institution , the next step in onboarding a practice is to create a sync. A sync represents an instance of the NexHealth Synchronizer which allows NexHealth to exchange data between the health record system and your application.

Please note that a sync is needed for each database and that one sync represents one database. Just as a database may contain records for a single office or several office locations, a sync may connect to one or several locations. For example, if sync A is installed on a Dentrix server which hosts a database for a single location, then this sync will be connected to one location. If sync B is installed on a Dentrix Enterprise server which hosts a database for multiple locations, then this sync will be connected to multiple locations.

Server-based (on-prem) syncs
Server-based databases are usually hosted on a machine in an office location or on a virtual machine hosted by a web service such as AWS. In either case, the NexHealth Synchronizer must be installed on each server you need access to.

Keep in mind that when working with institutions with several office locations, the offices may share a single server (multi location or multi clinic databases), they may have one server per location, or a combination of both. Please work with the office and/or their IT to understand their specific office network setup as this will inform the number of syncs and therefore installations necessary.

Cloud-based syncs
Cloud-based databases do not rely on a physical server. Instead, users log into the service from a browser with a username and password. For cloud syncs, the NexHealth Synchronizer requires a set of user credentials for installation. Additionally, in most cases, the sync is maintained by a Chrome extension which must be installed and authenticated on the workstation of each office user.

Like server-based databases, cloud-based databases may also contain records for a single or multiple offices. In the latter, the office manager should provision a single user with access to multiple locations or facilities. It is important to note that the NexHealth structure of institutions and syncs must reflect that of the health record system. For example, if multiple offices share the same Dentrix Ascend org ID (i.e. they can switch between multiple locations or facilities without signing out), then NexHealth must also have one sync and one Ascend user on file with access to all applicable locations. Since all locations are part of the same sync, they will share the same Chrome extension token.

Locations

Locations represent the lowest level of the hierarchy. A majority of practice records that you will be accessing (e.g. patients, appointments, charges), are scoped to a specific location. As such, these endpoints require that the location ID and the subdomain parameter are specified (i.e. ?subdomain=example-subdomain&location_id=100). Specifying a location ID that doesn't exist within the institution will result in a 404 Not Found response.

API access is provided on a per location basis, meaning that an individual API key may have access to one or many locations within a subdomain. Specifying a location ID that your API key does not have access to will result in a 403 Forbidden response.

Furthermore, API access is not endpoint specific, meaning that access to a location provides access to all endpoints for that location.

A Guide to Managing Syncs

Initially, it can be difficult to determine whether you need to create a new sync or read in another location for an existing sync. This guide includes scenarios to help you determine the best path. In order to determine next steps, ask the customer if the new location shares a database with any other locations.

I’m onboarding an entirely new customer with a single location database setup
Once you’ve confirmed that your new customer isn’t part of any of your existing institutions (e.g. practice groups you already work with), then create a new institution for this customer. Create a sync and follow the onboarding process.

I’m onboarding an entirely new customer with a multi location cloud setup
In many cases, offices working in eCW or Dentrix Ascend will create a user with access to more locations than are needed for onboarding purposes. After submitting cloud credentials, please email [email protected] to specify which locations need to be synced for fastest processing. If you do not do so, support may reach out to request additional information before the installation can be initialized.

One of my existing customers wants to add a new location
In this case, you will start from an existing institution and either create a new sync OR add another location to an existing sync.

• If the new location has their own server (on-prem) or uses a cloud health record system that is not shared with any other offices, create a new sync and follow the onboarding process from there.
• If the new office shares a server with other sister locations, determine if you already have access to those sister locations
  • If you do not already have an active sync for any of those sister locations, create a new sync and follow the onboarding process from there.
  • If you do have an active sync for at least one of those sister locations, do not create a new sync. Instead, follow these instructions for activating additional locations in the Developer Portal.

One of my existing customers left their practice group but wants to keep using my application
If this office is now operating independently, deactivate the office’s existing location from the portal. Then create a new institution for them in the Developer Portal and follow the onboarding process from there.

My customer accidentally deleted the Synchronizer from their server
In this case, the NexHealth Synchronizer will need to be reinstalled on the server. Please reach out to [email protected] to obtain a new product key.

My existing customer migrated their health record system to a new server
If the customer has a new server but has made no changes to their health record system setup (e.g. continuing to use single location Open Dental just on a new Windows machine) you will continue to use the same sync and location. However, the NexHealth Synchronizer will need to be installed on the new server. Until the installation is complete, NexHealth will have stale data. Please reach out to [email protected] to obtain a new product key.

My existing customer migrated to a different health record system
In some cases, a customer may make major changes that affect IDs within the database (e.g. location IDs, patient IDs, provider IDs). This may include moving from Open Dental to Dentrix or from single location Open Dental to multi-location Open Dental. In these cases, you will keep the existing institution but create a new sync in the Portal. Once you complete the installation process, the Synchronizer will create a new location. Please update your API calls to reflect the new location ID. Please note that while the underlying data should remain the same, their IDs will change between locations. In other words, after the migration, the new location should have roughly the same providers, patients and appointments data, but their IDs will have changed.

📘

Store Subdomains and Locations Ids

Since you will likely be providing the subdomain and location_id in your requests often and these values are unlikely to change, it is a good idea to periodically perform a GET request to /locations and store the response data for reuse. Thus saving extraneous API calls.

Important Location Configuration Flags