--- title: "Create onboarding (beta)" method: POST path: "/onboardings" tags: ["Onboardings"] --- # Create onboarding (beta) `POST /onboardings` ## Request - Base URL: `https://nexhealth.info` - URL: `https://nexhealth.info/onboardings` - Auth: API key in header `Authorization` > 🚧 Beta > > Send `Nex-Api-Version: v3.1.0` to use this endpoint. It is still changing, and access is limited to approved partner institutions. Contact NexHealth before you build on it. > **Changed from v3.0.0:** Adds request fields `onboarding.callback_url`, `onboarding.locations`, `onboarding.locations[].city`, `onboarding.locations[].external_id` (+4 more); removes request field `onboarding.emr_name`; changes request field `onboarding`; and other schema changes. ## Headers - `Nex-Api-Version` string, required ## Request body - PostOnboardings: Create onboarding - `onboarding` object, required: Onboarding details - `institution_name` string: The institution's' name. Only include this if you are onboarding a new institution. - `institution_zip_code` string: The institution's zip code. Only include this if you do not already have Synchronizer access. If you omit it, practice staff will be asked to enter it during setup. - `institution_website` string: The institution's website URL. Only include this if you are onboarding a new institution. If you omit it, practice staff will be asked to enter it during setup. - `institution_email` string: The institution's primary email address. Only include this if you are onboarding a new institution. If you omit it, practice staff will be asked to enter it during setup. - `subdomain` string: The subdomain for the institution you want to add locations to. You need to include this when you want to add new locations to an existing institution. Ensure the subdomain used is returned by the API in a previous query. - `callback_url` string: Where practice staff are redirected once setup completes. Must be an http(s) URL on one of your application's registered redirect domains; a URL on another domain is replaced by your application's first redirect URI. If you omit it, practice staff stay on the setup completion page. - `locations` object[], required: The location to set up. Exactly one entry is accepted; a call with no entries or more than one is rejected. - `external_id` string: Your identifier for the location. When present, retrying this call with the same external_id returns the onboarding created by the first call instead of creating another. - `name` string, required: The location's name. - `zip_code` string, required: The location's zip code. - `street_address` string, required: The location's street address. - `city` string: The location's city. - `state` string: The location's state or region. ## Response `201` Successful - APIV31EntitiesApiOnboardingResponse: API_V31_Entities_Api_Onboarding_Response model - `code` boolean: Indicates the success or failure of the request - `description` string: Additional context on the request to help with debugging. - `error` string[]: Any errors that occur during the execution of the request. - `data` APIV31EntitiesApiOnboarding - `id` string: The ID of the onboarding process. - `created_at` string, date-time: The timestamp the onboarding url was created. - `subdomain` string, nullable: The subdomain of the institution this onboarding belongs to. Null until the onboarding has been matched to an institution (e.g. while a new institution is still being set up). - `url` string: The link to send to practice staff to complete setup. Format varies by onboarding type. Expires at url_expires_at. - `url_expires_at` string, date-time: When the url will expire and no longer be valid. - `status` 'in_progress' | 'complete' | 'failed': Lifecycle of the onboarding. in_progress: setup has not finished; complete: setup finished (including installations completed manually by NexHealth); failed: NexHealth cancelled or disabled the onboarding. A failure the practice can retry does not change it: see locations[].progress. - `booking_params` object, nullable: Data collected during setup for online booking. Contains "location_id" (ID of the location selected during setup; may be serialized as an integer or numeric string) and "appointment_type_ids" (array of appointment type IDs), each present only after the corresponding setup step has run. Always null for installation-based onboardings. It can also be an empty object on a completed (non-installation) onboarding, if that onboarding's completion was driven by its linked installation finishing rather than by the location/appointment-type setup steps ever running. Before setup begins it is an empty object on the retrieve and create endpoints and null on the list endpoint. - `availability_ready_at` string, date-time, nullable: When the onboarding location first became bookable. Null until availability is ready. - `locations` APIV31EntitiesApiOnboardingLocation[]: The locations this onboarding sets up, one entry per location. Empty when the onboarding was created without location details. Correlate entries by external_id when you supplied one, otherwise by name, zip_code and street_address; the order of entries is not guaranteed. Present in GET /onboardings, GET /onboardings/:hashid and webhook payloads. - `location_id` integer, nullable: The NexHealth ID of this location, assigned once practice staff select or create it during setup. Null until then. - `external_id` string, nullable: The identifier you supplied for this location when creating the onboarding. Null when none was supplied. - `name` string: The location name supplied when creating the onboarding. - `zip_code` string, nullable: The location zip code supplied when creating the onboarding. Null when none was supplied. - `street_address` string, nullable: The location street address supplied when creating the onboarding. Null when none was supplied. - `city` string, nullable: The location city supplied when creating the onboarding. Null when none was supplied. - `state` string, nullable: The location state or region supplied when creating the onboarding. Null when none was supplied. - `progress` APIV31EntitiesApiOnboardingProgress - `status` 'complete' | 'failed' | 'installing_chrome_extension' | 'configuring_schedule' | 'initial_read_complete' | 'locations_selected' | 'setup_time_booked' | 'nexhealth_installing' | 'installation_in_progress' | 'credentials_shared' | 'credentials_entered' | 'installer_instructions_shared' | 'ehr_selected' | 'started': How far the practice has got in setup. started: the link has been opened but no EHR chosen yet; ehr_selected: the practice picked their EHR; credentials_entered: cloud EHR credentials were submitted; installer_instructions_shared: on-prem installer instructions were shown to the practice; credentials_shared: credentials were submitted for an EHR NexHealth installs by hand; setup_time_booked: the practice booked a slot for NexHealth to perform the installation; nexhealth_installing: NexHealth is performing the installation; installation_in_progress: the Synchronizer installation is running; locations_selected: the practice picked the locations to sync; initial_read_complete: the practice data needed to finish setup has been read; configuring_schedule: the practice is setting up appointment types, providers and hours; installing_chrome_extension: the practice is installing the Chrome extension; complete: setup finished; failed: setup is blocked, and error carries the failure unless NexHealth cancelled or disabled the onboarding. failed is not final while the practice can retry: status moves on again once they do. - `path` 'cloud' | 'onprem' | 'manual', nullable: Which sequence of status values applies. cloud: the practice enters credentials and the Synchronizer installs itself; onprem: the practice installs the Synchronizer on their own server; manual: NexHealth performs the installation. Null until the practice has chosen an EHR. - `error` APIV31EntitiesApiOnboardingError - `key` 'invalid_credentials' | 'insufficient_permissions' | 'invalid_login_url' | 'connection_error' | 'license_limit' | 'unknown_error': Machine-readable classification of the failure. Failures NexHealth cannot classify are reported as unknown_error. - `responsible_party` 'practice' | 'nexhealth' | 'unknown': Who has to act to clear the failure. practice: the practice can fix it themselves in the setup flow or in their EHR. nexhealth: only NexHealth can resolve it, and the setup flow has pointed the practice to NexHealth support. unknown: the failure cannot be attributed to one side (e.g. the EHR could not be reached). - `message` string: What went wrong, written for you rather than for the practice staff in the setup flow. - `remediation` string: What has to happen for the setup to continue. - `data_ready_at` string, date-time, nullable: When the historical data read for your application at this location finished. Set once for as long as your access to the location lasts. Null until then. - `count` integer: Number of total objects, in case of collection. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `500`: Internal Server Error --- [API](https://skmtc.dev/nexhealth/apis/nexhealth-api-v3-1-0-beta.md) - [All operations](https://skmtc.dev/nexhealth/apis/nexhealth-api-v3-1-0-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/nexhealth/apis/nexhealth-api-v3-1-0-beta/revisions/93cb4af790a5?raw)