openapi: 3.0.1
info:
title: Address Validation 5103 Waiver Disability Rating API
description: "The Address Validation API accepts and validates an address and standardizes it for mailing. It can also help you process an address by:\n* Inferring missing or incorrect address components\n* Supplementing an address with additional information, such as geocode, latitude and longitude, and postal service metadata (when available)\n## Technical Overview\nThe Address Validation API returns validated addresses as they appear in the USPS database for domestic addresses. It validates by separating the address into individual components and then providing component-level validation checks.\n\nThis API is certified by the United States Postal Service (USPS) Coding Accuracy Support System (CASS) and adheres to [United States Postal Service (USPS) Publication 28 standards](https://pe.usps.com/text/pub28/welcome.htm) for domestic, military, and US territory addresses.\n\nFor international addresses, validation relies on Universal Postal Union (UPU) standards. \n\n## Validation\nIf an address is found, it is considered valid based on metadata returned by the Address Validation service, such as the confidence score and the [Delivery Point Validation (DPV)](https://postalpro.usps.com/address-quality/dpv).\n\nIf an address is found, there are multiple checks performed on the validated address. The address can fail validation for a variety of reasons, such as the inability to deliver (for domestic mailing addresses) or the format. For specific reasons why an address failed, refer to the error messages returned.\n\nIf an address is not found, it automatically fails validation.\n\n## Address override indicator\nSometimes an entered address is accurate for a Veteran but does not pass validation rules. These instances can occur when an address is newer than what is in the CASS software or in regions where address data is less accurate.\n\nSystems can accept these addresses despite the lack of address validation by submitting an \"accepted address\" (usually confirmed by the Veteran) to the Contact Information API (see Requirements below). An address is considered accepted after the address has been sent to the validation API and has failed validation, but the Veteran has confirmed the address is correct as entered. The accepted address can then be passed to the Contact Information API using an address override indicator set to show that the validation was overridden. To set an override indicator, the original address and the `overrideValidationKey` returned in the validation API response must be provided to the Contact Information API, in order to prove that a validation attempt has been made before overriding.\n\n## Version Interoperability\n\nTo ensure interoperability between APIs and eliminate the need for transforming data as one API feeds into the other, we strongly recommend using versions of the following APIs that are compatible.\n\n| <h3>If Using</h3> | <h3>Then Use...</h3> |\n| :------------------------------:|:----------------------------------------------:|\n| Address Validation API v1/v2 | Contact Information API v1<br><br>Profile Service API v1/v2 |\n| Address Validation API v3 | Contact Information API v2<br><br>Profile Service API v3 |\n\n## Authorization\nAPI requests are authorized through a symmetric API token provided in an HTTP header with name apikey.\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us)."
license:
name: Creative Commons
url: https://developer.va.gov/terms-of-service
version: '3'
servers:
- url: https://sandbox-api.va.gov/services/address-validation/{version}
description: Sandbox
variables:
version:
default: v3
- url: https://api.va.gov/services/address-validation/{version}
description: Production
variables:
version:
default: v3
security:
- apikey: []
tags:
- name: Disability Rating
paths:
/disability_rating:
get:
tags:
- Disability Rating
summary: Retrieve disability rating of authorized Veteran
description: This endpoint provides a veteran's combined and individual disability rating(s) and related decisions and dates.
operationId: GET:/disability_rating
responses:
'200':
description: Disability Rating retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DisabilityRatingResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ServerSoapFaultApiError'
'401':
description: Not authorized
content:
application/json:
schema:
type: string
example:
message: Invalid authentication credentials
'403':
description: Forbidden
content:
application/json:
schema:
type: string
example:
message: You cannot consume this service
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/MissingIcn'
'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
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerApiError'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/InaccessibleServiceDefintionErrorApiError'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/BackendServiceApiError'
deprecated: true
security:
- bearer_token: []
post:
tags:
- Disability Rating
summary: Search for information about a Veteran's VA disability ratings using demographic data. Data returned includes individual and combined ratings, diagnoses, and eligibility dates for compensation for service-connected conditions.
description: 'This endpoint provides a Veteran''s disability ratings and related decisions and dates.
Required information:
* First Name
* Last Name
* Date of Birth
* Street Address
* City
* State
* Country
* Zipcode
Optional information:
* Middle Name
* Gender
* Mother''s Maiden Name
* Home Phone Number
* Birth Place City
* Birth Place State
* Birth Place Country
Tips for finding a match:
* First and Last Name, Address and DOB are often essential to uniquely identifying
a Veteran.
* Home Address is recommended, but it may be beneficial to retry the search with
additional addresses if they are available and the first attempt is not confirmed.
* To find a match, it can help to retry with different demographic information,
such as alternate last names or addresses.
* It can also help to remove special characters, hyphens, apostrophes, or spaces
in a name prior to matching.
NOTE: In the Sandbox only DOB and ZIP are required to identify the test user.
'
operationId: POST:/disability_rating
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VeteranAttributes'
example:
first_name: Alfredo
last_name: Armstrong
birth_date: '1993-06-08'
middle_name: M
gender: M
street_address_line1: 17020 Tortoise St
street_address_line2: ''
street_address_line3: ''
city: Round Rock
zipcode: '78664'
state: TX
country: USA
required: true
responses:
'200':
description: Disability Rating retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DisabilityRatingResponseV2'
example:
data:
id: '12303'
type: disability-rating
attributes:
combined_disability_rating: 100
combined_effective_date: '2018-03-27'
legal_effective_date: '2018-03-27'
individual_ratings:
- decision: Service Connected
disability_rating_id: '1070379'
effective_date: '2018-03-27'
rating_end_date: '2022-08-27'
rating_percentage: 50
diagnostic_type_code: '0502'
hyph_diagnostic_type_code: '1234'
diagnostic_type_name: Schizophrenia, disorganized type
diagnostic_text: bilateral hearing loss
static_ind: true
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
title: Bad Request
detail: Bad Request
code: '400'
status: '400'
'401':
description: Not Authorized
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationError'
example:
status: '401'
error: Invalid Token.
path: /veteran_verification/v2/disability_rating
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenServerError'
example:
status: '403'
error: Token not granted requested scope.
path: /veteran_verification/v2/disability_rating
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/MissingIcn'
example:
title: Veteran not identifiable.
detail: No data found for ID or demographics.
code: '404'
status: '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
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerApiError'
example:
title: Internal server error
detail: Internal server error
code: '500'
status: '500'
'502':
description: Bad Gateway. Also, could indicate Person Not Found in MPI backend.
content:
application/json:
schema:
$ref: '#/components/schemas/InaccessibleServiceDefintionErrorApiError'
example:
title: Bad Gateway
detail: Upstream Request Error.
code: '502'
status: '502'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/BackendServiceApiError_2'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- sandboxOauth2:
- disability_rating.read
- productionOauth2:
- disability_rating.read
/restricted/disability_rating:
post:
tags:
- Disability Rating
summary: Search for information about a Veteran's disability rating using Social Security number and demographic data Data returned includes individual and combined ratings, diagnoses, and eligibility dates for compensation for service-connected conditions.(restricted access).
description: 'This endpoint provides a Veteran''s combined and individual disability ratings and
related decisions and dates. It allows searching for a Veteran using Social Security number and demographic information.
If using Social Security number, the following information is required:
* Social Security number
* First name
* Last name
* Birth date
If using demographic data, the following information is required:
* First Name
* Last Name
* Birth date
* Street Address
* City
* State
* Country
* Zipcode
The following optional information may also be used with Social Security number
or demographic data:
* Middle Name
* Gender
* Mother''s Maiden Name
* Home Phone Number
* Birth Place City
* Birth Place State
* Birth Place Country
Tips for finding a match:
* First and Last Name, Address and Birth date are often essential to uniquely
identifying a Veteran.
* Home address is recommended, but it may also help to retry the search with
additional available addresses when the first attempt is not confirmed.
* To find a match, it can help to retry with different demographic information,
such as alternate last names or addresses.
* It can also help to remove special characters, hyphens, apostrophes, or spaces
in a name prior to matching.
NOTE: In the Sandbox only birth date and zip code are required to identify the
test user.
'
operationId: POST:/restricted/disability_rating
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FederalVeteranAttributes'
example:
ssn: 796-01-2476
first_name: Alfredo
last_name: Armstrong
birth_date: '1993-06-08'
middle_name: M
gender: M
street_address_line1: 17020 Tortoise St
street_address_line2: ''
street_address_line3: ''
city: Round Rock
zipcode: '78664'
state: TX
country: USA
required: true
responses:
'200':
description: Disability Rating retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DisabilityRatingResponseV2'
example:
data:
id: '12303'
type: disability-rating
attributes:
combined_disability_rating: 100
combined_effective_date: '2018-03-27'
legal_effective_date: '2018-03-27'
individual_ratings:
- decision: Service Connected
disability_rating_id: '1070379'
effective_date: '2018-03-27'
rating_end_date: '2022-08-27'
rating_percentage: 50
diagnostic_type_code: '0502'
hyph_diagnostic_type_code: '1234'
diagnostic_type_name: Schizophrenia, disorganized type
diagnostic_text: bilateral hearing loss
static_ind: true
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
title: Bad Request
detail: Bad Request
status: '400'
code: '400'
'401':
description: Not Authorized
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationError'
example:
status: '401'
error: Invalid Token.
path: /veteran_verification/v2/restricted/disability_rating
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenServerError'
example:
status: '403'
error: Token not granted requested scope.
path: /veteran_verification/v2/restricted/disability_rating
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/MissingIcn'
example:
title: Veteran not identifiable.
detail: No data found for ID or demographics.
code: '404'
status: '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
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerApiError'
example:
title: Internal server error
detail: Internal server error
code: '500'
status: '500'
'502':
description: Bad Gateway. Also, could indicate Person Not Found in MPI backend.
content:
application/json:
schema:
$ref: '#/components/schemas/InaccessibleServiceDefintionErrorApiError'
example:
title: Bad Gateway
detail: Upstream Request Error.
status: '502'
code: '502'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/BackendServiceApiError_2'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- sandboxOauth2:
- disability_rating_restricted.read
- productionOauth2:
- disability_rating_restricted.read
/summary/disability_rating:
get:
tags:
- Disability Rating
summary: Get information about a Veteran's VA disability ratings. Data returned includes individual and combined ratings and eligibility dates for compensation for service-connected conditions.
description: This endpoint provides disability ratings and related decisions and dates for a Veteran, based on the ID in the bearer token.
operationId: GET:/summary/disability_rating
responses:
'200':
description: Disability Rating retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DisabilityRatingSummaryResponseV2'
example:
data:
id: '12303'
type: disability-rating
attributes:
combined_disability_rating: 100
combined_effective_date: '2018-03-27'
legal_effective_date: '2018-03-27'
individual_ratings:
- decision: Service Connected
disability_rating_id: '1070379'
effective_date: '2018-03-27'
rating_end_date: '2022-08-27'
rating_percentage: 50
static_ind: true
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
title: Bad Request
detail: Bad Request
code: '400'
status: '400'
'401':
description: Not Authorized
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationError'
example:
status: '401'
error: Invalid Token.
path: /veteran_verification/v2/summary/disability_rating
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenServerError'
example:
status: '403'
error: Token not granted requested scope.
path: /veteran_verification/v2/summary/disability_rating
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/MissingIcn'
example:
title: Veteran not identifiable.
detail: No data found for ID or demographics.
code: '404'
status: '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
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerApiError'
example:
title: Internal server error
detail: Internal server error
code: '500'
status: '500'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/InaccessibleServiceDefintionErrorApiError'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/BackendServiceApiError_2'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- sandboxOauth2:
- disability_rating_summary.read
- productionOauth2:
- disability_rating_summary.read
post:
tags:
- Disability Rating
summary: Search for information about a Veteran's VA disability ratings using demographic data. Data returned includes individual and combined ratings and eligibility dates for compensation for service-connected conditions.
description: 'This endpoint provides a Veteran''s disability ratings and related decisions and dates.
Required information:
* First Name
* Last Name
* Date of Birth
* Street Address
* City
* State
* Country
* Zipcode
Optional information:
* Middle Name
* Gender
* Mother''s Maiden Name
* Home Phone Number
* Birth Place City
* Birth Place State
* Birth Place Country
Tips for finding a match:
* First and Last Name, Address and DOB are often essential to uniquely identifying
a Veteran.
* Home Address is recommended, but it may be beneficial to retry the search with
additional addresses if they are available and the first attempt is not confirmed.
* To find a match, it can help to retry with different demographic information,
such as alternate last names or addresses.
* It can also help to remove special characters, hyphens, apostrophes, or spaces
in a name prior to matching.
NOTE: In the Sandbox only DOB and ZIP are required to identify the test user.
'
operationId: POST:/summary/disability_rating
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VeteranAttributes'
example:
first_name: Alfredo
last_name: Armstrong
birth_date: '1993-06-08'
middle_name: M
gender: M
street_address_line1: 17020 Tortoise St
street_address_line2: ''
street_address_line3: ''
city: Round Rock
zipcode: '78664'
state: TX
country: USA
required: true
responses:
'200':
description: Disability Rating retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DisabilityRatingSummaryResponseV2'
example:
data:
id: '12303'
type: disability-rating
attributes:
combined_disability_rating: 100
combined_effective_date: '2018-03-27'
legal_effective_date: '2018-03-27'
individual_ratings:
- decision: Service Connected
disability_rating_id: '1070379'
effective_date: '2018-03-27'
rating_end_date: '2022-08-27'
rating_percentage: 50
static_ind: true
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
title: Bad Request
detail: Bad Request
code: '400'
status: '400'
'401':
description: Not Authorized
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationError'
example:
status: '401'
error: Invalid Token.
path: /veteran_verification/v2/summary/disability_rating
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenServerError'
example:
status: '403'
error: Token not granted requested scope.
path: /veteran_verification/v2/summary/disability_rating
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/MissingIcn'
example:
title: Veteran not identifiable.
detail: No data found for ID or demographics.
code: '404'
status: '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
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerApiError'
example:
title: Internal server error
detail: Internal server error
code: '500'
status: '500'
'502':
description: Bad Gateway. Also, could indicate Person Not Found in MPI backend.
content:
application/json:
schema:
$ref: '#/components/schemas/InaccessibleServiceDefintionErrorApiError'
example:
title: Bad Gateway
detail: Upstream Request Error.
code: '502'
status: '502'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/BackendServiceApiError_2'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- sandboxOauth2:
- disability_rating_summary.read
- productionOauth2:
- disability_rating_summary.read
/restricted/summary/disability_rating:
post:
tags:
- Disability Rating
summary: Search for information about a Veteran's VA disability ratings using Social Security number and demographic data. Data returned includes individual and combined ratings and eligibility dates for compensation for service-connected conditions. (restricted access)
description: "This endpoint provides a Veteran's disability ratings and related decisions and dates. It allows searching for a Veteran using Social Sec
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va-gov/refs/heads/main/openapi/va-gov-disability-rating-api-openapi.yml