This API is intended to be used in applications which are 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 will allow 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.
It is important to note that this API will return all matching patients for the user provided search criteria, and partners will 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. Please note the more characters provided in the search criterion, the more the search will be able to narrow down the list of possible patients that the user is looking for.
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. Please note the more characters provided in the search criteria, the more the search will be able to narrow down the list of possible patients that the user is looking for.
For partners who are utilizing the Patients/Search API for patient look up, please 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 will receive a 403 error which 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 athena suggest 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. Please wait until you receive the first response before calling the API again.