Onboardings

The POST /onboarding endpoint lets you onboard new practices and add new locations to existing practices. The endpoint returns a unique onboarding link you can share with your practices to complete setting up the synchronizer.

Overview

In the NexHealth context, “onboarding” refers to one of the following workflows:

Adding a completely new institution
Adding a new location to an existing institution

Each of these scenarios can be initiated through the same POST /onboardings endpoint with different request parameters.

For detailed field definitions, visit the API Reference. For a full end to end guide on onboarding practices, read this.

Usage Scenarios

1. Adding a Completely New Institution

Use this approach when onboarding a brand new practice.

Important: Do not include the subdomain field. You should only include subdomain when you want to add locations to an existing practice that you've already onboarded.

👍
Tip: If you know the institution name, ZIP code, and website, we recommend including them in your API request.
If you do not pass these fields, the practice will be prompted to enter this information manually during onboarding. If you do pass them, the practice won’t need to re-enter these details, which helps speed up the onboarding process.

Example Request

curl -v --request POST \
  --url 'https://nexhealth.info/onboardings' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'nex-api-version: v20240412' \
  --header 'content-type: application/json' \
  --data '{
    "onboarding": {
      "institution_name": "new-test-practice",
      "institution_email": "[email protected]",
      "institution_zipcode": "10023",
      "institution_website": "www.example-nexhealth.com"
    }
  }'

2. Adding a New Location to an Existing Institution

Use this approach when you're already connected to the practice. Include the subdomain parameter to associate the new location with the existing institution.

👍
Tip: If you include the emr_name, then the practice won't need to select their health record system during setup. The process will be easier for them because they'll have less steps to do.

Example Request

curl -v --request POST \
  --url 'https://nexhealth.info/onboardings' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'nex-api-version: v20240412' \
  --header 'content-type: application/json' \
  --data '{
    "onboarding": {
    "subdomain": "nexhealthsmiles",
		"emr_name": dentrix
    }
  }'

Example Response

{
  "code": true,
  "description": null,
  "error": null,
  "data": {
    "id": "rwk15wd31x2z",
    "created_at": "2025-10-29T11:08:02.228Z",
    "subdomain": null,
    "url": "https://app.nexhealth.com/onboardings/rwk15wdk1x2z",
    "url_expires_at": "2025-11-29T11:08:02.228Z",
    "status": "in_progress"
  },
  "count": null
}

The url field in the response provides the onboarding link that you can share with the customer or practice to complete setup.

Checking Onboarding Status

Use the id from the response to check the current onboarding status.

Request

curl --request GET \
  --url 'https://nexhealth.info/onboardings/865ewkn35er7' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'nex-api-version: v20240412'

Troubleshooting

Error: "Institution not found"

{"code":false,"description":null,"data":null,"error":["Institution not found"]}

This error occurs when either:

The provided subdomain doesn't exist
You don't have permissions to access this institution.