VA Lighthouse Disability Compensation Claims API

openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver Disability Compensation Claims 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: Disability Compensation Claims
  description: 'Allows authenticated and authorized users to automatically establish a Disability Compensation Claim (21-526EZ) in VBMS

    '
paths:
  /veterans/{veteranId}/526/synchronous:
    post:
      summary: Submits disability compensation claim synchronously (restricted access)
      tags:
      - Disability Compensation Claims
      operationId: POST:/veterans/{veteranId}/526/synchronous
      security:
      - productionOauth:
        - system/526.override
      - sandboxOauth:
        - system/526.override
      description: "Automatically establishes a disability compensation claim (21-526EZ) in Veterans Benefits Management System (VBMS). This endpoint synchronously generates a filled and electronically signed 526EZ form and establishes the disability claim in VBMS. The 526EZ form is uploaded asynchronously.\n\nA 202 response indicates the API submission was accepted and the claim was established in VBMS. Check claim status using the GET veterans/{veteranId}/claims/{id} endpoint. The claim status details response will return the associated 526EZ PDF in the supportingDocuments list.\n\n**A substantially complete 526EZ claim must include:**\n* Veteran's name\n* Sufficient service information for VA to verify the claimed service\n* At least one claimed disability or medical condition and how it relates to service\n* Veteran and/or Representative signature\n\n**Standard and fully developed claims (FDCs)**\n\n[Fully developed claims (FDCs)](https://www.va.gov/disability/how-to-file-claim/evidence-needed/fully-developed-claims/)\nare claims certified by the submitter to include all information needed for processing. These claims process faster \nthan claims submitted through the standard claim process. If a claim is certified for the FDC, but is missing needed information, \nit will be processed as a standard claim.\n\nTo certify a claim for the FDC process, set the claimProcessType to FDC_PROGRAM.\n"
      parameters:
      - name: veteranId
        in: path
        required: true
        example: 1012667145V762142
        description: ID of claimant
        schema:
          type: string
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              examples:
                202 without a transactionId:
                  value:
                    data:
                      id: 00000000-0000-0000-0000-000000000001
                      type: forms/526
                      attributes:
                        claimId: '600442191'
                        claimProcessType: STANDARD_CLAIM_PROCESS
                        claimNotes: Some things that are important to know, and are not included in any other place.
                        veteranIdentification:
                          serviceNumber: '123456789'
                          veteranNumber:
                            telephone: '5555555555'
                            internationalTelephone: +44 20 1234 5678
                          mailingAddress:
                            addressLine1: 1234 Couch Street
                            addressLine2: Unit 4
                            addressLine3: Room 1
                            city: Schenectady
                            state: NY
                            country: USA
                            zipFirstFive: '12345'
                            zipLastFour: '1234'
                          emailAddress:
                            email: valid@somedomain.com
                            agreeToEmailRelatedToClaim: true
                          currentVaEmployee: false
                        changeOfAddress:
                          typeOfAddressChange: TEMPORARY
                          addressLine1: 10 Peach St
                          addressLine2: Unit 4
                          addressLine3: Room 1
                          city: Schenectady
                          state: NY
                          country: USA
                          zipFirstFive: '12345'
                          zipLastFour: '9897'
                          dates:
                            beginDate: '2025-12-31'
                            endDate: '2025-12-31'
                        homeless:
                          isCurrentlyHomeless: true
                          currentlyHomeless:
                            homelessSituationOptions: FLEEING_CURRENT_RESIDENCE
                            otherDescription: ABCDEFGHIJKLM
                          isAtRiskOfBecomingHomeless: false
                          pointOfContact: john stewart
                          pointOfContactNumber:
                            telephone: '5555555555'
                            internationalTelephone: +44 20 1234 5678
                        toxicExposure:
                          gulfWarHazardService:
                            servedInGulfWarHazardLocations: 'YES'
                            serviceDates:
                              beginDate: 2018-07
                              endDate: 2018-08
                          herbicideHazardService:
                            servedInHerbicideHazardLocations: 'YES'
                            otherLocationsServed: ABCDEFGHIJKLM
                            serviceDates:
                              beginDate: 2018-07
                              endDate: 2018-08
                          additionalHazardExposures:
                            additionalExposures:
                            - ASBESTOS
                            - SHIPBOARD_HAZARD_AND_DEFENSE
                            specifyOtherExposures: Other exposure details
                            exposureDates:
                              beginDate: 2018-07
                              endDate: 2018-08
                          multipleExposures:
                          - hazardExposedTo: RADIATION
                            exposureLocation: Guam
                            exposureDates:
                              beginDate: 2012-12
                              endDate: 2013-07
                        disabilities:
                        - name: Traumatic Brain Injury
                          exposureOrEventOrInjury: EXPOSURE
                          serviceRelevance: ABCDEFG
                          approximateDate: '2018-03-11'
                          disabilityActionType: NEW
                          classificationCode: '9014'
                          ratedDisabilityId: ABCDEFGHIJKLMNOPQRSTUVWX
                          diagnosticCode: 9020
                          isRelatedToToxicExposure: true
                          secondaryDisabilities:
                          - name: Post Traumatic Stress Disorder (PTSD) Combat - Mental Disorders
                            exposureOrEventOrInjury: EXPOSURE
                            serviceRelevance: ABCDEFGHIJKLMNOPQ
                            disabilityActionType: SECONDARY
                            approximateDate: '2018-03-12'
                            classificationCode: '9014'
                        - name: Cancer - Musculoskeletal - Elbow
                          exposureOrEventOrInjury: EXPOSURE
                          approximateDate: '2018-03-02'
                          serviceRelevance: ABCDEFG
                          disabilityActionType: NEW
                          classificationCode: '9014'
                          ratedDisabilityId: ABCDEFGHIJKLMNOPQRSTUVWX
                          diagnosticCode: 249470
                          isRelatedToToxicExposure: true
                        - name: Cancer - Musculoskeletal - Knee
                          exposureOrEventOrInjury: EXPOSURE
                          approximateDate: '2015'
                          serviceRelevance: ABCDEFG
                          disabilityActionType: NEW
                          classificationCode: '9014'
                          ratedDisabilityId: ABCDEFGHIJKLMNOPQRSTUVWX
                          diagnosticCode: 249470
                          isRelatedToToxicExposure: true
                        treatments:
                        - beginDate: 2009-03
                          treatedDisabilityNames:
                          - Traumatic Brain Injury
                          - Post Traumatic Stress Disorder (PTSD) Combat - Mental Disorders
                          - Cancer - Musculoskeletal - Elbow
                          center:
                            name: Center One
                            city: Decatur
                            state: GA
                        serviceInformation:
                          alternateNames:
                          - john jacob
                          - johnny smith
                          servicePeriods:
                          - serviceBranch: Public Health Service
                            serviceComponent: Active
                            activeDutyBeginDate: '2008-11-14'
                            activeDutyEndDate: '2023-10-30'
                            separationLocationCode: '98282'
                          servedInActiveCombatSince911: 'NO'
                          reservesNationalGuardService:
                            component: National Guard
                            obligationTermsOfService:
                              beginDate: '2019-06-04'
                              endDate: '2020-06-04'
                            unitName: National Guard Unit Name
                            unitAddress: 1243 pine court
                            unitPhone:
                              areaCode: '555'
                              phoneNumber: '5555555'
                            receivingInactiveDutyTrainingPay: 'YES'
                          federalActivation:
                            activationDate: '2023-10-01'
                            anticipatedSeparationDate: '2025-12-31'
                          confinements:
                          - approximateBeginDate: '2018-06-04'
                            approximateEndDate: '2018-07-04'
                          - approximateBeginDate: 2020-06
                            approximateEndDate: 2020-07
                        servicePay:
                          receivingMilitaryRetiredPay: 'NO'
                          futureMilitaryRetiredPay: 'YES'
                          futureMilitaryRetiredPayExplanation: ABCDEFGHIJKLMNOPQRSTUVW
                          militaryRetiredPay:
                            branchOfService: Army
                            monthlyAmount: 840
                          retiredStatus: PERMANENT_DISABILITY_RETIRED_LIST
                          favorMilitaryRetiredPay: false
                          receivedSeparationOrSeverancePay: 'NO'
                          separationSeverancePay:
                            datePaymentReceived: '2022-03-12'
                            branchOfService: Naval Academy
                            preTaxAmountReceived: 379
                          favorTrainingPay: true
                        directDeposit:
                          noAccount: false
                          accountNumber: ABCDEF
                          accountType: CHECKING
                          financialInstitutionName: Chase
                          routingNumber: '123123123'
                        claimantCertification: true
                202 with a transactionId:
                  value:
                    data:
                      id: 00000000-0000-0000-0000-000000000002
                      type: forms/526
                      attributes:
                        claimId: '600442191'
                        claimProcessType: STANDARD_CLAIM_PROCESS
                        claimNotes: Some things that are important to know, and are not included in any other place.
                        veteranIdentification:
                          serviceNumber: '123456789'
                          veteranNumber:
                            telephone: '5555555555'
                            internationalTelephone: +44 20 1234 5678
                          mailingAddress:
                            addressLine1: 1234 Couch Street
                            addressLine2: Unit 4
                            addressLine3: Room 1
                            city: Schenectady
                            state: NY
                            country: USA
                            zipFirstFive: '12345'
                            zipLastFour: '1234'
                          emailAddress:
                            email: valid@somedomain.com
                            agreeToEmailRelatedToClaim: true
                          currentVaEmployee: false
                        changeOfAddress:
                          typeOfAddressChange: TEMPORARY
                          addressLine1: 10 Peach St
                          addressLine2: Unit 4
                          addressLine3: Room 1
                          city: Schenectady
                          state: NY
                          country: USA
                          zipFirstFive: '12345'
                          zipLastFour: '9897'
                          dates:
                            beginDate: '2025-12-31'
                            endDate: '2025-12-31'
                        homeless:
                          isCurrentlyHomeless: true
                          currentlyHomeless:
                            homelessSituationOptions: FLEEING_CURRENT_RESIDENCE
                            otherDescription: ABCDEFGHIJKLM
                          isAtRiskOfBecomingHomeless: false
                          pointOfContact: john stewart
                          pointOfContactNumber:
                            telephone: '5555555555'
                            internationalTelephone: +44 20 1234 5678
                        toxicExposure:
                          gulfWarHazardService:
                            servedInGulfWarHazardLocations: 'YES'
                            serviceDates:
                              beginDate: 2018-07
                              endDate: 2018-08
                          herbicideHazardService:
                            servedInHerbicideHazardLocations: 'YES'
                            otherLocationsServed: ABCDEFGHIJKLM
                            serviceDates:
                              beginDate: 2018-07
                              endDate: 2018-08
                          additionalHazardExposures:
                            additionalExposures:
                            - ASBESTOS
                            - SHIPBOARD_HAZARD_AND_DEFENSE
                            specifyOtherExposures: Other exposure details
                            exposureDates:
                              beginDate: 2018-07
                              endDate: 2018-08
                          multipleExposures:
                          - hazardExposedTo: RADIATION
                            exposureLocation: Guam
                            exposureDates:
                              beginDate: 2012-12
                              endDate: 2013-07
                        disabilities:
                        - name: Traumatic Brain Injury
                          exposureOrEventOrInjury: EXPOSURE
                          serviceRelevance: ABCDEFG
                          approximateDate: '2018-03-11'
                          disabilityActionType: NEW
                          classificationCode: '9014'
                          ratedDisabilityId: ABCDEFGHIJKLMNOPQRSTUVWX
                          diagnosticCode: 9020
                          isRelatedToToxicExposure: true
                          secondaryDisabilities:
                          - name: Post Traumatic Stress Disorder (PTSD) Combat - Mental Disorders
                            exposureOrEventOrInjury: EXPOSURE
                            serviceRelevance: ABCDEFGHIJKLMNOPQ
                            disabilityActionType: SECONDARY
                            approximateDate: '2018-03-12'
                            classificationCode: '9014'
                        - name: Cancer - Musculoskeletal - Elbow
                          exposureOrEventOrInjury: EXPOSURE
                          approximateDate: '2018-03-02'
                          serviceRelevance: ABCDEFG
                          disabilityActionType: NEW
                          classificationCode: '9014'
                          ratedDisabilityId: ABCDEFGHIJKLMNOPQRSTUVWX
                          diagnosticCode: 249470
                          isRelatedToToxicExposure: true
                        - name: Cancer - Musculoskeletal - Knee
                          exposureOrEventOrInjury: EXPOSURE
                          approximateDate: '2015'
                          serviceRelevance: ABCDEFG
                          disabilityActionType: NEW
                          classificationCode: '9014'
                          ratedDisabilityId: ABCDEFGHIJKLMNOPQRSTUVWX
                          diagnosticCode: 249470
                          isRelatedToToxicExposure: true
                        treatments:
                        - beginDate: 2009-03
                          treatedDisabilityNames:
                          - Traumatic Brain Injury
                          - Post Traumatic Stress Disorder (PTSD) Combat - Mental Disorders
                          - Cancer - Musculoskeletal - Elbow
                          center:
                            name: Center One
                            city: Decatur
                            state: GA
                        serviceInformation:
                          alternateNames:
                          - john jacob
                          - johnny smith
                          servicePeriods:
                          - serviceBranch: Public Health Service
                            serviceComponent: Active
                            activeDutyBeginDate: '2008-11-14'
                            activeDutyEndDate: '2025-12-31'
                            separationLocationCode: '98282'
                          servedInActiveCombatSince911: 'NO'
                          reservesNationalGuardService:
                            component: National Guard
                            obligationTermsOfService:
                              beginDate: '2019-06-04'
                              endDate: '2020-06-04'
                            unitName: National Guard Unit Name
                            unitAddress: 1243 pine court
                            unitPhone:
                              areaCode: '555'
                              phoneNumber: '5555555'
                            receivingInactiveDutyTrainingPay: 'YES'
                          federalActivation:
                            activationDate: '2023-10-01'
                            anticipatedSeparationDate: '2025-12-31'
                          confinements:
                          - approximateBeginDate: '2018-06-04'
                            approximateEndDate: '2018-07-04'
                          - approximateBeginDate: 2020-06
                            approximateEndDate: 2020-07
                        servicePay:
                          receivingMilitaryRetiredPay: 'NO'
                          futureMilitaryRetiredPay: 'YES'
                          futureMilitaryRetiredPayExplanation: ABCDEFGHIJKLMNOPQRSTUVW
                          militaryRetiredPay:
                            branchOfService: Army
                            monthlyAmount: 840
                          retiredStatus: PERMANENT_DISABILITY_RETIRED_LIST
                          favorMilitaryRetiredPay: false
                          receivedSeparationOrSeverancePay: 'NO'
                          separationSeverancePay:
                            datePaymentReceived: '2022-03-12'
                            branchOfService: Naval Academy
                            preTaxAmountReceived: 379
                          favorTrainingPay: true
                        directDeposit:
                          noAccount: false
                          accountNumber: ABCDEF
                          accountType: CHECKING
                          financialInstitutionName: Chase
                          routingNumber: '123123123'
                        claimantCertification: true
                    meta:
                      transactionId: 00000000-0000-0000-0000-000000000003
              schema:
                name: data
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - id
                    - type
                    - attributes
                    properties:
                      id:
                        type: string
                        example: 00000000-0000-0000-0000-000000000004
                      type:
                        type: string
                        example: form/8675309
                      attributes:
                        description: Claims API 526 Schema
                        type: object
                        additionalProperties: false
                        required:
                        - claimProcessType
                        - disabilities
                        - serviceInformation
                        - veteranIdentification
                        properties:
                          claimProcessType:
                            type: string
                            description: Select type of claim program/process that applies to the Veteran.
                            enum:
                            - STANDARD_CLAIM_PROCESS
                            - FDC_PROGRAM
                            - BDD_PROGRAM
                          veteranIdentification:
                            type: object
                            additionalProperties: false
                            required:
                            - mailingAddress
                            - currentVaEmployee
                            properties:
                              serviceNumber:
                                type: string
                                description: Service identification number
                                maxLength: 1000
                                nullable: true
                              veteranNumber:
                                description: If there isn't a ten digit phone number in VBMS for the Veteran, the exams will not be ordered. Including the phone number is recommended to avoid claim processing delays.
                                type: object
                                nullable: true
                                properties:
                                  telephone:
                                    description: Veteran's phone number.
                                    type: string
                                    pattern: ^\d{10}?$
                                    example: '5555555555'
                                    nullable: true
                                  internationalTelephone:
                                    type: string
                                    description: Veteran's international phone number.
                                    example: +44 20 1234 5678
                                    maxLength: 1000
                                    nullable: true
                              mailingAddress:
                                type: object
                                additionalProperties: false
                                required:
                                - addressLine1
                                - city
                                - country
                                properties:
                                  addressLine1:
                                    description: Address line 1 for the Veteran's current mailing address.
                                    type: string
                                    pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$
                                    maxLength: 20
                                    example: 1234 Couch Street
                                  addressLine2:
                                    description: Address line 2 for the Veteran's current mailing address.
                                    type: string
                                    pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$
                                    maxLength: 20
                                    example: Unit 4
                                    nullable: true
                                  addressLine3:
                                    description: Address line 3 for the Veteran's current mailing address.
                                    type: string
                                    pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$
                                    maxLength: 20
                                    example: Room 1
                                    nullable: true
                                  city:
                                    description: City for the Veteran's current mailing address.
                                    type: string
                                    pattern: ^$|([a-zA-Z0-9\'-'.# ]([a-zA-Z0-9\'-'.# ])?)+$
                                    minLength: 1
                                    maxLength: 20
                                    example: Schenectady
                                  state:
                                    description: State for the Veteran's current mailing address. Required if 'country' is 'USA'.
                                    type: string
                                    pattern: ^[a-z,A-Z]{2}$
                                    example: NY
                                    nullable: true
                                  country:
                                    description: Country for the Veteran's current mailing address.  Must match the values returned by the /countries endpoint on the [Benefits Reference Data API](https://developer.va.gov/explore/benefits/docs/benefits_reference_data?version=current).
                                    type: string
                                    maxLength: 1000
                                    example: USA
                                  zipFirstFive:
                                    description: Zip code (First 5 digits) for the Veteran's current mailing address. Required if 'country' is 'USA'.
                                    type: string
                                    pattern: ^\d{5}?$
                                    example: '12345'
                                    nullable: true
                                  zipLastFour:
                                    description: Zip code (Last 4 digits) for the Veteran's current mailing address.
                                    type: string
                                    pattern: ^\d{4}?$
                                    example: '6789'
                                    nullable: true
                                  internationalPostalCode:
                                    description: International postal code for the Veteran's current mailing address. Do not include if 'country' is 'USA'.
                                    type: string
                                    maxLength: 16
                                    nullable: true
                                    pattern: ^[a-zA-Z0-9]*$
                              emailAddress:
                                description: Information associated with the Veteran's email address.
                                type: object
                                nullable: true
                                properties:
                                  email:
                                    type: string
                                    pattern: ^[^\s@]+@([^\s@.,]+\.)+[^\s@.,]{2,}$
                                    description: The most current email address of the Veteran.
                                    maxLength: 80
                                    nullable: true
                                  agreeToEmailRelatedToClaim:
                                    type: boolean
                                    description: Agreement to email 

# --- truncated at 32 KB (309 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va-gov/refs/heads/main/openapi/va-gov-disability-compensation-claims-api-openapi.yml