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