Developer docs
Developer docs
Breadcrumbs

PCIU to VA Profile Integration: Design Decision Log and Agreements

Last Updated:

This document serves as the authoritative source of truth for the design decisions, technical agreements, and implementation details related to the VA.gov VA Profile integration with a slight emphasis on VA Profile ContactInformationV2 and AddressValidationV3 API integrations. The document's purpose is to provide clarity for current and future technical stakeholders, reduce ambiguity during future iterations or migrations, and ensure that lessons learned and key decisions are well documented for reference. We also aim to ensure that the officially stated agreements (ICD) are captured in one place so that all involved parties have a consistent and reliable point of reference.

Intake Process

The VA Profile intake and onboarding process often involves obtaining a new API key, or enabling the new API versions under the existing API key. The VA Profile team has recommended splitting API keys for the monolith, as the current approach uses a single shared key for all VFS teams and Platform, which limits permission granularity. The existing permissions model defaults to the highest access level required by any consumer, reducing our ability to tailor access based on specific use cases from a security perspective.

Getting Started

Here are the getting started docs (only available on the VA Network). We initially reached out to the VA Profile team via email under the assumption that the intake form had to be obtained through email.

ICD Form

The official ICD (Interface Control Document) is a formal document that defines the interface between VA.gov and VA Profile. It ensures both sides agree on how they communicate with one another. The ICD can be found here.

Note: The ICD is stored in a sensitive VA Github repo and specific Github access is required.

Configuration Specifics

Lighthouse vs Direct integration

AddressValidationV3

Address validation requests flow directly through the Kong gateway through Lighthouse. Our Source System is set as VETSGOV via the Lighthouse team, which was just updated to match the Vets API direct connect API key sourceSystemUser of VETSGOV (previously they deviated). The VA Profile team is working on getting these identifiers to match for each system type. Lighthouse has the ability to distinguish between various sourceSystemUser types vs Vets API where we make requests as one entity.

ContactInformationV2

For CIv2, Vets API makes direct calls to VA Profile rather than routing through Lighthouse. While there was a broader effort to expose VA Profile APIs through Lighthouse (See Lighthouse migration Playbook), this particular VA Profile integration from the EVSS PCIU sunsetting was not included. Integrating through Lighthouse can act as a black box for the Platform team and once traffic leaves our network, we lose visibility and control, though it does reduce the need for us to manage the integration directly. In this case, however, we own and manage the integration end to end from revproxy to fwdproxy, giving us greater transparency and oversight.

ICN vs VA Profile ID

While VAProfile_ID may be preferred, this preference is not currently reflected in the official VA Profile Swagger documentation for Address Validation and Contact Information (docs only available on the VA Network).

The VA Profile recommended using the vaprofile_id instead of the Veteran ICN. In our current design, we typically fall back to the ICN if the vaprofile_id is unavailable. The vaprofile_id (technically called vet360_id per legacy naming convention) is cached on the Vets API side on the User RedisStore model, while the ICN is saved to the user accounts record during the authentication process. It may be worth considering storing the vaprofile_id with the user accounts record as well, rather than relying solely on caching.

Specific Identifiers

As with many new API versions, changes were introduced to identifiers, parameters, and other fields.

Source System

As mentioned elsewhere, Vets API is currently treated as a single source system entity to VA Profile and shares a common source system user (VETSGOV seen here). A ticket has been created to explore separating these into distinct components per product/team.

ICN vs Other Identifiers

According to the VA Profile API documentation, there are several acceptable identifiers available. Vets API defaults to the VA Profile ID and falls back to ICN. However, VA Profile ID is currently the preferred option, stated by the VA Profile team.

Override/Validation Key

In this case, the validation key name was updated between versions, and corresponding changes were made across both the frontend and backend repositories.

Address Validation

With the move to the AddressValidationV3 API, the address_pou parameter changed from RESIDENCE/CHOICE to RESIDENCE.

Override/Validation key

  • The validationKey and overrideIndicator was deprecated with CIV2. CIV2 only requires the override_validation_key for overriding addresses.

Testing Requirements

The VA Profile team provided a comprehensive set of testing scenarios, including edge cases, to ensure full coverage on our end. These scenarios were used during the live testing session and also served as the foundation for a template (example in the ticket here) that the other VFS teams adopted for their own testing. Meeting these specific scenarios was a critical stakeholder requirement as part of the VA Profile intake process.

TX_AUDIT_ID

For testing and traceability, requests/responses include an TX_AUDIT_ID that allows them to track requests and responses between VA.gov and VA Profile. This has been extremely helpful for debugging. The transaction_id is used to track when email, addresses, and phone numbers have been successfully updated in ContactInformationV2 or if the transaction was denied.

Dashboards

This is the current AddressValidation & Contact Information monitoring dashboard in Datadog. To access this dashboard, Datadog access is required.

Go/No-Go

An example of the go/no-go process can be found here. This is required by VA Profile stakeholders for onboarding to VA Profile APIs.

API Documentation

There are more Swagger references on the VA Profile getting started page, but the following links are the ones in use for the EVSS/PCIU to VA Profile migration.

The VA Profile docs are only available on the VA Network.

Points of Contact

For further details, see the ICD as this will have the most up to date contact information.

Next Up

Current Issues

Help and feedback