VA Lighthouse Power of Attorney API

openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver Power of Attorney 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: Power of Attorney
  description: Used for 21-22 and 21-22a form submissions.
paths:
  /forms/2122:
    get:
      summary: Gets schema for POA form.
      deprecated: true
      tags:
      - Power of Attorney
      operationId: GET:/forms/2122
      description: Returns schema to automatically generate a POA form.
      responses:
        '200':
          description: schema response
          content:
            application/json:
              example:
                data:
                - $schema: http://json-schema.org/draft-07/schema#
                  description: Form 2122 Schema
                  type: object
                  additionalProperties: false
                  required:
                  - serviceOrganization
                  properties:
                    veteran:
                      type: object
                      additionalProperties: false
                      required:
                      - address
                      properties:
                        address:
                          type: object
                          additionalProperties: false
                          required:
                          - numberAndStreet
                          - city
                          - country
                          allOf:
                          - if:
                              properties:
                                country:
                                  const: US
                            then:
                              required:
                              - zipFirstFive
                          properties:
                            numberAndStreet:
                              description: Street address with number and name.
                              type: string
                              pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$
                              maxLength: 30
                            aptUnitNumber:
                              oneOf:
                              - type: integer
                              - type: string
                            city:
                              description: City for the address.
                              type: string
                              example: Portland
                            state:
                              description: State or province for the address.
                              type: string
                              example: OR
                            country:
                              description: Country of the address.
                              type: string
                              example: US
                            zipFirstFive:
                              description: Zip code (First 5 digits) of the address. Required if country is 'US'.
                              type: string
                              pattern: ^\d{5}?$
                              example: '12345'
                            zipLastFour:
                              description: Zip code (Last 4 digits) of the address.
                              type: string
                              pattern: ^\d{4}?$
                              example: '6789'
                        phone:
                          $comment: the phone fields must not exceed 20 chars, when concatenated
                          type: object
                          additionalProperties: false
                          required:
                          - phoneNumber
                          properties:
                            countryCode:
                              description: Country code of the phone number. Required for international phone numbers.
                              type: string
                              pattern: ^[0-9]+$
                            areaCode:
                              description: Area code of the phone number. Required if countryCode is '1' or not included.
                              type: string
                              pattern: ^[2-9][0-9]{2}$
                              example: '555'
                            phoneNumber:
                              description: Phone number.
                              type: string
                              pattern: ^[0-9]{1,14}$
                              example: '5555555'
                            phoneNumberExt:
                              type: string
                              pattern: ^[a-zA-Z0-9]{1,10}$
                          if:
                            properties:
                              countryCode:
                                anyOf:
                                - type: string
                                  enum:
                                  - '1'
                          then:
                            required:
                            - areaCode
                          else:
                            anyOf:
                            - required:
                              - countryCode
                            - required:
                              - areaCode
                        email:
                          description: Email address of the veteran.
                          type: string
                          pattern: .@.
                          maxLength: 61
                          example: veteran@example.com
                        serviceBranch:
                          description: Service Branch for the veteran.
                          type: string
                          enum:
                          - AIR FORCE
                          - ARMY
                          - COAST GUARD
                          - MARINE CORPS
                          - NAVY
                          - SPACE FORCE
                          - OTHER
                          example: ARMY
                        serviceBranchOther:
                          description: For a 'service branch' of value 'other', please provide the service branch name.
                          type: string
                          maxLength: 50
                          example: Air National Guard
                    claimant:
                      type: object
                      additionalProperties: false
                      required:
                      - firstName
                      - lastName
                      - address
                      - relationship
                      properties:
                        firstName:
                          description: First name of Claimant.
                          type: string
                          example: John
                        middleInitial:
                          description: Middle initial of Claimant.
                          type: string
                          example: M
                        lastName:
                          description: Last name of Claimant.
                          type: string
                          example: Dow
                        address:
                          type: object
                          additionalProperties: false
                          required:
                          - numberAndStreet
                          - city
                          - country
                          allOf:
                          - if:
                              properties:
                                country:
                                  const: US
                            then:
                              required:
                              - zipFirstFive
                          properties:
                            numberAndStreet:
                              description: Street address with number and name.
                              type: string
                              pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$
                              maxLength: 30
                            aptUnitNumber:
                              oneOf:
                              - type: integer
                              - type: string
                            city:
                              description: City for the address.
                              type: string
                              example: Portland
                            state:
                              description: State or province for the address.
                              type: string
                              example: OR
                            country:
                              description: Country of the address.
                              type: string
                              example: US
                            zipFirstFive:
                              description: Zip code (First 5 digits) of the address. Required if country is 'US'.
                              type: string
                              pattern: ^\d{5}?$
                              example: '12345'
                            zipLastFour:
                              description: Zip code (Last 4 digits) of the address.
                              type: string
                              pattern: ^\d{4}?$
                              example: '6789'
                            additionalProperties:
                              type: boolean
                        phone:
                          $comment: the phone fields must not exceed 20 chars, when concatenated
                          type: object
                          additionalProperties: false
                          required:
                          - phoneNumber
                          properties:
                            countryCode:
                              description: Country code of the phone number. Required for international phone numbers.
                              type: string
                              pattern: ^[0-9]+$
                            areaCode:
                              description: Area code of the phone number. Required if countryCode is '1' or not included.
                              type: string
                              pattern: ^[2-9][0-9]{2}$
                              example: '555'
                            phoneNumber:
                              description: Phone number.
                              type: string
                              pattern: ^[0-9]{1,14}$
                              example: '5555555'
                            phoneNumberExt:
                              type: string
                              pattern: ^[a-zA-Z0-9]{1,10}$
                          if:
                            properties:
                              countryCode:
                                anyOf:
                                - type: string
                                  enum:
                                  - '1'
                          then:
                            required:
                            - areaCode
                          else:
                            anyOf:
                            - required:
                              - countryCode
                            - required:
                              - areaCode
                        email:
                          description: Email address of the claimant.
                          type: string
                          pattern: .@.
                          maxLength: 61
                          example: claimant@example.com
                        relationship:
                          description: Relationship of claimant to the veteran.
                          type: string
                          example: Spouse
                    serviceOrganization:
                      description: Details of the service organization or individual representing the veteran.
                      type: object
                      additionalProperties: false
                      required:
                      - poaCode
                      properties:
                        poaCode:
                          description: The POA code of the organization or individual representative
                          type: string
                          example: A1Q
                        organizationName:
                          description: Name of the service organization.
                          type: string
                          example: I help vets LLC.
                        firstName:
                          description: First Name of the representative
                          type: string
                          example: John
                        lastName:
                          description: Last Name of the representative
                          type: string
                          example: Doe
                        jobTitle:
                          description: Job title of the representative
                          type: string
                          example: Veteran Service representative
                        address:
                          type: object
                          description: address details for an individual representative
                          additionalProperties: false
                          required:
                          - numberAndStreet
                          - city
                          - country
                          allOf:
                          - if:
                              properties:
                                country:
                                  const: US
                            then:
                              required:
                              - zipFirstFive
                          properties:
                            numberAndStreet:
                              description: Street address with number and name.
                              type: string
                              pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$
                              maxLength: 30
                            aptUnitNumber:
                              oneOf:
                              - type: integer
                              - type: string
                            city:
                              description: City for the address.
                              type: string
                              example: Portland
                            state:
                              description: State or province for the address.
                              type: string
                              example: OR
                            country:
                              description: Country of the address.
                              type: string
                              example: US
                            zipFirstFive:
                              description: Zip code (First 5 digits) of the address. Required if country is 'US'.
                              type: string
                              pattern: ^\d{5}?$
                              example: '12345'
                            zipLastFour:
                              description: Zip code (Last 4 digits) of the address.
                              type: string
                              pattern: ^\d{4}?$
                              example: '6789'
                            additionalProperties:
                              type: boolean
                        email:
                          description: Email address of the service organization or representative.
                          type: string
                          pattern: .@.
                          maxLength: 61
                          example: veteran_representative@example.com
                        appointmentDate:
                          description: Date of appointment with Veteran.
                          type: string
                          pattern: ^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$
                    recordConsent:
                      description: AUTHORIZATION FOR REPRESENTATIVE'S ACCESS TO RECORDS PROTECTED BY SECTION 7332, TITLE 38, U.S.C.
                      type: boolean
                    consentLimits:
                      description: Consent in Item 19 for the disclosure of records relating to treatment for drug abuse, alcoholism or alcohol abuse, infection with the human immunodeficiency virus (HIV), or sickle cell anemia is limited as follows.
                      type: array
                      items:
                        type: string
                        enum:
                        - DRUG ABUSE
                        - ALCOHOLISM
                        - HIV
                        - SICKLE CELL
                      example: DRUG ABUSE
                    consentAddressChange:
                      description: AUTHORIZATION FOR REPRESENTATIVE TO ACT ON CLAIMANT'S BEHALF TO CHANGE CLAIMANT'S ADDRESS.
                      type: boolean
                    signatures:
                      type: object
                      additionalProperties: false
                      required:
                      - veteran
                      - representative
                      properties:
                        veteran:
                          description: Base64 encoded png image of the veteran or claimant signature.
                          title: Signature of the Veteran
                          type: string
                        representative:
                          description: Base64 encoded png image of the representative signature.
                          title: Signature of the Veteran Representative
                          type: string
        '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
    post:
      summary: Submit a POA form.
      tags:
      - Power of Attorney
      operationId: POST:/forms/2122
      security:
      - productionOauth:
        - claim.read
        - claim.write
      - sandboxOauth:
        - claim.read
        - claim.write
      - bearer_token: []
      description: "Signature images\n\n\n\nIf the request includes signature images for both the Veteran and the representative, the API will:\n\n   - Generate VA Form 21-22 PDF for organizations or VA Form 21-22a PDF for individual representatives.\n\n   - Automatically establish POA for the representative.\n\n\n\nThe signature can be provided in either of these formats:\n\n   - Base64-encoded image or signature block. This allows the API to auto-populate and attach the VA Form\n   21-22 without requiring a manual PDF upload.\n\n   - PDF of VA Form 21-22 with an ink signature. This should be attached using the PUT /forms/2122/{id}\n   endpoint.\n\n\n\n   If signature images are not included in the initial request, the response will return an id which must be\n   used to submit the signed PDF via the PUT /forms/2122/{id} endpoint.\n\n\n\nDependent claimant information:\n\n   - If dependent claimant information is included in the request, the dependentʼs relationship to the Veteran\n   will be validated.\n\n   - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n\n\nResponse information:\n\n   - A successful submission returns a 200 response, indicating that the request was successfully processed.\n\n   - A 200 response does not confirm that the POA has been appointed.\n\n   - To check the status of a POA submission, use the GET /forms/2122/{id} endpoint.\n\n"
      parameters:
      - in: header
        name: X-VA-SSN
        required: false
        description: Claimant SSN if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-First-Name
        required: false
        description: Claimant first name if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-Last-Name
        required: false
        description: Claimant last name if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-Birth-Date
        required: false
        description: Claimant birthdate if consumer is representative, in iso8601 format
        schema:
          type: string
      responses:
        '200':
          description: 2122 Response
          content:
            application/json:
              example:
                data:
                  id: 00000000-0000-0000-0000-000000000001
                  type: claims_api_power_of_attorneys
                  attributes:
                    date_request_accepted: '2024-01-01'
                    previous_poa: null
                    representative:
                      service_organization:
                        poa_code: '074'
                    status: pending
              schema:
                $schema: http://json-schema.org/draft-04/schema#
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    additionalProperties: false
                    required:
                    - id
                    - type
                    - attributes
                    properties:
                      id:
                        type: string
                        description: Power of Attorney Submission UUID
                      type:
                        type: string
                      attributes:
                        type: object
                        additionalProperties: false
                        required:
                        - status
                        - date_request_accepted
                        - representative
                        properties:
                          status:
                            type: string
                            description: Says if the power of attorney is pending, submitted, updated or errored
                            enum:
                            - pending
                            - submitted
                            - updated
                            - errored
                          date_request_accepted:
                            type: string
                            description: Date request was first accepted
                            format: date
                          representative:
                            type: object
                            additionalProperties: false
                            required:
                            - service_organization
                            properties:
                              service_organization:
                                type: object
                                additionalProperties: true
                                required:
                                - poa_code
                                properties:
                                  poa_code:
                                    type: string
                                    description: Power of Attorney Code submitted for Veteran
                          previous_poa:
                            type: string
                            nullable: true
                            description: Current or Previous Power of Attorney Code submitted for Veteran
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                errors:
                - title: Not authorized
                  detail: Not authorized
                  code: '401'
                  status: '401'
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      additionalProperties: false
                      required:
                      - title
                      - detail
                      - code
                      - status
                      properties:
                        title:
                          type: string
                          description: HTTP error title
                        detail:
                          type: string
                          description: HTTP error detail
                        code:
                          type: string
                          description: HTTP error code
                        status:
                          type: string
                          description: HTTP error code
                        source:
                          type: object
                          additionalProperties: false
                          description: Source of error
                          properties:
                            pointer:
                              type: string
                              description: Pointer to source of error
        '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:
              example:
                errors:
                - status: 422
                  detail: 'The property /serviceOrganization/poaCode did not match the following requirements: {"description"=>"The POA code of the organization or individual representative", "type"=>"string", "example"=>"A1Q"}'
                  source: /serviceOrganization/poaCode
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      additionalProperties: false
                      required:
                      - status
                      - detail
                      - source
                      properties:
                        status:
                          type: integer
                          description: HTTP error code
                        detail:
                          type: string
                          description: HTTP error detail
                        source:
                          type: string
        '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
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - attributes
                  example:
                    type: form/21-22
                    attributes:
                      serviceOrganization:
                        poaCode: A1Q
                  properties:
                    attributes:
                      $schema: http://json-schema.org/draft-07/schema#
                      description: Form 2122 Schema
                      type: o

# --- truncated at 32 KB (291 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va-gov/refs/heads/main/openapi/va-gov-power-of-attorney-api-openapi.yml