The Patient Object

The Patient Object represents basic demographics data about a patient

Field Deprecation Warning

April 1st, 2026 is the last day of support for writing to insurances field. insurances will become read only on April 2nd, and all writes must go through the new insurance policies endpoints. Please see https://help.elationhealth.com/articles/rest/insurance-api/transitioning-from-patient-endpoints and the FAQ for more details.

Object Definition

{
  "id": 64184451073,                          // long(64)  read-only
  "first_name": "Paula",                      // string(70)  required for POST and PUT
  "middle_name": "P",                         // string(50)
  "last_name": "Patient",                     // string(70)  required for POST and PUT
  "actual_name": "Paul Patient",              // string(150) optional for POST or PUT
  "gender_identity": "woman",                 // ["unknown", "man", "woman", "transgender_man", "transgender_woman", "nonbinary", "option_not_listed", "prefer_not_to_say", "two_spirit"] optional for POST or PUT
  "legal_gender_marker": "F",                 // ["M", "F", "X", "U"] optional for POST or PUT
  "pronouns": "he_him_his",                   // ["he_him_his", "she_her_hers", "they_them_theirs", "not_listed"] optional for POST and PUT
  "sex": "Female",                            // ["Male", "Female", "Other", "Unknown"]  required for POST and PUT
  "sexual_orientation": "queer",              // ["unknown", "straight", "gay", "bisexual", "option_not_listed", "prefer_not_to_say", "lesbian", "queer", "asexual"] optional for POST or PUT
  "primary_physician": 131074,                // required for POST and PUT, see below
  "caregiver_practice": 65540,                // read-only. required for POST and PUT
  "dob": "1940-08-29",                        // date(YYYY-MM-DD)  required for POST and PUT
  "ssn": "123456789",                         // integer(9 digits)
  "race": "Asian",                            // see below
  "preferred_language": "English",            // see below
  "preferred_contact": "email",               // ["sms", "email", "phone", "passport"] optional for POST and PUT
  "ethnicity": "Not Hispanic or Latino",      // see below
  "notes": "This is test Notes",              // string(500)
  "sms_opt_in_status": false,                 // boolean read-only
  "vip": false,								  // feature must be enabled for practice
  "address": {
    "address_line1": "2093 Philadelphia Pike", // string(200)
    "address_line2": "#2541",                 // string(35)
    "city": "Claymont",                       // string(50)
    "state": "DE",                            // string(2)
    "zip": "19703"                            // integer(9 digits)
  },
  "phones": [                                 // list of objects. max 2 phones
    {
      "phone": "4155555555",                  // string(20)
      "phone_type": "Home",                   // see below
      "created_date": "2016-10-10T23:31:49",  // datetime(iso8601)  read-only
      "deleted_date": null                    // datetime(iso8601)  read-only
    }
  ],
  "emails": [                                 // list of objects. only 1 email with empty deleted_date
    {
      "email": "paul.patient@elationemr.com",  // string(75)
      "created_date": "2016-10-10T23:31:49",  // datetime(iso8601)  read-only
      "deleted_date": null                    // datetime(iso8601)  read-only
    }
  ],
  "guarantor": {
      "id": 123456789,
      "address": "101 Lane Street",
      "city": "Madison",
      "state": "WI",
      "zip": "53711",
      "phone": "1231231233",
      "email": "other@email.com",
      "relationship": "Other",								// {"Spouse", "Child", "Other"}
      "first_name": "Other",
      "last_name": "Test",
      "middle_name": null
    },
  "insurances": [                             // list of objects. max 2 insurances
    {
      "id": 140767609356371,
      "insurance_company": 70970048878,       // from Insurance Company resource
      "insurance_plan": 70971687279,          // from Insurance Plan resource
      "rank": "primary",                      // ["primary", "secondary", "tertiary"]
      "carrier": "Blue Cross",                // string(200)
      "member_id": "test_member_id",          // string(50)
      "group_id": "test_group_id",            // string(50)
      "plan": "Blue Cross Blue Shield",       // string(200)
      "phone": "",                            // string(20)
      "extension": "",                        // string(6)
      "address": "123 medicare st",           // string(200)
      "suite": null,                          // string(35)
      "city": "Claymont",                     // string(50)
      "state": "DE",                          // string(2)
      "zip": "19703",                         // integer(9 digits)
      "copay": null,                          // decimal
      "deductible": null,                     // decimal
      "payment_program": "Commercial - Other",	// ["Medicare Part B", "Medicare Advantage", "Medicaid", "Commercial - HMSA", "Commercial - SFHP", "Commercial - Other", "Worker's Compensation"]
      "insured_person_first_name": "Paula",   // string(200)
      "insured_person_last_name": "Patient",  // string(200)
      "insured_person_address": "2093 Philadelphia Pike",// string(200)
      "insured_person_city": "Claymont",      // string(50)
      "insured_person_state": "DE",           // string(2)
      "insured_person_zip": "19703",          // integer(9 digits)
      "insured_person_id": "12345",           // string(50)
      "insured_person_dob": "08/29/1940",     // string(50)
      "insured_person_gender": "F",           // ["M", "F", "N"]
      "insured_person_ssn": "123456789",      // integer(9 digits)
      "relationship_to_insured": null,        // string(20)
      "created_date": "2020-05-12T22:52:25Z", // datetime(iso8601). read-only
      "deleted_date": null,                   // datetime(iso8601). read-only
      "start_date": null,                     // date(YYYY-MM-DD)
      "end_date": null,                       // date(YYYY-MM-DD)
    }
  ],
  "deleted_insurances": [                    // list of objects, max 5 deleted insurances
    {
      "id": 140745403531347,
      "insurance_company": 140744693383534,   // from Insurance Company resource
      "insurance_plan": 140745403466095,      // from Insurance Plan resource
      "rank": "secondary",                    // ["primary", "secondary", "tertiary"]
      "carrier": "PBMX",                      // string(200)
      "member_id": "test_member_id",          // string(50)
      "group_id": "test_group_id",            // string(50)
      "plan": "PBMX Test Plan",               // string(200)
      "phone": "",                            // string(20)
      "extension": "",                        // string(6)
      "address": "",                          // string(200)
      "suite": null,                          // string(35)
      "city": "Claymont",                     // string(50)
      "state": "DE",                          // string(2)
      "zip": "19703",                         // integer(9 digits)
      "copay": null,                          // decimal
      "deductible": null,                     // decimal
      "payment_program": "Commercial - Other",	// ["Medicare Part B", "Medicare Advantage", "Medicaid", "Commercial - HMSA", "Commercial - SFHP", "Commercial - Other", "Worker's Compensation"]
      "insured_person_first_name": "Paula",   // string(200)
      "insured_person_last_name": "Patient",  // string(200)
      "insured_person_address": "2093 Philadelphia Pike",// string(200)
      "insured_person_city": "Claymont",      // string(50)
      "insured_person_state": "DE",           // string(2)
      "insured_person_zip": "19703",          // integer(9 digits)
      "insured_person_id": "12345",           // string(50)
      "insured_person_dob": "08/29/1940",     // string(50)
      "insured_person_gender": "F",           // ["M", "F"]
      "insured_person_ssn": "123456789",      // integer(9 digits)
      "relationship_to_insured": null,        // string(20)
      "created_date": "2020-05-12T22:52:25Z", // datetime(iso8601). read-only
      "deleted_date": "2021-04-28T10:50:22Z", // datetime(iso8601). read-only
      "start_date": null,                     // date(YYYY-MM-DD)
      "end_date": null,                       // date(YYYY-MM-DD)
    }
   ],
  "tags": [                                   // list of string(100), max 10 tags
    "PAID",
    "Test Patient"
  ],
  "patient_status": {
     "deceased_date": "2023-02-23",                   // date("YYYY-MM-DD")
    "inactive_reason": null,                 // ["other", "patient left on bad terms", "patient left on good terms", "practice ended relationship", "unknown"]
    "last_status_change": "2022-08-24T13:03:05", // datetime(iso8601). read-only
    "notes": "my notes",                     // string
    "status": "active"                       // ["active", "deceased", "inactive", "prospect"]
   },
  "preference": {
    "preferred_pharmacy_1": null,             // ncpdpid. See "Pharmacy API"
    "preferred_pharmacy_2": null
  },
  "emergency_contact": {
    "first_name": "John",                     // string(70)
    "last_name": "Doe",                       // string(70)
    "relationship": "Child",                  // string(30)
    "phone": "4151231234",                    // string(20)
    "address_line1": "19 test ave",           // string(200)
    "address_line2": "#12",                   // string(35)
    "city": "Claymont",                       // string(50)
    "state": "DE",                            // string(2)
    "zip": "123456789"                        // string(10)
  },
  "primary_care_provider": 131074,            // read-only, see below
  "primary_care_provider_npi": "1234567893",  // string(10), see below
  "previous_first_name": null,                // DEPRECATED; use previous_name object
  "previous_last_name": null,                 // DEPRECATED; use previous_name object
  "previous_name": {
    "first_name": "Petunia",                  // string(70)
    "middle_name": "Penny",                   // string(50)
    "last_name": "Smith",                     // string(70)
    "suffix": ""                              // string(20)
  },
  "master_patient": null,
  "employer": {                               // employer field is enterprise use only
    "code": "EMP_1",
    "name": "Employer Name 1",
    "description": "Employer Description 1"
  },
  "consents": [                               // list of objects, no max, read-only
    {
     "consented": true,                            // boolean
     "last_modified_date": "2016-05-02T11:57:41Z", // datetime(iso8601)
     "application": "healthix",                    // string(255)
    }
  ],
  "metadata": null,
  "created_date": "2016-05-02T11:57:41Z",     // datetime(iso8601)  read-only
  "deleted_date": null,                       // datetime(iso8601)  read-only
  "merged_into_chart": null,                  // long(64)  read-only
  "verified": true                            // boolean
}

Allowed Values

Attribute	Allowed Values
race	”No race specified”, “American Indian or Alaska Native”, “Asian”, “Black or African American”, “Native Hawaiian or Other Pacific Islander”, “White”, “Declined to specify”
ethnicity	”No ethnicity specified”, “Hispanic or Latino”, “Not Hispanic or Latino”, “Declined to specify”
patient_status.inactive_reason	”other”, “left_bad_terms”, “left_good_terms”, “practice_ended”, “unknown” - can only be provided if `patient_status.status = inactive`
patient_status.status	”active”, “deceased”, “inactive”, “prospect”
preferred_language	See Language resources
phones[].phone_type	”Mobile”, “Home”, “Main”, “Work”, “Night”, “Fax”, “Other”
emergency_contact.relationship	”Caregiver”, “Child”, “Friend”, “Grandparent”, “Guardian”, “Parent”, “Sibling”, “Spouse”, “Other”

Preventing Duplicate Patients

When you create a patient, Elation checks first_name, last_name, dob, and sex against existing patients in the practice. If all four match an existing patient, the request returns a 409 Conflict instead of creating a new chart, to prevent accidental duplicates. Two different patients can occasionally share all four of these fields. This safeguard can’t be bypassed through the API — if you’ve confirmed the patient you’re creating is not a duplicate of the existing match, create the chart manually in the Elation web UI instead (which allows it), then query or pull the new patient’s profile to retrieve their generated id and use that going forward via the API.

Setting Patient Providers

primary_physician represents the physician providing care to the patient within your practice. This is a required field. This value must match the id of one of the physicians retrieved via the Find Physicians endpoint. primary_care_provider_npi represents the patient’s primary care provider. This person may be in a different practice. This field is not required. primary_care_provider is a read-only field that provides the internal Elation id of the collaborator record that is created within your practice to represent your practice’s connection with the patient’s primary care provider.

Working with patients via the API

A patient’s metadata.object_web_link appears as a link in the patient chart. Practice users see it on the patient’s profile, labeled with your application’s vendor name and using metadata.object_id as the link text, while your application is active for the practice. The link opens the URL in a new tab exactly as stored. Include your own patient identifier in the URL so the link opens the matching record in your application. See Metadata for the field format.

API Reference

REST API

FHIR API

HL7 Interface

Field Deprecation Warning

Object Definition

Allowed Values

Preventing Duplicate Patients

Setting Patient Providers

Working with patients via the API

​Field Deprecation Warning

​Object Definition

​Allowed Values

​Preventing Duplicate Patients

​Setting Patient Providers

​Working with patients via the API

Field Deprecation Warning

Object Definition

Allowed Values

Preventing Duplicate Patients

Setting Patient Providers

Working with patients via the API