Patient

The Patient feature allows the user to add and view patient details. The Patient Gender Identity Reference feature allows the user to view the list of valid gender identity fields that are configured for this practice. The Patient Changed Subscription feature will allow the user to retrieve changes made to patient details (generally new or updated). The user will need to subscribe for these endpoints. For more information about subscriptions, please refer Changed Data Subscriptions.

The patient creation API, POST /patients, requires the following fields:
First Name
Last Name
Date of Birth (DOB)
Department

At least one of the following fields must also be provided:
Email
Guarantor Email
SSN
Home Phone
Mobile Phone
Work Phone
ZIP Code

When POST call is made, the logic first verifies that all necessary fields are provided and validates DOB field(s). Then, the logic uses bestmatch to check if an existing patient matches given data. If a match is found, the patient ID of the matched patient is returned. Only when there is no match will a new patient  be created and the patient ID returned. 

Prior to the POST call, we recommend making a call to our enhancedbestmatch endpoint to check for existing patient records. This endpoint has superior patient matching logic to the bestmatch check that is built into the POST endpoint, reducing the chances of a duplicate. Enhancedbestmatch also offers additional inputs related to upcoming appointments and thus provides a better search in scenarios where a new patient entry is being created just before an appointment.

Paperless statements (e-statements) are a simple and effective way to receive, manage, and keep records of patients’ billing information online while reducing environmental impact. 

The e-statement flag is set with the 'onlinestatementonly' parameter in the PUT and POST/patients/API call.

This API is intended for use in applications used by providers, practice staff, or entities that have a signed BAA with a practice. Due to the risk of exposing PHI, this API cannot be utilized in patient-facing applications. 

The GET/Patients/Search API allows partners to provide users of their application a workflow that replicates the patient search functionality in athenaNet. With this API, users can search for patients with either a partial last name, or with a partial last name and partial first name. Note: This API returns all matching patients for the user provided search criteria, and partners need to have a screen in their applications UI to allow the user to select the correct patient from the list returned by the API. 

Using the Patient/Search API
If searching for a patient with a partial last name: 
The user must provide a minimum of two characters of a patient’s last name to search for a patient. The more characters provided in the search criterion, the more the search is able to narrow down the list of possible patients that the user is looking for. 
Or 
If searching for a patient with a partial last name and partial first name: 
The user must provide a minimum of two characters of a patient’s last name, and two characters of the patient’s first name. The more characters provided in the search criteria, the more the search is able to narrow down the list of possible patients that the user is looking for. 

For partners utilizing the Patients/Search API for patient lookup, remember that your API key has a limit of 100 queries per second (in production; lower on preview). Should your API key exceed the limit, you'll receive a 403 error that indicates a QPS violation. If you receive this 403 QPS violation error, your key will be free to make more calls in the subsequent second. 

To prevent this QPS violation athenahealth suggests you use the following best practices: 
•  Build a time delay into your application to only call the API if you detect a user has stopped typing for a set amount of time. 
•  If your application is waiting on a response from the API, do not call the API again when a user has typed in an additional character in either the first or last name of the patient. 
•  Wait until you receive the first response before calling the API again.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit

Endpoints

Create new patient record
POST
/v1/{practiceid}/patients

Add a new patient record in the system Note: This endpoint may rely on specific settings to be enabled in athenaNet Production to function properly that are not required in other environments. Please see <a href="https://docs.athenahealth.com/api/resources/best-practices-and-troubles… Rollout of APIs</a> for more information if you are experiencing issues.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
Content-Type string Content type of the payload

❙ Request Body

Expand all
address1 string Patient's address - 1st line (Max length: 100)
address2 string Patient's address - 2nd line (Max length: 100)
agriculturalworker string Used to identify this patient as an agricultural worker. Only settable if client has Social Determinant fields turned on.
agriculturalworkertype string For patients that are agricultural workers, identifies the type of worker. Only settable if client has Social Determinant fields turned on.
altfirstname string Alternate first name that differs from legal name. (Max length: 20)
assignedsexatbirth string Sex that this patient was assigned at birth. (Max length: 20)
caresummarydeliverypreference string The patient's preference for care summary delivery.
city string Patient's city (Max length: 30)
clinicalordertypegroupid string The clinical order type group of the clinical provider (Prescription: 10, Lab: 11, Vaccinations: 16).
consenttocall boolean The flag is used to record the consent of a patient to receive automated calls per FCC requirements. The requested legal language is 'Entry of any telephone contact number constitutes written consent to receive any automated, prerecorded, and artificial voice telephone calls initiated by the Practice. To alter or revoke this consent, visit the Patient Portal "Contact Preferences" page.'
consenttotext boolean The flag is used to record the consent of a patient to receive text messages per FCC requirements. In order for this to be true, a valid mobile phone number must be set and the practice setting "Hide SMS Opt-in option" must be set to Off.
contacthomephone string Emergency contact home phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactmobilephone string Emergency contact mobile phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactname string The name of the (emergency) person to contact about the patient. The contactname, contactrelationship, contacthomephone, and contactmobilephone fields are all related to the emergency contact for the patient. They are NOT related to the contractpreference_* fields. (Max length: 20)
contactpreference string The MU-required field for "preferred contact method". This is not used by any automated systems.
contactpreference_announcement_email boolean If set, the patient has indicated a preference to get or not get "announcement" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_announcement_phone boolean If set, the patient has indicated a preference to get or not get "announcement" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_announcement_sms boolean If set, the patient has indicated a preference to get or not get "announcement" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_appointment_email boolean If set, the patient has indicated a preference to get or not get "appointment" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_appointment_phone boolean If set, the patient has indicated a preference to get or not get "appointment" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_appointment_sms boolean If set, the patient has indicated a preference to get or not get "appointment" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_billing_email boolean If set, the patient has indicated a preference to get or not get "billing" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_billing_phone boolean If set, the patient has indicated a preference to get or not get "billing" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_billing_sms boolean If set, the patient has indicated a preference to get or not get "billing" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_lab_email boolean If set, the patient has indicated a preference to get or not get "lab" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_lab_phone boolean If set, the patient has indicated a preference to get or not get "lab" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_lab_sms boolean If set, the patient has indicated a preference to get or not get "lab" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactrelationship string Emergency contact relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
countrycode3166 string Patient's country code (ISO 3166-1) (Max length: 20)
deceaseddate string If present, the date on which a patient died.
defaultpharmacyncpdpid string The NCPDP ID of the patient's preferred pharmacy. See http://www.ncpdp.org/ for details. Note: if updating this field, please make sure to have a CLINICALORDERTYPEGROUPID field as well.
departmentid integer Primary (registration) department ID.
dob string Patient's DOB (mm/dd/yyyy)
donotcallyn boolean Warning! This patient will not receive any communication from the practice if this field is set to true. This field should only be used if you are absolutely certain that's what you want to do.
driverslicenseexpirationdate string The expiration date of the patient's driver's license.
driverslicensenumber string The number of the patient's driver's license (Max length: 20)
driverslicensestateid string The state of the patient's driver's license. This is in the form of a 2 letter state code.
email string Patient's email address. 'declined' can be used to indicate just that.
employerid integer The patient's employer's ID (from /employers call)
employerphone string The patient's employer's phone number. Normally, this is set by setting employerid. However, setting this value can be used to override this on an individual patient. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
ethnicitycode string Ethnicity of the patient, using the 2.16.840.1.113883.5.50 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer.
firstname string Patient's first name (Max length: 20)
genderidentity string Gender with which this patient identifies. To see the available options for this input, please see GET /configuration/patients/genderidentity?show2015edcehrtvalues=true (Max length: 20)
genderidentityother string Only valid when used in conjunction with a gender identity choice that allows the patient to describe their identity (if it doesn't conform to any other choice). (Max length: 20)
guarantoraddress1 string Guarantor's address (Max length: 100)
guarantoraddress2 string Guarantor's address - line 2 (Max length: 100)
guarantoraddresssameaspatient boolean If set, the address of the guarantor is the same as the patient.
guarantorcity string Guarantor's city (Max length: 30)
guarantorcountrycode3166 string Guarantor's country code (ISO 3166-1) (Max length: 20)
guarantordob string Guarantor's DOB (mm/dd/yyyy)
guarantoremail string Guarantor's email address
guarantoremployerid integer The guaranror's employer's ID (from /employers call)
guarantorfirstname string Guarantor's first name (Max length: 20)
guarantorlastname string Guarantor's last name (Max length: 20)
guarantormiddlename string Guarantor's middle name (Max length: 20)
guarantorphone string Guarantor's phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
guarantorrelationshiptopatient string The guarantor's relationship to the patient
guarantorssn string Guarantor's SSN
guarantorstate string Guarantor's state (2 letter abbreviation)
guarantorsuffix string Guarantor's name suffix (Max length: 20)
guarantorzip string Guarantor's zip
guardianfirstname string The first name of the patient's guardian.
guardianlastname string The last name of the patient's guardian.
guardianmiddlename string The middle name of the patient's guardian.
guardiansuffix string The suffix of the patient's guardian.
hasmobileyn boolean Set to false if a client has declined a phone number.
homeboundyn boolean If the patient is homebound, this is true.
homeless string Used to identify this patient as homeless. Only settable if client has Social Determinant fields turned on.
homelesstype string For patients that are homeless, provides more detail regarding the patient's homeless situation. Only settable if client has Social Determinant fields turned on.
homephone string The patient's home phone number. Invalid numbers in a GET will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Only phone numbers that exist in the North American Naming Plan (NANP) are acceptable for input.
ignorerestrictions boolean Set to true to allow ability to find patients with record restrictions and blocked patients. This should only be used when there is no reflection to the patient at all that a match was found or not found.
industrycode string Industry of the patient, using the US Census industry code (code system 2.16.840.1.113883.6.310). "other" can be used as well.
language6392code string Language of the patient, using the ISO 639.2 code. (http://www.loc.gov/standards/iso639-2/php/code_list.php; "T" or terminology code) Special case: use "declined" to indicate that the patient declined to answer.
lastname string Patient's last name (Max length: 20)
maritalstatus string Marital Status (D=Divorced, M=Married, S=Single, U=Unknown, W=Widowed, X=Separated, P=Partner)
middlename string Patient's middle name (Max length: 20)
mobilecarrierid string The ID of the mobile carrier, from /mobilecarriers or the list below.
mobilephone string The patient's mobile phone number. On input, 'declined' can be used to indicate no number. (Alternatively, hasmobile can also be set to false. "declined" simply does this for you.) Invalid numbers in a GET will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Only phone numbers that exist in the North American Naming Plan (NANP) are acceptable for input.
nextkinname string The full name of the next of kin.
nextkinphone string The next of kin phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
nextkinrelationship string The next of kin relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
notes string Notes associated with this patient.
occupationcode string Occupation of the patient, using the US Census occupation code (code system 2.16.840.1.113883.6.240). "other" can be used as well.
onlinestatementonlyyn boolean Set to true if a patient wishes to get e-statements instead of paper statements. Should only be set for patients with an email address and clients with athenaCommunicator. The language we use in the portal is, "Future billing statements will be sent to you securely via your Patient Portal account. You will receive an email notice when new statements are available." This language is not required, but it is given as a suggestion.
portalaccessgiven boolean This flag is set if the patient has been given access to the portal. This may be set by the API user if a patient has been given access to the portal "by providing a preprinted brochure or flyer showing the URL where patients can access their Patient Care Summaries." The practiceinfo endpoint can provide the portal URL. While technically allowed, it would be very unusual to set this to false via the API.
povertylevelcalculated number Patient's poverty level (% of the Federal Poverty Level), as calculated from family size, income per pay period, pay period, and state. Typically only valued if client has Federal Poverty Level fields turned on.
povertylevelfamilysize number Patient's family size (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelfamilysizedeclined boolean Indicates if the patient delcines to provide "povertylevelfamilysize". Should be set to Yes if the patient declines.
povertylevelincomedeclined boolean Indicates if the patient delcines to provide "povertylevelincomeperpayperiod". Should be set to Yes if the patient declines.
povertylevelincomepayperiod string Patient's pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomeperpayperiod integer Patient's income per specified pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomerangedeclined boolean Indicates whether or not the patient declines to provide an income level (povertylevelcalculated).
preferredname string The patient's preferred name (i.e. nickname).
preferredpronouns string Pronoun this patient uses. (Max length: 20)
primarydepartmentid string The patient's "current" department. This field is not always set by the practice.
primaryproviderid string The "primary" provider for this patient, if set.
publichousing string Used to identify this patient as living in public housing. Only settable if client has Social Determinant fields turned on.
race string The patient race, using the 2.16.840.1.113883.5.104 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer. Multiple values or a tab-seperated list of codes is acceptable for multiple races for input. The first race will be considered "primary". Note: you must update all values at once if you update any.
referralsourceid string The referral / "how did you hear about us" ID.
referralsourceother string If selecting "other" for referral source, this is the text field that can be filled out. (Max length: 20)
schoolbasedhealthcenter string Used to identify this patient as school-based health center patient. Only settable if client has Social Determinant fields turned on.
sex string Patient's sex (M/F)
sexualorientation string Sexual orientation of this patient. (Max length: 20)
sexualorientationother string Only valid when used in conjunction with a sexual orientation choice that allows the patient to describe their orientation (if it doesn't conform to any other choice). (Max length: 20)
showerrormessage boolean If set to true returns error message on patient match (Defaults to false).
ssn string
state string Patient's state (2 letter abbreviation)
status string The "status" of the patient, one of active, inactive, prospective, or deleted.
suffix string Patient's name suffix (Max length: 20)
veteran string Used to identify this patient as a veteran. Only settable if client has Social Determinant fields turned on.
workphone string The patient's work phone number. Generally not used to contact a patient. Invalid numbers in a GET will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Only phone numbers that exist in the North American Naming Plan (NANP) are acceptable for input.
zip string Patient's zip. Matching occurs on first 5 characters.

Output Parameters

Expand all
errormessage string Error message will be returned if show error message flag is set to true and patient match found.
patientid string Please remember to never disclose this ID to patients since it may result in inadvertant disclosure that a patient exists in a practice already.
Example Code
Get specific patient record
GET
/v1/{practiceid}/patients/{patientid}

Retrieves data of a specific patient Note: This endpoint may rely on specific settings to be enabled in athenaNet Production to function properly that are not required in other environments. Please see <a href="https://docs.athenahealth.com/api/resources/best-practices-and-troubles… Rollout of APIs</a> for more information if you are experiencing issues.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
patientid integer patientid
showallpatientdepartmentstatus boolean Include an array of all departments the patient is a part of along with all statuses for those departments.
showfullssn boolean If set, will show full SSN instead of a masked number.
showlocalpatientid boolean If set, will show local patient id.
checkuseraccess boolean If set, validate that the session user has access to the patient record. May only be used in conjunction with INTERNALUSE and SESSIONUSER, and DEPARTMENTID. DEPARTMENTID is required because user access is department-specific. If the user does not have access to the patient record, returns a 403 error.
limitlocalpatientid boolean If set, will return local patient id tied to the passed in DepartmentID.
showinsurance boolean Include patient insurance information.
showportalstatus boolean If set, will include portal enrollment status in response.
showbalancedetails boolean Show detailed information on patient balances.
ignorerestrictions boolean Set to true to allow ability to find patients with record restrictions and blocked patients. This should only be used when there is no reflection to the patient at all that a match was found or not found.
showpreviouspatientids boolean If set, will show the previous patient ID this patient was merged from.
showallclaims boolean Include information on claims where there is no outstanding patient balance. (Only to be used when showbalancedetails is selected.)
departmentid integer This is the ID for the department of the patient you are retrieving. If you are calling this on an enterprise practice with multiple financial groups (also called "provider groups"), this will ensure you are retrieving the correct patient and not a copy that is in a different department.
show2015edcehrtvalues boolean Use 2015 Ed. CEHRT compliant strings for describing gender identity and sexual orientation.
showcustomfields boolean Include custom fields for the patient.
THIRDPARTYUSERNAME string User name of the patient in the third party application.
PATIENTFACINGCALL boolean When 'true' is passed we will collect relevant data and store in our database.

Output Parameters

Expand all
address1 string Patient's address - 1st line
address2 string Patient's address - 2nd line
agriculturalworker string Used to identify this patient as an agricultural worker. Only settable if client has Social Determinant fields turned on.
agriculturalworkertype string For patients that are agricultural workers, identifies the type of worker. Only settable if client has Social Determinant fields turned on.
allpatientstatuses array
altfirstname string Alternate first name that differs from legal name.
assignedsexatbirth string Sex that this patient was assigned at birth.
balances array List of balances owed by the patient, broken down by provider (financial) group.
caresummarydeliverypreference string The patient's preference for care summary delivery.
city string Patient's city
claimbalancedetails array Claim level details on patient balances. (This is only included when SHOWBALANCEDETAILS is set.)
confidentialitycode string Gives the confidentiality code for the patient. Only returned when IGNORERESTRICTIONS is set to true and COLCR_RETURN_CONFIDENTIALITY_CODE is ON
consenttocall string The flag is used to record the consent of a patient to receive automated calls per FCC requirements. The requested legal language is 'Entry of any telephone contact number constitutes written consent to receive any automated, prerecorded, and artificial voice telephone calls initiated by the Practice. To alter or revoke this consent, visit the Patient Portal "Contact Preferences" page.'
consenttotext string The flag is used to record the consent of a patient to receive text messages per FCC requirements. In order for this to be true, a valid mobile phone number must be set and the practice setting "Hide SMS Opt-in option" must be set to Off.
contacthomephone string Emergency contact home phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactmobilephone string Emergency contact mobile phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactname string The name of the (emergency) person to contact about the patient. The contactname, contactrelationship, contacthomephone, and contactmobilephone fields are all related to the emergency contact for the patient. They are NOT related to the contractpreference_* fields.
contactpreference string The MU-required field for "preferred contact method". This is not used by any automated systems.
contactpreference_announcement_email string If set, the patient has indicated a preference to get or not get "announcement" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_announcement_phone string If set, the patient has indicated a preference to get or not get "announcement" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_announcement_sms string If set, the patient has indicated a preference to get or not get "announcement" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_appointment_email string If set, the patient has indicated a preference to get or not get "appointment" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_appointment_phone string If set, the patient has indicated a preference to get or not get "appointment" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_appointment_sms string If set, the patient has indicated a preference to get or not get "appointment" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_billing_email string If set, the patient has indicated a preference to get or not get "billing" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_billing_phone string If set, the patient has indicated a preference to get or not get "billing" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_billing_sms string If set, the patient has indicated a preference to get or not get "billing" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_lab_email string If set, the patient has indicated a preference to get or not get "lab" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_lab_phone string If set, the patient has indicated a preference to get or not get "lab" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_lab_sms string If set, the patient has indicated a preference to get or not get "lab" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactrelationship string Emergency contact relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
countrycode string Patient's country code
countrycode3166 string Patient's country code (ISO 3166-1)
customfields array Same as /patients/{patientid}/customfields call, but without the department ID. Depending on setup, and only in large practices, the custom field values may or may not be the same between departments. If this is a concern, using the /patients/{patientid}/customfields call is preferred. Only for a single patient when showcustomfields is set to true.
deceaseddate string If present, the date on which a patient died.
defaultpharmacyncpdpid string The NCPDP ID of the patient's preferred pharmacy. See http://www.ncpdp.org/ for details. Note: if updating this field, please make sure to have a CLINICALORDERTYPEGROUPID field as well.
departmentid string Primary (registration) department ID.
dob string Patient's DOB (mm/dd/yyyy)
donotcallyn string Warning! This patient will not receive any communication from the practice if this field is set to true.
driverslicenseexpirationdate string The expiration date of the patient's driver's license.
driverslicensenumber string The number of the patient's driver's license
driverslicensestateid string The state of the patient's driver's license. This is in the form of a 2 letter state code.
driverslicenseurl string The URL to the patient's driver's license
driverslicenseyn string True if the patient has a driver's license uploaded
email string Patient's email address. 'declined' can be used to indicate just that.
emailexistsyn string True if email exists. False if patient declined. Null if status is unknown.
employeraddress string The patient's employer's address.
employercity string The patient's employer's city.
employerfax string The patient's employer's fax.
employerid string The patient's employer's ID (from /employers call)
employername string The patient's employer's name.
employerphone string The patient's employer's phone number. Normally, this is set by setting employerid. However, setting this value can be used to override this on an individual patient. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
employerstate string The patient's employer's state.
employerzip string The patient's employer's zip.
ethnicitycode string Ethnicity of the patient, using the 2.16.840.1.113883.5.50 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer.
firstappointment string The first appointment for this patient, excluding cancelled or no-show appointments. (mm/dd/yyyy h24:mi)
firstname string Patient's first name
genderidentity string Gender with which this patient identifies.
genderidentityother string If a patient does not identify with any prescribed gender identity choice, this field stores the patient-provided description of gender identity.
guarantoraddress1 string Guarantor's address
guarantoraddress2 string Guarantor's address - line 2
guarantoraddresssameaspatient string The address of the guarantor is the same as the patient.
guarantorcity string Guarantor's city
guarantorcountrycode string Guarantor's country code
guarantorcountrycode3166 string Guarantor's country code (ISO 3166-1)
guarantordob string Guarantor's DOB (mm/dd/yyyy)
guarantoremail string Guarantor's email address
guarantoremployerid string The guaranror's employer's ID (from /employers call)
guarantorfirstname string Guarantor's first name
guarantorlastname string Guarantor's last name
guarantormiddlename string Guarantor's middle name
guarantorphone string Guarantor's phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
guarantorrelationshiptopatient string The guarantor's relationship to the patient
guarantorssn string Guarantor's SSN
guarantorstate string Guarantor's state (2 letter abbreviation)
guarantorsuffix string Guarantor's name suffix
guarantorzip string Guarantor's zip
guardianfirstname string The first name of the patient's guardian.
guardianlastname string The last name of the patient's guardian.
guardianmiddlename string The middle name of the patient's guardian.
guardiansuffix string The suffix of the patient's guardian.
hasmobileyn string Set to false if a client has declined a phone number.
homeboundyn string If the patient is homebound, this is true.
homeless string Used to identify this patient as homeless. Only settable if client has Social Determinant fields turned on.
homelesstype string For patients that are homeless, provides more detail regarding the patient's homeless situation. Only settable if client has Social Determinant fields turned on.
homephone string The patient's home phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
industrycode string Industry of the patient, using the US Census industry code (code system 2.16.840.1.113883.6.310). "other" can be used as well.
insurances array List of active patient insurance packages. Only shown for a single patient and if SHOWINSURANCE is set.
language6392code string Language of the patient, using the ISO 639.2 code. (http://www.loc.gov/standards/iso639-2/php/code_list.php; "T" or terminology code) Special case: use "declined" to indicate that the patient declined to answer.
lastappointment string The last appointment for this patient (before today), excluding cancelled or no-show appointments. (mm/dd/yyyy h24:mi)
lastemail string The last email for this patient on file.
lastname string Patient's last name
localpatientid string 'Given showlocalpatientid is true, comma separated local patient id will be returned, if patient id is enterprise id else given patient id will be displayed.'
maritalstatus string Marital Status (D=Divorced, M=Married, S=Single, U=Unknown, W=Widowed, X=Separated, P=Partner)
maritalstatusname string The long version of the marital status.
medicationhistoryconsentverified string Medication history consent status. If a practice doesn't have RXHub or Surescripts enabled, this will be null
middlename string Patient's middle name
mobilecarrierid string The ID of the mobile carrier, from /mobilecarriers or the list below.
mobilephone string The patient's mobile phone number. On input, 'declined' can be used to indicate no number. (Alternatively, hasmobile can also be set to false. "declined" simply does this for you.) Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
nextkinname string The full name of the next of kin.
nextkinphone string The next of kin phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
nextkinrelationship string The next of kin relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
notes string Notes associated with this patient.
occupationcode string Occupation of the patient, using the US Census occupation code (code system 2.16.840.1.113883.6.240). "other" can be used as well.
onlinestatementonlyyn string Set to true if a patient wishes to get e-statements instead of paper statements. Should only be set for patients with an email address and clients with athenaCommunicator. The language we use in the portal is, "Future billing statements will be sent to you securely via your Patient Portal account. You will receive an email notice when new statements are available." This language is not required, but it is given as a suggestion.
patientid string Please remember to never disclose this ID to patients since it may result in inadvertant disclosure that a patient exists in a practice already.
patientphotourl string The URL to the patient photo
patientphotoyn string True if the patient has a photo uploaded
portalaccessgiven string This flag is set if the patient has been given access to the portal. This may be set by the API user if a patient has been given access to the portal "by providing a preprinted brochure or flyer showing the URL where patients can access their Patient Care Summaries." The practiceinfo endpoint can provide the portal URL. While technically allowed, it would be very unusual to set this to false via the API.
portalsignatureonfile string This flag is set if the patient's signature is on file
portalstatus array Portal status details. See /patients/{patientid}/portalstatus for details.
portaltermsonfile string Flag determining whether or not the patient has accepted the Terms and Conditions for the patient portal.
povertylevelcalculated integer Patient's poverty level (% of the Federal Poverty Level), as calculated from family size, income per pay period, pay period, and state. Typically only valued if client has Federal Poverty Level fields turned on.
povertylevelfamilysize string Patient's family size (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelfamilysizedeclined string Indicates if the patient delcines to provide "povertylevelfamilysize". Should be set to Yes if the patient declines.
povertylevelincomedeclined string Indicates if the patient delcines to provide "povertylevelincomeperpayperiod". Should be set to Yes if the patient declines.
povertylevelincomepayperiod string Patient's pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomeperpayperiod string Patient's income per specified pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomerangedeclined string Indicates if the patient declines to provide an income range level. True if the patient declines.
preferredname string The patient's preferred name (i.e. nickname).
preferredpronouns string Pronoun this patient uses.
previouspatientids array The IDs of the patient this one was merged from.
primarydepartmentid string The patient's "current" department. This field is not always set by the practice.
primaryproviderid string The "primary" provider for this patient, if set.
privacyinformationverified string This flag is set if the patient's privacy information has been verified. Privacy information returns True if all of the items referenced in GET /patients/{patientid}/privacyinformationverified are true. Privacy information returns false if any of the items referenced in the GET /patients/{patientid}/privacyinformationverified API are false or expired.
publichousing string Used to identify this patient as living in public housing. Only settable if client has Social Determinant fields turned on.
race string The patient race, using the 2.16.840.1.113883.5.104 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer. Multiple values or a tab-seperated list of codes is acceptable for multiple races for input. The first race will be considered "primary". Note: you must update all values at once if you update any.
racecode string The patient race hierarchical code as specified in Race & Ethnicity - CDC * (2.16.840.1.113883.1.11.14914)
racename string The patient's primary race name. See race for more complete details.
referralsourceid string The referral / "how did you hear about us" ID.
referralsourceother string If choosing "other" for referral source, this is the text field that can be filled out.
registrationdate string Date the patient was registered.
schoolbasedhealthcenter string Used to identify this patient as school-based health center patient. Only settable if client has Social Determinant fields turned on.
sex string Patient's sex (M/F)
sexualorientation string Sexual orientation of this patient.
sexualorientationother string If a patient does not identify with any prescribed sexual orientation choice, this field stores the patient-provided description of sexual orientation.
smsoptindate string The date on which the patient's consent to receive text messages as per FCC requirements was recorded. In order for this to be valid, a valid mobile phone number must be set and the practice setting 'Hide SMS Opt-in option' must be set to Off.
ssn string The patient's SSN
state string Patient's state (2 letter abbreviation)
status string The "status" of the patient, one of active, inactive, prospective, or deleted.
suffix string Patient's name suffix
veteran string Used to identify this patient as a veteran. Only settable if client has Social Determinant fields turned on.
workphone string The patient's work phone number. Generally not used to contact a patient. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
zip string Patient's zip. Matching occurs on first 5 characters.
Example Code
Update specific patient record
PUT
/v1/{practiceid}/patients/{patientid}

Modifies data of a specific patient

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
patientid integer patientid
Content-Type string Content type of the payload

❙ Request Body

Expand all
PATIENTFACINGCALL boolean When 'true' is passed we will collect relevant data and store in our database.
THIRDPARTYUSERNAME string User name of the patient in the third party application.
address1 string Patient's address - 1st line (Max length: 100)
address2 string Patient's address - 2nd line (Max length: 100)
agriculturalworker string Used to identify this patient as an agricultural worker. Only settable if client has Social Determinant fields turned on.
agriculturalworkertype string For patients that are agricultural workers, identifies the type of worker. Only settable if client has Social Determinant fields turned on.
altfirstname string Alternate first name that differs from legal name. This is only available in practices with the appropriate practice settings.
assignedsexatbirth string Sex that this patient was assigned at birth. This is only available in practices with the appropriate practice settings.
caresummarydeliverypreference string The patient's preference for care summary delivery.
city string Patient's city (Max length: 30)
clinicalordertypegroupid string The clinical order type group of the clinical provider (Prescription: 10, Lab: 11, Vaccinations: 16).
consenttocall boolean The flag is used to record the consent of a patient to receive automated calls per FCC requirements. The requested legal language is 'Entry of any telephone contact number constitutes written consent to receive any automated, prerecorded, and artificial voice telephone calls initiated by the Practice. To alter or revoke this consent, visit the Patient Portal "Contact Preferences" page.'
consenttotext boolean The flag is used to record the consent of a patient to receive text messages per FCC requirements. In order for this to be true, a valid mobile phone number must be set and the practice setting "Hide SMS Opt-in option" must be set to Off.
contacthomephone string Emergency contact home phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactmobilephone string Emergency contact mobile phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactname string The name of the (emergency) person to contact about the patient. The contactname, contactrelationship, contacthomephone, and contactmobilephone fields are all related to the emergency contact for the patient. They are NOT related to the contractpreference_* fields.
contactpreference string The MU-required field for "preferred contact method". This is not used by any automated systems.
contactpreference_announcement_email boolean If set, the patient has indicated a preference to get or not get "announcement" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_announcement_phone boolean If set, the patient has indicated a preference to get or not get "announcement" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_announcement_sms boolean If set, the patient has indicated a preference to get or not get "announcement" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_appointment_email boolean If set, the patient has indicated a preference to get or not get "appointment" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_appointment_phone boolean If set, the patient has indicated a preference to get or not get "appointment" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_appointment_sms boolean If set, the patient has indicated a preference to get or not get "appointment" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_billing_email boolean If set, the patient has indicated a preference to get or not get "billing" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_billing_phone boolean If set, the patient has indicated a preference to get or not get "billing" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_billing_sms boolean If set, the patient has indicated a preference to get or not get "billing" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_lab_email boolean If set, the patient has indicated a preference to get or not get "lab" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_lab_phone boolean If set, the patient has indicated a preference to get or not get "lab" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_lab_sms boolean If set, the patient has indicated a preference to get or not get "lab" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactrelationship string Emergency contact relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
countrycode3166 string Patient's country code (ISO 3166-1)
deceaseddate string If present, the date on which a patient died.
defaultpharmacyncpdpid string The NCPDP ID of the patient's preferred pharmacy. See http://www.ncpdp.org/ for details. Note: if updating this field, please make sure to have a CLINICALORDERTYPEGROUPID field as well.
departmentid integer Primary (registration) department ID.
dob string Patient's DOB (mm/dd/yyyy)
donotcallyn boolean Warning! This patient will not receive any communication from the practice if this field is set to true. This field should only be used if you are absolutely certain that's what you want to do.
driverslicenseexpirationdate string The expiration date of the patient's driver's license.
driverslicensenumber string The number of the patient's driver's license
driverslicensestateid string The state of the patient's driver's license. This is in the form of a 2 letter state code.
email string Patient's email address. 'declined' can be used to indicate just that.
employerid integer The patient's employer's ID (from /employers call)
employerphone string The patient's employer's phone number. Normally, this is set by setting employerid. However, setting this value can be used to override this on an individual patient. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
ethnicitycode string Ethnicity of the patient, using the 2.16.840.1.113883.5.50 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer.
firstname string Patient's first name
genderidentity string Gender this patient identifies with. This is only available in practices with the appropriate practice settings. To see the available options for this input, please see GET /configuration/patients/genderidentity?show2015edcehrtvalues=true
genderidentityother string Only valid when used in conjunction with a gender identity choice that allows the patient to describe their identity (if it doesn't conform to any other choice).
guarantoraddress1 string Guarantor's address (Max length: 100)
guarantoraddress2 string Guarantor's address - line 2 (Max length: 100)
guarantoraddresssameaspatient boolean If set, the address of the guarantor is the same as the patient.
guarantorcity string Guarantor's city (Max length: 30)
guarantorcountrycode3166 string Guarantor's country code (ISO 3166-1)
guarantordob string Guarantor's DOB (mm/dd/yyyy)
guarantoremail string Guarantor's email address
guarantoremployerid integer The guaranror's employer's ID (from /employers call)
guarantorfirstname string Guarantor's first name
guarantorlastname string Guarantor's last name
guarantormiddlename string Guarantor's middle name
guarantorphone string Guarantor's phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
guarantorrelationshiptopatient string The guarantor's relationship to the patient
guarantorssn string Guarantor's SSN
guarantorstate string Guarantor's state (2 letter abbreviation)
guarantorsuffix string Guarantor's name suffix
guarantorzip string Guarantor's zip
guardianfirstname string The first name of the patient's guardian.
guardianlastname string The last name of the patient's guardian.
guardianmiddlename string The middle name of the patient's guardian.
guardiansuffix string The suffix of the patient's guardian.
hasmobileyn boolean Set to false if a client has declined a phone number.
homeboundyn boolean If the patient is homebound, this is true.
homeless string Used to identify this patient as homeless. Only settable if client has Social Determinant fields turned on.
homelesstype string For patients that are homeless, provides more detail regarding the patient's homeless situation. Only settable if client has Social Determinant fields turned on.
homephone string The patient's home phone number. Invalid numbers in a GET will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Only phone numbers that exist in the North American Naming Plan (NANP) are acceptable for input.
ignorerestrictions boolean Set to true to allow ability to find patients with record restrictions and blocked patients. This should only be used when there is no reflection to the patient at all that a match was found or not found.
industrycode string Industry of the patient, using the US Census industry code (code system 2.16.840.1.113883.6.310). "other" can be used as well.
language6392code string Language of the patient, using the ISO 639.2 code. (http://www.loc.gov/standards/iso639-2/php/code_list.php; "T" or terminology code) Special case: use "declined" to indicate that the patient declined to answer.
lastname string Patient's last name
lookupdepartmentid integer Use this in practices that register copies of patients in different departments in order to make sure you are updating the correct version of the patient.
maritalstatus string Marital Status (D=Divorced, M=Married, S=Single, U=Unknown, W=Widowed, X=Separated, P=Partner)
middlename string Patient's middle name
mobilecarrierid string The ID of the mobile carrier, from /mobilecarriers or the list below.
mobilephone string The patient's mobile phone number. On input, 'declined' can be used to indicate no number. (Alternatively, hasmobile can also be set to false. "declined" simply does this for you.) Invalid numbers in a GET will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Only phone numbers that exist in the North American Naming Plan (NANP) are acceptable for input.
nextkinname string The full name of the next of kin.
nextkinphone string The next of kin phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
nextkinrelationship string The next of kin relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
notes string Notes associated with this patient.
occupationcode string Occupation of the patient, using the US Census occupation code (code system 2.16.840.1.113883.6.240). "other" can be used as well.
onlinestatementonlyyn boolean Set to true if a patient wishes to get e-statements instead of paper statements. Should only be set for patients with an email address and clients with athenaCommunicator. The language we use in the portal is, "Future billing statements will be sent to you securely via your Patient Portal account. You will receive an email notice when new statements are available." This language is not required, but it is given as a suggestion.
portalaccessgiven boolean This flag is set if the patient has been given access to the portal. This may be set by the API user if a patient has been given access to the portal "by providing a preprinted brochure or flyer showing the URL where patients can access their Patient Care Summaries." The practiceinfo endpoint can provide the portal URL. While technically allowed, it would be very unusual to set this to false via the API.
povertylevelcalculated number Patient's poverty level (% of the Federal Poverty Level), as calculated from family size, income per pay period, pay period, and state. Typically only valued if client has Federal Poverty Level fields turned on.
povertylevelfamilysize number Patient's family size (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelfamilysizedeclined boolean Indicates if the patient delcines to provide "povertylevelfamilysize". Should be set to Yes if the patient declines.
povertylevelincomedeclined boolean Indicates if the patient delcines to provide "povertylevelincomeperpayperiod". Should be set to Yes if the patient declines.
povertylevelincomepayperiod string Patient's pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomeperpayperiod integer Patient's income per specified pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomerangedeclined boolean Indicates whether or not the patient declines to provide an income level (povertylevelcalculated).
preferredname string The patient's preferred name (i.e. nickname).
preferredpronouns string Pronoun this patient uses. This is only available in practices with the appropriate practice settings.
primarydepartmentid string The patient's "current" department. This field is not always set by the practice.
primaryproviderid string The "primary" provider for this patient, if set.
publichousing string Used to identify this patient as living in public housing. Only settable if client has Social Determinant fields turned on.
race string The patient race, using the 2.16.840.1.113883.5.104 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer. Multiple values or a tab-seperated list of codes is acceptable for multiple races for input. The first race will be considered "primary". Note: you must update all values at once if you update any.
referralsourceid string The referral / "how did you hear about us" ID.
referralsourceother string If selecting "other" for referral source, this is the text field that can be filled out.
registerpatientindepartment boolean If you use LOOKUPDEPARTMENTID to get the local copy of a patient to update, and if the patient is not currently registered in that department, setting this flag will register a new copy of this patient in that department.
schoolbasedhealthcenter string Used to identify this patient as school-based health center patient. Only settable if client has Social Determinant fields turned on.
sex string Patient's sex (M/F)
sexualorientation string Sexual orientation of this patient. This is only available in practices with the appropriate practice settings.
sexualorientationother string Only valid when used in conjunction with a sexual orientation choice that allows the patient to describe their orientation (if it doesn't conform to any other choice).
ssn string
state string Patient's state (2 letter abbreviation)
status string The "status" of the patient, either active, inactive or prospective
suffix string Patient's name suffix
veteran string Used to identify this patient as a veteran. Only settable if client has Social Determinant fields turned on.
workphone string The patient's work phone number. Generally not used to contact a patient. Invalid numbers in a GET will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Only phone numbers that exist in the North American Naming Plan (NANP) are acceptable for input.
zip string Patient's zip. Matching occurs on first 5 characters.

Output Parameters

Expand all
patientid string Please remember to never disclose this ID to patients since it may result in inadvertant disclosure that a patient exists in a practice already.
Example Code
Get list of patients - enhanced best matching search criteria
GET
/v1/{practiceid}/patients/enhancedbestmatch

Retrieves a list of patients based on the search criteria defined by the specific demographics that were passed. It can return multiple patients and will rank each one based off of how sure it is that this patient is the one you are looking for.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
firstname string Patient's first name.
showfullssn boolean If set, will show full SSN instead of a masked number.
showlocalpatientid boolean If set, will show local patient id.
limitlocalpatientid boolean If set, will return local patient id tied to the passed in DepartmentID.
checkuseraccess boolean If set, validate that the session user has access to the patient record. May only be used in conjunction with INTERNALUSE and SESSIONUSER, and DEPARTMENTID. DEPARTMENTID is required because user access is department-specific. If the user does not have access to the patient record, returns a 403 error.
lastname string Patient's last name.
showinsurance boolean Include patient insurance information.
preferredname string Patient's preferred name (or nickname).
showportalstatus boolean If set, will include portal enrollment status in response.
guarantorphone string Guarantor's phone number.
showbalancedetails boolean Show detailed information on patient balances.
ignorerestrictions boolean Set to true to allow ability to find patients with record restrictions and blocked patients. This should only be used when there is no reflection to the patient at all that a match was found or not found.
email string Patient's email address.
minscore number If you are only interested in matching a patient if they are above a specific confidence level, you can use this to require any patient matched to have a score greater than or equal to this value.
ssn string Patient's social security number.
suffix string Patient's name suffix.
returnbestmatches boolean If this field is set to true, the top five patients with a score of 16 or above will be returned.
departmentid integer This is the ID for the department of the patient you are retrieving. If you are calling this on an enterprise practice with multiple financial groups (also called "provider groups"), this will ensure you are retrieving the correct patient and not a copy that is in a different department.
homephone string The patient's home phone number.
showcustomfields boolean Include custom fields for the patient.
guarantoremail string Guarantor's email address.
showallpatientdepartmentstatus boolean Include an array of all departments the patient is a part of along with all statuses for those departments.
mobilephone string The patient's mobile phone number.
showpreviouspatientids boolean If set, will show the previous patient ID this patient was merged from.
showallclaims boolean Include information on claims where there is no outstanding patient balance. (Only to be used when showbalancedetails is selected.)
dob string Patient's DOB (mm/dd/yyyy).
zip string Patient's zip.
usesoundexsearch boolean If this field is set to true, search patients based on a soundex search. Soundex searching is disabled by default.
show2015edcehrtvalues boolean Use 2015 Ed. CEHRT compliant strings for describing gender identity and sexual orientation.
workphone string The patient's work phone number. Generally not used to contact a patient.

Output Parameters

Expand all
address1 string Patient's address - 1st line
address2 string Patient's address - 2nd line
agriculturalworker string Used to identify this patient as an agricultural worker. Only settable if client has Social Determinant fields turned on.
agriculturalworkertype string For patients that are agricultural workers, identifies the type of worker. Only settable if client has Social Determinant fields turned on.
allpatientstatuses array
altfirstname string Alternate first name that differs from legal name.
assignedsexatbirth string Sex that this patient was assigned at birth.
balances array List of balances owed by the patient, broken down by provider (financial) group.
caresummarydeliverypreference string The patient's preference for care summary delivery.
city string Patient's city
claimbalancedetails array Claim level details on patient balances. (This is only included when SHOWBALANCEDETAILS is set.)
confidentialitycode string Gives the confidentiality code for the patient. Only returned when IGNORERESTRICTIONS is set to true and COLCR_RETURN_CONFIDENTIALITY_CODE is ON
consenttocall string The flag is used to record the consent of a patient to receive automated calls per FCC requirements. The requested legal language is 'Entry of any telephone contact number constitutes written consent to receive any automated, prerecorded, and artificial voice telephone calls initiated by the Practice. To alter or revoke this consent, visit the Patient Portal "Contact Preferences" page.'
consenttotext string The flag is used to record the consent of a patient to receive text messages per FCC requirements. In order for this to be true, a valid mobile phone number must be set and the practice setting "Hide SMS Opt-in option" must be set to Off.
contacthomephone string Emergency contact home phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactmobilephone string Emergency contact mobile phone. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
contactname string The name of the (emergency) person to contact about the patient. The contactname, contactrelationship, contacthomephone, and contactmobilephone fields are all related to the emergency contact for the patient. They are NOT related to the contractpreference_* fields.
contactpreference string The MU-required field for "preferred contact method". This is not used by any automated systems.
contactpreference_announcement_email string If set, the patient has indicated a preference to get or not get "announcement" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_announcement_phone string If set, the patient has indicated a preference to get or not get "announcement" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_announcement_sms string If set, the patient has indicated a preference to get or not get "announcement" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_appointment_email string If set, the patient has indicated a preference to get or not get "appointment" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_appointment_phone string If set, the patient has indicated a preference to get or not get "appointment" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_appointment_sms string If set, the patient has indicated a preference to get or not get "appointment" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_billing_email string If set, the patient has indicated a preference to get or not get "billing" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_billing_phone string If set, the patient has indicated a preference to get or not get "billing" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_billing_sms string If set, the patient has indicated a preference to get or not get "billing" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactpreference_lab_email string If set, the patient has indicated a preference to get or not get "lab" communications delivered via email. Note that this will not be present if the practice or patient has not set it.For completeness, turning email off is supported via the API, but it is discouraged. When email is off, patients may not not get messages from the patient portal.
contactpreference_lab_phone string If set, the patient has indicated a preference to get or not get "lab" communications delivered via phone. Note that this will not be present if the practice or patient has not set it.
contactpreference_lab_sms string If set, the patient has indicated a preference to get or not get "lab" communications delivered via SMS. Note that this will not be present if the practice or patient has not set it.For SMS, there is specific terms of service language that must be used when displaying this as an option to be turned on. Turning on must be an action by the patient, not a practice user.
contactrelationship string Emergency contact relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
countrycode string Patient's country code
countrycode3166 string Patient's country code (ISO 3166-1)
customfields array Same as /patients/{patientid}/customfields call, but without the department ID. Depending on setup, and only in large practices, the custom field values may or may not be the same between departments. If this is a concern, using the /patients/{patientid}/customfields call is preferred. Only for a single patient when showcustomfields is set to true.
deceaseddate string If present, the date on which a patient died.
defaultpharmacyncpdpid string The NCPDP ID of the patient's preferred pharmacy. See http://www.ncpdp.org/ for details. Note: if updating this field, please make sure to have a CLINICALORDERTYPEGROUPID field as well.
departmentid string Primary (registration) department ID.
dob string Patient's DOB (mm/dd/yyyy)
donotcallyn string Warning! This patient will not receive any communication from the practice if this field is set to true.
driverslicenseexpirationdate string The expiration date of the patient's driver's license.
driverslicensenumber string The number of the patient's driver's license
driverslicensestateid string The state of the patient's driver's license. This is in the form of a 2 letter state code.
driverslicenseurl string The URL to the patient's driver's license
driverslicenseyn string True if the patient has a driver's license uploaded
email string Patient's email address. 'declined' can be used to indicate just that.
emailexistsyn string True if email exists. False if patient declined. Null if status is unknown.
employeraddress string The patient's employer's address.
employercity string The patient's employer's city.
employerfax string The patient's employer's fax.
employerid string The patient's employer's ID (from /employers call)
employername string The patient's employer's name.
employerphone string The patient's employer's phone number. Normally, this is set by setting employerid. However, setting this value can be used to override this on an individual patient. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
employerstate string The patient's employer's state.
employerzip string The patient's employer's zip.
ethnicitycode string Ethnicity of the patient, using the 2.16.840.1.113883.5.50 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer.
firstappointment string The first appointment for this patient, excluding cancelled or no-show appointments. (mm/dd/yyyy h24:mi)
firstname string Patient's first name
genderidentity string Gender with which this patient identifies.
genderidentityother string If a patient does not identify with any prescribed gender identity choice, this field stores the patient-provided description of gender identity.
guarantoraddress1 string Guarantor's address
guarantoraddress2 string Guarantor's address - line 2
guarantoraddresssameaspatient string The address of the guarantor is the same as the patient.
guarantorcity string Guarantor's city
guarantorcountrycode string Guarantor's country code
guarantorcountrycode3166 string Guarantor's country code (ISO 3166-1)
guarantordob string Guarantor's DOB (mm/dd/yyyy)
guarantoremail string Guarantor's email address
guarantoremployerid string The guaranror's employer's ID (from /employers call)
guarantorfirstname string Guarantor's first name
guarantorlastname string Guarantor's last name
guarantormiddlename string Guarantor's middle name
guarantorphone string Guarantor's phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
guarantorrelationshiptopatient string The guarantor's relationship to the patient
guarantorssn string Guarantor's SSN
guarantorstate string Guarantor's state (2 letter abbreviation)
guarantorsuffix string Guarantor's name suffix
guarantorzip string Guarantor's zip
guardianfirstname string The first name of the patient's guardian.
guardianlastname string The last name of the patient's guardian.
guardianmiddlename string The middle name of the patient's guardian.
guardiansuffix string The suffix of the patient's guardian.
hasmobileyn string Set to false if a client has declined a phone number.
homeboundyn string If the patient is homebound, this is true.
homeless string Used to identify this patient as homeless. Only settable if client has Social Determinant fields turned on.
homelesstype string For patients that are homeless, provides more detail regarding the patient's homeless situation. Only settable if client has Social Determinant fields turned on.
homephone string The patient's home phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
industrycode string Industry of the patient, using the US Census industry code (code system 2.16.840.1.113883.6.310). "other" can be used as well.
insurances array List of active patient insurance packages. Only shown for a single patient and if SHOWINSURANCE is set.
language6392code string Language of the patient, using the ISO 639.2 code. (http://www.loc.gov/standards/iso639-2/php/code_list.php; "T" or terminology code) Special case: use "declined" to indicate that the patient declined to answer.
lastappointment string The last appointment for this patient (before today), excluding cancelled or no-show appointments. (mm/dd/yyyy h24:mi)
lastemail string The last email for this patient on file.
lastname string Patient's last name
localpatientid string 'Given showlocalpatientid is true, comma separated local patient id will be returned, if patient id is enterprise id else given patient id will be displayed.'
maritalstatus string Marital Status (D=Divorced, M=Married, S=Single, U=Unknown, W=Widowed, X=Separated, P=Partner)
maritalstatusname string The long version of the marital status.
medicationhistoryconsentverified string Medication history consent status. If a practice doesn't have RXHub or Surescripts enabled, this will be null
middlename string Patient's middle name
mobilecarrierid string The ID of the mobile carrier, from /mobilecarriers or the list below.
mobilephone string The patient's mobile phone number. On input, 'declined' can be used to indicate no number. (Alternatively, hasmobile can also be set to false. "declined" simply does this for you.) Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
nextkinname string The full name of the next of kin.
nextkinphone string The next of kin phone number. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
nextkinrelationship string The next of kin relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
notes string Notes associated with this patient.
occupationcode string Occupation of the patient, using the US Census occupation code (code system 2.16.840.1.113883.6.240). "other" can be used as well.
onlinestatementonlyyn string Set to true if a patient wishes to get e-statements instead of paper statements. Should only be set for patients with an email address and clients with athenaCommunicator. The language we use in the portal is, "Future billing statements will be sent to you securely via your Patient Portal account. You will receive an email notice when new statements are available." This language is not required, but it is given as a suggestion.
patientid string Please remember to never disclose this ID to patients since it may result in inadvertant disclosure that a patient exists in a practice already.
patientphotourl string The URL to the patient photo
patientphotoyn string True if the patient has a photo uploaded
portalaccessgiven string This flag is set if the patient has been given access to the portal. This may be set by the API user if a patient has been given access to the portal "by providing a preprinted brochure or flyer showing the URL where patients can access their Patient Care Summaries." The practiceinfo endpoint can provide the portal URL. While technically allowed, it would be very unusual to set this to false via the API.
portalsignatureonfile string This flag is set if the patient's signature is on file
portalstatus array Portal status details. See /patients/{patientid}/portalstatus for details.
portaltermsonfile string Flag determining whether or not the patient has accepted the Terms and Conditions for the patient portal.
povertylevelcalculated integer Patient's poverty level (% of the Federal Poverty Level), as calculated from family size, income per pay period, pay period, and state. Typically only valued if client has Federal Poverty Level fields turned on.
povertylevelfamilysize string Patient's family size (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelfamilysizedeclined string Indicates if the patient delcines to provide "povertylevelfamilysize". Should be set to Yes if the patient declines.
povertylevelincomedeclined string Indicates if the patient delcines to provide "povertylevelincomeperpayperiod". Should be set to Yes if the patient declines.
povertylevelincomepayperiod string Patient's pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomeperpayperiod string Patient's income per specified pay period (used for determining poverty level). Only settable if client has Federal Poverty Level fields turned on.
povertylevelincomerangedeclined string Indicates if the patient declines to provide an income range level. True if the patient declines.
preferredname string The patient's preferred name (i.e. nickname).
preferredpronouns string Pronoun this patient uses.
previouspatientids array The IDs of the patient this one was merged from.
primarydepartmentid string The patient's "current" department. This field is not always set by the practice.
primaryproviderid string The "primary" provider for this patient, if set.
privacyinformationverified string This flag is set if the patient's privacy information has been verified. Privacy information returns True if all of the items referenced in GET /patients/{patientid}/privacyinformationverified are true. Privacy information returns false if any of the items referenced in the GET /patients/{patientid}/privacyinformationverified API are false or expired.
publichousing string Used to identify this patient as living in public housing. Only settable if client has Social Determinant fields turned on.
race string The patient race, using the 2.16.840.1.113883.5.104 codeset. See http://www.hl7.org/implement/standards/fhir/terminologies-v3.html Special case: use "declined" to indicate that the patient declined to answer. Multiple values or a tab-seperated list of codes is acceptable for multiple races for input. The first race will be considered "primary". Note: you must update all values at once if you update any.
racecode string The patient race hierarchical code as specified in Race & Ethnicity - CDC * (2.16.840.1.113883.1.11.14914)
racename string The patient's primary race name. See race for more complete details.
referralsourceid string The referral / "how did you hear about us" ID.
referralsourceother string If choosing "other" for referral source, this is the text field that can be filled out.
registrationdate string Date the patient was registered.
schoolbasedhealthcenter string Used to identify this patient as school-based health center patient. Only settable if client has Social Determinant fields turned on.
score number This is the patient's matching score. This indicates how likely this patient is to be the patient you are searching for given the demographics input. A score of 26 indicates the patient is automatically assumed to be the same. A score under 16 indicates that this is almost guaranteed to NOT be the patient you are looking for (we will never return any patient with a score under 16). A score of around 23 is the maximum you can get if the only parameters you pass in are the required parameters.
sex string Patient's sex (M/F)
sexualorientation string Sexual orientation of this patient.
sexualorientationother string If a patient does not identify with any prescribed sexual orientation choice, this field stores the patient-provided description of sexual orientation.
smsoptindate string The date on which the patient's consent to receive text messages as per FCC requirements was recorded. In order for this to be valid, a valid mobile phone number must be set and the practice setting 'Hide SMS Opt-in option' must be set to Off.
ssn string The patient's SSN
state string Patient's state (2 letter abbreviation)
status string The "status" of the patient, one of active, inactive, prospective, or deleted.
suffix string Patient's name suffix
veteran string Used to identify this patient as a veteran. Only settable if client has Social Determinant fields turned on.
workphone string The patient's work phone number. Generally not used to contact a patient. Invalid numbers in a GET/PUT will be ignored. Patient phone numbers and other data may change, and one phone number may be associated with multiple patients. You are responsible for taking additional steps to verify patient identity and for using this data in accordance with applicable law, including HIPAA. Invalid numbers in a POST will be ignored, possibly resulting in an error.
zip string Patient's zip. Matching occurs on first 5 characters.
Example Code
Get list of patients - matching custom-field criteria
GET
/v1/{practiceid}/patients/customfields/{customfieldid}/{customfieldvalue}

Retrieves matching patients based on custom field value. The customfieldvalue is either an actual value for non-select fields or an optionid when the value was from select field.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others