---
title: "View onboardings (beta)"
method: GET
path: "/onboardings"
tags: ["Onboardings"]
---

# View onboardings (beta)

`GET /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 response fields `data[].locations`, `data[].locations[].city`, `data[].locations[].data_ready_at`, `data[].locations[].external_id` (+13 more).

## Query parameters

- `subdomain` string
- `status` 'in_progress' | 'complete' | 'failed'
- `start_cursor` string
- `end_cursor` string
- `per_page` integer
- `sort` string

## Headers

- `Nex-Api-Version` string, required

## Response `200`

Successful

- APIV31EntitiesApiOnboardingCollectionResponseWithCursor: API_V31_Entities_Api_Onboarding_Collection_Response_WithCursor 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.
  - `page_info` object: Pagination information that can be used for fetching previous and next pages.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `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)