Athena Health API

Athena Health v1.0.0

Base URLs:

Authentication

  • oAuth2 authentication. This API uses OAuth 2 with the clientCredentials grant flow. More info

API Details

Get available practice IDs

Code samples

GET https://api.athenahealth.com/{apivariant}/{practiceid}/practiceinfo HTTP/1.1
Host: api.athenahealth.com
Accept: application/json

GET /{apivariant}/{practiceid}/practiceinfo

Parameters

Name

In

Type

Required

Description

practiceid

path

integer(int32)

true

Id of the practice

apivariant

path

string

true

Variant of the API

limit

query

integer(int32)

false

Number of entries to return (default 1500, max 5000)

offset

query

integer(int32)

false

Starting point of entries; 0-indexed

Example responses

200 Response

{
"totalcount": 0,
"practiceinfo": [
{
"iscoordinatorsender": true,
"hasclinicals": true,
"name": "string",
"golivedate": "string",
"experiencemode": "string",
"hascommunicator": true,
"iscoordinatorreceiver": true,
"hascollector": true,
"practiceid": "string"
}
]
}

Responses

Status

Meaning

Description

Schema

200

OK

Array of available practices

PracticesInformationList

default

Default

unexpected error

Error

To perform this operation, you must be authenticated by means of one of the following methods: defaultSecurityScheme

Get department IDs

Code samples

GET https://api.athenahealth.com/{apivariant}/{practiceid}/departments HTTP/1.1
Host: api.athenahealth.com
Accept: application/json

GET /{apivariant}/{practiceid}/departments

Parameters

Name

In

Type

Required

Description

practiceid

path

integer(int32)

true

Id of the practice

apivariant

path

string

true

Variant of the API

limit

query

integer(int32)

false

Number of entries to return (default 1500, max 5000)

offset

query

integer(int32)

false

Starting point of entries; 0-indexed

hospitalonly

query

boolean

false

If set to true, return hospital only departments.

showalldepartments

query

boolean

false

By default, departments hidden in the portal do not appear. When this is set to true, that restriction is not applied. Default is false.

providerlist

query

boolean

false

If set to true, list providers who see patients in this department. Default is false.

Example responses

200 Response

{
"totalcount": 0,
"departments": [
{
"creditcardtypes": [
"string"
],
"timezoneoffset": 0,
"singleappointmentcontractmax": "string",
"state": "string",
"placeofservicefacility": true,
"latitude": "string",
"departmentid": "string",
"address": "string",
"placeofservicetypeid": "string",
"longitude": "string",
"clinicals": "string",
"timezone": 0,
"name": "string",
"patientdepartmentname": "string",
"chartsharinggroupid": "string",
"placeofservicetypename": "string",
"zip": "string",
"timezonename": "string",
"communicatorbrandid": "string",
"medicationhistoryconsent": true,
"ishospitaldepartment": true,
"providergroupid": "string",
"portalurl": "string",
"city": "string",
"servicedepartment": true,
"oneyearcontractmax": "string",
"fax": "string",
"providergroupname": "string",
"doesnotobservedst": true,
"phone": "string",
"ecommercecreditcardtypes": [
"string"
]
}
]
}

Responses

Status

Meaning

Description

Schema

200

OK

Array of available departments

DepartmentInformationList

default

Default

unexpected error

Error

To perform this operation, you must be authenticated by means of one of the following methods: defaultSecurityScheme

Get department by ID

Code samples

GET https://api.athenahealth.com/{apivariant}/{practiceid}/departments/{departmentid} HTTP/1.1
Host: api.athenahealth.com
Accept: application/json

GET /{apivariant}/{practiceid}/departments/{departmentid}

Parameters

Name

In

Type

Required

Description

practiceid

path

integer(int32)

true

Id of the practice

apivariant

path

string

true

Variant of the API

departmentid

path

string

true

Department ID

hospitalonly

query

boolean

false

If set to true, return hospital only departments.

showalldepartments

query

boolean

false

By default, departments hidden in the portal do not appear. When this is set to true, that restriction is not applied. Default is false.

providerlist

query

boolean

false

If set to true, list providers who see patients in this department. Default is false.

Example responses

200 Response

[
{
"creditcardtypes": [
"string"
],
"timezoneoffset": 0,
"singleappointmentcontractmax": "string",
"state": "string",
"placeofservicefacility": true,
"latitude": "string",
"departmentid": "string",
"address": "string",
"placeofservicetypeid": "string",
"longitude": "string",
"clinicals": "string",
"timezone": 0,
"name": "string",
"patientdepartmentname": "string",
"chartsharinggroupid": "string",
"placeofservicetypename": "string",
"zip": "string",
"timezonename": "string",
"communicatorbrandid": "string",
"medicationhistoryconsent": true,
"ishospitaldepartment": true,
"providergroupid": "string",
"portalurl": "string",
"city": "string",
"servicedepartment": true,
"oneyearcontractmax": "string",
"fax": "string",
"providergroupname": "string",
"doesnotobservedst": true,
"phone": "string",
"ecommercecreditcardtypes": [
"string"
]
}
]

Responses

Status

Meaning

Description

Schema

200

OK

Array of available departments

Inline

default

Default

unexpected error

Error

Response Schema

Status Code 200

Name

Type

Required

Restrictions

Description

anonymous

[DepartmentInformation]

false

none

none

» creditcardtypes

[string]

true

none

none

» timezoneoffset

integer(int32)

true

none

none

» singleappointmentcontractmax

string

false

none

none

» state

string

false

none

none

» placeofservicefacility

boolean

false

none

none

» latitude

string

false

none

none

» departmentid

string

false

none

none

» address

string

false

none

none

» placeofservicetypeid

string

false

none

none

» longitude

string

false

none

none

» clinicals

string

false

none

none

» timezone

integer(int32)

false

none

none

» name

string

false

none

none

» patientdepartmentname

string

false

none

none

» chartsharinggroupid

string

false

none

none

» placeofservicetypename

string

false

none

none

» zip

string

false

none

none

» timezonename

string

false

none

none

» communicatorbrandid

string

false

none

none

» medicationhistoryconsent

boolean

false

none

none

» ishospitaldepartment

boolean

false

none

none

» providergroupid

string

false

none

none

» portalurl

string

false

none

none

» city

string

false

none

none

» servicedepartment

boolean

false

none

none

» oneyearcontractmax

string

false

none

none

» fax

string

false

none

none

» providergroupname

string

false

none

none

» doesnotobservedst

boolean

false

none

none

» phone

string

false

none

none

» ecommercecreditcardtypes

[string]

false

none

none

To perform this operation, you must be authenticated by means of one of the following methods: defaultSecurityScheme

Search for patients

Code samples

GET https://api.athenahealth.com/{apivariant}/{practiceid}/patients HTTP/1.1
Host: api.athenahealth.com
Accept: application/json

GET /{apivariant}/{practiceid}/patients

Parameters

Name

In

Type

Required

Description

practiceid

path

integer(int32)

true

Id of the practice

apivariant

path

string

true

Variant of the API

departmentid

query

integer

false

Primary (registration) department ID.

firstname

query

string

false

First name of the patient to find.

lastname

query

string

false

Last name of the patient to find.

offset

query

integer(int32)

false

Starting point of entries; 0-indexed

limit

query

integer(int32)

false

Number of entries to return (default 1500, max 5000)

Example responses

200 Response

{
"totalcount": 0,
"next": "string",
"patients": [
{
"homeboundyn": true,
"assignedsexatbirth": "string",
"altfirstname": "string",
"ethnicitycode": "string",
"industrycode": 0,
"language6392code": "string",
"localpatientid": "string",
"deceaseddate": "string",
"firstappointment": "string",
"primaryproviderid": "string",
"genderidentityother": "string",
"portalstatus": [
{
"familyregisteredyn": true,
"lastloginentity": "string",
"noportalyn": true,
"portalregistrationdate": "string",
"entitytodisplay": "string",
"status": "string",
"termsaccepted": true,
"registeredyn": true,
"blockedfailedloginsyn": true,
"lastlogindate": "string",
"familyblockedfailedloginsyn": true
}
],
"preferredpronouns": "string",
"lastappointment": "string",
"allpatientstatuses": [
{
"departmentid": 0,
"primaryproviderid": "string",
"status": "string"
}
],
"donotcallyn": true,
"primarydepartmentid": "string",
"status": "string",
"balances": [
{
"contracts": [
{
"availablebalance": "string",
"contractclass": "string",
"maxamount": "string"
}
],
"providergroupid": null,
"departmentlist": "string",
"balance": null,
"cleanbalance": null,
"collectionsbalance": "string",
"paymentplanbalance": "string"
}
],
"lastemail": "string",
"racecode": "string",
"sexualorientation": "string",
"genderidentity": "string",
"emailexistsyn": true,
"occupationcode": 0,
"race": [
"string"
],
"sexualorientationother": "string",
"patientid": "string",
"firstname": "string",
"middlename": "string",
"lastname": "string",
"suffix": "string",
"preferredname": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"zip": "string",
"countrycode": "string",
"countrycode3166": "string",
"homephone": "string",
"mobilephone": "string",
"hasmobileyn": true,
"workphone": "string",
"email": "string",
"ssn": "string",
"racename": "string",
"sex": "string",
"dob": "string",
"maritalstatus": "string",
"contactpreference": "string",
"contactname": "string",
"contactrelationship": "string",
"contacthomephone": "string",
"contactmobilephone": "string",
"nextkinname": "string",
"nextkinrelationship": "string",
"nextkinphone": "string",
"guardianfirstname": "string",
"guardianmiddlename": "string",
"guardianlastname": "string",
"guardiansuffix": "string",
"guarantorfirstname": "string",
"guarantormiddlename": "string",
"guarantorlastname": "string",
"guarantorsuffix": "string",
"guarantoraddress1": "string",
"guarantoraddress2": "string",
"guarantorcity": "string",
"guarantorstate": "string",
"guarantorzip": "string",
"guarantorcountrycode": "string",
"guarantorcountrycode3166": "string",
"guarantordob": "string",
"guarantorssn": "string",
"guarantoremail": "string",
"guarantorphone": "string",
"guarantorrelationshiptopatient": "string",
"guarantoraddresssameaspatient": null,
"registrationdate": "string",
"departmentid": "string",
"portaltermsonfile": null,
"portalsignatureonfile": true,
"privacyinformationverified": null,
"medicationhistoryconsentverified": true,
"maritalstatusname": "string",
"employerid": 0,
"employerphone": "string",
"guarantoremployerid": 0,
"employername": "string",
"employeraddress": "string",
"employercity": "string",
"portalaccessgiven": null
}
]
}

Responses

Status

Meaning

Description

Schema

200

OK

Array of available patients with given search criteria

PatientInformationList

default

Default

unexpected error

Error

To perform this operation, you must be authenticated by means of one of the following methods: defaultSecurityScheme

Register new patient

Code samples

POST https://api.athenahealth.com/{apivariant}/{practiceid}/patients HTTP/1.1
Host: api.athenahealth.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

POST /{apivariant}/{practiceid}/patients

Body parameter

address1: string
address2: string
city: string
departmentid: 0
dob: string
email: string
firstname: string
homephone: string
lastname: string
mobilephone: string
state: string
zip: string
sex: string
race: string

Parameters

Name

In

Type

Required

Description

practiceid

path

integer(int32)

true

Id of the practice

apivariant

path

string

true

Variant of the API

body

body

object

true

none

» address1

body

string

false

Patient's address - 1st line (Max length: 100)

» address2

body

string

false

Patient's address - 2nd line (Max length: 100)

» city

body

string

false

Patient's city (Max length: 30)

» departmentid

body

integer(int32)

false

Primary (registration) department ID.

» dob

body

string

false

Patient's DOB (mm/dd/yyyy)

» email

body

string

false

Patient's email address. 'declined' can be used to indicate just that.

» firstname

body

string

false

Patient's first name

» homephone

body

string

false

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.

» lastname

body

string

false

Patient's last name

» mobilephone

body

string

false

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.

» state

body

string

false

Patient's state (2 letter abbreviation)

» zip

body

string

false

Patient's zip. Matching occurs on first 5 characters.

» sex

body

string

false

Patient's sex (M/F)

» race

body

string

false

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.

Example responses

200 Response

[
{
"patientid": 0
}
]

Responses

Status

Meaning

Description

Schema

200

OK

Array of information about created patients

Inline

400

Bad Request

Bad request

Error

500

Internal Server Error

Bad request

Error

default

Default

unexpected error

Error

Response Schema

Status Code 200

Name

Type

Required

Restrictions

Description

anonymous

[PatientCreatedResponse]

false

none

none

» patientid

integer(int32)

false

none

none

To perform this operation, you must be authenticated by means of one of the following methods: defaultSecurityScheme

Get a patients by ID

Code samples

GET https://api.athenahealth.com/{apivariant}/{practiceid}/patients/{patientId} HTTP/1.1
Host: api.athenahealth.com
Accept: application/json

GET /{apivariant}/{practiceid}/patients/{patientId}

Parameters

Name

In

Type

Required

Description

practiceid

path

integer(int32)

true

Id of the practice

apivariant

path

string

true

Variant of the API

patientId

path

integer

true

Id of the patient for which get information

departmentid

query

integer

false

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.

ignorerestrictions

query

boolean

false

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.

show2015edcehrtvalues

query

boolean

false

Use 2015 Ed. CEHRT compliant strings for describing gender identity and sexual orientation.

showallclaims

query

boolean

false

Include information on claims where there is no outstanding patient balance. (Only to be used when showbalancedetails is selected.)

showallpatientdepartmentstatus

query

boolean

false

Include an array of all departments the patient is a part of along with all statuses for those departments.

showbalancedetails

query

boolean

false

Show detailed information on patient balances.

showcustomfields

query

boolean

false

Include custom fields for the patient.

showfullssn

query

boolean

false

If set, will show full SSN instead of a masked number.

showinsurance

query

boolean

false

Include patient insurance information.

showlocalpatientid

query

boolean

false

If set, will show local patient id.

showportalstatus

query

boolean

false

If set, will include portal enrollment status in response.

Detailed descriptions

departmentid: 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.

ignorerestrictions: 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.

showallclaims: Include information on claims where there is no outstanding patient balance. (Only to be used when showbalancedetails is selected.)

Example responses

200 Response

[
{
"homeboundyn": true,
"assignedsexatbirth": "string",
"altfirstname": "string",
"ethnicitycode": "string",
"industrycode": 0,
"language6392code": "string",
"localpatientid": "string",
"deceaseddate": "string",
"firstappointment": "string",
"primaryproviderid": "string",
"genderidentityother": "string",
"portalstatus": [
{
"familyregisteredyn": true,
"lastloginentity": "string",
"noportalyn": true,
"portalregistrationdate": "string",
"entitytodisplay": "string",
"status": "string",
"termsaccepted": true,
"registeredyn": true,
"blockedfailedloginsyn": true,
"lastlogindate": "string",
"familyblockedfailedloginsyn": true
}
],
"preferredpronouns": "string",
"lastappointment": "string",
"allpatientstatuses": [
{
"departmentid": 0,
"primaryproviderid": "string",
"status": "string"
}
],
"donotcallyn": true,
"primarydepartmentid": "string",
"status": "string",
"balances": [
{
"contracts": [
{
"availablebalance": "string",
"contractclass": "string",
"maxamount": "string"
}
],
"providergroupid": null,
"departmentlist": "string",
"balance": null,
"cleanbalance": null,
"collectionsbalance": "string",
"paymentplanbalance": "string"
}
],
"lastemail": "string",
"racecode": "string",
"sexualorientation": "string",
"genderidentity": "string",
"emailexistsyn": true,
"occupationcode": 0,
"race": [
"string"
],
"sexualorientationother": "string",
"patientid": "string",
"firstname": "string",
"middlename": "string",
"lastname": "string",
"suffix": "string",
"preferredname": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"zip": "string",
"countrycode": "string",
"countrycode3166": "string",
"homephone": "string",
"mobilephone": "string",
"hasmobileyn": true,
"workphone": "string",
"email": "string",
"ssn": "string",
"racename": "string",
"sex": "string",
"dob": "string",
"maritalstatus": "string",
"contactpreference": "string",
"contactname": "string",
"contactrelationship": "string",
"contacthomephone": "string",
"contactmobilephone": "string",
"nextkinname": "string",
"nextkinrelationship": "string",
"nextkinphone": "string",
"guardianfirstname": "string",
"guardianmiddlename": "string",
"guardianlastname": "string",
"guardiansuffix": "string",
"guarantorfirstname": "string",
"guarantormiddlename": "string",
"guarantorlastname": "string",
"guarantorsuffix": "string",
"guarantoraddress1": "string",
"guarantoraddress2": "string",
"guarantorcity": "string",
"guarantorstate": "string",
"guarantorzip": "string",
"guarantorcountrycode": "string",
"guarantorcountrycode3166": "string",
"guarantordob": "string",
"guarantorssn": "string",
"guarantoremail": "string",
"guarantorphone": "string",
"guarantorrelationshiptopatient": "string",
"guarantoraddresssameaspatient": null,
"registrationdate": "string",
"departmentid": "string",
"portaltermsonfile": null,
"portalsignatureonfile": true,
"privacyinformationverified": null,
"medicationhistoryconsentverified": true,
"maritalstatusname": "string",
"employerid": 0,
"employerphone": "string",
"guarantoremployerid": 0,
"employername": "string",
"employeraddress": "string",
"employercity": "string",
"portalaccessgiven": null
}
]

Responses

Status

Meaning

Description

Schema

200

OK

Array of information about patient

Inline

Response Schema

Status Code 200

Name

Type

Required

Restrictions

Description

anonymous

[PatientInformation]

false

none

none

» homeboundyn

boolean

false

none

If the patient is homebound, this is true.

» assignedsexatbirth

string

false

none

Sex that this patient was assigned at birth.

» altfirstname

string

false

none

Alternate first name that differs from legal name.

» ethnicitycode

string

false

none

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.

» industrycode

integer

false

none

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

false

none

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.

» localpatientid

string

false

none

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.

» deceaseddate

string

false

none

If present, the date on which a patient died.

» firstappointment

string

false

none

The first appointment for this patient, excluding cancelled or no-show appointments. (mm/dd/yyyy h24:mi)

» primaryproviderid

string

false

none

The "primary" provider for this patient, if set.

» genderidentityother

string

false

none

If a patient does not identify with any prescribed gender identity choice, this field stores the patient-provided description of gender identity.

» portalstatus

[PatientPortalStatus]

false

none

Portal status details. See /patients/{patientid}/portalstatus for details.

»» familyregisteredyn

boolean

false

none

Is there a family member registered with access to this patient.

»» lastloginentity

string

false

none

Either "PATIENT" or "FAMILY", the last entity who accessed this patient.

»» noportalyn

boolean

false

none

The privacy setting for blocking the patient from the portal is set.

»» portalregistrationdate

string

false

none

The date the patient registered for the portal.

»» entitytodisplay

string

false

none

Either "FAMILY" or "PATIENT".

»» status

string

false

none

The status of the patient. Possible statuses: REGISTERED: The patient is registered for the portal. NOTREGISTERED: The patient is not registered for the portal. FAMILYLOGIN: This patient is set up for a family member to login. NOPORTAL: The privacy setting for blocking the patient from the portal is set. BLOCKEDFAILEDLOGINS: The patient is blocked because of failed login attempts. FAMILYBLOCKEDFAILEDLOGINS: The family member is blocked because of failed login attempts.

»» termsaccepted

boolean

false

none

Has this patient accepted the portal's Terms and Conditions. This is a good indicator if the patient has actually logged in to the portal or simply is registered without ever having logged in.

»» registeredyn

boolean

false

none

If this patient is registered or not for the portal.

»» blockedfailedloginsyn

boolean

false

none

Is this patient blocked from the portal due to failed login attempts.

»» lastlogindate

string

false

none

The last login date.

»» familyblockedfailedloginsyn

boolean

false

none

Is this patient's family blocked from the portal due to failed login attempts.

» preferredpronouns

string

false

none

Pronoun this patient uses.

» lastappointment

string

false

none

The last appointment for this patient (before today), excluding cancelled or no-show appointments. (mm/dd/yyyy h24:mi)

» allpatientstatuses

[PatientDeparmentStatus]

false

none

message

»» departmentid

integer(int32)

false

none

The ID of a department that this patient is registered in.

»» primaryproviderid

string

false

none

The "primary" provider for this patient, if set.

»» status

string

false

none

The "status" of the patient, one of active, inactive, prospective, or deleted.

» donotcallyn

boolean

false

none

Warning! This patient will not receive any communication from the practice if this field is set to true.

» primarydepartmentid

string

false

none

The patient's "current" department. This field is not always set by the practice.

» status

string

false

none

The "status" of the patient, one of active, inactive, prospective, or deleted.

» balances

[PatientBalanceInformation]

false

none

List of balances owed by the patient, broken down by provider (financial) group.

»» contracts

[PatientBalanceContract]

false

none

Information related to existing credit card contracts.

»»» availablebalance

string

false

none

The available balance on this contract.

»»» contractclass

string

false

none

The type of contract. For example, "ONEYEAR,"

»»» maxamount

string

false

none

The maximum allowed amount for this contract.

»» providergroupid

IntegerString

false

none

Athena ID for this financial group.

»» departmentlist

string

false

none

Comma separated list of department IDs that belong to this group

»» balance

IntegerString

false

none

Balance for this provider group.

»» cleanbalance

BooleanString

false

none

Indicates whether the balance is associated with a contract, payment plan, or collections agency.

»» collectionsbalance

string

false

none

The outstanding amount associated with a collections agency.

»» paymentplanbalance

string

false

none

The outstanding amount associated with a payment plan.

» lastemail

string

false

none

The last email for this patient on file.

» racecode

string

false

none

The patient race hierarchical code as specified in Race & Ethnicity - CDC * (2.16.840.1.113883.1.11.14914)

» sexualorientation

string

false

none

Sexual orientation of this patient.

» genderidentity

string

false

none

Gender with which this patient identifies.

» emailexistsyn

boolean

false

none

True if email exists. False if patient declined. Null if status is unknown.

» occupationcode

integer

false

none

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.

» race

[string]

false

none

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.

» sexualorientationother

string

false

none

If a patient does not identify with any prescribed sexual orientation choice, this field stores the patient-provided description of sexual orientation.

» patientid

string

false

none

Please remember to never disclose this ID to patients since it may result in inadvertant disclosure that a patient exists in a practice already.

» firstname

string

false

none

Patient's first name

» middlename

string

false

none

Patient's middle name

» lastname

string

false

none

Patient's last name

» suffix

string

false

none

Patient's name suffix

» preferredname

string

false

none

The patient's preferred name (i.e. nickname).

» address1

string

false

none

Patient's address - 1st line

» address2

string

false

none

Patient's address - 2nd line

» city

string

false

none

Patient's city

» state

string

false

none

Patient's state (2 letter abbreviation)

» zip

string

false

none

Patient's zip. Matching occurs on first 5 characters.

» countrycode

string

false

none

Patient's country code

» countrycode3166

string

false

none

Patient's country code (ISO 3166-1)

» homephone

string

false

none

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.

» mobilephone

string

false

none

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.

» hasmobileyn

boolean

false

none

Set to false if a client has declined a phone number.

» workphone

string

false

none

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.

» email

string

false

none

Patient's email address. 'declined' can be used to indicate just that.

» ssn

string

false

none

The patient's SSN

» racename

string

false

none

The patient's primary race name. See race for more complete details.

» sex

string

false

none

Patient's sex (M/F)

» dob

string

false

none

Patient's DOB (mm/dd/yyyy)

» maritalstatus

string

false

none

Marital Status (D=Divorced, M=Married, S=Single, U=Unknown, W=Widowed, X=Separated, P=Partner)

» contactpreference

string

false

none

The MU-required field for "preferred contact method". This is not used by any automated systems.

» contactname

string

false

none

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.

» contactrelationship

string

false

none

Emergency contact relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)

» contacthomephone

string

false

none

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

false

none

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.

» nextkinname

string

false

none

The full name of the next of kin.

» nextkinrelationship

string

false

none

The next of kin relationship (one of SPOUSE, PARENT, CHILD, SIBLING, FRIEND, COUSIN, GUARDIAN, OTHER)

» nextkinphone

string

false

none

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.

» guardianfirstname

string

false

none

The first name of the patient's guardian.

» guardianmiddlename

string

false

none

The middle name of the patient's guardian.

» guardianlastname

string

false

none

The last name of the patient's guardian.

» guardiansuffix

string

false

none

The suffix of the patient's guardian.

» guarantorfirstname

string

false

none

Guarantor's first name

» guarantormiddlename

string

false

none

Guarantor's middle name

» guarantorlastname

string

false

none

Guarantor's last name

» guarantorsuffix

string

false

none

Guarantor's name suffix

» guarantoraddress1

string

false

none

Guarantor's address

» guarantoraddress2

string

false

none

Guarantor's address - line 2

» guarantorcity

string

false

none

Guarantor's city

» guarantorstate

string

false

none

Guarantor's state (2 letter abbreviation)

» guarantorzip

string

false

none

Guarantor's zip

» guarantorcountrycode

string

false

none

Guarantor's country code

» guarantorcountrycode3166

string

false

none

Guarantor's country code (ISO 3166-1)

» guarantordob

string

false

none

Guarantor's DOB (mm/dd/yyyy)

» guarantorssn

string

false

none

Guarantor's SSN

» guarantoremail

string

false

none

Guarantor's email address

» guarantorphone

string

false

none

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

false

none

The guarantor's relationship to the patient

» guarantoraddresssameaspatient

BooleanString

false

none

The address of the guarantor is the same as the patient.

» registrationdate

string

false

none

Date the patient was registered.

» departmentid

string

false

none

Primary (registration) department ID.

» portaltermsonfile

BooleanString

false

none

Flag determining whether or not the patient has accepted the Terms and Conditions for the patient portal.

» portalsignatureonfile

boolean

false

none

This flag is set if the patient's signature is on file

» privacyinformationverified

BooleanString

false

none

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.

» medicationhistoryconsentverified

boolean

false

none

Medication history consent status. If a practice doesn't have RXHub or Surescripts enabled, this will be null

» maritalstatusname

string

false

none

The long version of the marital status.

» employerid

integer

false

none

The patient's employer's ID (from /employers call)

» employerphone

string

false

none

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.

» guarantoremployerid

integer

false

none

The guaranror's employer's ID (from /employers call)

» employername

string

false

none

The patient's employer's name.

» employeraddress

string

false

none

The patient's employer's address.

» employercity

string

false

none

The patient's employer's city.

» portalaccessgiven

BooleanString

false

none

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.

To perform this operation, you must be authenticated by means of one of the following methods: defaultSecurityScheme

Get a providers

Code samples

GET https://api.athenahealth.com/{apivariant}/{practiceid}/providers/{providerId} HTTP/1.1
Host: api.athenahealth.com
Accept: application/json

GET /{apivariant}/{practiceid}/providers/{providerId}

Parameters

Name

In

Type

Required

Description

practiceid

path

integer(int32)

true

Id of the practice

apivariant

path

string

true

Variant of the API

providerId

path

integer

true

Id of the provider for which get information

showallproviderids

query

boolean

false

In athenaNet's internal data structures, a single provider can be represented by multiple IDs. These IDs are used in certain external messages (e.g. HL7) and thus these IDs may need to be known by the API user as well. When set to true, a list of all of these ancillary IDs will be provided.

showfederalidnumber

query

integer

false

Include the provider's federal ID number in results.

showusualdepartmentguessthreshold

query

number

false

There are situations where determining where a provider "normally" practices is desired. Unfortuantely, there is no such concept in athenaNet since providers often practice in multiple locations. However, we can use some intelligence to determine this by looking back over the previous few months (90 days) to see actual practice. To enable this, set this value between 0 and 1; it is highly recommended to be at least .5. This is the ratio of appointments in a given department to the total number of appointments for that provider. A value of .5 means "the provider's appointments are 50% in the department guessed." Setting this to 1 would only return a department if ALL of the provider's appointments were in one department.

Detailed descriptions

showallproviderids: In athenaNet's internal data structures, a single provider can be represented by multiple IDs. These IDs are used in certain external messages (e.g. HL7) and thus these IDs may need to be known by the API user as well. When set to true, a list of all of these ancillary IDs will be provided.

showfederalidnumber: Include the provider's federal ID number in results.

showusualdepartmentguessthreshold: There are situations where determining where a provider "normally" practices is desired. Unfortuantely, there is no such concept in athenaNet since providers often practice in multiple locations. However, we can use some intelligence to determine this by looking back over the previous few months (90 days) to see actual practice. To enable this, set this value between 0 and 1; it is highly recommended to be at least .5. This is the ratio of appointments in a given department to the total number of appointments for that provider. A value of .5 means "the provider's appointments are 50% in the department guessed." Setting this to 1 would only return a department if ALL of the provider's appointments were in one department.

Example responses

200 Response

[
{
"billable": true,
"ansispecialtycode": "string",
"firstname": "string",
"entitytype": "string",
"otherprovideridlist": "string",
"ansinamecode": "string",
"displayname": "string",
"homedepartment": "string",
"providerid": 0,
"providertypeid": "string",
"providerusername": "string",
"supervisingproviderid": 0,
"providertype": "string",
"createencounterprovideridlist": "string",
"schedulingname": "string",
"usualdepartmentid": "string",
"createencounteroncheckinyn": true,
"specialty": "string",
"hideinportalyn": true,
"lastname": "string",
"npi": 0,
"providergrouplist": "string",
"federalidnumber": "string",
"supervisingproviderusername": "string"