openapi: 3.0.1
info:
title: Address Validation 5103 Waiver Uploads 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: Uploads
paths:
/uploads:
post:
tags:
- Uploads
responses:
'202':
description: Accepted. Location generated
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/DocumentUploadPath'
'401':
description: Authorization information not provided
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: No API key found in request
'403':
description: Invalid authorization
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: You cannot consume this service
'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:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorModel'
'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:
type: object
required:
- data
properties:
title:
description: Human readable title description.
type: string
example: Internal server error
detail:
description: Human readable error detail. Only present if status = "error"
type: string
example: Internal server error
code:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 500
status:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 500
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
summary: Get a location for subsequent document upload PUT request
operationId: POST:/uploads
security:
- apikey: []
/uploads/{id}:
get:
tags:
- Uploads
responses:
'200':
description: Upload status retrieved successfully
content:
application/json:
schema:
required:
- data
properties:
data:
$ref: '#/components/schemas/DocumentUploadStatus'
'401':
description: Authorization information not provided
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: No API key found in request
'403':
description: Invalid authorization
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: You cannot consume this service
'404':
description: Not found
content:
application/json:
schema:
type: object
required:
- data
properties:
title:
description: Human readable title description.
type: string
example: Record not found
detail:
description: Human readable error detail. Only present if status = "error"
type: string
example: The record identified by {{id}} could not be found
code:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 404
status:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 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:
type: object
required:
- data
properties:
title:
description: Human readable title description.
type: string
example: Internal server error
detail:
description: Human readable error detail. Only present if status = "error"
type: string
example: Internal server error
code:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 500
status:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 500
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
summary: Get status for a previous benefits document upload
operationId: GET:/uploads/{id}
description: A request to the `/uploads/{id}` endpoint will return a real-time status for that GUID, and update its status in `/uploads/report`.\n\nThe `updated_at` field indicates the last time the status for a given GUID was updated.
security:
- apikey: []
parameters:
- name: id
in: path
description: ID as returned by a previous create upload request
required: true
example: 6d8433c1-cd55-4c24-affd-f592287a7572
schema:
type: string
format: uuid
/uploads/{id}/download:
get:
tags:
- Uploads
responses:
'200':
description: Zip file with the contents of your payload as parsed by our server
content:
application/zip:
schema:
type: string
format: binary
example: Binary File
'401':
description: Authorization information not provided
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: No API key found in request
'403':
description: Invalid authorization
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: You cannot consume this service
'404':
description: Not found
content:
application/json:
schema:
type: object
required:
- data
properties:
title:
description: Human readable title description.
type: string
example: Record not found
detail:
description: Human readable error detail. Only present if status = "error"
type: string
example: The record identified by {{id}} could not be found
code:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 404
status:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 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:
type: object
required:
- data
properties:
title:
description: Human readable title description.
type: string
example: Internal server error
detail:
description: Human readable error detail. Only present if status = "error"
type: string
example: Internal server error
code:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 500
status:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
* `DOC201` - Upload server error.
* `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
'
type: string
example: 500
'504':
description: Gateway Timeout
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: The server took too long to respond
summary: Download zip of "what the server sees"
description: An endpoint that will allow you to see exactly what the server sees. We split apart all submitted docs and metadata and zip the file to make it available to you to help with debugging purposes. Files are deleted after 10 days. Only available in testing environments, not production.
operationId: GET:/uploads/{id}/download
security:
- apikey: []
parameters:
- name: id
in: path
description: ID as returned by a previous create upload request
required: true
example: 6d8433c1-cd55-4c24-affd-f592287a7572
schema:
type: string
format: uuid
/uploads/report:
post:
tags:
- Uploads
responses:
'200':
description: Upload status report retrieved successfully
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/DocumentUploadStatusReport'
'400':
description: Bad Request - invalid, missing, or oversized list of guids (max 1000)
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UploadsReportBadRequestErrorModel'
'401':
description: Authorization information not provided
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: No API key found in request
'403':
description: Invalid authorization
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: You cannot consume this service
'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:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorModel'
'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:
type: object
required:
- data
properties:
title:
description: Human readable title description.
type: string
example: Internal server error
detail:
description: Human readable error detail. Only present if status = "error"
type: string
example: Internal server error
code:
description: 'Unambiguous status code. Only present if status = "error"
* `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
* `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
* `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
* `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
* `DOC105` - Invalid or unknown id
* `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
* `DOC107` - Empty payload.
* `DOC108` - Maximum dimensions exceeded. Height and width must be less than 78 in x 101 in.
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va-gov/refs/heads/main/openapi/va-gov-uploads-api-openapi.yml