Technical API Documentation

GETTING STARTED

By using or accessing any API services or materials, you agree to be bound by the API Terms of Use available at:
https://www.modmed.com/api-terms-of-use/.

All RESTful web service endpoints require HTTP Basic Authentication with a valid username and password for either a Staff or a Patient for a Practice known on this server.
For all endpoints, please use the same server root portion of the url was used to access this FHIR Capability Statement.
Review the official HL7.org guidelines on FHIR implementation here:
https://hl7.org/fhir/index.html

ENDPOINT TO RETRIEVE FHIR CAPABILITY STATEMENT
The following endpoint may be used to retrieve the server’s FHIR Capability Statement:

TITLE: FHIR Capability Statement

DESCRIPTION: Retrieve the server’s FHIR Capability Statement.

URL: /fhir/metadata

METHOD: Get

OPTIONAL URL PARAMETERS:
_format [By default data will be returned as application/fhir+xml. Pass this optional parameter and set the value to json if you would like data returned as application/fhir+json.]

SUCCESSFUL HTTP RESPONSE CODE: 200 [The full server FHIR Capability Statement will be returned.]

ERROR HTTP RESPONSE CODES:
404 [Resource Not Found. This will occur if the Web Service Url was typed in error.]
500 [A general server error has occurred.]

EXAMPLE REQUEST: https://SERVER_ROOT/fhir/metadata&_format=json

ENDPOINTS FOR STAFF MEMBERS
The following endpoints are meant to be accessed with valid credentials for a Staff member:

TITLE: Lookup Patient Identifier

DESCRIPTION: Searches for a Unique Patient Identifier for the given demographics.

URL: /fhir/Patient

METHOD: Get

REQUIRED URL PARAMETERS:
given [An exact match for the Patient’s first name]
family [An exact match for the Patient’s last name]
gender [An exact match for the Patient’s gender. Valid values are male or female]
birthdate [An exact match for the Patient’s birthdate. Valid format is yyyy-MM-dd]

SUCCESSFUL HTTP RESPONSE CODE: 200 [The matching Patient Resource will be returned. Only the id property of the Patient will be returned, and no additional data.]

ERROR HTTP RESPONSE CODES:
401 [Unauthenticated User detected. To remedy, ensure that you use HTTP Basic Authentication with a valid username and password for a Staff member known on this server.]
403 [Forbidden access. This will occur if the authenticated user is attempting to access Patient information that they do not have access to.]
404 [Resource Not Found. This will occur if no Patients exactly match the demographics or if the Web Service Url was typed in error.]
500 [A general server error has occurred.]

EXAMPLE REQUEST: https://SERVER_ROOT/fhir/Patient?given=Clayton&family=Abernathy&gender=male&birthdate=1982-06-02&_format=json

TITLE: Get All Data for Single Patient

DESCRIPTION: Retrieves All Data for a Patient.

URL: /fhir/Patient

METHOD: Get

REQUIRED URL PARAMETERS:
identifier [The unique Patient Identifier on the server. This identifier can be retrieved using the Lookup Patient Identifier Endpoint described earlier.]

SUCCESSFUL HTTP RESPONSE CODE: 200 [The matching Patient Resource will be returned with all available data points.]

ERROR HTTP RESPONSE CODES:
401 [Unauthenticated User detected. To remedy, ensure that you use HTTP Basic Authentication with a valid username and password for a Staff member known on this server.]
403 [Forbidden access. This will occur if the authenticated user is attempting to access Patient information that they do not have access to.]
404 [Resource Not Found. This will occur if no Patient matches the requested Patient identifier or if the Web Service Url was typed in error.]
500 [A general server error has occurred.]

EXAMPLE REQUEST: https://SERVER_ROOT/fhir/Patient?identifier=1125&_format=json

TITLE: Get Specific Data for Single Patient

DESCRIPTION: Retrieves Specific Data for a Patient.

URL: /fhir/Patient

METHOD: Get

REQUIRED URL PARAMETERS:
identifier [The unique Patient Identifier on the server. This identifier can be retrieved using the Lookup Patient Identifier Endpoint described earlier.]

OPTIONAL URL PARAMETERS:
_include [Send a separate _include parameter for each desired section. See the NOTES below for a detail on each _include parameter]
date [Send a maximum of 2 date parameters to indicate a date range. Data for each included section for the Patient will be returned if it satisfies the date range. See the NOTES below for a further explanation of valid date parameter formats.]
_format [By default data will be returned as application/fhir+xml. Pass this optional parameter and set the value to json if you would like data returned as application/fhir+json.]

SUCCESSFUL HTTP RESPONSE CODE: 200 [The matching Patient Resource will be returned with the requested data points. Also included will be the Patient given name, family name, birthdate and gender.]

ERROR HTTP RESPONSE CODES:
401 [Unauthenticated User detected. To remedy, ensure that you use HTTP Basic Authentication with a valid username and password for a Staff member known on this server.]
403 [Forbidden access. This will occur if the authenticated user is attempting to access Patient information that they do not have access to.]
404 [Resource Not Found. This will occur if no Patient matches the requested Patient identifier or if the Web Service Url was typed in error.]
500 [A general server error has occurred.]

NOTES:
Valid date parameter values are as follows:
eqyyyy-MM-dd [date equals the yyyy-MM-dd formatted date]
ltyyyy-MM-dd [date is less than the yyyy-MM-dd formatted date]
leyyyy-MM-dd [date is less than or equal to the yyyy-MM-dd formatted date]
gtyyyy-MM-dd [date is greater than the yyyy-MM-dd formatted date]
geyyyy-MM-dd [date is greater than or equal to the yyyy-MM-dd formatted date]

Valid _include parameter values are as follows:
Patient:allergy [Patient allergy information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/allergyintolerance.html

Patient:assessment [Patient assessment information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/careplan.html

Patient:careTeam [Patient care team information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/careteam.html

Patient:device [Patient medical device information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/device.html

Patient:ethnicGroup [Patient ethnic group information will be returned if it is available]
Info on this data structure is available at https://hl7.org/fhir/us/core/2017Jan/ValueSet-detailed-ethnicity.html

Patient:goal [Patient goal information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/goal.html

Patient:healthConcern [Patient health concern information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/riskassessment.html

Patient:immunization [Patient immunization information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/immunization.html

Patient:medication [Patient medication information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/medicationstatement.html

Patient:preferredLanguage [Patient preferred language will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/valueset-languages.html

Patient:problem [Patient problem information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/problem.html

Patient:procedure [Patient procedure information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/procedure.html

Patient:race [Patient race information will be returned if it is available]
Info on this data structure is available at https://hl7.org/fhir/us/core/2017Jan/ValueSet-omb-race.html

Patient:result [Patient lab result information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/observation.html

Patient:smokingStatus [Patient smoking status will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/observation.html

Patient:treatmentPlan [Patient treatment plan information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/careplan.html

Patient:vitalSign [Patient vital sign information will be returned if it is available]
Info on this data structure is available at https://www.hl7.org/fhir/observation.html

EXAMPLE REQUEST: https://SERVER_ROOT/fhir/Patient?identifier=1125&_include=Patient:allergy&_include=Patient:medication&date=gt2015-12-31&date=le2016-03-31&_format=json

TITLE: Get All Data for All Patients in the Organization of the Staff member

DESCRIPTION: Retrieves all Data for all Patients in the Organization of the Staff member.

URL: /fhir/Patient

METHOD: Get

SUCCESSFUL HTTP RESPONSE CODE: 200 [The matching Patient Resources will be returned with all available data points.]

ERROR HTTP RESPONSE CODES:
401 [Unauthenticated User detected. To remedy, ensure that you use HTTP Basic Authentication with a valid username and password for a Staff member known on this server.]
403 [Forbidden access. This will occur if the authenticated user is attempting to access Patient information that they do not have access to.]
404 [Resource Not Found. This will occur if no Patient Resources are found or if the Web Service Url was typed in error.]
500 [A general server error has occurred.]

EXAMPLE REQUEST: https://SERVER_ROOT/fhir/Patient?_format=json

TITLE: Get Specific Data for All Patients in the Organization of the Staff member

DESCRIPTION: Retrieves Specific Data for all Patients in the Organization of the Staff member.

URL: /fhir/Patient

METHOD: Get

OPTIONAL URL PARAMETERS:
_include [Send a separate _include parameter for each desired section. See the NOTES below for a detail on each _include parameter]
date [Send a maximum of 2 date parameters to indicate a date range. Data for each included section for Patients will be returned if it satisfies the date range. See the NOTES below for a further explanation of valid date parameter formats.]
_format [By default data will be returned as application/fhir+xml. Pass this optional parameter and set the value to json if you would like data returned as application/fhir+json.]

SUCCESSFUL HTTP RESPONSE CODE: 200 [The matching Patient Resources will be returned with the requested data points. Also included will be the Patient given name, family name, birthdate and gender.]