openapi: 3.0.1
info:
title: Address Validation 5103 Waiver Letters API
description: "The Address Validation API accepts and validates an address and standardizes it for mailing. It can also help you process an address by:\n* Inferring missing or incorrect address components\n* Supplementing an address with additional information, such as geocode, latitude and longitude, and postal service metadata (when available)\n## Technical Overview\nThe Address Validation API returns validated addresses as they appear in the USPS database for domestic addresses. It validates by separating the address into individual components and then providing component-level validation checks.\n\nThis API is certified by the United States Postal Service (USPS) Coding Accuracy Support System (CASS) and adheres to [United States Postal Service (USPS) Publication 28 standards](https://pe.usps.com/text/pub28/welcome.htm) for domestic, military, and US territory addresses.\n\nFor international addresses, validation relies on Universal Postal Union (UPU) standards. \n\n## Validation\nIf an address is found, it is considered valid based on metadata returned by the Address Validation service, such as the confidence score and the [Delivery Point Validation (DPV)](https://postalpro.usps.com/address-quality/dpv).\n\nIf an address is found, there are multiple checks performed on the validated address. The address can fail validation for a variety of reasons, such as the inability to deliver (for domestic mailing addresses) or the format. For specific reasons why an address failed, refer to the error messages returned.\n\nIf an address is not found, it automatically fails validation.\n\n## Address override indicator\nSometimes an entered address is accurate for a Veteran but does not pass validation rules. These instances can occur when an address is newer than what is in the CASS software or in regions where address data is less accurate.\n\nSystems can accept these addresses despite the lack of address validation by submitting an \"accepted address\" (usually confirmed by the Veteran) to the Contact Information API (see Requirements below). An address is considered accepted after the address has been sent to the validation API and has failed validation, but the Veteran has confirmed the address is correct as entered. The accepted address can then be passed to the Contact Information API using an address override indicator set to show that the validation was overridden. To set an override indicator, the original address and the `overrideValidationKey` returned in the validation API response must be provided to the Contact Information API, in order to prove that a validation attempt has been made before overriding.\n\n## Version Interoperability\n\nTo ensure interoperability between APIs and eliminate the need for transforming data as one API feeds into the other, we strongly recommend using versions of the following APIs that are compatible.\n\n| <h3>If Using</h3> | <h3>Then Use...</h3> |\n| :------------------------------:|:----------------------------------------------:|\n| Address Validation API v1/v2 | Contact Information API v1<br><br>Profile Service API v1/v2 |\n| Address Validation API v3 | Contact Information API v2<br><br>Profile Service API v3 |\n\n## Authorization\nAPI requests are authorized through a symmetric API token provided in an HTTP header with name apikey.\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us)."
license:
name: Creative Commons
url: https://developer.va.gov/terms-of-service
version: '3'
servers:
- url: https://sandbox-api.va.gov/services/address-validation/{version}
description: Sandbox
variables:
version:
default: v3
- url: https://api.va.gov/services/address-validation/{version}
description: Production
variables:
version:
default: v3
security:
- apikey: []
tags:
- name: Letters
paths:
/eligible-letters:
get:
tags:
- Letters
summary: Returns a list of letters that a Veteran or a dependent is eligible for.
description: " The endpoint also returns the specific data that will be populated\n within each eligible letter. This includes, if relevant:\n\n\n * Veteran's or dependent's address\n * Veteran service details\n * Benefits information the Veteran or dependent is eligible for\n * Survivor benefits awarded\n\n If the API is able to determine eligibility for some but not all letters because\n a partner is down, the list of letters for which a Veteran or dependent is\n determined to be eligible will be returned, along with a\n \"letterGeneration.letterEligibilityError\" message.\n"
operationId: GET:/eligible-letters
parameters:
- name: icn
in: query
description: MPI ICN
required: true
schema:
maxLength: 17
minLength: 17
pattern: ^\d{10}V\d{6}$
type: string
example: 1000000000V100000
responses:
'200':
description: A Response which indicates a successful Request. The Response may contain "messages" that could describe warnings or further information.
content:
application/json:
schema:
$ref: '#/components/schemas/LettersResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: Not authorized
content:
application/json:
schema:
type: string
example:
message: Invalid authentication credentials
'403':
description: Forbidden
content:
application/json:
schema:
type: string
example:
message: You cannot consume this service
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/UserNotFound'
'406':
description: Not Acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/NotAcceptable'
'413':
description: Payload too large
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: Request size limit exceeded
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntity'
'429':
description: Too many requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: API rate limit exceeded
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- OAuth: []
/letter-contents/{letterType}:
get:
tags:
- Letters
summary: Generates JSON-formatted letter content by letter type.
description: 'Returns the descriptions and content of letters a Veteran or dependent is eligible for in JSON format.
| If the GET /eligible-letters endpoint returns | Generate the letter contents with these query parameters |
| --- | --- |
| hasServiceConnectedDisabilities | serviceConnectedDisabilities |
| serviceConnectedPercentage | serviceConnectedEvaluation |
| hasNonServiceConnectedPension | nonServiceConnectedPension |
| monthlyAwardAmount<br />And<br />awardEffectiveDate | monthlyAward |
| hasIndividualUnemployabilityGranted | unemployable |
| hasSpecialMonthlyCompensation | specialMonthlyCompensation |
| hasAdaptedHousing | adaptedHousing |
| hasChapter35Eligibility | chapter35Eligibility |
| hasDeathResultOfDisability | deathResultOfDisability |
| hasSurvivorsPensionAward | survivorsAward |
'
operationId: GET:/letter-contents/{letterType}
parameters:
- name: letterType
in: path
description: Letter Type
required: true
schema:
maxLength: 64
type: string
description: 'Possible values: BENEFIT_SUMMARY, BENEFIT_SUMMARY_DEPENDENT, BENEFIT_VERIFICATION, CIVIL_SERVICE, COMMISSARY, COMMISSARY_SHORT_TERM, PROOF_OF_SERVICE, SERVICE_VERIFICATION, MEDICARE_PARTD, MINIMUM_ESSENTIAL_COVERAGE'
example: BENEFIT_SUMMARY
- name: icn
in: query
description: MPI ICN
required: true
schema:
maxLength: 17
minLength: 17
pattern: ^\d{10}V\d{6}$
type: string
example: 1000000000V100000
- name: militaryService
in: query
description: Include military service
schema:
type: boolean
example: false
default: true
- name: serviceConnectedDisabilities
in: query
description: Include service connected disabilities
schema:
type: boolean
example: false
default: true
- name: serviceConnectedEvaluation
in: query
description: Include service connected evaluation
schema:
type: boolean
example: false
default: true
- name: nonServiceConnectedPension
in: query
description: Include non-service connected pension
schema:
type: boolean
example: false
default: true
- name: monthlyAward
in: query
description: Include monthly award
schema:
type: boolean
example: false
default: true
- name: unemployable
in: query
description: Include unemployable data
schema:
type: boolean
example: false
default: true
- name: specialMonthlyCompensation
in: query
description: Include special monthly compensation
schema:
type: boolean
example: false
default: true
- name: adaptedHousing
in: query
description: Include adapted housing
schema:
type: boolean
example: false
default: true
- name: chapter35Eligibility
in: query
description: Include chapter 35 eligibility
schema:
type: boolean
example: false
default: true
- name: deathResultOfDisability
in: query
description: Include death result of disability
schema:
type: boolean
example: false
default: true
- name: survivorsAward
in: query
description: Include survivors pension award
schema:
type: boolean
example: false
default: true
responses:
'201':
description: Json representation of a letter
content:
application/json:
schema:
$ref: '#/components/schemas/LetterContentsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: Not authorized
content:
application/json:
schema:
type: string
example:
message: Invalid authentication credentials
'403':
description: Forbidden
content:
application/json:
schema:
type: string
example:
message: You cannot consume this service
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/UserNotFound'
'413':
description: Payload too large
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: Request size limit exceeded
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntity'
'429':
description: Too many requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: API rate limit exceeded
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- OAuth: []
/letters/{letterType}/letter:
get:
tags:
- Letters
summary: Generates PDF letters by letter type.
description: 'Returns the letters a Veteran or dependent is eligible for, with watermarks and logo, in PDF format.
| If the GET /eligible-letters endpoint returns | Generate the letter with these query parameters |
| --- | --- |
| hasServiceConnectedDisabilities | serviceConnectedDisabilities |
| serviceConnectedPercentage | serviceConnectedEvaluation |
| hasNonServiceConnectedPension | nonServiceConnectedPension |
| monthlyAwardAmount<br />And<br />awardEffectiveDate | monthlyAward |
| hasIndividualUnemployabilityGranted | unemployable |
| hasSpecialMonthlyCompensation | specialMonthlyCompensation |
| hasAdaptedHousing | adaptedHousing |
| hasChapter35Eligibility | chapter35Eligibility |
| hasDeathResultOfDisability | deathResultOfDisability |
| hasSurvivorsPensionAward | survivorsAward |
'
operationId: GET:/letters/{letterType}/letter
parameters:
- name: letterType
in: path
description: Letter Type
required: true
schema:
maxLength: 64
type: string
description: 'Possible values: BENEFIT_SUMMARY, BENEFIT_SUMMARY_DEPENDENT, BENEFIT_VERIFICATION, CIVIL_SERVICE, COMMISSARY, COMMISSARY_SHORT_TERM, PROOF_OF_SERVICE, SERVICE_VERIFICATION, MEDICARE_PARTD, MINIMUM_ESSENTIAL_COVERAGE'
example: BENEFIT_SUMMARY
- name: icn
in: query
description: MPI ICN
required: true
schema:
maxLength: 17
minLength: 17
pattern: ^\d{10}V\d{6}$
type: string
example: 1000000000V100000
- name: militaryService
in: query
description: Include military service
schema:
type: boolean
example: false
default: true
- name: serviceConnectedDisabilities
in: query
description: Include service connected disabilities
schema:
type: boolean
example: false
default: true
- name: serviceConnectedEvaluation
in: query
description: Include service connected evaluation
schema:
type: boolean
example: false
default: true
- name: nonServiceConnectedPension
in: query
description: Include non-service connected pension
schema:
type: boolean
example: false
default: true
- name: monthlyAward
in: query
description: Include monthly award
schema:
type: boolean
example: false
default: true
- name: unemployable
in: query
description: Include unemployable data
schema:
type: boolean
example: false
default: true
- name: specialMonthlyCompensation
in: query
description: Include special monthly compensation
schema:
type: boolean
example: false
default: true
- name: adaptedHousing
in: query
description: Include adapted housing
schema:
type: boolean
example: false
default: true
- name: chapter35Eligibility
in: query
description: Include chapter 35 eligibility
schema:
type: boolean
example: false
default: true
- name: deathResultOfDisability
in: query
description: Include death result of disability
schema:
type: boolean
example: false
default: true
- name: survivorsAward
in: query
description: Include survivors pension award
schema:
type: boolean
example: false
default: true
responses:
'201':
description: Actual PDF File, application/pdf
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: Not authorized
content:
application/json:
schema:
type: string
example:
message: Invalid authentication credentials
'403':
description: Forbidden
content:
application/json:
schema:
type: string
example:
message: You cannot consume this service
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/UserNotFound'
'413':
description: Payload too large
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: Request size limit exceeded
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntity'
'429':
description: Too many requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: API rate limit exceeded
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- OAuth: []
components:
schemas:
LettersResponse:
required:
- benefitInformation
- letterDestination
- letters
- messages
- militaryServices
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
letters:
type: array
items:
$ref: '#/components/schemas/Letter'
letterDestination:
$ref: '#/components/schemas/LetterDestination'
militaryServices:
type: array
items:
$ref: '#/components/schemas/MilitaryService'
benefitInformation:
$ref: '#/components/schemas/BenefitInformation'
LetterDestination:
required:
- addressLine1
type: object
properties:
country:
type: string
example: USA
addressLine1:
type: string
example: 2476 MAIN STREET
addressLine2:
type: string
example: 'STE # 12'
addressLine3:
type: string
example: West
city:
type: string
example: RESTON
state:
type: string
example: VA
zipCode:
type: string
example: '12345'
fullName:
type: string
example: John A Smith
MilitaryService:
type: object
properties:
branch:
type: string
example: Army
characterOfService:
maxLength: 28
type: string
example: HONORABLE
enum:
- HONORABLE
- OTHER_THAN_HONORABLE
- UNDER_HONORABLE_CONDITIONS
- GENERAL
- UNCHARACTERIZED
- UNCHARACTERIZED_ENTRY_LEVEL
- DISHONORABLE
releasedDateTime:
type: string
format: date-time
example: '2016-02-04T17:51:56Z'
enteredDateTime:
type: string
format: date-time
example: '2016-02-04T17:51:56Z'
UnprocessableEntity:
type: object
properties:
type:
type: string
description: A URI reference that identifies the problem type.
example: https://example.net/validation-error
title:
type: string
description: A short, human-readable summary of the problem type.
example: Invalid field value
status:
type: integer
description: The HTTP status code generated by the origin server for this occurrence of the problem.
format: int32
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
example: This error occurred because of...
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
example: e6d1119e-dc91-4b4d-b583-0f309de0807b
debuggingPayload:
type: string
description: Encrypted message to assist with debugging that occur while generating letters.
example: VkEgUHJvZmlsZSBDb250YWN0IEluZm9ybWF0aW9uIF...
example:
type: https://api.va.gov/services/va-letter-generator/errors/va-profile/address-exception
title: Va Profile address invalid
status: 422
detail: No zipCode5 provided for domestic address
instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
BenefitInformation:
type: object
properties:
serviceConnectedPercentage:
type: integer
format: int32
example: 2
awardEffectiveDateTime:
type: string
format: date-time
example: '2016-02-04T17:51:56Z'
monthlyAwardAmount:
$ref: '#/components/schemas/MonetaryAmount'
serviceConnectedDisabilities:
type: boolean
example: true
nonServiceConnectedPension:
type: boolean
example: false
individualUnemployabilityGranted:
type: boolean
example: false
chapter35Eligibility:
type: boolean
example: true
specialMonthlyCompensation:
type: boolean
example: false
adaptedHousing:
type: boolean
example: false
chapter35EligibilityDateTime:
type: string
format: date-time
example: '2016-02-04T17:51:56Z'
hasDeathResultOfDisability:
type: boolean
example: false
hasSurvivorsIndemnityCompensationAward:
type: boolean
example: false
hasSurvivorsPensionAward:
type: boolean
example: false
Letter:
type: object
properties:
letterName:
type: string
example: Benefit Summary Dependent
letterType:
type: string
description: 'Possible values: BENEFIT_SUMMARY, BENEFIT_SUMMARY_DEPENDENT, BENEFIT_VERIFICATION, CIVIL_SERVICE, COMMISSARY, COMMISSARY_SHORT_TERM, PROOF_OF_SERVICE, SERVICE_VERIFICATION, MEDICARE_PARTD, MINIMUM_ESSENTIAL_COVERAGE'
example: BENEFIT_SUMMARY_DEPENDENT
LetterContent:
type: object
properties:
contentKey:
type: string
example: gross-benefit
contentTitle:
type: string
example: Gross Benefit Amount
content:
type: string
example: $1,288.03
InternalServerError:
type: object
properties:
type:
type: string
description: A URI reference that identifies the problem type.
example: https://example.net/validation-error
title:
type: string
description: A short, human-readable summary of the problem type.
example: Invalid field value
status:
type: integer
description: The HTTP status code generated by the origin server for this occurrence of the problem.
format: int32
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
example: This error occurred because of...
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
example: e6d1119e-dc91-4b4d-b583-0f309de0807b
example:
type: https://api.va.gov/services/letters/errors/generic/internal-server-error
title: Internal Server Error
status: 500
detail: Internal Server Error
instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
NotAcceptable:
type: object
properties:
type:
type: string
description: A URI reference that identifies the problem type.
example: https://example.net/validation-error
title:
type: string
description: A short, human-readable summary of the problem type.
example: Invalid field value
status:
type: integer
description: The HTTP status code generated by the origin server for this occurrence of the problem.
format: int32
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
example: This error occurred because of...
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
example: e6d1119e-dc91-4b4d-b583-0f309de0807b
example:
type: https://api.va.gov/services/letters/v1/api-schema/errors/not-acceptable
title: Media type not acceptable
status: 406
detail: Could not find acceptable representation
instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
BadRequest:
type: object
properties:
type:
type: string
description: A URI reference that identifies the problem type.
example: https://example.net/validation-error
title:
type: string
description: A short, human-readable summary of the problem type.
example: Invalid field value
status:
type: integer
description: The HTTP status code generated by the origin server for this occurrence of the problem.
format: int32
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
example: This error occurred because of...
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
example: e6d1119e-dc91-4b4d-b583-0f309de0807b
example:
type: https://api.va.gov/services/letters/v1/api-schema/errors/constraint-violation
title: Invalid field value
status: 400
detail: Data in request is malformed
LetterContentsResponse:
type: object
properties:
letterDescription:
type: string
example: This letter shows the benefits you're receiving from VA. The letter also shows your benefit gross amount (the amount before anything is taken out) and net amount (the amount after deductions are taken out), your benefit effective date, and your disability rating.
letterContent:
type: array
items:
$ref: '#/components/schemas/LetterContent'
MonetaryAmount:
type: object
properties:
value:
type: number
format: double
example: 2673
currency:
type: string
example: USD
Message:
type: object
properties:
key:
type: string
example: letterGeneration.letterEligibilityError
text:
type: string
example: string
severity:
type: string
example: WARN
enum:
- FATAL
- ERROR
- WARN
- INFO
UserNotFound:
type: object
properties:
type:
type: string
description: A URI reference that identifies the problem type.
example: https://example.net/validation-error
title:
type: string
description: A short, human-readable summary of the problem type.
example: Invalid field value
status:
type: integer
description: The HTTP status code generated by the origin server for this occurrence of the problem.
format: int32
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
example: This error occurred because of...
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
example: e6d1119e-dc91-4b4d-b583-0f309de0807b
example:
type: https://api.va.gov/services/va-letter-generator/errors/generic/not-found
title: Person for ICN not found
status: 404
detail: No data found for ICN
instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
securitySchemes:
apikey:
type: apiKey
name: apikey
in: header