openapi: 3.0.1
info:
title: Address Validation 5103 Waiver Documents Service 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: Documents Service
paths:
/uploads/status:
post:
tags:
- Documents Service
summary: Returns the upload status of multiple disability claim documents.
description: " Returns the current processing status of multiple disability\n claims document uploads related to the given list of request IDs.\n"
operationId: POST:/uploads/status
parameters:
- name: includeInternalOnlyStepStatuses
in: query
required: false
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestAsyncProcessingStatusBulkRequestV1'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestAsyncProcessingStatusBulkResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
/participant/documents/search:
post:
tags:
- Documents Service
summary: ' Returns all VBMS document names associated with a participantId.
'
description: ' Returns a list of all VBMS document names related to participantId.
'
operationId: POST:/participant/documents/search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VbmsSearchDocumentsRequestV1'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VbmsSearchDocumentsResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
/participant/documents/download:
post:
tags:
- Documents Service
summary: Download the document for a participant.
description: " Use this endpoint to download the full content of a document (such\n as a PDF). The document must be identified by its unique ID, and associated with\n either a Participant ID or File Number.\n"
operationId: POST:/participant/documents/download
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VbmsDownloadDocumentRequestV1'
required: true
responses:
'200':
description: Binary document stream (e.g., PDF).
content:
application/octet-stream:
schema:
type: string
format: binary
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
/documents:
post:
tags:
- Documents Service
summary: Uploads a file to a Veteran's VBMS eFolder.
description: "Receives and uploads a file based on the required parameters of systemName, docType,\nfileNumber, participantId, claimId, and fileName. Parameters are described in\nthe schema section for UploadRequestV1.UploadData.\n\n## Example Payload (using File Number)\n\nThe following demonstrates a (redacted) multipart payload, identified by fileNumber,\nsuitable for submitting to this endpoint. Most programming languages should have\nprovisions for assembling a multipart payload like this without having to do so\nmanually.\n\n```\nPOST /benefits-documents/v1/documents HTTP/1.1\nHost: <server>\nUser-Agent: curl/7.75.0\nAccept: */*\nAuthorization: Bearer <token>\nContent-Length: 11871\nContent-Type: multipart/form-data; boundary=------------------------94408bea7cc00a68\n\nContent-Type: application/json\n\n{\n \"data\": {\n \"systemName\":\"VA.gov\",\n \"docType\":\"L533\",\n \"fileNumber\":\"987654321\",\n \"claimId\":\"123\",\n \"fileName\":\"Test-PDF-Valid.pdf\",\n \"trackedItemIds\": [ 456,789 ]\n }\n}\n\n```\n\nIn this curl example, we store the parameters inside JSON file called\nupload-request.p2iO.json:\n\n```\n{\n \"data\": {\n \"systemName\":\"VA.gov\",\n \"docType\":\"L533\",\n \"fileNumber\":\"987654321\",\n \"claimId\":\"123\",\n \"fileName\":\"Test-PDF-Valid.pdf\",\n \"trackedItemIds\": [ 456,789 ]\n }\n}\n\n```\n\nThis is an example curl command:\n\n```\n\ncurl -v '-HAuthorization: Bearer <token>' -HContent-Type:multipart/form-data --form 'parameters=@upload-request.p2iO.json;type=application/json' --form 'file=@<path/to/pdf/file>;type=application/pdf' https://sandbox-api.va.gov/services/benefits-documents/v1/documents\n\n```\n\n## Example Payload (using Participant ID)\n\nTo upload using participantId, we'll use the same upload example as above, this time\nproviding a participantId instead of a fileNumber:\n\n```\nPOST /benefits-documents/v1/documents HTTP/1.1\nHost: <server>\nUser-Agent: curl/7.75.0\nAccept: */*\nAuthorization: Bearer <token>\nContent-Length: 11871\nContent-Type: multipart/form-data; boundary=------------------------94408bea7cc00a68\n\nContent-Type: application/json\n\n{\n \"data\": {\n \"systemName\":\"VA.gov\",\n \"docType\":\"L533\",\n \"participantId\":\"123456789\",\n \"claimId\":\"123\",\n \"fileName\":\"Test-PDF-Valid.pdf\",\n \"trackedItemIds\": [ 456,789 ]\n }\n}\n\n```\n\nWe can store the parameters inside a JSON file as in the previous example - this time\nwe'll call it upload-request-participant-id.p2iO.json.\n\nThen, we can execute the same cURL command in the previous example,\nusing the new parameters file:\n\n```\n\ncurl -v '-HAuthorization: Bearer <token>' -HContent-Type:multipart/form-data --form 'parameters=@upload-request-participant-id.p2iO.json;type=application/json' --form 'file=@<path/to/pdf/file>;type=application/pdf' https://sandbox-api.va.gov/services/benefits-documents/v1/documents\n\n```\n\n"
operationId: POST:/documents
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
parameters:
$ref: '#/components/schemas/UploadRequestV1'
file:
type: string
format: binary
required:
- file
- parameters
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UploadResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.write
/documents/validate/claimant:
post:
tags:
- Documents Service
summary: Validates that the claimant can upload a file to a Veteran's VBMS eFolder.
description: 'Determines whether a claimant, identified by either a fileNumber or participantId,
can upload documents of the given docType for the claim identified by the
provided claimId. If the claimant is successfully validated, a validation token
and token expiration time are provided. The token can be used to avoid duplicate
validation for an upload using identical parameters. Note that while a successful
response indicates the pairing of claimant, document, and claim information is
valid, it does not guarantee success of the operation itself.
'
operationId: POST:/documents/validate/claimant
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateUploadClaimantRequestV1'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimantValidationResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
/documents/search:
post:
tags:
- Documents Service
summary: " Returns all claims evidence document names associated with a participantId\n or fileNumber.\n"
description: " Returns a list of all claims evidence document names related to the\n claim identified by the claimId, fileNumber, or participantId.\n"
operationId: POST:/documents/search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimDocumentsRequestV1'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimDocumentsResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
/claim-letters/search:
post:
tags:
- Documents Service
summary: " Returns a list of downloadable Claims Evidence claim letter documents, along with\n their associated metadata, linked to a Participant ID or File Number.\n"
description: " Returns a list of downloadable Claims Evidence claim letter documents associated\n with the provided Participant ID or File Number. Each document entry includes\n metadata such as the document UUID, type, subject, original file name, tracked\n item ID, and upload date.\n"
operationId: POST:/claim-letters/search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FindClaimLetterDocumentsRequestV1'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FindClaimLetterDocumentsResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
/claim-letters/download:
post:
tags:
- Documents Service
summary: Download the full claim letter document for a claimant.
description: " Use this endpoint to download the full content of a claim letter document (such\n as a PDF). The document must be identified by its unique ID, and associated with\n either a Participant ID or File Number. Note: Only some document types are\n available for download.\n"
operationId: POST:/claim-letters/download
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadClaimLetterDocumentRequestV1'
required: true
responses:
'200':
description: Binary document stream (e.g., PDF).
content:
application/octet-stream:
schema:
type: string
format: binary
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
/uploads/{requestId}/status:
get:
tags:
- Documents Service
summary: Returns the processing status of a single disability claim document upload.
description: " Returns the current processing status of a disability claims document upload\n related to the given requestId.\n"
operationId: GET:/uploads/{requestId}/status
parameters:
- name: requestId
in: path
required: true
schema:
type: integer
format: int64
- name: includeInternalOnlyStepStatuses
in: query
required: false
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestAsyncProcessingStatusResponseV1'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'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/BasicErrorDocumentV1'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorDocumentV1'
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
security:
- oauth2:
- documents.read
components:
schemas:
VbmsDownloadDocumentRequestV1.DocumentInfo:
type: object
properties:
fileNumber:
type: string
description: "The Veteran's VBMS fileNumber used when uploading the document to VBMS.\n It indicates the eFolder in which the document resides.\n"
example: '999012105'
participantId:
type: integer
format: int64
description: 'A unique identifier assigned to each patient entry in the Master Patient Index
linking patients to their records across VA systems.
'
example: 999012105
documentUuid:
type: string
description: 'The document''s unique identifier in VBMS, obtained by making a Document Service API
request to search for documents that are available to download for the Veteran.
Note that this differs from the document''s current version UUID.
'
example: 12345678-ABCD-0123-cdef-124345679ABC
required:
- documentUuid
UploadResponseV1.UploadInfo:
type: object
properties:
success:
type: boolean
description: Indicates if the upload request was successful.
example: true
requestId:
type: integer
format: int64
description: The upload request identifier.
example: 12345678
maximum: 9223372036854776000
required:
- requestId
- success
ValidateUploadClaimantRequestV1:
type: object
properties:
data:
$ref: '#/components/schemas/Valid
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va-gov/refs/heads/main/openapi/va-gov-documents-service-api-openapi.yml