Lighthouse API Implementation
When an IDT User requests to mail the document they will be prompted to input the addresses, and these addresses will get sent for validation. We will be using the external Lighthouse API to verify the addresses.
Endpoints
Type |
Endpoint |
Description |
POST |
/idt/api/v1/addresses/validate |
Validating recipient information |
Process
When uploading a document to eFolder as an IDT user there will be an option to upload the document with recipient information for mailing. When recipient information gets inputted, in addition to uploading the document we will also validate the information.
We will be using the endpoint POST idt/api/v1/services/address_validation/v1/validate
.
This endpoint when it gets called will be processed via the Appeals Controller to call on VaDotGovService with the required params which will then be sent to the Lighthouse API for Address Validation. The request params that are needed for this endpoint will need to be the added in addition to the params of the upload endpoints used to interact with the validation endpoint. The upload endpoints noted below.
Upload Endpoints
Type |
Endpoint |
Description |
POST |
/idt/api/v1/upload_document |
Upload a document |
POST |
/idt/api/v2/appeals/{appealId}/outcode |
Outcode a decision review |
Success Codes
Code |
Description |
200 |
Request processed successfully |
Example Request Parameters
{
"request_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"zip_code_5": "string",
"zip_code_4": "string",
"international_postal_code": "string",
"stateProvince": {
"code": "string",
"name": "string"
},
"request_country": {
"country_name": "string",
"country_code": "string"
},
"address_pou": "string"
}
}
Success Object
{
"messages": [
{
"code": "string",
"key": "string",
"text": "string",
"severity": "INFO",
"potentiallySelfCorrectingOnRetry": true
}
],
"candidate_addresses": [
{
"messages": [
{
"code": "string",
"key": "string",
"text": "string",
"severity": "INFO",
"potentiallySelfCorrectingOnRetry": true
}
],
"address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"zip_code_5": "string",
"zip_code_4": "string",
"international_post_code": "string",
"county": {
"name": "string",
"county_fips_code": "string"
},
"state_province": {
"code": "string"
},
"country": {
"name": "string",
"code": "string",
"fips_code": "string",
"iso2_code": "string",
"iso3_code": "string"
}
},
"geocode": {
"calc_date": "2023-06-05T16:12:46.173Z",
"location_precision": 0,
"latitude": 0,
"longitude": 0
},
"us_congressional_district": "string",
"address_metadata": {
"confidence_score": 0,
"address_type": "string",
"delivery_point_validation": "CONFIRMED",
"residential_delivery_indicator": "RESIDENTIAL",
"non_postal_input_data": [
"string"
],
"validation_key": 0
}
}
]
}
Data Definitions
Data |
Description |
request_address.address_line_1 |
Solely the first line of the requested address without city, state, or zip. Cannot be null if addressLine2 and addressLine3 are null. |
request_address.address_line_2 |
Solely the second line of the requested address without city, state, or zip. Cannot be null if addressLine1 and addressLine3 are null. |
request_address.address_line_3 |
Solely the third line of the requested address without city, state, or zip. Cannot be null if addressLine1 and addressLine2 are null. |
request_address.city |
The name of the city of the requested address. Must only contain letters. |
request_address.zip_code_5 |
The five digit postal code of the requested address. Must only contain five digits and only used for domestic or military addresses. |
request_address.zip_code_4 |
The four digit postal code of the requested address. Must only contain four digits and only used for domestic or military addresses. |
request_address.international_postal_code |
The postal code for an international address. This can contain numbers and letters and used for international addresses. |
request_address.state_province.code |
The two digit code for state/province of the requested address. Must only contain two digits. |
request_address.state_province.name |
The name of the state/province of the requested address. |
request_address.country_name |
The name of the country of the requested address. |
request_address.country_code |
The ISO2, ISO3, or FIPS country code of the requested address. Must only contain two or three letters. |
request_address.address_pou |
Should be either RESIDENCE, CHOICE, or CORRESPONDENCE. Optional |
Error Response Codes
Code |
Description |
400 |
There was an error encountered processing the Request. This request shouldn't be retried until corrected. |
403 |
Invalid authorization. |
429 |
Too many requests. |
500 |
There was an error encountered processing the Request. May retry. |
400 Example Response
{
"message": "Missing token"
}
403 Example Response
{
"message": "Invalid token"
}
429 Example Response
{
"errors": [
{
"status": 429,
"title": "Service is temporarily unavailable, please try again later.",
"detail": "Service is temporarily unavailable, please try again later."
}
]
}
500 Example Response
{
"message": "Lighthouse API Error ID: 322483ae-7953-4d3c-9738-e108506d52c2 An unexpected error occurred, please try again."
}