---
title: "Create onboarding"
method: POST
path: "/onboardings"
tags: ["Onboardings"]
---

# Create onboarding

`POST /onboardings`

Creates an onboarding link to set up NexHealth at a practice. Include institution_name to onboard a new institution, or subdomain to add locations to an existing institution. Send the returned url to practice staff; it expires 3 months after creation. Only production applications can create onboardings.

## 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 used when onboarding a new institution (institution_name); ignored when subdomain is provided. 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. If both subdomain and institution_name are provided, subdomain takes precedence and all institution_* fields are ignored.
    - `emr_name` 'athena' | 'curve2' | 'cloud9' | 'denticon' | 'dentrix' | 'dentrixascend' | 'drchrono' | 'eaglesoft' | 'ecw' | 'modmed' | 'nextgen' | 'opendental' — The name of the electronic medical record (EMR) system where you want to install the Synchronizer. Note: drchrono is only supported when onboarding a new institution (institution_name), not when adding to an existing institution (subdomain).

## Response `201`

Successful

- APIV20240412EntitiesApiOnboardingResponse — API_V20240412_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` APIV20240412EntitiesApiOnboarding
    - `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' — Current state of the onboarding. in_progress: the link has been created and setup is not finished; complete: setup finished (including installations completed manually by NexHealth); failed: the onboarding failed, was cancelled, or was disabled and will not proceed.
    - `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. 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.
  - `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.net/nexhealth/apis/nexhealth-api.md) · [All operations](https://skmtc.net/nexhealth/apis/nexhealth-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nexhealth/nexhealth-api/revisions/a180e830b672/schema)