---
title: "Create patient (beta)"
method: POST
path: "/patients"
tags: ["Patients"]
---

# Create patient (beta)

`POST /patients`

## Request

- Base URL: `https://nexhealth.info`
- URL: `https://nexhealth.info/patients`
- 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 `patient.address`, `patient.address.city`, `patient.address.line_1`, `patient.address.line_2` (+10 more); removes request fields `patient.bio`, `patient.bio.address_line_1`, `patient.bio.address_line_2`, `patient.bio.cell_phone_number` (+16 more); and other schema changes.

This endpoint creates a new patient (201 Created), or returns the existing patient (200 OK) when one with a matching name and date of birth already exists. At least one non-blank phone number (cell_phone_number, home_phone_number, or work_phone_number) is required. Phone numbers are written to typed fields in the integrated system, but many systems report the main number back as an untyped primary number — see the cell_phone_number and preferred_phone_number response fields for how that is surfaced.

## Query parameters

- `subdomain` string, required
- `location_id` integer, required

## Headers

- `Nex-Api-Version` string, required

## Request body

- PostPatients: Create patient
  - `provider` object, required
    - `provider_id` integer, required: ID of the provider with which to intake this new patient
  - `patient` object, required
    - `first_name` string, required: Patient first name
    - `last_name` string, required: Patient last name
    - `email` string, required: Patient email address. Must match regular expression /\A([^@\s]+)@((?:[-a-z0-9]\.)[a-z]{2,})\Z/
    - `date_of_birth` string, date, required: Patient date of birth. Must be a parseable date string, recommended format is YYYY-MM-DD
    - `middle_name` string: Patient middle name
    - `gender` 'Male' | 'Female' | 'Other': Patient gender.
    - `cell_phone_number` string: Patient cell phone number, written to the integrated system's cell/mobile phone field. Some integrated systems report the number back as an untyped primary number; the cell_phone_number response field falls back to that number, so the value stays visible after the write syncs.
    - `home_phone_number` string: Patient home phone number
    - `work_phone_number` string: Patient work place phone number
    - `work_phone_extension` string: Patient work phone extension
    - `ssn` string: Patient social security number
    - `address` object: Patient address
      - `line_1` string: Address line 1
      - `line_2` string: Address line 2
      - `city` string: City
      - `region` string: State
      - `postal_code` string: Zip code

## Response `201`

Successful

- APIV31EntitiesPatientDetailedResponse: API_V31_Entities_PatientDetailed_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` APIV31EntitiesPatientDetailed
    - `id` integer: User ID
    - `email` string: User email
    - `first_name` string: First name
    - `middle_name` string: Middle name
    - `last_name` string: Last name
    - `name` string: Full name
    - `created_at` string, date-time: User creation date in UTC
    - `updated_at` string, date-time: User last update date in UTC
    - `institution_id` integer: The institution this user belongs to
    - `foreign_id` string: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
    - `foreign_id_type` string: Foreign ID type is a unique string identifier for the integrated system
    - `inactive` boolean: Is the user inactivated?
    - `home_phone_number` string: Home phone number
    - `work_phone_number` string: Work phone number
    - `work_phone_extension` string: Work phone extension
    - `cell_phone_number` string: Cell phone number. When the integrated system reports the patient's main number as an untyped primary number instead of a typed cell number — which is how most systems report it back after a write — this field falls back to that primary number. The fallback is usually the cell number, but the integrated system does not guarantee the primary number is a cell number.
    - `preferred_phone_number` string: The best-known phone number for reaching the patient: the first available of the integrated system's untyped primary number, cell phone number, home phone number, and work phone number. Read-only — write one of the typed phone number fields to change it.
    - `guarantor_id` integer: User ID of this patient's responsible party
    - `billing_type` string: Used by practices in some integrated systems to categorize and filter patients when creating reports, requesting payments, and performing other related office tasks. Some integrated systems call this an account type rather than a billing type
    - `chart_id` string: User-facing ID for referencing patient data, used in some integrated systems. Depending on the system, the chart ID supplements or replaces the foreign_id as the ID visible to EHR users
    - `preferred_language` string: Patient's preferred language as an ISO 639-1 code, if specified in the integrated system
    - `provider_id` integer: User ID of this patient's primary provider
    - `gender` string: Gender from biographical data
    - `new_patient` boolean: Whether the patient is new
    - `non_patient` boolean: Whether this is a non-patient user record
    - `date_of_birth` string: Date of birth in YYYY-MM-DD format
    - `premedication` string: Premedication notes
    - `address` APIV2EntitiesPatientAddress
      - `line_1` string, nullable: Address line 1
      - `line_2` string, nullable: Address line 2
      - `postal_code` string, nullable: Zip code
      - `city` string, nullable: City
      - `region` string, nullable: State
    - `hipaa` APIV2EntitiesPrivacyAuthorization
      - `authorization` boolean: Whether the patient has provided HIPAA authorization
      - `authorization_date` string, date: Date the patient provided HIPAA authorization
      - `privacy` boolean: Whether the patient has acknowledged HIPAA privacy notice
      - `privacy_date` string, date: Date the patient acknowledged HIPAA privacy notice
      - `consent` boolean: Whether the patient has provided HIPAA consent
      - `consent_date` string, date: Date the patient provided HIPAA consent
    - `ehr_unsubscribe_sms` boolean: Whether the patient is unsubscribed from SMS in the EHR
    - `ehr_unsubscribe_emails` boolean: Whether the patient is unsubscribed from emails in the EHR
    - `preferred_location_id` integer: Patient's preferred location from the EHR
    - `children` APIV31EntitiesPatientBasic[]: Patient children
      - `id` integer: User ID
      - `email` string: User email
      - `first_name` string: First name
      - `middle_name` string: Middle name
      - `last_name` string: Last name
      - `name` string: Full name
      - `created_at` string, date-time: User creation date in UTC
      - `updated_at` string, date-time: User last update date in UTC
      - `institution_id` integer: The institution this user belongs to
      - `foreign_id` string: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
      - `foreign_id_type` string: Foreign ID type is a unique string identifier for the integrated system
      - `inactive` boolean: Is the user inactivated?
      - `home_phone_number` string: Home phone number
      - `work_phone_number` string: Work phone number
      - `work_phone_extension` string: Work phone extension
      - `cell_phone_number` string: Cell phone number. When the integrated system reports the patient's main number as an untyped primary number instead of a typed cell number — which is how most systems report it back after a write — this field falls back to that primary number. The fallback is usually the cell number, but the integrated system does not guarantee the primary number is a cell number.
      - `preferred_phone_number` string: The best-known phone number for reaching the patient: the first available of the integrated system's untyped primary number, cell phone number, home phone number, and work phone number. Read-only — write one of the typed phone number fields to change it.
      - `guarantor_id` integer: User ID of this patient's responsible party
      - `billing_type` string: Used by practices in some integrated systems to categorize and filter patients when creating reports, requesting payments, and performing other related office tasks. Some integrated systems call this an account type rather than a billing type
      - `chart_id` string: User-facing ID for referencing patient data, used in some integrated systems. Depending on the system, the chart ID supplements or replaces the foreign_id as the ID visible to EHR users
      - `preferred_language` string: Patient's preferred language as an ISO 639-1 code, if specified in the integrated system
      - `provider_id` integer: User ID of this patient's primary provider
      - `gender` string: Gender from biographical data
      - `new_patient` boolean: Whether the patient is new
      - `non_patient` boolean: Whether this is a non-patient user record
      - `date_of_birth` string: Date of birth in YYYY-MM-DD format
      - `premedication` string: Premedication notes
      - `address` APIV2EntitiesPatientAddress
        - `line_1` string, nullable: Address line 1
        - `line_2` string, nullable: Address line 2
        - `postal_code` string, nullable: Zip code
        - `city` string, nullable: City
        - `region` string, nullable: State
    - `guarantor` APIV31EntitiesPatientBasic
      - `id` integer: User ID
      - `email` string: User email
      - `first_name` string: First name
      - `middle_name` string: Middle name
      - `last_name` string: Last name
      - `name` string: Full name
      - `created_at` string, date-time: User creation date in UTC
      - `updated_at` string, date-time: User last update date in UTC
      - `institution_id` integer: The institution this user belongs to
      - `foreign_id` string: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
      - `foreign_id_type` string: Foreign ID type is a unique string identifier for the integrated system
      - `inactive` boolean: Is the user inactivated?
      - `home_phone_number` string: Home phone number
      - `work_phone_number` string: Work phone number
      - `work_phone_extension` string: Work phone extension
      - `cell_phone_number` string: Cell phone number. When the integrated system reports the patient's main number as an untyped primary number instead of a typed cell number — which is how most systems report it back after a write — this field falls back to that primary number. The fallback is usually the cell number, but the integrated system does not guarantee the primary number is a cell number.
      - `preferred_phone_number` string: The best-known phone number for reaching the patient: the first available of the integrated system's untyped primary number, cell phone number, home phone number, and work phone number. Read-only — write one of the typed phone number fields to change it.
      - `guarantor_id` integer: User ID of this patient's responsible party
      - `billing_type` string: Used by practices in some integrated systems to categorize and filter patients when creating reports, requesting payments, and performing other related office tasks. Some integrated systems call this an account type rather than a billing type
      - `chart_id` string: User-facing ID for referencing patient data, used in some integrated systems. Depending on the system, the chart ID supplements or replaces the foreign_id as the ID visible to EHR users
      - `preferred_language` string: Patient's preferred language as an ISO 639-1 code, if specified in the integrated system
      - `provider_id` integer: User ID of this patient's primary provider
      - `gender` string: Gender from biographical data
      - `new_patient` boolean: Whether the patient is new
      - `non_patient` boolean: Whether this is a non-patient user record
      - `date_of_birth` string: Date of birth in YYYY-MM-DD format
      - `premedication` string: Premedication notes
      - `address` APIV2EntitiesPatientAddress
        - `line_1` string, nullable: Address line 1
        - `line_2` string, nullable: Address line 2
        - `postal_code` string, nullable: Zip code
        - `city` string, nullable: City
        - `region` string, nullable: State
    - `provider` APIV31EntitiesProvider
      - `id` integer: User ID
      - `email` string: User email
      - `first_name` string: First name
      - `middle_name` string: Middle name
      - `last_name` string: Last name
      - `name` string: Full name
      - `created_at` string, date-time: User creation date in UTC
      - `updated_at` string, date-time: User last update date in UTC
      - `institution_id` integer: The institution this user belongs to
      - `foreign_id` string: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
      - `foreign_id_type` string: Foreign ID type is a unique string identifier for the integrated system
      - `inactive` boolean: Is the user inactivated?
      - `phone_number` string: Primary phone number
      - `cell_phone_number` string: Cell phone number
      - `home_phone_number` string: Home phone number
      - `work_phone_number` string: Work phone number
      - `work_phone_extension` string: Work phone extension
      - `display_name` string: Display name
      - `npi` string: National Provider Identifier as registered in NPPES. May be null if the practice did not enter it into the integrated system.
      - `tin` string: Taxpayer Identification Number (SSN or ITIN). May be null if the practice did not enter it into the integrated system.
      - `state_license` string: State license number. May be null if the practice did not enter it into the integrated system.
      - `specialty_code` string: Specialty code corresponding to the provider's state license and NPI. May be null if the practice did not enter it into the integrated system.
    - `last_visited_appointment` APIV2EntitiesAppointmentBasic
      - `id` integer: Appointment ID
      - `provider_id` integer: Provider ID
      - `provider_name` string: Provider name
      - `start_time` string, date-time: Start time of the appointment in UTC
      - `end_time` string, date-time: End time of the appointment in UTC
      - `location_id` integer: Location ID
      - `confirmed` boolean: Is this appointment confirmed?
    - `upcoming_appts` APIV2EntitiesAppointmentBasic[]: Scheduled appointments for one year. Not included by default
      - `id` integer: Appointment ID
      - `provider_id` integer: Provider ID
      - `provider_name` string: Provider name
      - `start_time` string, date-time: Start time of the appointment in UTC
      - `end_time` string, date-time: End time of the appointment in UTC
      - `location_id` integer: Location ID
      - `confirmed` boolean: Is this appointment confirmed?
    - `procedures` APIV31EntitiesProcedure[]: Procedures assigned to the patient. Not included by default
      - `id` integer: Procedure ID
      - `foreign_id` string, nullable: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
      - `location_id` integer: Location ID
      - `patient_id` integer: Patient ID
      - `provider_id` integer: Provider ID
      - `appointment_id` integer: Appointment ID
      - `code` string: Procedure code
      - `name` string: Procedure name
      - `status` 'planned' | 'scheduled' | 'completed' | 'inactive' | 'referred' | 'existing': Procedure status
      - `updated_at` string, date-time: Procedure update date in UTC
      - `body_site` APIV2EntitiesProcedureBodySite
        - `tooth` string[]: Tooth identifier strings, typically tooth numbers
        - `surface` string: Tooth surface codes
      - `fee` APIV2EntitiesPrice
        - `amount` string: The currency value, in whole units (e.g. dollars)
        - `currency` string: The ISO currency code
      - `start_date` string, date: Start date for procedure
      - `end_date` string, date: End date for procedure
      - `treatment_plan_ids` integer[]: Treatment plan IDs
    - `insurance_coverages` APIV2EntitiesInsurancePatientCoverageForIndividual[]: Insurance coverages
      - `id` integer: Coverage ID
      - `subscription_relation` 'self' | 'spouse' | 'child' | 'employee' | 'handicap_dep' | 'signif_other' | 'injured_plaintiff' | 'life_partner' | 'dependent' | 'other': The relationship of this patient to the subscriber
      - `patient_id` integer, nullable: The ID of the covered patient
      - `priority` integer, nullable: The relative priority of this insurance coverage where the lowest value is the patient's primary insurance and higher values represent secondary and tertiary policies
      - `plan_id` integer, nullable: The ID of the insurance plan this coverage subscribes to
      - `subscriber_num` string, nullable: The subscriber's identification number for the plan
      - `effective_date` string, date, nullable: The date the coverage takes effect
      - `expiration_date` string, date, nullable: The date the coverage expires
      - `plan` APIEntitiesInsuranceEhrPlan
        - `id` integer: Plan ID
        - `payer_id` string, nullable: A unique ID number that is assigned to an insurance company for the purpose of transmitting provider claims electronically
        - `name` string, nullable: Plan name
        - `address` string, nullable: Street address
        - `address2` string, nullable: Street address 2
        - `city` string, nullable: City
        - `state` string, nullable: 2 letter state code
        - `zip_code` string, nullable: Zip code
        - `country_code` string, nullable: 2 letter country code
        - `group_num` string, nullable: Group number
        - `employer_name` string, nullable: Employer name
        - `foreign_id` string, nullable: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
        - `updated_at` string, date-time: Insurance Plan update date in UTC
        - `deleted_at` string, date-time, nullable: The UTC date and time the insurance plan was deleted. Null unless the plan is soft-deleted; deleted plans are only returned when include_deleted is true
      - `subscriber` APIV2EntitiesInsuranceSubscriber
        - `id` integer: The subscriber's ID
        - `name` string: The subscriber's full name
        - `date_of_birth` string, nullable: The subscriber's date of birth in YYYY-MM-DD format
    - `adjustments` APIV31EntitiesLedgerAdjustment[]: Payment ledger adjustments
      - `id` integer: Resource ID
      - `foreign_id` string: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
      - `location_id` integer: The ID of the location that this item is for
      - `patient_id` integer: The ID of the patient that this item is for
      - `guarantor_id` integer: The ID of the guarantor that this item is for
      - `provider_id` integer: The ID of the provider that this item is for
      - `updated_at` string, date-time: Last updated time for item in UTC
      - `description` string: A description of the item
      - `deleted_at` string, date-time: Deleted time for item in UTC
      - `adjustment_amount` APIV2EntitiesPrice
        - `amount` string: The currency value, in whole units (e.g. dollars)
        - `currency` string: The ISO currency code
      - `adjusted_at` string, date: The UTC date adjustment was made
      - `transaction_id` string: The ID of the transaction for this payment
      - `charge_id` integer: The ID of the charge for this payment
      - `claim_id` integer: The ID of the insurance claim for this payment
      - `adjustment_type_id` integer: The ID of the adjustment type for this payment
    - `charges` APIV31EntitiesLedgerChargeBasicWithDelete[]: Payment ledger charges
      - `id` integer: Resource ID
      - `foreign_id` string: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
      - `location_id` integer: The ID of the location that this item is for
      - `patient_id` integer: The ID of the patient that this item is for
      - `guarantor_id` integer: The ID of the guarantor that this item is for
      - `provider_id` integer: The ID of the provider that this item is for
      - `procedure_id` integer: The ID of the procedure associated with this charge
      - `procedure_code` string: The procedure code associated with this charge
      - `updated_at` string, date-time: Last updated time for item in UTC
      - `description` string: A description of the charge
      - `fee` APIV2EntitiesPrice
        - `amount` string: The currency value, in whole units (e.g. dollars)
        - `currency` string: The ISO currency code
      - `charged_at` string, date: The UTC date charge was made
      - `deleted_at` string, date-time: The UTC datetime the charge was deleted
    - `payments` APIV31EntitiesLedgerPayment[]: Payment ledger payments
      - `id` integer: Resource ID
      - `foreign_id` string: Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.
      - `location_id` integer: The ID of the location that this item is for
      - `patient_id` integer: The ID of the patient that this item is for
      - `guarantor_id` integer: The ID of the guarantor that this item is for
      - `provider_id` integer: The ID of the provider that this item is for
      - `updated_at` string, date-time: Last updated time for item in UTC
      - `description` string: A description of the item
      - `deleted_at` string, date-time: Deleted time for item in UTC
      - `payment_amount` APIV2EntitiesPrice
        - `amount` string: The currency value, in whole units (e.g. dollars)
        - `currency` string: The ISO currency code
      - `paid_at` string, date: The UTC date payment was made
      - `transaction_id` string: The ID of the transaction for this payment
      - `charge_id` integer: The ID of the charge for this payment
      - `claim_id` integer: The ID of the insurance claim for this payment
      - `payment_plan_id` integer: The ID of the payment plan associated with this payment
      - `insurance_plan_id` integer: The ID of the insurance plan associated with this payment
      - `payment_type_id` integer: The ID of the payment type for this payment
    - `patient_alerts` APIV2EntitiesPatientAlert[]: Patient Alerts
      - `id` integer: Patient Alert ID
      - `patient_id` integer: ID of the associated patient
      - `note` string: The note for the patient alert
      - `disabled_at` string, date-time: The time that the alert was disabled in UTC
      - `created_at` string, date-time: The time that the alert was created in UTC
      - `updated_at` string, date-time: The time that the alert was last updated in UTC
    - `appointments` APIV2EntitiesAppointmentBasic[]: Appointments for patient within date range
      - `id` integer: Appointment ID
      - `provider_id` integer: Provider ID
      - `provider_name` string: Provider name
      - `start_time` string, date-time: Start time of the appointment in UTC
      - `end_time` string, date-time: End time of the appointment in UTC
      - `location_id` integer: Location ID
      - `confirmed` boolean: Is this appointment confirmed?
    - `location_ids` integer[]: Array of location IDs associated with the user
    - `ssn` string: Patient social security number. Returned only when fetching a single patient; omitted from patient lists and from patient objects embedded in other resources.
  - `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)