openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver Forms 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: Forms
paths:
  /forms:
    get:
      security:
      - apikey: []
      summary: Returns all VA Forms and their last revision date
      description: Returns an index of all available VA forms. Optionally, pass a query parameter to filter forms by form number or title.
      operationId: GET:/forms
      produces:
      - application/json
      tags:
      - Forms
      parameters:
      - name: query
        in: query
        description: Returns form data based on entered form name.
        required: false
        type: string
      responses:
        '200':
          description: VA Forms index response
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FormsIndex'
        '401':
          description: Authorization information not provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: No API key found in request
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: You cannot consume this service
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: API rate limit exceeded
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
  /forms/{form_name}:
    get:
      security:
      - apikey: []
      summary: Find form by form name
      description: Returns a single form and the full revision history
      operationId: GET:/forms/{form_name}
      tags:
      - Forms
      parameters:
      - name: form_name
        in: path
        description: The VA form_name of the form being requested. The exact form name must be passed, including proper placement of prefixes and/or hyphens.
        required: true
        example: 10-10EZ
        schema:
          type: string
      responses:
        '200':
          description: VA Form Show response
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/FormShow'
        '401':
          description: Authorization information not provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: No API key found in request
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: You cannot consume this service
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      properties:
                        message:
                          type: string
                          example: Form not found
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: API rate limit exceeded
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
components:
  schemas:
    FormsIndex:
      description: A listing of available VA forms and their location.
      properties:
        id:
          description: JSON API identifier
          type: string
          example: '5403'
        type:
          description: JSON API type specification
          type: string
          example: va_form
        attributes:
          properties:
            form_name:
              description: Name of the VA Form
              type: string
              example: 10-10EZ
            url:
              description: Web location of the form
              type: string
              example: https://www.va.gov/vaforms/medical/pdf/10-10EZ-fillable.pdf
            title:
              description: Title of the form as given by VA
              type: string
              example: Instructions and Enrollment Application for Health Benefits
            first_issued_on:
              description: The date the form first became available
              type: string
              nullable: true
              example: '2016-07-10'
              format: date
            last_revision_on:
              description: The date the form was last updated
              type: string
              nullable: true
              example: '2020-01-17'
              format: date
            pages:
              description: Number of pages contained in the form
              type: integer
              example: 5
            sha256:
              description: A sha256 hash of the form contents
              type: string
              nullable: true
              example: 6e6465e2e1c89225871daa9b6d86b92d1c263c7b02f98541212af7b35272372b
            last_sha256_change:
              description: The date of the last sha256 hash change
              type: string
              nullable: true
              example: '2019-05-30'
              format: date
            valid_pdf:
              description: A flag indicating whether the form url was confirmed as a valid download
              type: boolean
              example: 'true'
            form_usage:
              description: A description of how the form is to be used
              type: string
              nullable: true
              example: <p>Use VA Form 10-10EZ if you’re a Veteran and want to apply for VA health care. You must be enrolled in...</p>
            form_tool_intro:
              description: Introductory text describing the VA online tool for this form
              type: string
              nullable: true
              example: You can apply online instead of filling out and sending us the paper form.
            form_tool_url:
              description: Location of the online tool for this form
              type: string
              nullable: true
              example: https://www.va.gov/health-care/apply/application/introduction
            form_details_url:
              description: Location on www.va.gov of the info page for this form
              type: string
              nullable: true
              example: https://www.va.gov/find-forms/about-form-10-10ez
            form_type:
              description: VA Type of the form
              type: string
              nullable: true
              example: benefit
            language:
              description: Language code of the form
              type: string
              example: en
            deleted_at:
              description: The timestamp at which the form was deleted
              type: string
              nullable: true
              example: 'null'
              format: date-time
            related_forms:
              description: A listing of other forms that relate to current form
              type: array
              nullable: true
              items:
                type: string
                example: 10-10EZR
            benefit_categories:
              description: Listing of benefit categories and match
              type: array
              nullable: true
              items:
                properties:
                  name:
                    description: Name of the benefit category of the form
                    type: string
                    example: Health care
                  description:
                    description: Description of the benefit category of the form
                    type: string
                    example: VA health care
            va_form_administration:
              description: The VA organization that administers the form
              type: string
              nullable: true
              example: Veterans Health Administration
    FormShow:
      description: Data for a particular VA form, including form version history.
      properties:
        id:
          description: JSON API identifier
          type: string
          example: 10-10-EZ
        type:
          description: JSON API type specification
          type: string
          example: va_form
        attributes:
          properties:
            form_name:
              description: Name of the VA Form
              type: string
              example: 10-10EZ
            url:
              description: Web location of the form
              type: string
              example: https://www.va.gov/vaforms/medical/pdf/10-10EZ-fillable.pdf
            title:
              description: Title of the form as given by VA
              type: string
              example: Instructions and Enrollment Application for Health Benefits
            first_issued_on:
              description: The date the form first became available
              type: string
              nullable: true
              example: '2016-07-10'
              format: date
            last_revision_on:
              description: The date the form was last updated
              type: string
              nullable: true
              example: '2020-01-17'
              format: date
            created_at:
              description: Internal field for VA.gov use
              type: string
              nullable: true
              example: '2021-03-30T16:28:30.338Z'
              format: date-time
            pages:
              description: Number of pages contained in the form
              type: integer
              example: 5
            sha256:
              description: A sha256 hash of the form contents
              type: string
              nullable: true
              example: 5fe171299ece147e8b456961a38e17f1391026f26e9e170229317bc95d9827b7
            valid_pdf:
              description: A flag indicating whether the form url was confirmed as a valid download
              type: boolean
              example: 'true'
            form_usage:
              description: A description of how the form is to be used
              type: string
              nullable: true
              example: <p>Use VA Form 10-10EZ if you’re a Veteran and want to apply for VA health care. You must be enrolled in...</p>
            form_tool_intro:
              description: Introductory text describing the VA online tool for this form
              type: string
              nullable: true
              example: You can apply online instead of filling out and sending us the paper form.
            form_tool_url:
              description: Location of the online tool for this form
              type: string
              nullable: true
              example: https://www.va.gov/health-care/apply/application/introduction
            form_details_url:
              description: Location on www.va.gov of the info page for this form
              type: string
              nullable: true
              example: https://www.va.gov/find-forms/about-form-10-10ez
            form_type:
              description: VA Type of the form
              type: string
              nullable: true
              example: benefit
            language:
              description: Language code of the form
              type: string
              nullable: true
              example: en
            deleted_at:
              description: The timestamp at which the form was deleted
              nullable: true
              type: string
              example: null
              format: date-time
            related_forms:
              description: A listing of other forms that relate to current form
              type: array
              nullable: true
              items:
                type: string
                example: 10-10EZR
            benefit_categories:
              description: Listing of benefit categories and match
              type: array
              nullable: true
              items:
                properties:
                  name:
                    description: Name of the benefit category of the form
                    type: string
                    example: Health care
                  description:
                    description: Description of the benefit category of the form
                    type: string
                    example: VA health care
            va_form_administration:
              description: The VA organization that administers the form
              type: string
              nullable: true
              example: Veterans Health Administration
            versions:
              type: array
              nullable: true
              description: The version history of revisions to the form
              items:
                properties:
                  sha256:
                    description: A sha256 hash of the form contents for that version
                    type: string
                    example: 5fe171299ece147e8b456961a38e17f1391026f26e9e170229317bc95d9827b7
                  revision_on:
                    description: The date the sha256 hash was calculated
                    type: string
                    example: '2012-01-01'
                    format: date
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header