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.
Endpoints
-
Primary
POST
- Reference
-
Subscription
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.
Input Parameters
Expand all❙ Request Body
Expand allOutput Parameters
Expand allRetrieves 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.
Input Parameters
Expand all❙ required
Output Parameters
Expand allModifies data of a specific patient
Input Parameters
Expand all❙ Request Body
Expand allRetrieves 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.
Input Parameters
Expand all❙ required
Output Parameters
Expand allRetrieves 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.
Input Parameters
Expand all❙ required
Output Parameters
Expand allRetrieves patients in a practice based on their partial name or full patient id
Input Parameters
Expand all❙ required
Output Parameters
Expand allRetrieves 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.
Input Parameters
Expand all❙ required
Output Parameters
Expand allBETA: Retrieves a list of gender identities configured for the practice
Input Parameters
Expand all❙ required
BETA: Returns the list of possible search types to utilize with the /patients/search endpoint.
Input Parameters
Expand allRetrieve a list of events for modified patient records
Input Parameters
Expand all❙ required
Subscribes for changed patients events
Input Parameters
Expand allOutput Parameters
Expand allRetrieves list of events applicable for patients changed
Input Parameters
Expand all❙ required
Retrieve list of changes made to the patient record
Input Parameters
Expand all❙ required
Output Parameters
Expand allDeletes a specific event which is no longer required