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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
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 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. (Max length: 20)
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)
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 string 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 (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 string 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 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 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 string 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 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.
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.
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 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 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 string 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 string 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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
patientid integer patientid
showallpatientdepartmentstatus string Include an array of all departments the patient is a part of along with all statuses for those departments.
showfullssn string If set, will show full SSN instead of a masked number.
showlocalpatientid string If set, will show local patient id.
checkuseraccess string 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 string If set, will return local patient id tied to the passed in DepartmentID.
showinsurance string Include patient insurance information.
showportalstatus string If set, will include portal enrollment status in response.
showbalancedetails string Show detailed information on patient balances.
ignorerestrictions string 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 string If set, will show the previous patient ID this patient was merged from.
showallclaims string 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 string Use 2015 Ed. CEHRT compliant strings for describing gender identity and sexual orientation.
showcustomfields string 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.
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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
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 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)
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 string 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
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 string 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 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 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 string 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 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.
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.
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 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 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 string 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 string 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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
firstname string Patient's first name.
showfullssn string If set, will show full SSN instead of a masked number.
showlocalpatientid string If set, will show local patient id.
limitlocalpatientid string If set, will return local patient id tied to the passed in DepartmentID.
checkuseraccess string 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 string Include patient insurance information.
preferredname string Patient's preferred name (or nickname).
showportalstatus string If set, will include portal enrollment status in response.
guarantorphone string Guarantor's phone number.
showbalancedetails string Show detailed information on patient balances.
ignorerestrictions string 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 string 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 string Include custom fields for the patient.
guarantoremail string Guarantor's email address.
showallpatientdepartmentstatus string 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 string If set, will show the previous patient ID this patient was merged from.
showallclaims string 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 string If this field is set to true, search patients based on a soundex search. Soundex searching is disabled by default.
show2015edcehrtvalues string 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.
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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
customfieldid integer customfieldid
customfieldvalue string customfieldvalue
limit integer Number of entries to return (default 10, max 100)Please note that this endpoint has a different default and max than normal.
offset integer Starting point of entries; 0-indexed

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.
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 string 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
driverslicensenumber string
driverslicensestateid string
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
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.
hierarchicalcode string The patient race hierarchical code
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 Tthe last email for this patient on file.
lastname string Patient's last name
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
portalstatus string Portal status details. See /patients/{patientid}/portalstatus for details.
portaltermsonfile string
povertylevelcalculated string 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 whether or not the patient declines to provide an income level.
preferredname string The patient's preferred name (i.e. nickname).
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.
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.
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)
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
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 - (optional) visible to a practitioner
GET
/v1/{practiceid}/patients/search

Retrieves patients in a practice based on their partial name or full patient id

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
athenanetuser string Username to check permissions against, required for restricted patients
maxresults string Maximum number of results to return (default 50)
searchtype string The search type to search by. The types can be retrieved in /configuration/patients/searchtypes
searchterm string The search term for finding patients, partial name or full patient id

Output Parameters

Expand all
patients array List of patients matching the search criteria
Example Code
Get list of patients for a practice
GET
/v1/{practiceid}/patients

Retrieves a list of patients in the given practice based on search criteria 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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
povertylevelincomepayperiod string Patient's pay period (used for determining poverty level). Only settable 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.
primarydepartmentid string The patient's "current" department. This field is not always set by the practice.
preferredname string The patient's preferred name (i.e. nickname).
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.
email string Patient's email address. 'declined' can be used to indicate just that.
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.
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.
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.
suffix string Patient's name suffix (Max length: 20)
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.
departmentid integer Primary (registration) department ID. A special value of -1 can be used to search for cases where, due to an unusual import or other reasons, the registration department is not set.
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.
guarantorstate string Guarantor's state (2 letter abbreviation)
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.
agriculturalworkertype string For patients that are agricultural workers, identifies the type of worker. Only settable if client has Social Determinant fields turned on.
publichousing string Used to identify this patient as living in public housing. Only settable if client has Social Determinant fields turned on.
nextkinrelationship string The next of kin relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
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.
upcomingappointmenthours integer Used to identify patients with appointments scheduled within the upcoming input hours (maximum 24). Also includes results from the previous 2 hours.
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.
primaryproviderid string The "primary" provider for this patient, if set.
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.
referralsourceid string The referral / "how did you hear about us" ID.
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.'
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.
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.
nextkinname string The full name of the next of kin.
schoolbasedhealthcenter string Used to identify this patient as school-based health center patient. Only settable if client has Social Determinant fields turned on.
appointmentproviderid integer The ID of the provider associated with the upcoming appointment.
povertylevelincomerangedeclined string Indicates whether or not the patient declines to provide an income level.
deceaseddate string If present, the date on which a patient died.
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_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.
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)
driverslicensestateid string The state of the patient's driver's license. This is in the form of a 2 letter state code. (Max length: 20)
guardianfirstname string The first name of the patient's guardian.
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.
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.
driverslicenseexpirationdate string The expiration date of the patient's driver's license.
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.
registrationdate string Date the patient was registered.
address2 string Patient's address - 2nd line (Max length: 100)
omitdefaultpharmacy string When true, the default NCPDPID for patients will not be determined (and "defaultpharmacyncpdpid' will be omitted), speeding up the /patients endpoint.
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.
guarantorsuffix string Guarantor's name suffix (Max length: 20)
notes string Notes associated with this patient.
caresummarydeliverypreference string The patient's preference for care summary delivery.
hierarchicalcode string The patient race hierarchical code (Max length: 20)
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.
show2015edcehrtvalues string When true, 2015 Ed. CEHRT compliant strings will be returned for describing gender identity and sexual orientation.
guarantorlastname string Guarantor's last name (Max length: 20)
firstname string Patient's first name (Max length: 20)
contactpreference string The MU-required field for "preferred contact method". This is not used by any automated systems.
contactrelationship string Emergency contact relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)
veteran string Used to identify this patient as a veteran. Only settable if client has Social Determinant fields turned on.
employerid integer The patient's employer's ID (from /employers call)
state string Patient's state (2 letter abbreviation)
appointmentdepartmentid integer The ID of the department associated with the upcoming appointment.
clinicalordertypegroupid string The clinical order type group of the clinical provider (Prescription: 10, Lab: 11, Vaccinations: 16).
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.
guardianmiddlename string The middle name of the patient's guardian.
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.
mobilecarrierid string The ID of the mobile carrier, from /mobilecarriers or the list below.
guarantorssn string Guarantor's SSN
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_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.
dob string Patient's DOB (mm/dd/yyyy)
homeless string Used to identify this patient as homeless. Only settable if client has Social Determinant fields turned on.
guarantordob string Guarantor's DOB (mm/dd/yyyy)
zip string Patient's zip. Matching occurs on first 5 characters.
anyphone string Any phone number for the patient. 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.
guarantorrelationshiptopatient string The guarantor's relationship to the patient
address1 string Patient's address - 1st line (Max length: 100)
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.
povertylevelcalculated string 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.
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.
omitbalances string When true, current patient balances will not be calculated and the "balances" parameters will be omitted, speeding up the /patients endpoint.
guardianlastname string The last name of the patient's guardian.
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.
agriculturalworker string Used to identify this patient as an agricultural worker. Only settable if client has Social Determinant fields turned on.
hasmobileyn string Set to false if a client has declined a phone number.
guarantoremployerid integer The guaranror's employer's ID (from /employers call)
status string The "status" of the patient, one of active, inactive, prospective, or deleted.
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.
guardiansuffix string The suffix of the patient's guardian.
lastname string Patient's last name (Max length: 20)
guarantorfirstname string Guarantor's first name (Max length: 20)
guarantoraddress2 string Guarantor's address - line 2 (Max length: 100)
ignorerestrictions string 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. When COLCR_RETURN_CONFIDENTIALITY_CODE is ON, will also add the confidentialitycode flag to the output for the patient.
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.
povertylevelfamilysizedeclined string Indicates if the patient delcines to provide "povertylevelfamilysize". Should be set to Yes if the patient declines.
city string Patient's city (Max length: 30)
ssn string
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.
omitphotoinformation string When true, current patient photo information will not be determined (and "patientphoto" and "patientphotourl" will be omitted), speeding up the /patients endpoint.
povertylevelincomedeclined string Indicates if the patient delcines to provide "povertylevelincomeperpayperiod". Should be set to Yes if the patient declines.
guarantoremail string Guarantor's email address
guarantorcity string Guarantor's city (Max length: 30)
middlename string Patient's middle name (Max length: 20)
maritalstatus string Marital Status (D=Divorced, M=Married, S=Single, U=Unknown, W=Widowed, X=Separated, P=Partner)
driverslicensenumber string The number of the patient's driver's license (Max length: 20)
guarantorzip string Guarantor's zip
guarantoraddress1 string Guarantor's address (Max length: 100)
sex string Patient's sex (M/F)
guarantormiddlename string Guarantor's middle name (Max length: 20)
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.
countrycode3166 string Patient's country code (ISO 3166-1) (Max length: 20)
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.
homeboundyn string If the patient is homebound, this is true.
guarantorcountrycode3166 string Guarantor's country code (ISO 3166-1) (Max length: 20)
limit integer Number of entries to return (default 10, max 1000)Please note that this endpoint has a different default and max than normal.
offset integer Starting point of entries; 0-indexed

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.
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 string 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
driverslicensenumber string
driverslicensestateid string
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
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.
hierarchicalcode string The patient race hierarchical code
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 Tthe last email for this patient on file.
lastname string Patient's last name
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
portalstatus string Portal status details. See /patients/{patientid}/portalstatus for details.
portaltermsonfile string
povertylevelcalculated string 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 whether or not the patient declines to provide an income level.
preferredname string The patient's preferred name (i.e. nickname).
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.
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.
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)
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
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
Returns the list of possible search types to utilize with the /patients/search endpoint.
GET
/v1/{practiceid}/configuration/patients/searchtypes

BETA: Returns the list of possible search types to utilize with the /patients/search endpoint.

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
limit integer Number of entries to return (default 1500, max 5000)
offset integer Starting point of entries; 0-indexed

Output Parameters

Expand all
displayname string Display name of the type
name string The name of the type of search. This will also be the value of the searchtype parameter in the /patients/search endpoint',
Example Code
Get list of change events for patient's records
GET
/v1/{practiceid}/patients/changed/subscription/events

Retrieve a list of events for modified patient records

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid

Output Parameters

Expand all
status string Will return one of following statuses: ACTIVE, INACTIVE, or PARTIAL. The PARTIAL status means that not all events are subscribed to. In the event of a problem, UNKNOWN may be returned.
subscriptions array List of events you are subscribed to.
Example Code
Subscribe to all/specific change events for patient's records
POST
/v1/{practiceid}/patients/changed/subscription

Subscribes for changed patients events

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

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

❙ Request Body

Expand all
eventname string By default, you are subscribed to all possible events. If you only wish to subscribe to an individual event, pass the event name with this argument.

Output Parameters

Expand all
success string Returns if the call to manipulate subscriptions for patients was successful.
Example Code
Get list of subscribed events for changes in patient's records
GET
/v1/{practiceid}/patients/changed/subscription

Retrieves list of events applicable for patients changed

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid

Output Parameters

Expand all
status string Will return one of following statuses: ACTIVE, INACTIVE, or PARTIAL. The PARTIAL status means that not all events are subscribed to. In the event of a problem, UNKNOWN may be returned.
subscriptions array List of events you are subscribed to.
Example Code
Get list of changes in patient records
GET
/v1/{practiceid}/patients/changed

Retrieve list of changes made to the patient record

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
leaveunprocessed string For testing purposes, do not mark records as processed.
patientid array Patient ID. Multiple Patient IDs are allowed, either comma separated or with multiple values.
returnglobalid string Fetch the Global ID of the patients.
ignorerestrictions string Patient information for patients with record restrictions and blocked patients will not be shown. Setting this flag to true will show that information for those patients.
showpreviouspatientids string If set, will show the previous patient ID this patient was merged from.
departmentid array Department ID. Multiple departments are allowed, either comma separated or with multiple values.
showprocessedenddatetime string See showprocessestartdatetime.
showprocessedstartdatetime string Show already processed changes. This will show changes that you previously retrieved at some point after this datetime mm/dd/yyyy hh24:mi:ss (Eastern). Can be used to refetch data if there was an error, such as a timeout, and records are marked as already retrieved. This is intended to be used with showprocessedenddatetime and for a short period of time only. Also note that processed messages will eventually be deleted.
limit integer Number of entries to return (default 1000, max 10000)Please note that this endpoint has a different default and max than normal.
offset integer Starting point of entries; 0-indexed

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.
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
Unsubscribe to all/specific events for changes in patient's records
DELETE
/v1/{practiceid}/patients/changed/subscription

Deletes a specific event which is no longer required

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Try in Postman

Input Parameters

Expand all

❙ required

practiceid integer practiceid
eventname string By default, you are unsubscribed from all possible events. If you only wish to unsubscribe from an individual event, pass the event name with this argument.

Output Parameters

Expand all
success string Returns if the call to manipulate subscriptions for patients was successful.
Example Code