West Virginia Medicaid Electronic Visit Verification (EVV) Data Aggregator API Specifications

This specification provides guidance and instructions in preparing data for import to HHAeXchange. Herein are the various Application Programming Interface (API) endpoint definitions indicating required fields and proper format for a successful import.

The topic is intended for project management and technical teams at designated providers and/or Electronic Visit Verification (EVV) vendors who are implementing this interface.

Submit a General inquiries ticket for EVV aggregation to 3rd Party Integration Support Desk. Include 'State Abbreviation' EVV General Inquiry in the subject line. Cases are escalated to the Integration Support queue. An available team member will contact you to assist.

Index   Element   Description   Max Length   Type   Required 
1  providerTaxID Provider Tax ID - Unique Identifier for the Provider.   Format: 999999999 9 String   Required  
2 qualifier  Identifier being sent as the unique identifier for the Caregiver.  Possible Values:NPI 50  String  Required 
3 externalID Unique Caregiver identifier in the external system.  20  String   Required 
4 npi Unique Caregiver NPI # in the external system.  10  String   Required 
5 ssn Provider and EVV vendors should only send a default value of ‘999999999’ for the social security number field Format: 999999999 9 String   Required 
6 dateOfBirth Caregiver's Date of Birth. Format: YYYY-MM-DD Cannot be greater than the current date. 10  Date  Required 
7 lastName Caregiver’s Last Name.  30  String   Required 
8 firstName Caregiver’s First Name.  30  String   Required 
9 gender  Caregiver’s Gender. This is an HHAeXchange application requirement.  If you do not wish to send this, default to ‘Other’. Possible Values: Male, Female, Other  20  String   Required 
10 email   Caregiver’s Email Address. If the value is empty, then the existing value of caregiver’s email address in HHAeXchange is removed  100  String   Optional 
11 phoneNumber Caregiver’s Phone Number. Format: 9999999999 If the value is empty, then the existing value of caregiver’s phone number in HHAeXchange is removed. 10  String   Optional 
12 type  Caregiver’s Type. Possible Value: Both  15  String  Required 
13 stateRegistrationID Unique ID provided by State of WV Caregiver Registration System. If the value is empty, then the existing value of caregiver’s state registration ID in HHAeXchange is removed. 20 String   Optional 
14 professionalLicenseNumber Unique ID provided to Caregiver once credentialed by state. If providing self-directed services and license number is not available, please default to ‘999999999999’. If the value is empty, then the existing value of Professional License Number in HHAeXchange is removed 50  String  Required
15 hireDate

Date on which caregiver hired by Provider. This is an HHAeXchange application requirement. Providers and EVV vendors should default to sending 1900-01-02

Format: YYYY-MM-DD

10  Date  Required 
16 address
addressLine1    Individual’s street address. 100 String   Optional 
addressLine2    Individual’s additional street address information if applicable. 50 String   Optional 
city   City  50 String   Optional
state   State abbreviation (2 letter state code) e.g. WV 2  String   Required   
zipcode Zip Code (5 or 9-digit format i.e., 12345). Format: 99999 OR 999999999 9 String   Required   
Code Task Name HHAeXchange Category
115 Meal Preparation Personal Care
116 Housework/Chore Personal Care
117 Managing Finances Personal Care
118 Managing Medications Personal Care
119 Shopping Personal Care
120 Transportation Personal Care
122 Hygiene Personal Care
123 Dressing Upper Personal Care
124 Dressing Lower Personal Care
125 Locomotion Personal Care
126 Transfer Personal Care
127 Toilet Use Personal Care
128 Bed Mobility Personal Care
129 Eating Personal Care
130 Bladder Incontinence Personal Care
131 Bowel Incontinence Personal Care
132 Personal Care T1019 Personal Care
134 Bathing Personal Care
135 Bathing Personal Care
137 Lotion/Ointment Personal Care
138 Laundry Personal Care
139 Reading/Writing Personal Care
140 Supervision/Coaching/Cueing Personal Care
141 Incontinence Care Personal Care
142 Catheter Care Personal Care
143 Wound Care Personal Care
144 G-Tube Feeding Personal Care
145 Stairs Personal Care
201 In Person Patient Support Activities
202 Via Telephone Patient Support Activities
203 Other Patient Support Activities
206 Phone Use Personal Care

When the third-party EVV system sends EVV records, the EVV API returns a transaction ID. This transaction ID can be queried by the caller (Vendor/Provider) to get status of the EVV records. Upon successful submission of an EVV record, an EVVMSID (unique visit identifier) is returned along with status. The EVVMSID can be used to update or delete that EVV record in the future. All data sent to HHAeXchange is loaded as-is; there is no data manipulation when processing.

  • Third-Party EVV systems can submit multiple EVV records (new or update) per request. Currently a maximum of 100 EVV records are allowed per request.

  • Third-Party EVV systems can submit EVV records from multiple providers.calltype.

  • If the EVV data does not pass validations, the records are rejected with the appropriate error code and message. The EVV Provider can react by resubmitting corrected EVV records.

An option exists for the 3rd party EVV submitter to provide the EVVMSID. The external EVVMSID must be unique across agencies if the 3rd party is sending on behalf of multiple agencies using same Client ID.

  • This value must be prefixed with a tilde ("~") sign to differentiate it from the HHAeXchange derived EVVMSID.

  • The EVV submitter will be responsible to pass a Unique Visit Identifier as the EVVMSID for each new visit created in the system.

  • When selecting this option use the same EVVMSID with the prefixed tilde when calling the PUT and DELETE endpoints.

  • Using this option, the HHAeXchange EVVMSID will still be returned in the transactions endpoint and can be used interchangeably.

Visit Endpoint Workflow

API consumers must adhere to the following rules:

  • 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, PUT, DELETE, and GET).

  • 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 and PUT Operation

Optional fields are not required. Situational fields are dependent on other fields and may be required as indicated. For example, if a Missed Visit is marked as True, then the Situational fields Missed Visit Reason Code and Missed Visit Action Code are required.

Index Element Description Max Length Type Required?
1 providerTaxID Provider Tax ID - Unique Identifier for the Provider. Format: 999999999 9 String   Required 
2 Office
qualifier Value being sent to uniquely identify the member. Possible Values: FederalTaxID, NPI or UMPI. If agency operates in a single office location, same tax ID can be submitted as ‘providerTaxID’ above. If agency has multiple locations, submit office-level NPI, or UMPI.   If service code is configured for auto-placement, submit office-level NPI, or UMPI.   50 String Required
identifier Office identifier identified by Office Qualifier. 64 String Required
3 Member
qualifier Value being sent to uniquely identify the member. Possible Values: MedicaidID 50 String Required
identifier Member identifier identified by Member Qualifier. *Length of this field will be based on the qualifier (For MedicaidID, it will be 50 characters) *64 String Required
admissionId Secondary Member identifier. If patient has multiple profiles in HHAeXchange, send both Member qualifier and Admission ID.  80 String Optional
4 Caregiver
qualifier  Value being sent to unique identify the Caregiver. Possible Values: NPI 50 String  Required 
identifier  Caregiver identifier identified by Caregiver Qualifier.  *Length of this field will be based on the qualifier (For NPI, it will be 20 characters) *64 String  Required 
5 payerID HHAeXchange assigned ID for the payer. Payer ID is determined during the implementation process. 50 String  Required 
6 externalVisitID Unique Visit identifier in the external system. 30 String  Required 
7 evvmsId Unique Visit identifier in the HHAeXchange aggregator system. HHAeXchange EVVMSID: Required for updates to the EVV record. External EVVMSID:  Required for creation and updates to the EVV record. If externally sourced, must start with a “~” and contain alphanumeric, the “_” or “-” characters. 64 String  Situational
8 procedureCode This is the billable procedure code which would be mapped to the associated service.  50 String  Required 
9 procedureModifierCode Two characters Modifier for the HCPCS code for the 837. Up to 4 of these are allowed. Consult specific program requirements for exact usage. 2 Array of String Optional
10 timezone Time zone visit data is captured in.  Required timezone: US/Eastern All time sent to HHAeXchange from third-party provider will be in UTC. Time zone values are based on the Internet Assigned Numbers Authority (IANA) Time Zone Database, which contains data that represents the history of local time for locations around the globe. It is updated periodically to reflect changes made by political bodies to time zone boundaries, UTC offsets, and daylight-saving rules. 20 String Required
11 scheduleStartTime Schedule Start Time in UTC Time. Format: YYYY-MM-DDThh:mm If the schedule already exists in HHAeXchange, the Schedule Start Time is overwritten.   DateTime Required
12 scheduleEndTime Schedule End Time in UTC Time. Format: YYYY-MM-DDThh:mm If the schedule already exists in HHAeXchange, the Schedule Start Time is overwritten   DateTime Required
13 visitStartDateTime

When Required: When “Visit End Date Time” OR “EVV Clock In Time” is provided. Visit Start Time in UTC Time. Format: YYYY-MM-DDThh:mm If a value is provided in this field, then the schedule is confirmed with the start time provided. Cannot be greater than current date. If the value is empty, then the existing value of Visit Start Time in HHAeXchange is removed.

If visitStartDateTime/visitEndDateTime and EVV Clock In/Out Time do not match, visit is marked as manually confirmed or adjusted and visit edits should be transmitted.

   DateTime Situational
14 visitEndDateTime

When Required: When “EVV Clock Out Time” is provided. Visit End Time in UTC Time. Format: YYYY-MM-DDThh:mm If a value is provided in this field, then the Schedule is confirmed with the End Time provided. Must be greater than Visit Start Date Time. Cannot be greater than current date. If the value is empty, then the existing value of Visit End Time in HHAeXchange is removed. 

If visitStartDateTime/visitEndDateTime and EVV Clock In/Out Time do not match, visit is marked as manually confirmed or adjusted and visit edits should be transmitted.

  DateTime Situational
15 timesheetRequired Timesheet Required. Possible Values: True or False An empty value is considered as “False”. If the value is empty, then the existing value of Timesheet Required in HHAeXchange is removed.   Boolean Optional
16 timesheetApproved Timesheet Approved. Possible Values: True or False  An empty value is considered as “False”. If the value is empty, then the existing value of Timesheet Approved in HHAeXchange is removed. If timesheetRequired is set as “False", then this field’s value is ignored.   Boolean Optional
Evv
clockIn: When Required: if EVV Clock In Time is confirmed via EVV
1 callDateTime When Required: if EVV Clock In Time is confirmed via EVV  EVV Clock In Time in UTC Time. Format: YYYY-MM-DDThh:mm If a value is provided in this field, then the Visit Start Time is marked as confirmed via EVV; otherwise, it is considered manually confirmed if visitStartDateTime is provided.   DateTime Situational
2 callType When Required: if EVV Clock In Time is confirmed via EVV The type of device used to create the event. Values: Telephony, Mobile and FOB.  Any call with GPS data collected should be identified as Mobile. 20 String  Situational
3 callLatitude When Required: - If EVV Clock In Time is confirmed by GPS (i.e. CallType = Mobile) GPS Latitude recorded during event. Latitude has a range of -90 to 90 with a 6-digit precision.   Decimal (8,6) Situational
4 callLongitude When Required: - If EVV Clock In Time is confirmed by GPS (i.e. CallType = Mobile) GPS Longitude recorded during event. Longitude has a range of -180 to 180 with a 6-digit precision.   Decimal (9,6) Situational
5 originatingPhoneNumber When Required: - If EVV Clock In Time is confirmed by Telephony (i.e. CallType = Telephony) Originating Phone Number (Caller ID) for telephony.  Format: 9999999999 If a value is provided in this field, then it is considered as a Telephony confirmation and this phone number is imported into HHAeXchange. 10 String Situational
6 serviceAddress
addressLine1   The physical address where the EVV check-in took place. 100 String Situational
addressLine2   The physical address where the EVV check-in took place. 50 String Optional
city City 50 String Situational
state State abbreviation (2 letter state code). 2 String Situational
zipcode Zip Code (5 or 9-digit format i.e., 12345). Format: 99999 OR 999999999 9 String Situational
clockOut: When Required: if EVV Clock Out Time is confirmed via EVV
1 callDateTime When Required: if EVV Clock Out Time is confirmed via EVV  EVV Clock Out Time in UTC Time. Format: YYYY-MM-DDThh:mm If a value is provided in this field, then the Visit End Time is marked as confirmed via EVV; otherwise, it is considered manually confirmed if visitEndDateTime is provided.   DateTime Situational
2 callType When Required: if EVV Clock Out Time is confirmed via EVV The type of device used to create the event. Values: Telephony, Mobile and FOB.  Any call with GPS data collected should be identified as Mobile.  20 String  Situational
3 callLatitude When Required: - If EVV Clock In Time is confirmed by GPS (i.e. CallType = Mobile) GPS Latitude recorded during event. Latitude has a range of -90 to 90 with a 6-digit precision.   Decimal (8,6) Situational
4 callLongitude When Required: - If EVV Clock Out Time is confirmed by GPS (i.e. CallType = Mobile) GPS Longitude recorded during event. Longitude has a range of -180 to 180 with a 6-digit precision.   Decimal (9,6) Situational
5 originatingPhoneNumber When Required: - If EVV Clock Out Time is confirmed by Telephony (i.e. CallType = Telephony) Originating Phone Number (Caller ID) for telephony.  Format: 9999999999 10 String Situational
6 performedTasks List of performed task codes.   Array of String Optional
7 refusedTasks List of refused task codes.   Array of String Optional
8 serviceAddress
addressLine1   The physical address where the EVV check-out took place. 100 String Situational
addressLine2   The physical address where the EVV check-out took place. 50 String Optional
city City 50 String Situational
state State abbreviation (2 letter state code). 2 String Situational
zipcode Zip Code (5 or 9-digit format i.e., 12345). Format: 99999 OR 999999999 9 String Situational
missedVisit: When Required: When Visit is marked as Missed
1 missed When Required: When Visit is marked as Missed Possible Values: True or False An empty value is considered as False. If the value is True, then the Visit is marked as a ‘Missed’ Visit. If False, then the Missed Visit is removed from HHAeXchange if Visit was previously marked as missed and schedule reappears (if the Visit is not yet billed in HHAeXchange). If the Visit is already billed in HHAeXchange, then this flag is ignored.   Boolean Situational
2 reasonCode When Required: When Missed Visit = True Missed Visit Reason Code If the value is empty, then the existing value of Reason in HHAeXchange is not removed. 4 String   Situational
3 actionCode When Required: When Missed Visit = True Missed Visit Action Code. If the value is empty, then the existing value of Action Taken in HHAeXchange is not removed. 4 String Situational
4 notes Free Text Notes - Data in this field is imported as Visit Notes. Reason/Description of the change being made if entered. If the value is empty, then the existing value of Notes in HHAeXchange is not removed. 256 String  Optional
editVisit
1  edited When Required: When Visit is updated after confirmation Possible Values: True or False If the value is True, then the Visit is considered as manually updated. An empty value is considered as False.   Boolean Situational
2 reasonCode When Required: When Edit Visit = True Edit Visit Reason Code. If the value is empty, then the existing value of Reason in HHAeXchange is not removed. 4 String   Situational
3 actionCode When Required: When Edit Visit = True Edit Visit Action Code. If the value is empty, then the existing value of Action Taken in HHAeXchange is not removed. 4 String Situational
4 Notes Free Text Notes - Data in this field is imported as Visit Notes. Reason/Description of the change being made if entered. If the value is empty, then the existing value of Notes in HHAeXchange is not removed. 256 String  Optional
Billing
1 externalInvoiceNumber

Field is required to trigger the submission of claims to the payer. To avoid duplicate billing, this field should not be sent if the provider is billing the payer directly.

  • If a value is provided in this field, the visit is considered billed in the provider’s third-party EVV system. The invoice number is imported, and the visit is processed for billing overnight, maintaining the same batching structure as invoiced in the file submission.

  • Visits must be invoiced in accordance with Payer specific billing requirements noted in the Payer Companion Guide.

  • If this field is left empty, visit is not processed for billing.

18 String Situational
2 totalBilledAmount When Required: When Visit is billed; this field should be sent along with externalInvoiceNumber. Total billed amount in third-party system.   Decimal (8,2) Situational
3 totalUnitsBilled When Required: When visit is billed; this field should be sent along with externalInvoiceNumber. Total units billed in third-party system 5 Integer Situational
4 contractRate When Required: When visit is billed; this field should be sent along with externalInvoiceNumber. Hourly contract rate.   Decimal (8,2) Situational
5 diagnosisCodes When Required: When visit is billed; this field should be sent along with externalInvoiceNumber. Diagnosis Code Up to 26 of these are allowed. 50 Array of String Situational
billSecondaryPayer : When Required: When Visit has secondary bill info
1 enableSecondaryBilling When Required: When Visit has secondary billing info. Possible Values: True or False If the value is True, then the Visit is considered to have secondary billing info. An empty value is considered as False.   Boolean Situational
2 otherSubscriberId When Required: When enableSecondaryBilling = true Other Subscriber ID 80 String   Situational
3 primaryPayerId When Required: When enableSecondaryBilling = true Primary Payer ID 80 String   Situational
4 primaryPayerName When Required: When enableSecondaryBilling = true Primary Payer Name 60 String   Optional
5 relationshipToInsured Relationship to Insured If the value is empty, then the existing value of Reason in HHAeXchange is removed. 2 String   Situational
6 primaryPayerPolicyOrGroupNumber When Required: When enableSecondaryBilling = true Primary payer policy or Group number 3 String   Situational
7 primaryPayerProgramName Primary Payer Program Name If the value is empty, then the existing value of Reason in HHAeXchange is removed. 2 String   Situational
8 planType Plan Type If the value is empty, then the existing value of Reason in HHAeXchange is removed.   2 String   Situational
9 totalPaidAmount When Required: When enableSecondaryBilling = true Total Paid Amount   Decimal (7,2) Situational
10 paidDate When Required: When enableSecondaryBilling = true Paid Date   Decimal (7,2) Situational
11 Deductible Deductible If the value is empty, then the existing value of Reason in HHAeXchange is removed.   Decimal (7,2) Situational
12 Coinsurance Coinsurance. If the value is empty, then the existing value of Reason in HHAeXchange is removed.   Decimal (7,2) Situational
13 Copay Copay If the value is empty, then the existing value of Reason in HHAeXchange is removed.   Decimal (7,2) Situational
14 contractedAdjustments Contracted Adjustments If the value is empty, then the existing value of Reason in HHAeXchange is removed.   Decimal (7,2) Situational
15 notMedicallyNecessary Not Medically Necessary If the value is empty, then the existing value of Reason in HHAeXchange is removed.   Decimal (7,2) Situational
16 nonCoveredCharges Non-Covered Charges If the value is empty, then the existing value of Reason in HHAeXchange is removed.   Decimal (7,2) Situational
17 maxBenefitExhausted Max Benefit Exhausted If the value is empty, then the existing value of Reason in HHAeXchange is removed.   Decimal (7,2) Situational
MCO/Payer Initials
Aetna ATWV
FFS West Virginia FFWV
West Virginia HHCS WVHH
West Virginia Unicare HHCS UCHH
West Virginia The Health Plan HHCS HPHH
Code Description
501 Confirmed with the Member or the Member's family member/representative and documented (this service cannot be billed)
502 New attendant assigned to member (this service cannot be billed)
503 Other (this service cannot be billed)
504 Service(s) cancelled or suspended until further notice (this service cannot be billed)
505 Unverified visit; this service cannot be billed 
506 Visit rescheduled (this service cannot be billed)
Code Description
600 Agency unable to provide replacement coverage (no show, no replacement)
601 Attendant failed to report to Member's home
602 Member requested to change/cancel scheduled visit; or the scheduled visit has been cancelled due to the Member's services being suspended
603 Member Refused Service
604 Member Refused Service - original aide on vacation
608 Hospitalization unplanned
605 COVID-19: All other cases where the agency could not staff due to COVID-19
607 COVID-19: Member refused, self-isolating, not receiving service
606 COVID-19: Member refused, receiving service through informal supports
609 Other
Code Plan Type
BL Blue Cross/Blue Shield
CH Champus
CI Commercial Insurance Co.
MB Medicare Part B
MC Medicaid
Description Unit of Service Procedure Code Payer
Case Management ADW Visit G9002:U1 FFS
Personal Attendant-Traditional ADW Hourly S5130 FFS
Personal Attendant-Personal Options ADW Hourly S5130:U1 FFS
Case Management (Effective until 3/31/2021) TBIW Hourly T1016:UB FFS
Case Management (Effective from 4/1/2021) TBIW Visit G9002:U2 FFS
Personal Attendant-Traditional TBIW Hourly S5125:UB FFS
Personal Attendant-Personal Options TBIW Hourly S5125:UC FFS
Service Coordination (Effective until 3/31/2021) IDDW Hourly T1016:HI FFS
Case Management-NF/SFC (Effective from 4/1/2021) IDDW Visit G9002:U3 FFS
Case Management-ISS/GH (Effective from 4/1/2021) IDDW Visit G9002:U4 FFS
Home-Based Person-Centered Support-Traditional IDDW 1:1 Ratio Hourly S5125:U7 FFS
Home-Based Person-Centered Support-Traditional IDDW 1:2 Ratio Hourly S5125:U8 FFS
Family Person-Centered Support-Personal Options IDDW 1:1 Ratio Hourly S5125:UA FFS
In-Home Respite-Traditional  IDDW 1:1 Ratio Hourly T1005:UA FFS
Private Duty Nursing Hourly T1000 FSS, Aetna, Unicare, THP
In-Home Respite-Traditional  IDDW 1:2 Ratio Hourly T1005:UB FFS
In-Home Respite-Personal Options IDDW 1:1 Ratio Hourly T1005:UD FFS
Direct-Care Worker PC Hourly T1019 FFS
Case Management CSEDW Hourly T1016:HA Aetna
Independent Living/Skills Building CSEDW Hourly H2033:HA Aetna
Respite Care In-Home CSEDW 1:1 Ratio Hourly T1005:HA Aetna
Physical Therapy Services Visit 0421 HHCS
Occupational Therapy Services Visit 0431 HHCS
Speech Language Pathology Therapy Services Visit 0441 HHCS
Skilled Nursing Visit Visit 0551 HHCS
Home Health Aide Service Visit 0571 HHCS
Code Relationship
01 Spouse
18 Self
19 Child
G8 Other
Status Meaning Description
Pending Request Pending Request is received at HHAeXchange. Request is yet to be processed
Success Request Success Request processed successfully and data is also saved into HHAeXchange system
Failed Request Failed Request processed successfully and data is not saved into HHAeXchange system due to either validation errors or issue at request data.
Code Description
101 Confirmed visit with outside entity and documented
103 New attendant assigned to Member
104 Visit rescheduled
105 Service(s) cancelled or suspended until further notice
106 Updated Member's address and documented
107 Updated Member's phone number and documented
108 Changed verification collection method and documented
109 Timesheet received and signed by supervisor
110 Mutual Case/ or Cluster Case/ or Live-in Case
111 Change in schedule
122 Unverified visit; this service cannot be billed
123 Supervisor approved change
124 Confirmed with the Member or the Member's family member/representative and documented (this service cannot be billed)
125 Timesheet Verified
126 Other
Code Description
200 Phone number did not link to the Member
201 Member won't let attendant use phone
202 Member doesn't have a phone in home
203 Phone in use by member or individual in member's home
204 Member received services outside of the home
205 Member's phone line not working (technical issue or natural disaster)
206 Member requested to change/cancel scheduled visit; or the scheduled visit has been cancelled due to the Member's services being suspended
207 Address did not link to the Member (GPS)
208 Attendant failed to call in
209 Attendant failed to call out
210 Attendant failed to call in and out
211 Attendant called in to or out of the EVV system early or late
212 Attendant's identification number (s) does not match the scheduled shift or task discrepancy/task does not match plan of care
213 Attendant entered invalid fixed location device code(s)
214 Attendant failed to report to Member's home
215 Fixed location device on order or pending placement in the home
216 Fixed location device malfunctioned
217 Attendant unable to use mobile device
218 Attendant unable to connect to internet or EVV system down
219 Data Entry Error
220 Agency unable to provide replacement coverage (no show, no replacement)
221 Timesheet Received
222 Other