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|

If Using

Then Use...

|\n| :------------------------------:|:----------------------------------------------:|\n| Address Validation API v1/v2 | Contact Information API v1

Profile Service API v1/v2 |\n| Address Validation API v3 | Contact Information API v2

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: 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 examples: POA for Veteran: value: data: type: form/2122 attributes: serviceOrganization: poaCode: '074' POA for Dependent Claimant: value: data: type: form/2122 attributes: serviceOrganization: poaCode: '074' claimant: firstName: Mary lastName: Lincoln address: numberAndStreet: 123 anystreet city: anytown state: OR country: USA zipFirstFive: '12345' relationship: Spouse /forms/2122/{id}: put: summary: Upload a signed 21-22 document. tags: - Power of Attorney operationId: PUT:/forms/2122/{id} security: - productionOauth: - claim.read - claim.write - sandboxOauth: - claim.read - claim.write - bearer_token: [] description: 'Accepts a document binary as part of a multipart payload. Use this PUT endpoint after the POST endpoint for uploading the signed 21-22 PDF form. ' parameters: - name: id in: path description: UUID given when Power of Attorney was submitted required: true schema: type: string - 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-000000000002 type: claims_api_power_of_attorneys attributes: date_request_accepted: '2024-01-01' previous_poa: '074' representative: service_organization: poa_code: '074' status: submitted 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 '400': description: Bad Request content: application/json: example: errors: - title: Missing parameter detail: Must include attachment code: '108' status: '400' 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 '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 '404': description: Resource not found content: application/json: example: errors: - title: Resource not found detail: Resource not found code: '404' status: '404' 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: - title: Unprocessable Entity detail: The SSN provided does not match Master Person Index (MPI). Please correct the SSN or submit an issue at ask.va.gov or call 1-800-MyVA411 (800-698-2411) for assistance. code: '422' status: '422' 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 '424': description: Failed Dependency content: application/json: example: errors: - title: Failed Dependency detail: Failure occurred in a system dependency code: '424' status: '424' 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 '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: multipart/form-data: schema: type: object properties: attachment: type: file description: 'Attachment contents. Must be provided in binary PDF or [base64 string](https://va.ghe.com/software/vets-api/blob/master/modules/claims_api/spec/fixtures/base64pdf) format and less than 11 in x 11 in. ' required: true get: summary: Check POA status by ID. tags: - Power of Attorney operationId: GET:/forms/2122/{id} security: - productionOauth: - claim.read - sandboxOauth: - claim.read - bearer_token: [] description: Based on ID, returns a 21-22 submission and current status. parameters: - name: id in: path description: The ID of the 21-22 submission required: true schema: type: string - 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-000000000003 type: claims_api_power_of_attorneys attributes: date_request_accepted: '2024-01-01' previous_poa: '074' representative: service_organization: poa_code: '074' status: errored 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 '404': description: Resource not found content: application/json: example: errors: - title: Resource not found detail: Resource not found code: '404' status: '404' 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 '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/2122/active: get: summary: Check active POA status. tags: - Power of Attorney operationId: GET:/forms/2122/active security: - productionOauth: - claim.read - sandboxOauth: - claim.read - bearer_token: [] description: 'Returns the last active POA for a claimant. To check the status of new POA submissions, use the GET /forms/2122/{id} endpoint. ' 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: null type: claims_api_power_of_attorneys attributes: status: updated date_request_accepted: null representative: service_organization: first_name: Jane last_name: Doe organization_name: null phone_number: 555-555-5555 poa_code: A01 previous_poa: null 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: 'null' type: type: string attributes: type: object additionalProperties: false required: - status - date_request_accepted - representative properties: status: type: string description: Status of Power of Attorney establishment enum: - pending - submitted - updated - errored date_request_accepted: type: string nullable: true description: Date request was first accepted format: date representative: type: object additionalProperties: false required: - service_organization properties: service_organization: type: object additionalProperties: false required: - poa_code properties: poa_code: type: string description: Power of Attorney Code submitted for Veteran first_name: description: First name of representative, null if representative is an organization type: string nullable: true example: Jane last_name: description: Last name of representative, null if representative is an organization type: string nullable: true example: Doe organization_name: description: Name of representing organization, null if representative is an individual type: string nullable: true example: Some Great Organization phone_number: description: Phone number of representative. Can be organization or individual phone number. type: string example: 555-555-5555 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 '404': description: Resource not found content: application/json: example: errors: - title: Resource not found detail: Power of Attorney not found code: '404' status: '404' 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 '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/2122/validate: post: summary: 21-22 POA form submission test run. deprecated: true tags: - Power of Attorney operationId: POST:/forms/2122/validate security: - productionOauth: - claim.read - claim.write - sandboxOauth: - claim.read - claim.write - bearer_token: [] description: 'Test to make sure the form submission works with your parameters. ' 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: type: powerOfAttorneyValidation attributes: status: valid schema: $schema: http://json-schema.org/draft-04/schema# type: object required: - data properties: data: type: object additionalProperties: false required: - type - attributes properties: type: type: string attributes: type: object additionalProperties: false required: - status properties: status: type: string description: Says if the power of attorney is pending, submitted, updated or errored enum: - valid '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 / did not contain the required key serviceOrganization source: / 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: 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 required: true /veterans/{veteranId}/power-of-attorney: get: summary: Retrieves current power of attorney tags: - Power of Attorney operationId: GET:/veterans/{veteranId}/power-of-attorney security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] description: Retrieve a claimant’s currently appointed accredited representative with power of attorney (General POA) for the claimant. Returns empty data if no General POA is assigned. parameters: - name: veteranId in: path required: true example: 1012667145V762142 description: ID of claimant schema: type: string responses: '200': description: Successful response with a current Power of Attorney content: application/json: example: data: type: individual attributes: code: A1Q name: Firstname Lastname phoneNumber: 555-555-5555 schema: type: object required: - data properties: data: type: object additionalProperties: false required: - type - attributes properties: type: type: string nullable: true description: Type of representative, organization or individual example: individual attributes: type: object additionalProperties: false required: - code - name - phoneNumber properties: code: type: string nullable: true description: Power of Attorney Code currently assigned to Veteran name: description: Name of individual representative or organization type: string nullable: true example: Jane Smith phoneNumber: description: Phone number of representative. Can be organization or individual phone number. type: string nullable: true example: 555-555-5555 '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not retrieve Power of Attorney with code: A1Q' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status 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: - title: Unprocessable entity status: '422' detail: 'Could not retrieve Power of Attorney due to multiple representatives with code: A1Q' source: pointer: /modules/claims_api/app/controllers/claims_api/v2/veterans/power_of_attorney/base_controller.rb:191:in `representative' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '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 /veterans/{veteranId}/power-of-attorney-request: post: summary: Creates power of attorney request for an accredited representative description: Request the appointment of an accredited representative, on behalf of a claimant. tags: - Power of Attorney operationId: POST:/veterans/{veteranId}/power-of-attorney-request security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] parameters: - name: veteranId in: path required: true example: 1012667145V762142 description: ID of claimant schema: type: string responses: '201': description: Valid request response content: application/json: example: data: id: 00000000-0000-0000-0000-000000000009 type: power-of-attorney-request attributes: veteran: serviceNumber: '123678453' serviceBranch: ARMY address: addressLine1: 2719 Hyperion Ave addressLine2: Apt 2 city: Los Angeles stateCode: CA countryCode: US zipCode: '92264' zipCodeSuffix: '0200' phone: countryCode: null areaCode: '555' phoneNumber: '5551234' email: test@test.com insuranceNumber: '1234567890' claimant: claimantId: null address: addressLine1: null addressLine2: null city: null stateCode: null countryCode: null zipCode: null zipCodeSuffix: null phone: countryCode: null areaCode: null phoneNumber: null email: null relationship: null representative: poaCode: '067' recordConsent: true consentLimits: - DRUG_ABUSE - SICKLE_CELL - HIV - ALCOHOLISM consentAddressChange: true schema: type: object required: - data properties: data: type: object required: - type - attributes properties: id: type: string format: uuid type: type: string enum: - power-of-attorney-request attributes: type: object required: - veteran - claimant - representative properties: veteran: type: object properties: serviceNumber: type: string serviceBranch: type: string phone: type: object properties: countryCode: type: string areaCode: type: string phoneNumber: type: string address: type: object properties: addressLine1: type: string addressLine2: type: string city: type: string stateCode: type: string countryCode: type: string zipCode: type: string zipCodeSuffix: type: string email: type: string insuranceNumber: type: string claimant: type: object properties: claimantId: type: string phone: type: object properties: countryCode: type: string areaCode: type: string phoneNumber: type: string address: type: object properties: addressLine1: type: string addressLine2: type: string city: type: string stateCode: type: string countryCode: type: string zipCode: type: string zipCodeSuffix: type: string email: type: string relationship: type: string representative: type: object properties: poaCode: type: string consentLimits: type: array items: type: string enum: - DRUG_ABUSE - ALCOHOLISM - HIV - SICKLE_CELL consentAddressChange: description: Authorization for Representative to Act on Claimant's Behalf to Change Claimant's Address. type: boolean recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. type: boolean '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find an Accredited Representative with poa code: 067' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status 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: - title: Unprocessable entity detail: The property /representative did not contain the required key poaCode status: '422' source: pointer: data/attributes/representative schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '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 - null properties: attributes: $schema: http://json-schema.org/draft-07/schema# description: POA Request (21-22/a) Schema type: object additionalProperties: false required: - veteran - representative - recordConsent - consentAddressChange properties: veteran: type: object additionalProperties: false required: - address properties: serviceNumber: description: Service number for the veteran. type: string maxLength: 9 serviceBranch: description: Service branch for the veteran. type: string enum: - AIR_FORCE - ARMY - COAST_GUARD - MARINE_CORPS - NAVY - SPACE_FORCE - OTHER example: ARMY address: type: object additionalProperties: false required: - addressLine1 - city - stateCode - countryCode - zipCode properties: addressLine1: description: Street number and name for the veteran's address. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the veteran's address. type: string maxLength: 5 city: description: City for the veteran's address. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the veteran's address. type: string example: US pattern: ^[A-Za-z0-9-]{2,6}$ zipCode: description: Zip code (first 5 digits) for the veteran's address. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the veteran's 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 for the veteran's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the veteran's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the veteran. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the veteran. type: string pattern: .@. maxLength: 61 example: veteran@example.com insuranceNumber: type: string maxLength: 10 description: Insurance number for the veteran, if applicable. Include letter prefix. claimant: description: Include claimant information for dependent claimants. type: object additionalProperties: false properties: claimantId: description: Integration Control Number (ICN) for the dependent claimant. type: string example: '123456789' address: type: object additionalProperties: false properties: addressLine1: description: Street number and name for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the dependent claimant's address. type: string maxLength: 5 city: description: City for the dependent claimant's address. Required if claimant information provided. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the dependent claimant's address. Required if claimant information provided. type: string example: US pattern: ^[A-Za-z0-9-]{2,6}$ zipCode: description: Zip code (first 5 digits) for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the dependent claimant's 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 for the dependent claimant's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the dependent claimant's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the dependent claimant. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the dependent claimant. type: string pattern: .@. maxLength: 61 example: claimant@example.com relationship: description: Relationship of claimant to the veteran. Required if claimant information provided. type: string example: Spouse representative: description: Details of the requested Power of Attorney representing the veteran. type: object additionalProperties: false required: - poaCode properties: poaCode: description: The POA code of the accredited representative or organization. type: string example: A1Q recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. Explicitly permits the designated representative to access sensitive medical records within VA. Setting 'recordConsent' to false will prevent the designated representative from accessing the claimant's documents in VBMS. type: boolean consentLimits: description: Consent 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 to this list. Including 'consentLimits' will prevent the designated representative from accessing the claimant's documents in VBMS. 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 example: data: attributes: veteran: serviceNumber: '123678453' serviceBranch: ARMY address: addressLine1: 2719 Hyperion Ave addressLine2: Apt 2 city: Los Angeles countryCode: US stateCode: CA zipCode: '92264' zipCodeSuffix: '0200' phone: areaCode: '555' phoneNumber: '5551234' email: test@test.com insuranceNumber: '1234567890' representative: poaCode: '067' recordConsent: true consentAddressChange: true consentLimits: - DRUG_ABUSE - SICKLE_CELL - HIV - ALCOHOLISM required: true /veterans/power-of-attorney-requests: post: summary: Retrieves power of attorney requests for accredited representatives tags: - Power of Attorney operationId: POST:/veterans/power-of-attorney-requests security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] description: Search for power of attorney requests by specified POA codes. Optional filters include searching by status, city, state, and country. parameters: - name: page[size] in: query required: false example: '20' description: Number of results to return per page. Max value allowed is 100. - name: page[number] in: query required: false example: '1' description: Number of pages of results to return. Max value allowed is 100. responses: '200': description: Search results content: application/json: example: data: - id: null type: power-of-attorney-request attributes: veteran: firstName: '[Vet First Name]' middleName: null lastName: '[Vet Last Name]' claimant: firstName: '[Claimant First Name]' lastName: '[Claimant Last Name]' address: city: Charlottesville stateCode: null zipCode: '00123' countryCode: USA representative: poaCode: 083 receivedDate: '2012-11-23T16:49:16-06:00' actionedDate: '2024-05-25T13:45:00-05:00' status: New declinedReason: null consentAddressChange: true recordConsent: true - id: null type: power-of-attorney-request attributes: veteran: firstName: first middleName: null lastName: last claimant: firstName: null lastName: null address: city: USAG J stateCode: null zipCode: '01234' countryCode: USA representative: poaCode: '002' receivedDate: '2013-01-14T08:50:17-06:00' actionedDate: '2013-01-14T08:50:17-06:00' status: New declinedReason: null consentAddressChange: true recordConsent: true - id: null type: power-of-attorney-request attributes: veteran: firstName: first middleName: null lastName: last claimant: firstName: null lastName: null address: city: Bourges stateCode: null zipCode: '00123' countryCode: France representative: poaCode: '002' receivedDate: '2013-01-14T08:51:25-06:00' actionedDate: '2013-01-14T08:51:25-06:00' status: New declinedReason: null consentAddressChange: true recordConsent: true meta: pagination: pageNumber: 1 pageSize: 10 pages: 1 records: 3 schema: type: object required: - data - meta properties: data: type: array items: type: object required: - type - attributes properties: id: type: string format: uuid type: type: string enum: - power-of-attorney-request attributes: type: object required: - veteran - claimant - representative properties: veteran: type: object properties: firstName: description: First name for the veteran. type: string lastName: description: Last name for the veteran. type: string middleName: description: Middle name for the veteran. type: string claimant: type: object properties: firstName: description: First name for the dependent claimant. type: string lastName: description: Last name for the dependent claimant. type: string middleName: description: Middle name for the dependent claimant. type: string address: city: type: string country: type: string militaryPo: type: string militaryPostalCode: type: string state: type: string zip: type: string representative: type: object properties: poaCode: type: string vsoUserEmail: type: string vsoUserFirstName: type: string vsoUserLastName: type: string receivedDate: description: Date the request for representation was established. type: string format: date-time actionedDate: description: Date the request for representation was accepted or declined by a representative. type: string format: date-time status: description: Status of the request for representation. type: string declinedReason: description: Reason for declining the request for representation. type: string consentAddressChange: description: Authorization for Representative to Act on Claimant's Behalf to Change Claimant's Address. type: boolean enum: - true - false recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. type: boolean enum: - true - false meta: type: object required: - pagination properties: pagination: type: object required: - pageNumber - pageSize - pages - records properties: pageNumber: description: Current page number. type: integer pageSize: description: Number of results per page. type: integer pages: description: Total number of pages. type: integer records: description: Total number of records. type: integer '400': description: Invalid request content: application/json: example: errors: - title: Missing parameter detail: poaCodes is required and cannot be empty code: '108' status: '400' schema: type: object required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail - code - status properties: title: type: string detail: type: string code: type: string status: type: string enum: - '400' '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: type: object required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail - status properties: title: type: string enum: - Not authorized detail: type: string enum: - Not authorized status: type: string enum: - '401' '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 requestBody: content: application/json: schema: type: object required: - data properties: data: type: object additionalProperties: false required: - attributes properties: attributes: type: object additionalProperties: false required: - poaCodes properties: poaCodes: type: array minItems: 1 items: type: string minLength: 1 pageSize: type: string pageIndex: type: string filter: type: object additionalProperties: false properties: status: type: array items: type: string enum: - NEW - ACCEPTED - DECLINED state: type: string city: type: string country: type: string example: data: attributes: poaCodes: - '002' - '003' - 083 filter: status: - NEW - ACCEPTED - DECLINED state: OR city: Portland country: USA required: true /veterans/power-of-attorney-requests/{id}: get: summary: Retrieves a power of attorney request tags: - Power of Attorney operationId: GET:/veterans/power-of-attorney-requests/{id} security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] description: Retrieve a power of attorney request by id. parameters: - name: id in: path required: true example: 00000000-0000-0000-0000-000000000010 description: The ID of the Power of Attorney request schema: type: string responses: '200': description: Successful response with a current Power of Attorney request content: application/json: example: data: id: 00000000-0000-0000-0000-000000000011 type: power-of-attorney-request attributes: veteran: firstName: ANDREA middleName: L lastName: MITCHELL claimant: firstName: null lastName: null address: city: Portland stateCode: OR zipCode: '56789' countryCode: USA representative: poaCode: '074' receivedDate: '2024-10-30T08:22:07-05:00' actionedDate: '2025-01-09T10:19:26-06:00' status: Accepted declinedReason: null consentAddressChange: true recordConsent: true schema: type: object required: - data properties: data: type: object required: - type - attributes properties: id: type: string format: uuid type: type: string enum: - power-of-attorney-request attributes: type: object required: - veteran - claimant - representative properties: veteran: type: object properties: firstName: description: First name for the veteran. type: string lastName: description: Last name for the veteran. type: string middleName: description: Middle name for the veteran. type: string claimant: type: object properties: firstName: description: First name for the dependent claimant. type: string lastName: description: Last name for the dependent claimant. type: string middleName: description: Middle name for the dependent claimant. type: string address: city: type: string country: type: string militaryPo: type: string militaryPostalCode: type: string state: type: string zip: type: string representative: type: object properties: poaCode: type: string vsoUserEmail: type: string vsoUserFirstName: type: string vsoUserLastName: type: string receivedDate: description: Date the request for representation was established. type: string format: date-time actionedDate: description: Date the request for representation was accepted or declined by a representative. type: string format: date-time status: description: Status of the request for representation. type: string declinedReason: description: Reason for declining the request for representation. type: string consentAddressChange: description: Authorization for Representative to Act on Claimant's Behalf to Change Claimant's Address. type: boolean enum: - true - false recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. type: boolean enum: - true - false '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: type: object required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail - status properties: title: type: string enum: - Not authorized detail: type: string enum: - Not authorized status: type: string enum: - '401' '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find Power of Attorney Request with id: 12e13134-7229-4e44-90ae-bcea2a4525fa' schema: type: object required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail - status properties: title: type: string enum: - Resource not found detail: type: string status: type: string enum: - '404' '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 /veterans/power-of-attorney-requests/{id}/decide: post: summary: Submits representative decision for a power of attorney request tags: - Power of Attorney operationId: POST:/veterans/power-of-attorney-requests/{id}/decide security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] description: Approve or decline a power of attorney request. If approved, the power of attorney request will be submitted to VA. The claimant will be notified of the decision by email. parameters: - name: id in: path required: true example: 00000000-0000-0000-0000-000000000012 description: The ID of the request for representation schema: type: string responses: '200': description: Submit decision content: application/json: example: data: id: 5ff6a995-5b29-4819-91af-13f1bb312fg5 type: power-of-attorney-request attributes: veteran: firstName: ANDREA middleName: L lastName: MITCHELL claimant: firstName: null lastName: null address: city: Portland stateCode: OR zipCode: '56789' countryCode: USA representative: poaCode: '074' receivedDate: '2024-10-30T08:22:07-05:00' actionedDate: '2025-01-09T10:19:26-06:00' status: Accepted declinedReason: null consentAddressChange: true recordConsent: true schema: type: object required: - data properties: data: type: object required: - type - attributes properties: id: type: string format: uuid type: type: string enum: - power-of-attorney-request attributes: type: object required: - veteran - claimant - representative properties: veteran: type: object properties: firstName: description: First name for the veteran. type: string lastName: description: Last name for the veteran. type: string middleName: description: Middle name for the veteran. type: string claimant: type: object properties: firstName: description: First name for the dependent claimant. type: string lastName: description: Last name for the dependent claimant. type: string middleName: description: Middle name for the dependent claimant. type: string address: city: type: string country: type: string militaryPo: type: string militaryPostalCode: type: string state: type: string zip: type: string representative: type: object properties: poaCode: type: string vsoUserEmail: type: string vsoUserFirstName: type: string vsoUserLastName: type: string receivedDate: description: Date the request for representation was established. type: string format: date-time actionedDate: description: Date the request for representation was accepted or declined by a representative. type: string format: date-time status: description: Status of the request for representation. type: string declinedReason: description: Reason for declining the request for representation. type: string consentAddressChange: description: Authorization for Representative to Act on Claimant's Behalf to Change Claimant's Address. type: boolean enum: - true - false recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. type: boolean enum: - true - false '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: type: object required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string enum: - Not authorized detail: type: string enum: - Not authorized status: type: string enum: - '401' '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find Power of Attorney request with id: 348fa995-5b29-4819-91af-13f1bb3c7d77' schema_validation_error: summary: Schema validation error value: errors: - status: '404' title: Resource not found detail: 'Could not find Power of Attorney request with id: 348fa995-5b29-4819-91af-13f1bb3c7d77' schema: type: object required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail - status properties: title: type: string enum: - Resource not found detail: type: string status: type: string enum: - '404' '413': description: Payload too large content: application/json: schema: type: object properties: message: type: string example: message: Request size limit exceeded '422': description: Malformed request body content: application/json: example: errors: - title: Unprocessable entity status: '422' detail: 'The request body is not a valid JSON object: Hash/Object not terminated (after ) at line 1' source: pointer: ' at line 1' schema: type: object required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail - status properties: title: type: string detail: type: string source: type: object status: type: string enum: - '422' '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: $schema: http://json-schema.org/draft-07/schema# description: Power Of Attorney Request Decision type: object required: - data properties: data: type: object additionalProperties: false required: - attributes properties: attributes: type: object additionalProperties: false required: - decision - representativeId properties: decision: type: string description: The decision of the request. enum: - ACCEPTED - DECLINED declinedReason: type: string description: The reason for declining the request. nullable: true representativeId: type: string description: The unique identifier of the requestʼs representative. example: data: attributes: decision: ACCEPTED representativeId: '12345678' declinedReason: null required: true /veterans/{veteranId}/2122/validate: post: summary: Validates request to establish an organization as a claimant’s accredited representative tags: - Power of Attorney operationId: POST:/veterans/{veteranId}/2122/validate security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] parameters: - name: veteranId in: path required: true example: 1012667145V762142 description: ID of claimant schema: type: string description: 'Validate a request to establish an organization with power of attorney (VA Form 21-22). Use POST /veterans/{veteranId}/2122 to automatically establish submit VA Form 21-22. ' responses: '200': description: Valid request response content: application/json: example: data: type: form/21-22/validation attributes: status: valid schema: $schema: http://json-schema.org/draft-07/schema# type: object required: - data properties: data: type: object additionalProperties: false required: - type - attributes properties: type: type: string attributes: type: object additionalProperties: false required: - status properties: status: type: string description: Says if submission of 21-22 would work with the given parameters enum: - valid '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find an Accredited Representative with registration number: 999999999999 and poa code: 083' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status 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: - title: Unprocessable entity detail: The property /serviceOrganization did not contain the required key poaCode status: '422' source: pointer: data/attributes/serviceOrganization - title: Unprocessable entity detail: The property /serviceOrganization did not contain the required key registrationNumber status: '422' source: pointer: data/attributes/serviceOrganization - title: Unprocessable entity detail: The property / did not contain the required key veteran status: '422' source: pointer: data/attributes/ - title: Unprocessable entity detail: The property /serviceOrganization/withoutPoaCode is not defined on the schema. Additional properties are not allowed status: '422' source: pointer: data/attributes/serviceOrganization/withoutPoaCode schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '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 - null properties: attributes: $schema: http://json-schema.org/draft-07/schema# description: Form 2122 Schema type: object additionalProperties: false required: - veteran - serviceOrganization properties: veteran: type: object additionalProperties: false required: - address properties: address: type: object additionalProperties: false required: - addressLine1 - city - stateCode - countryCode properties: addressLine1: description: Street number and name for the veteran's address. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the veteran's address. type: string maxLength: 5 city: description: City for the veteran's address. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the veteran's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the veteran's 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 for the veteran's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the veteran's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the veteran. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the veteran. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 61 example: veteran@example.com serviceNumber: description: Service number for the veteran. type: string pattern: ^\d{9}?$ example: '123456789' insuranceNumber: type: string maxLength: 60 description: Insurance number for the veteran, if applicable. Include letter prefix. claimant: description: Include claimant information for dependent claimants. type: object additionalProperties: false properties: claimantId: type: string example: '123456789' description: Integration Control Number (ICN) for the dependent claimant. address: type: object additionalProperties: false properties: addressLine1: description: Street number and name for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the dependent claimant's address. type: string maxLength: 5 city: description: City for the dependent claimant's address. Required if claimant information provided. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the dependent claimant's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the dependent claimant's 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 for the dependent claimant's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the dependent claimant's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the dependent claimant. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the dependent claimant. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 30 example: claimant@example.com relationship: description: Relationship of claimant to the veteran. Required if claimant information provided. type: string example: Spouse serviceOrganization: description: Details of the Service Organization representing the veteran. type: object additionalProperties: false required: - poaCode - registrationNumber properties: poaCode: description: The POA code of the organization. type: string example: A1Q registrationNumber: description: Registration Number of representative. type: string example: '12345' jobTitle: description: Job title of the representative. type: string example: Veteran Service representative email: description: Email address of the service organization or representative. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 61 example: veteran_representative@example.com recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. Explicitly permits the designated representative to access sensitive medical records within VA. Setting 'recordConsent' to false will prevent the designated representative from accessing the claimant's documents in VBMS. type: boolean consentLimits: description: Consent 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 to this list. Including 'consentLimits' will prevent the designated representative from accessing the claimant's documents in VBMS. 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 example: data: attributes: veteran: address: addressLine1: '123' city: city stateCode: OR countryCode: US zipCode: '12345' serviceOrganization: poaCode: 083 registrationNumber: '999999999999' required: true /veterans/{veteranId}/2122: post: summary: Automatically establishes an organization as a claimant’s accredited representative (VA Form 21-22) description: 'Submit VA Form 21-22 to automatically establish a VA accredited organization with power of attorney (General POA). ' tags: - Power of Attorney operationId: POST:/veterans/{veteranId}/2122 security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] parameters: - name: veteranId in: path required: true example: 1012667145V762142 description: ID of claimant schema: type: string responses: '202': description: Valid request response content: application/json: example: data: id: 00000000-0000-0000-0000-000000000013 type: organization attributes: code: 083 name: 083 - DISABLED AMERICAN VETERANS phoneNumber: 555-555-5555 schema: $schema: http://json-schema.org/draft-07/schema# type: object required: - data properties: data: type: object additionalProperties: false required: - type - attributes properties: type: type: string id: type: string attributes: type: object additionalProperties: false required: - code properties: code: type: string description: code for Power of attorney phoneNumber: type: string name: type: string '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find an Accredited Representative with registration number: 999999999999 and poa code: 083' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status 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: - title: Unprocessable entity detail: The property /serviceOrganization did not contain the required key poaCode status: '422' source: pointer: data/attributes/serviceOrganization - title: Unprocessable entity detail: The property /serviceOrganization did not contain the required key registrationNumber status: '422' source: pointer: data/attributes/serviceOrganization - title: Unprocessable entity detail: The property / did not contain the required key veteran status: '422' source: pointer: data/attributes/ - title: Unprocessable entity detail: The property /serviceOrganization/withoutPoaCode is not defined on the schema. Additional properties are not allowed status: '422' source: pointer: data/attributes/serviceOrganization/withoutPoaCode schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '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 - null properties: attributes: $schema: http://json-schema.org/draft-07/schema# description: Form 2122 Schema type: object additionalProperties: false required: - veteran - serviceOrganization properties: veteran: type: object additionalProperties: false required: - address properties: address: type: object additionalProperties: false required: - addressLine1 - city - stateCode - countryCode properties: addressLine1: description: Street number and name for the veteran's address. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the veteran's address. type: string maxLength: 5 city: description: City for the veteran's address. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the veteran's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the veteran's 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 for the veteran's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the veteran's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the veteran. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the veteran. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 61 example: veteran@example.com serviceNumber: description: Service number for the veteran. type: string pattern: ^\d{9}?$ example: '123456789' insuranceNumber: type: string maxLength: 60 description: Insurance number for the veteran, if applicable. Include letter prefix. claimant: description: Include claimant information for dependent claimants. type: object additionalProperties: false properties: claimantId: type: string example: '123456789' description: Integration Control Number (ICN) for the dependent claimant. address: type: object additionalProperties: false properties: addressLine1: description: Street number and name for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the dependent claimant's address. type: string maxLength: 5 city: description: City for the dependent claimant's address. Required if claimant information provided. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the dependent claimant's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the dependent claimant's 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 for the dependent claimant's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the dependent claimant's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the dependent claimant. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the dependent claimant. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 30 example: claimant@example.com relationship: description: Relationship of claimant to the veteran. Required if claimant information provided. type: string example: Spouse serviceOrganization: description: Details of the Service Organization representing the veteran. type: object additionalProperties: false required: - poaCode - registrationNumber properties: poaCode: description: The POA code of the organization. type: string example: A1Q registrationNumber: description: Registration Number of representative. type: string example: '12345' jobTitle: description: Job title of the representative. type: string example: Veteran Service representative email: description: Email address of the service organization or representative. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 61 example: veteran_representative@example.com recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. Explicitly permits the designated representative to access sensitive medical records within VA. Setting 'recordConsent' to false will prevent the designated representative from accessing the claimant's documents in VBMS. type: boolean consentLimits: description: Consent 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 to this list. Including 'consentLimits' will prevent the designated representative from accessing the claimant's documents in VBMS. 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 example: data: attributes: veteran: address: addressLine1: '123' city: city stateCode: OR countryCode: US zipCode: '12345' serviceOrganization: poaCode: 083 registrationNumber: '999999999999' examples: POA for Veteran: value: data: attributes: veteran: address: addressLine1: '123' city: city stateCode: OR countryCode: US zipCode: '12345' serviceOrganization: poaCode: 083 registrationNumber: '999999999999' POA for Dependent Claimant: value: data: attributes: veteran: address: addressLine1: '123' city: city stateCode: OR countryCode: US zipCode: '12345' serviceOrganization: poaCode: 083 registrationNumber: '999999999999' claimant: claimantId: 1013093331V548481 address: addressLine1: 123 anystreet city: anytown stateCode: OR countryCode: US zipCode: '12345' relationship: Spouse required: true /veterans/{veteranId}/2122a/validate: post: summary: Validates request to establish an individual as a claimant’s accredited representative (VA Form 21-22a) tags: - Power of Attorney operationId: POST:/veterans/{veteranId}/2122a/validate security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] parameters: - name: veteranId in: path required: true example: 1012667145V762142 description: ID of claimant schema: type: string description: 'Validate a request to establish an individual with power of attorney (VA Form 21-22a). Use POST /veterans/{veteranId}/2122a to automatically establish submit VA Form 21-22a. ' responses: '200': description: Valid request response content: application/json: example: data: type: form/21-22a/validation attributes: status: valid schema: $schema: http://json-schema.org/draft-07/schema# type: object required: - data properties: data: type: object additionalProperties: false required: - type - attributes properties: type: type: string attributes: type: object additionalProperties: false required: - status properties: status: type: string description: Says if submission of 21-22a would work with the given parameters enum: - valid '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find an Accredited Representative with registration number: 999999999999 and poa code: 067' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status 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: - title: Unprocessable entity detail: The property /representative did not contain the required key poaCode status: '422' source: pointer: data/attributes/representative - title: Unprocessable entity detail: The property /representative did not contain the required key registrationNumber status: '422' source: pointer: data/attributes/representative - title: Unprocessable entity detail: The property / did not contain the required key veteran status: '422' source: pointer: data/attributes/ schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '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 - null properties: attributes: $schema: http://json-schema.org/draft-07/schema# description: Form 2122a Schema type: object additionalProperties: false required: - veteran - representative properties: veteran: type: object additionalProperties: false required: - address properties: serviceNumber: description: Service number for the veteran. type: string maxLength: 9 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: 27 example: Air National Guard address: type: object additionalProperties: false required: - addressLine1 - city - stateCode - countryCode properties: addressLine1: description: Street number and name for the veteran's address. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the veteran's address. type: string maxLength: 5 city: description: City for the veteran's address. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the veteran's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the veteran's 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 for the veteran's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the veteran's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the veteran. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the veteran. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 61 example: veteran@example.com claimant: description: Include claimant information for dependent claimants. type: object additionalProperties: false properties: claimantId: type: string example: '123456789' description: Integration Control Number (ICN) for the dependent claimant. address: type: object additionalProperties: false properties: addressLine1: description: Street number and name for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the dependent claimant's address. type: string maxLength: 5 city: description: City for the dependent claimant's address. Required if claimant information provided. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: USA zipCode: description: Zip code (first 5 digits) for the dependent claimant's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the dependent claimant's 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 for the dependent claimant's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the dependent claimant's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the dependent claimant. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the dependent claimant. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 30 example: claimant@example.com relationship: description: Relationship of claimant to the veteran. Required if claimant information provided. type: string example: Spouse representative: description: Details of the individual representative representing the veteran. type: object additionalProperties: false required: - poaCode - registrationNumber - type properties: poaCode: description: The POA code of the representative. type: string example: A1Q registrationNumber: description: Registration Number of representative. type: string example: '12345' type: description: Type of individual representative type: string enum: - ATTORNEY - AGENT example: ATTORNEY address: type: object additionalProperties: false properties: addressLine1: description: Street number and name for the representative's address. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the representative's address. type: string maxLength: 5 city: description: City for the representative's address. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the representative's address. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the representative's address. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the representative's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the representative's address. type: string pattern: ^\d{4}?$ example: '6789' recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. Explicitly permits the designated representative to access sensitive medical records within VA. Setting 'recordConsent' to false will prevent the designated representative from accessing the claimant's documents in VBMS. type: boolean consentLimits: description: Consent 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 to this list. Including 'consentLimits' will prevent the designated representative from accessing the claimant's documents in VBMS. 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 conditionsOfAppointment: description: If the individual named in Item 15A is an accredited agent or attorney, the scope of representation provided before VA may be limited by the agent or attorney as indicated below in Item 23 type: array items: type: string example: data: attributes: veteran: address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' representative: poaCode: '067' registrationNumber: '999999999999' type: ATTORNEY address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' required: true /veterans/{veteranId}/2122a: post: summary: Automatically establishes an individual as a claimant’s accredited representative (VA Form 21-22a) tags: - Power of Attorney operationId: POST:/veterans/{veteranId}/2122a security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] parameters: - name: veteranId in: path required: true example: 1012667145V762142 description: ID of claimant schema: type: string description: 'Submit VA Form 21-22 to automatically establish a VA accredited individual with power of attorney (General POA). ' responses: '202': description: Valid request response content: application/json: example: data: id: 00000000-0000-0000-0000-000000000014 type: individual attributes: code: '067' name: Firstname Lastname phoneNumber: 555-555-5555 schema: $schema: http://json-schema.org/draft-07/schema# type: object required: - data properties: data: type: object additionalProperties: false required: - type - attributes properties: type: type: string id: type: string attributes: type: object additionalProperties: false required: - code properties: code: type: string description: code for Power of attorney phoneNumber: type: string name: type: string '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find an Accredited Representative with registration number: 999999999999 and poa code: 067' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status 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: - title: Unprocessable entity detail: The property /representative did not contain the required key poaCode status: '422' source: pointer: data/attributes/representative - title: Unprocessable entity detail: The property /representative did not contain the required key registrationNumber status: '422' source: pointer: data/attributes/representative - title: Unprocessable entity detail: The property / did not contain the required key veteran status: '422' source: pointer: data/attributes/ schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '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 - null properties: attributes: $schema: http://json-schema.org/draft-07/schema# description: Form 2122a Schema type: object additionalProperties: false required: - veteran - representative properties: veteran: type: object additionalProperties: false required: - address properties: serviceNumber: description: Service number for the veteran. type: string maxLength: 9 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: 27 example: Air National Guard address: type: object additionalProperties: false required: - addressLine1 - city - stateCode - countryCode properties: addressLine1: description: Street number and name for the veteran's address. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the veteran's address. type: string maxLength: 5 city: description: City for the veteran's address. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the veteran's address. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the veteran's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the veteran's 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 for the veteran's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the veteran's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the veteran. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the veteran. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 61 example: veteran@example.com claimant: description: Include claimant information for dependent claimants. type: object additionalProperties: false properties: claimantId: type: string example: '123456789' description: Integration Control Number (ICN) for the dependent claimant. address: type: object additionalProperties: false properties: addressLine1: description: Street number and name for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the dependent claimant's address. type: string maxLength: 5 city: description: City for the dependent claimant's address. Required if claimant information provided. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the dependent claimant's address. Required if claimant information provided. type: string pattern: ^[a-z,A-Z]{2}$ example: USA zipCode: description: Zip code (first 5 digits) for the dependent claimant's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the dependent claimant's 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 for the dependent claimant's phone number. Required for international phone numbers. type: string pattern: ^[0-9]+$ areaCode: description: Area code for the dependent claimant's phone number. Required if countryCode is '1' or not included. type: string pattern: ^[0-9]{1,5}$ example: '555' phoneNumber: description: Phone number for the dependent claimant. type: string pattern: ^\d(?:[- ]?\d){0,14}$ example: '5555555' minLength: 1 maxLength: 23 if: properties: countryCode: anyOf: - type: string enum: - '1' then: required: - areaCode else: anyOf: - required: - countryCode - required: - areaCode email: description: Email address for the dependent claimant. type: string pattern: ^(?!.*\s).+@.+\..+|^$ maxLength: 30 example: claimant@example.com relationship: description: Relationship of claimant to the veteran. Required if claimant information provided. type: string example: Spouse representative: description: Details of the individual representative representing the veteran. type: object additionalProperties: false required: - poaCode - registrationNumber - type properties: poaCode: description: The POA code of the representative. type: string example: A1Q registrationNumber: description: Registration Number of representative. type: string example: '12345' type: description: Type of individual representative type: string enum: - ATTORNEY - AGENT example: ATTORNEY address: type: object additionalProperties: false properties: addressLine1: description: Street number and name for the representative's address. type: string pattern: ^([-a-zA-Z0-9'.,&#]([-a-zA-Z0-9'.,&# ])?)+$ maxLength: 30 addressLine2: description: Apartment or unit number for the representative's address. type: string maxLength: 5 city: description: City for the representative's address. type: string example: Portland maxLength: 18 stateCode: description: State abbreviation for the representative's address. type: string pattern: ^[a-z,A-Z]{2}$ example: OR countryCode: description: Two-letter country code for the representative's address. type: string pattern: ^[a-z,A-Z]{2}$ example: US zipCode: description: Zip code (first 5 digits) for the representative's address. Required if 'countryCode' is 'US'. type: string pattern: ^\d{5}?$ example: '12345' zipCodeSuffix: description: Zip code suffix (last 4 digits) for the representative's address. type: string pattern: ^\d{4}?$ example: '6789' recordConsent: description: Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C. Explicitly permits the designated representative to access sensitive medical records within VA. Setting 'recordConsent' to false will prevent the designated representative from accessing the claimant's documents in VBMS. type: boolean consentLimits: description: Consent 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 to this list. Including 'consentLimits' will prevent the designated representative from accessing the claimant's documents in VBMS. 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 conditionsOfAppointment: description: If the individual named in Item 15A is an accredited agent or attorney, the scope of representation provided before VA may be limited by the agent or attorney as indicated below in Item 23 type: array items: type: string example: data: attributes: veteran: address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' representative: poaCode: '067' registrationNumber: '999999999999' type: ATTORNEY address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' examples: POA for Veteran: value: data: attributes: veteran: address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' representative: poaCode: '067' registrationNumber: '999999999999' type: ATTORNEY address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' POA for Dependent Claimant: value: data: attributes: veteran: address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' representative: poaCode: '067' registrationNumber: '999999999999' type: ATTORNEY address: addressLine1: '123' addressLine2: 2a city: city countryCode: US stateCode: OR zipCode: '12345' zipCodeSuffix: '6789' claimant: claimantId: 1013093331V548481 address: addressLine1: 123 anystreet city: anytown stateCode: OR countryCode: US zipCode: '12345' relationship: Spouse required: true /veterans/{veteranId}/power-of-attorney/{id}: get: summary: Checks status of power of attorney submission (VA Forms 21-22 or 21-22a) description: Check the submissions status of a request to appoint power of attorney (VA Forms 21-22 or 21-22a). tags: - Power of Attorney operationId: GET:/veterans/{veteranId}/power-of-attorney/{id} security: - productionOauth: - system/claim.read - system/claim.write - sandboxOauth: - system/claim.read - system/claim.write - bearer_token: [] parameters: - name: veteranId in: path required: true example: 1012667145V762142 description: ID of claimant schema: type: string - name: id in: path required: true example: 00000000-0000-0000-0000-000000000015 description: The ID of the 21-22 submission schema: type: string responses: '200': description: Valid request response content: application/json: example: data: id: 00000000-0000-0000-0000-000000000016 type: claimsApiPowerOfAttorneys attributes: createdAt: 2024-01-01 00:00:00 UTC representative: poaCode: '074' status: pending errors: [] steps: - type: PDF_SUBMISSION status: NOT_STARTED completedAt: null nextStep: POA_UPDATE - type: POA_UPDATE status: NOT_STARTED completedAt: null nextStep: POA_ACCESS_UPDATE - type: POA_ACCESS_UPDATE status: NOT_STARTED completedAt: null nextStep: CLAIMANT_NOTIFICATION - type: CLAIMANT_NOTIFICATION status: NOT_STARTED completedAt: null nextStep: null 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 - createdAt - representative properties: status: type: string description: Says if the power of attorney is pending, submitted, updated or errored enum: - pending - submitted - updated - errored createdAt: type: string description: Date request was first accepted format: date errors: type: array description: Error details if applicable items: type: object additionalProperties: false properties: title: type: string detail: type: string code: type: string enum: - PDF_SUBMISSION - POA_UPDATE - POA_ACCESS_UPDATE - CLAIMANT_NOTIFICATION steps: type: array items: type: object additionalProperties: false properties: type: type: string enum: - PDF_SUBMISSION - POA_UPDATE - POA_ACCESS_UPDATE - CLAIMANT_NOTIFICATION status: type: string enum: - NOT_STARTED - IN_PROGRESS - SUCCESS - FAILED completedAt: type: string format: date nextStep: type: string enum: - POA_UPDATE - POA_ACCESS_UPDATE - CLAIMANT_NOTIFICATION representative: type: object additionalProperties: false required: - poaCode properties: poaCode: type: string description: Power of Attorney Code submitted for Veteran '401': description: Unauthorized content: application/json: example: errors: - title: Not authorized status: '401' detail: Not authorized schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status code source: type: object additionalProperties: false description: Source of error properties: pointer: type: string description: Pointer to source of error '404': description: Resource not found content: application/json: example: errors: - status: '404' title: Resource not found detail: 'Could not find Power of Attorney with id: -1' schema: required: - errors properties: errors: type: array items: additionalProperties: false required: - title - detail properties: title: type: string description: HTTP error title detail: type: string description: HTTP error detail status: type: string description: HTTP error status 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 '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: securitySchemes: apikey: type: apiKey name: apikey in: header