Skip to content

Lighthouse API Implementation

minhazur9 edited this page Jun 9, 2023 · 21 revisions

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."
}
Clone this wiki locally