Hearings - VA.gov API Integration

Overview

This page describes how and why Caseflow hearings is integrated with VA.gov's API platform.

Integration

Caseflow integrates with VA.gov's address validation service and facility locator service to match a veteran to a nearby hearing location. Caseflow refers to this matching process as geomatching, and it involves geocoding a veteran/appellant's address, and determining the closest location(s) where the veteran/appellant can attend a hearing.

Implementation

Relationship to Appeal

Each appeal (irrespective of whether it is an AMA or legacy appeal) is related to a collection of hearing locations that gets populated on a recurring basis by a background job.

The collection of hearing locations represents all of the locations that are nearby to the veteran/appellant that have the ability to hold hearings (including their nearest regional office). Each location has a distance associated with it that represents the driving distance between the veteran/appellant's geocoded address and the hearing location. These are presented as location options to the hearing coordinator when they go to schedule a veteran.

Background Job

A background job runs on an hourly schedule to determine nearby hearing locations for each appeal. The job orders appeals by when they were last updated and picks the top N (N = 1000 as of 6/17/2020) appeals to discover available hearing locations (AHLs) for. For each appeal, the job does the following:

1. Discovers the veteran/appellant's closest regional office by leveraging VA.gov's address validation service to geocode the veteran/appellants address and VA.gov's facility locator service to find distances of nearby regional offices.
2. Removes any previously geomatched hearing locations.
3. Discovers a list of candidate facilities that are available based on the veteran's closest regional office (from step 1). These candidate facilities are predefined in a constants file.
4. Matches the list of candidate facilities to the response from VA.gov's facility locator service. Every facility that appears in both the response and from the predefined list are saved as an available hearing location.

Because the job runs for a subset of appeals, it can take some time for any changes to appear if the geomatching algorithm is tweaked. This is important to keep in mind when making modifications to the fetch hearing locations job.

Unverified Addresses

See error handling logic for more details

Occasionally the appellant's address data is incomplete or has errors in it. If that is the case, VA.gov's address validation API will return an error, which triggers Caseflow to create a new admin task to correct and verify the appellant's address.

Foreign Addresses

See error handling logic for more details

If the appellant has an address with a state code that isn't in the US or its territories, Caseflow will create a new admin task to manually associate the appeal with a regional office. Caseflow will geomatch the appellant based on the manually-associated regional office, which enables them to be scheduled.

Addresses in the Philippines

See error handling logic for more details

If the appellant's address is verified but in the Philippines, the appeal is automatically associated with RO50, and geomatched as such.

Resources

• #8428 PR for Initial Implementation
• Geomatching Documentation
• VA.gov API Documentation