Michigan EVV Physician Specifications

HHAeXchange developed APIs to manage healthcare resources to include Practitioner, Patient, and Organization, that are compliant with FHIR R5 standards.

For additional details on FHIR R5 standards, refer to the following links:

The specification requirements are intended for project management and technical teams at designated providers and vendors responsible for implementing the HHAeXchange interface.

The specifications continuously update as new system capabilities are implemented and additional functionalities become available.

Follow the API endpoint definitions to ensure all required fields are correctly formatted when preparing data for import to HHAeXchange.

For optimal system performance, HHAeXchange recommends that visit data be sent in near real-time. Providers or vendors are expected to send data to the system as it is added, changed, or deleted in the third-party system.

  • Data that is unchanged should not be resent to HHAeXchange.

  • HHAeXchange provides transaction statuses on a separate API call that is initiated by the third-party system.

  • HHAeXchange allows maximum 200 calls per minute per consumer.

The APIs are provided as a RESTful secure HTTP (HTTPS) web service for the third-party system.

  • The API leverages POST, PUT, and GET HTTP Methods.

  • The security approach for physician interfaces incorporate Encryption, Authentication and Authorization.

Physician APIs:

  • Use HTTPS with Security Socket Layer (SSL) encryption and Transport Layer Security (TLS) version 1.2.

    All communications with APIs should be on TLS 1.2.

  • Use OAuth2 (client id, client secret and scope) for authentication and authorization to enforce identity verification and authorization.

  • Accept data from providers linked with client ID.

Use Case HTTP Verb URI Request Parameter Response
Type Param Value
Generate Access Token before calling APIs POST /v1/auth/token Body

client id

client secret

 Provided by HHAeXchange Access token

  1. The third-party system sends a request to the HHAeXchange Identity Server for an Access Token (OAuth 2.0) using the client id and client secret.

  2. The HHAeXchange Identity Server validates the request and generates an Access Token.

  3. The third-party system initiates the API call using the Access Token (set as bearer token in HTTP Header).

  4. The HHAeXchange API validates the Access Token and sends a response back.

  5. The Access Token is valid for 60 minutes. If the token expires, the API returns a 401 (Unauthorized) status, requiring the third-party system to generate a new access token.

    The third-party system must reuse the generated token until it expires. A new token is not needed for each request.

When the Third-Party system sends a Practitioner record, the Practitioner API creates a new record or updates an existing record, and then returns a status along with the bundle ID for reference.

The Practitioner API may overwrite an existing record if one is found in the system. All data sent to HHAeXchange is loaded exactly as received, with no data manipulation during processing. Only one physician record should be sent at a time.

API consumers are required to follow the rules below:

  • Adhere to REST design principles while interacting with the API:

    • Protocol: secure HTTP (HTTPS).

    • Communication Method: Use the appropriate URI patterns along with HTTP verb (POST).

    • Message Format (Request/Response): application/json.

  • Produce JSON payloads that meet the API specification.

  • The API leverages the HTTP response status codes to inform the consumer.

POST: Practitioner Request

  • Used to create a new practitioner/physician record in HHAeXchange.

POST: Practitioner Request

  • Used to search for an existing practitioner in HHAeXchange.

PUT: Practitioner Request

  • Used to update an existing practitioner record in HHAeXchange.

GET: Practitioner Request

  • Used to retrieve practitioner roles in HHAeXchange.

Practitioner Interface
Index Element Description Max Length Type Required
1 Resource Type Refers to a specific category of data that represents a distinct aspect of healthcare information. Ex: Practitioner N/A String Required
Identifier
2 "system": "http://h17.org/fhir/sid/us-tin" "value":" " System represents the reference of ProviderTaxid and the value represents Unique Identifier value as ProviderTaxid. Ex: 999999999 9 String Required
3 "system": "http://h17.org/fhir/sid/us-medicaid" "value":" "

Medicaid number is a unique identifier assigned to individuals who are enrolled in the Maidicaid program.

Ex: XX99999XX

 N/A String Required
4 "system": "http://h17.org/fhir/sid/us-npi" "value":" "

NPI number (National Provider Identifier) is a unique identification number. Ex: 99999999999

 10 String Required
Name
5 name.use Indicated the purpose of this name (e.g., official,). N/A String Optional
6 name.family Family represents the Lastname of the Physician. Ex: John 51 String Required
7 name.given Given represents the Firstname of the Physician. Ex: Lakin 51 String Required
Telecom
8 telecom.use Indicates that this phone number is intended for work-related communication. Ex: work N/A String Optional
9 telecom.family Searched for Patients matching a given phone number in patient Home Phone, Phone 2 and Phone 3 fields. The number should have 10 digits and no special characters are allowed. Ex: 999 999 9999 10 String Required
10 telecom.given System represents the mode of contact. Ex: phone, fax, etc. N/A String Optional
Address
11 address.use Specifies the purpose or context of the address. Ex: home, work, etc. N/A String Optional
12 address.line Contains more than one lines of text that represent the street or other mailing address information. N/A String Optional
13 address.city The name of the city, town, or other locality where the person resides. Ex: Bangalore 51 String Required
14 address.state The state, province, or region where the address is located. Ex: Delhi 51 String Required
15 address.postalcode The postal code or Zip code for the address location. Ex: 1300109BA 10 String Required
16 address.country The country where the address is located, usually represented by it's name. Ex: USA N/A String Required
Specialty
17 "system": "http://h17.org/fhir/sid/specialty" "code":" " It describes the specialty of the Physician and code represents the PhysicianTypeID. Ex: 2237 N/A String Required
Qualification
18 "system": "http://h17.org/fhir/sid/license" "value":" " System represents the reference of License and the value represents License value. Ex: ABC123 N/A String Required
19 period.end Expiration date of the license. Ex: YYY-MM-DD 10 Date Required
Managing Organization
20 "reference":"Organization/" Receive a list of valid values and their IDs by calling the method GetOffices documented in the Reference Tables section. Ex: 1227 5 String Required
21 Active Status of the Physician. Ex: Active, Inactive N/A Boolean Required
parameters for GetPractitioner
22 _page Indicates the specific page of results to retrieve. Ex: 6, 10 N/A Integer Optional
23 _count Specifies the maximum number of records (patients) to return in the response. Ex: 100, 210 N/A Integer Optional

When the third-party system sends a patient record, the API returns a bundle ID.

  • When searching for a patient, a maximum of 100 records are returned.

  • When associating a patient with a physician, one record at a time is returned .

POST: Patient Request

  • Used for searching patients in HHAeXchange.

PUT: Associate Patient with Practitioner

  • Used to associate a patient with a practitioner in HHAeXchange.

Patient Interface
Index Element Description Max Length Type Required
1 PatientID Patient Id - uniquely identifies each patient. Ex: 20095549 N/A String Required
2 resourceType Refers to a specific category of dta that represents a distinct aspect of healthcare information. Ex: Patient N/A String Required
Identifier
3 "system": "http://h17.org/fhir/sid/us-tin" "value":" " System represents the reference of ProviderTaxid and the value represents Unique Identifier value as ProviderTaxid. Ex: 999999999 9 String Required
4 "system": "http://h17.org/fhir/sid/us-admission" "value":" "

System represents the reference of AdmissionID and the value represents Admission. Admission value is auto generated by the system. Ex: 1384793284095186

 80 String Required
5 "system": "http://h17.org/fhir/sid/us-medicaid" "value":" "

System represents the reference of MedicalID and the value represents Medicaid value. Medicaid number is a unique identifer assigned to individuals who are enrolled. Ex: XD32123M

 10 String Required
Name
6 name.family Family represents the Lastname of the Physician. Ex: John 50 String Required
7 name.given Given represents the Firstname of the Physician. Ex: Lakin 60 String Required
generalPractitioner
20 "reference":"Practitioner/"

Describes the specialty number of the Physician Id. Ex: 564104

 6 String Required
21 Active Status of the Physician. Ex: Active, Inactive N/A Boolean Required
parameters for GetPractitioner
22 _page Indicates the specific page of results to retrieve. Ex: 6, 10 N/A Integer Optional
23 _count Specifies the maximum number of records (patients) to return in the response. Ex: 100, 210 N/A Integer Optional

When the third-party system requires office-level information, the Organization API can be called to receive a bundle ID.

Third-Party systems can submit (new or updated) multiple records (maximum 100) per request.

GET: Organization Request

Used to retrieve office-level information from HHAeXchange.

Organizations Interface
Index Element Description Max Length Type Required
1 Identifier Provider Tax Id - Unique Identifier for Provider. Ex: 999999999 N/A String Required
parameters for GetPractitioner
22 _page Indicates the specific page of results to retrieve. Ex: 6, 10 N/A Integer Optional
23 _count Specifies the maximum number of records (patients) to return in the response. Ex: 100, 210 N/A Integer Optional
Status Codes & Details
Status Codes Description Action
200 Successful search, create or update was completed No action required - search, create or update was successful.
201 Successful create or update was completed No action required, data loaded successfully into HHAeXchange.
400 Bad Request - Required field missing Review required fields and ensure all data is populated; resend transaction.
401 Unauthorized The request requires user authentication information.
404 Not Found The requested resource could not be found but may be available again in the future.
500 Internal Service Error The server encountered an unexpected condition which prevented it from fulfilling the request. The request can be tried again once the API issues have been resolved.