Sign in

v1

latestOpenAPI 3.1.02026-07-2218105157.9 KB
Patients

Upsert Patient (forgiving)

Forgiving upsert for integration partners. Normalizes phone / email / date_of_birth and silently drops unparseable values (reported via dropped_fields). Matches existing patients in priority: external_id → demographics → phone + fuzzy name → email + fuzzy name. Overwrites all provided non-null fields on match (except phone_number once first communication has occurred — that lock is respected and the field is silently dropped). When external_id is supplied, the returned patient is guaranteed to carry it: a pre-existing different value for that type is overwritten and the old→new transition is recorded in the patient activity log (visible in the History panel).

post/v1/patients/upsert

Request body

first_namestring nullable
last_namestring nullable
middle_namestring nullable
date_of_birthstring nullable

DOB in any of: YYYY-MM-DD, YYYYMMDD, MM/DD/YYYY, MM-DD-YYYY, MM/DD/YY. Unparseable values are dropped.

genderstring nullable
phone_numberstring nullable
additional_phone_numberstring nullable
emailstring nullable
addressstring nullable
address2string nullable
citystring nullable
statestring nullable
zipstring nullable
commentsstring nullable
workflow_stage_idstring nullable
assigned_user_idstring nullable
location_idstring nullable

Company location ID. Foreign IDs are dropped.

tagsstring[] nullable
custom_fieldsobject nullable
created_from'form' | 'call' | 'api' | 'file' | 'sms' | 'fax' | 'chat_agent' | 'manual' | 'bulk_import' | 'eligibility' | 'prior_auth'

Patient creation source enum matching Prisma

Response

Successful Response

matchedboolean required

True if an existing patient was found and updated

createdboolean required

True if a new patient was created

match_reason'external_id' | 'demographics' | 'phone_fuzzy_name' | 'email_fuzzy_name' nullable

Which match tier resolved the patient. None when created=True.

dropped_fieldsstring[]

Fields the request supplied that were silently dropped during normalization (unparseable phone/email/DOB, or external_id conflict, or phone-immutability lock).

Example response

{
  "patient": {
    "payors": [
      {
        "services": [
          {
            "copay_in_network": 25,
            "created_at": "2024-01-15T10:30:00Z",
            "eligibility_check_status": "ELIGIBLE",
            "id": "550e8400-e29b-41d4-a716-446655440014",
            "payor_id": "550e8400-e29b-41d4-a716-446655440012",
            "service_type": "PT",
            "updated_at": "2024-01-15T10:30:00Z",
            "verification_benefits_status": "VERIFIED"
          }
        ]
      }
    ]
  }
}