API Processing Workflow and Endpoints

There are two types of messages provided to HHAeXchange by the third-party provider or EVV vendor: (1) caregiver demographic data and (2) visit information. Caregiver data must be sent to HHAeXchange first because an existing caregiver record is required for visit data to load successfully. The provider and/or EVV vendor provides data to HHAeXchange in JSON format only.

Use Case HTTP Verb URI Request: Type Request: Param Request: Value Response

Generate Access Token before calling Caregiver / EVV API

POST

/identity/connect/token

BODY

client_id

Provided by HHAeXchange

access_token

BODY

client_secret

Provided by HHAeXchange

BODY

scope

Provided by HHAeXchange

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

  2. The HHAeXchange Identity Server validates the request.

  3. The HHAeXchange Identity Server then generates an Access Token if the request passes validation.

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

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

  6. The Access Token expires in 30 minutes. If the token expires, then the API returns 401 (Unauthorized) response. The third-party EVV system must then generate a new access token.

  7. The third-party EVV system must reuse the generated token until its expiration. The integration does not require a new token for each request.

Use Case HTTP Verb URI Request: Type Request: Param Request: Value Response

Caregiver Request:

This can be used to create a new or update an existing caregiver record.

POST

/api/v{version}/caregivers

HEAD

Authorization

Bearer {value of token}

HTTP status code and Transaction ID

BODY

Caregiver

Caregiver record

When the third-party EVV system sends a Caregiver record, the Caregiver API processes it creates new record or updates existing record, and returns a status along with the transaction ID for reference. The Caregiver API might overwrite an existing record if found in the system. All data sent to HHAeXchange is loaded as-is; there is no data manipulation when processing. Send one caregiver at a time.

Caregiver Endpoint Workflow

API consumers must follow the rules below:

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

  • Protocol: secure HTTP (HTTPS).

  • Communication Method: Use the appropriate Uniform Resource Identifier (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.

  • If data is received and any required elements are missing, distorted, or incomplete, then the record is rejected.

  • Records are processed in the order they are received.

  • For any field listed as data type string, if the field is longer than the maximum allowed in the specification, then HHAeXchange truncates to the maximum length for that specific field.

  • The API allows an update of a Caregiver record if the Authentication Endpoint ClientID used when creating the record matches.

  • The Provider should be linked with the Authentication Endpoint ClientID to create or update Caregiver records via the API.

  • Refer to Error Messages for detailed error messages.

Use Case HTTP Verb URI Request: Type Request: Param Request: Value Response

Batch EVV Request:

This can be used for submitting one or many visit records (New or Update EVV record).

POST

/api/v{version}/visits

HEAD

Authorization

Bearer {value of token}

HTTP status code and Transaction ID

BODY

Visits

Array of visit records

Update EVV Request: This can be used to update specific visit record.

PUT

/api/v{version}/visits/{evvmsid}

HEAD

Authorization

 

Bearer {value of token}

HTTP status code and Transaction ID

BODY

Visit

visit record

Delete EVV Request: This can be used to delete specific visit record.

DELETE

/api/v{version}/visits/{evvmsid}

HEAD

Authorization

 

Bearer {value of token}

HTTP status code and Transaction ID

Check Transaction Status: This can be used to get status of transaction which was submitted earlier.

GET

/api/v{version}/visits/transactions/{transactionId}

HEAD

Authorization

 

Bearer {value of token}

HTTP status code, EVVMSID and Status

  • All timestamp data is to be sent in UTC (Coordinated Universal Time).

  • If data is received and any required elements are missing, distorted, or incomplete, then the record is rejected.

  • Records are processed in the order they are received.

  • EVVMSID:

    • This element is unique and is assigned to each visit record sent to HHAeXchange by the third-party EVV system once the record enters HHAeXchange’s aggregator.

    • This element is shared with the third-party EVV system with the expectation that this is loaded and stored in the third-party EVV system.

    • This element should be sent by the third-party EVV system to HHAeXchange each time an update occurs on an existing record that is being resent to HHAeXchange.

  • External EVVMSID (alternative):

    • The external EVVMSID must be a combination of alphanumeric characters and can include dashes (“-”) or underscores (“_”). The maximum length of the external EVVMSID is 64 characters (excluding the tilde)

  • For any field listed as data type string, if the field is longer than the maximum allowed in the specification, then HHAeXchange truncates to the maximum length for that specific field.

  • The API allows an update of the EVV record if the following fields match within the HHAeXchange system:

    • ClientID

    • EVVMSID or External EVVMSID

    • Provider Federal Tax ID

    • Payer ID

  • The API allows deletion of an EVV record if the following fields match within the HHAeXchange system:

    • ClientID

    • EVVMSID or External EVVMSID

  • If EVV Clock In is provided, then the EVV Clock Out is not mandatory. If the EVV Clock Out is provided, then the EVV Clock In is mandatory.

  • If visit start and end times are provided without EVV Clock In and Clock Out, then the visit is considered manually confirmed.

  • Once the visit is confirmed manually, then EVV Clock In/Out is not allowed in subsequent requests.

  • Once the EVV Clock In/Out is completed, then a change to an EVV Clock In/Out is not allowed in subsequent requests.

  • If the Provider sends visit data with missed visit information and Clock In/Out information, then the API rejects this request.

  • If the visit has already been marked as a missed visit and a provider sends an updated record with Clock In/Out information as well as the missed visit marked as ‘false’, then the API removes the original missed visit flag and capture the new Clock In/Out and missed visit false information.

  • Provider should be linked with Authentication Endpoint Client ID to create or update EVV records via API.

  • Refer to Error Messages for detailed error messages.

The EVV APIs are exposed as a Representational State Transfer (RESTful) secure Hypertext Transfer Protocol (HTTPS) web service for the third-party EVV system. The API leverages the following HTTP request methods: POST, PUT, DELETE, and GET.

The security approach for EVV interfaces incorporate Encryption and Authentication and Authorization.

EVV APIs:

  • Use HTTPS with Security Socket Layer (SSL) encryption and Transport Layer Security (TLS) version 1.2. All communications with EVV APIs should be on TLS 1.2.

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

  • Accept the data of those providers which are mapped with client ID.

API Interface Workflow

HHAeXchange provides an API for third-party providers and EVV vendors to use. Providers and EVV vendors must reach out to 3rd Party Integration Support Desk with the subject line 'State Abbreviation' API Onboarding Request to commence the onboarding process.

For optimal system performance, HHAeXchange recommends that visit data is sent in near real time. Data is sent by the provider or EVV vendor to HHAeXchange as it is added, changed, and/or deleted in the third-party EVV 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 EVV system and allows a maximum of five (5) calls per second per consumer.