Lighthouse API Implementation - department-of-veterans-affairs/caseflow GitHub Wiki

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."
}