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

# Create patient

`POST /patients`

This endpoint creates a new patient or returns an existing patient if return_existing_if_match is true. Responds with 201 when a new patient is created, or with 200 and the existing patient when return_existing_if_match is true and a patient with matching information already exists.

## 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 id. Must match regular expression /\A([^@\s]+)@((?:[-a-z0-9]\.)[a-z]{2,})\Z/
    - `bio` object, required — Patient Bio
      - `date_of_birth` string, date, required — Patient date of birth. Must be a parseable date string, recommended format is YYYY-MM-DD. Cannot be more than 130 years in the past or in the future
      - `phone_number` string, required — Patient phone number
      - `home_phone_number` string — Patient home phone number
      - `cell_phone_number` string — Patient cell phone number
      - `work_phone_number` string — Patient work place phone number
      - `custom_contact_number` string — Patient custom contact phone number
      - `gender` 'Male' | 'Female' | 'Other' — Patient gender. Gender will default to Female if not provided. This is to ensure compatibility with all EHRs. This will be updated when the patient visits the office and updates their info
      - `weight` integer — Patient weight in KG
      - `height` integer — Patient height in CM
      - `street_address` string — Patient full street address
      - `address_line_1` string — Patient street address line 1
      - `address_line_2` string — Patient street address line 2
      - `city` string — Patient city
      - `state` string — Patient living state
      - `zip_code` string — Patient zip code
      - `insurance_name` string — Insurance name
      - `ssn` string — Patient SSN
      - `race` string — Patient race
  - `return_existing_if_match` boolean — If true, return existing patient with matching information (200 OK) instead of raising an error. If false, raise an error when a patient with matching information already exists (400 Bad Request). Matching is based on date of birth, name, and phone number.

## Response `200`

Successful

- APIV2EntitiesPatientsResponsesCreateResponse — API_V2_Entities_PatientsResponses_Create_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` APIV2EntitiesPatientsResponsesCreate
    - `user` APIV2EntitiesPatientBasic
      - `id` integer — User id
      - `email` string, nullable — User email
      - `first_name` string — First name
      - `middle_name` string, nullable — 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 updation date in UTC
      - `institution_id` integer — The institution this user belongs to
      - `foreign_id` string, nullable — Foreign Id is a unique identifier from the integrated system
      - `foreign_id_type` string — Foreign Id type is a unique string identifier for the integrated system
      - `bio` object — Patient biographical data, fields shown in our example response represent all possible data we retrieve but depending on system and what is actually saved in the health records system you cannot assume any field will consistently be returned
      - `inactive` boolean — Is the user inactivated?
      - `last_sync_time` string, date-time, nullable — The most recent time the resource's data changed meaningfully at the source
      - `guarantor_id` integer, nullable — User id of this patient's responsible party
      - `billing_type` string, nullable — 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, nullable — 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, nullable — Patient's preferred language as an ISO 639-1 code, if specified in the integrated system
      - `preferred_locale` string, nullable — The patient's preferred language setting used for displaying NexHealth forms and communications
      - `location_ids` integer[] — Array of location ids associated with the user
  - `count` integer — Number of total objects, in case of collection.

## Other responses

- `201` — Successful
- `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)