Patient

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

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

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

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

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

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

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

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

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

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

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

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

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Create new patient record
POST
/v1/{practiceid}/patients

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

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

Input Parameters

Expand all

Request Body

Expand all
Example Code
Get specific patient record
GET
/v1/{practiceid}/patients/{patientid}

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

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

Input Parameters

Expand all

required

Output Parameters

Expand all
Example Code
Update specific patient record
PUT
/v1/{practiceid}/patients/{patientid}

Modifies data of a specific patient

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

Input Parameters

Expand all

Request Body

Expand all
Example Code
Get list of patients - enhanced best matching search criteria
GET
/v1/{practiceid}/patients/enhancedbestmatch

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

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

Input Parameters

Expand all

required

Output Parameters

Expand all
Example Code
Get list of patients - matching custom-field criteria
GET
/v1/{practiceid}/patients/customfields/{customfieldid}/{customfieldvalue}

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

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