---
title: "Batch create/update patients"
method: POST
path: "/v1/patients/batch"
tags: ["Patient Batch"]
---

# Batch create/update patients

`POST /v1/patients/batch`

Create or update multiple patients in a single request. New patients are created all-or-nothing. Existing patients (matched by phone, email, or demographics) get non-null safe fields merged — identity fields are never overwritten.

## Request body

- PatientBatchCreateRequest — Request body for batch patient creation.
  - `items` PatientBatchItem[], required
    - `first_name` string, nullable — Patient's first name
    - `last_name` string, nullable — Patient's last name
    - `middle_name` string, nullable — Patient's middle name
    - `phone_number` string, nullable — Patient's phone number (optional if demographics provided)
    - `additional_phone_number` string, nullable — Patient's additional phone number
    - `email` string, nullable — Patient's email address
    - `date_of_birth` string, date, nullable — Patient's date of birth (YYYY-MM-DD, MM/DD/YYYY, YYYYMMDD)
    - `gender` 'male' | 'female' | 'other' — Gender enum matching Prisma
    - `address` string, nullable — Patient's street address
    - `address2` string, nullable — Patient's address line 2
    - `city` string, nullable — Patient's city
    - `state` 'alabama' | 'alaska' | 'arizona' | 'arkansas' | 'california' | 'colorado' | 'connecticut' | 'delaware' | 'florida' | 'georgia' | 'hawaii' | 'idaho' | 'illinois' | 'indiana' | 'iowa' | 'kansas' | 'kentucky' | 'louisiana' | 'maine' | 'maryland' | 'massachusetts' | 'michigan' | 'minnesota' | 'mississippi' | 'missouri' | 'montana' | 'nebraska' | 'nevada' | 'new_hampshire' | 'new_jersey' | 'new_mexico' | 'new_york' | 'north_carolina' | 'north_dakota' | 'ohio' | 'oklahoma' | 'oregon' | 'pennsylvania' | 'rhode_island' | 'south_carolina' | 'south_dakota' | 'tennessee' | 'texas' | 'utah' | 'vermont' | 'virginia' | 'washington' | 'west_virginia' | 'wisconsin' | 'wyoming' | 'district_of_columbia' | 'puerto_rico' | 'virgin_islands' | 'guam' | 'northern_mariana_islands' | 'american_samoa' — US States enum matching Prisma @map values
    - `zip` string, nullable — Patient's ZIP code
    - `comments` string, nullable — Patient comments
    - `workflow_stage_id` string, nullable — Workflow stage ID or stage name
    - `assigned_user_id` string, nullable — User ID or user email
    - `location_id` string, nullable — Company location ID
    - `organization_id` string, nullable — Company organization ID
    - `tags` string[], nullable — Tag IDs or tag names
    - `referral` ReferralCreateRequest — Nested referral creation for patient creation
      - `physician_name` string, nullable — Referring physician's name
      - `physician_email` string, nullable — Referring physician's email
      - `physician_phone` string, nullable — Referring physician's phone
      - `physician_fax` string, nullable — Referring physician's fax
      - `physician_group` string, nullable — Referring physician's group/practice
      - `physician_npi` string, nullable — Referring physician's National Provider Identifier
      - `physician_address` string, nullable — Referring physician's street address
      - `physician_address_2` string, nullable — Referring physician's address line 2
      - `physician_city` string, nullable — Referring physician's city
      - `physician_state` 'alabama' | 'alaska' | 'arizona' | 'arkansas' | 'california' | 'colorado' | 'connecticut' | 'delaware' | 'florida' | 'georgia' | 'hawaii' | 'idaho' | 'illinois' | 'indiana' | 'iowa' | 'kansas' | 'kentucky' | 'louisiana' | 'maine' | 'maryland' | 'massachusetts' | 'michigan' | 'minnesota' | 'mississippi' | 'missouri' | 'montana' | 'nebraska' | 'nevada' | 'new_hampshire' | 'new_jersey' | 'new_mexico' | 'new_york' | 'north_carolina' | 'north_dakota' | 'ohio' | 'oklahoma' | 'oregon' | 'pennsylvania' | 'rhode_island' | 'south_carolina' | 'south_dakota' | 'tennessee' | 'texas' | 'utah' | 'vermont' | 'virginia' | 'washington' | 'west_virginia' | 'wisconsin' | 'wyoming' | 'district_of_columbia' | 'puerto_rico' | 'virgin_islands' | 'guam' | 'northern_mariana_islands' | 'american_samoa' — US States enum matching Prisma @map values
      - `physician_zip` string, nullable — Referring physician's ZIP code
      - `icd_codes` string[], nullable — ICD diagnosis codes
      - `service_types` ServiceType[], nullable — Service types for the referral
      - `start_date` string, date, nullable — Referral start date (YYYY-MM-DD)
      - `end_date` string, date, nullable — Referral end date (YYYY-MM-DD)
      - `location_id` string, nullable — Company location ID
      - `file_id` string, nullable — Source file ID — set when the referral originates from a document extraction so the UI can link back to the file.
    - `payors` BatchPayorInline[], nullable — Payors with insurance name lookup
      - `insurance` string, required — Insurance name (resolved case-insensitively)
      - `insured_member_id` string, nullable — Member ID
      - `payor_responsibility` 'primary' | 'secondary' | 'tertiary' | 'quaternary', required — Insurance tier enum matching Prisma

## Response `200`

Successful Response

- PatientBatchCreateResponse — Response from batch patient creation/upsert.
  - `created_count` integer, required
  - `updated_count` integer
  - `patient_ids` string[], required
  - `updated_patient_ids` string[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/getsolum/apis/solum-health-api.md) · [All operations](https://skmtc.net/getsolum/apis/solum-health-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getsolum/solum-health-api/revisions/2bf886cdf729/schema)