openapi: 3.0.1
info:
title: Address Validation 5103 Waiver facilities 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: facilities
description: VA Facilities API
paths:
/facilities/all:
get:
tags:
- facilities
summary: Bulk download information for all facilities
description: Retrieve all available facilities in a single operation, formatted as either a GeoJSON FeatureCollection or as a CSV. Due to the complexity of the facility resource type, the CSV response contains a subset of available facility data - specifically it omits the available services, patient satisfaction, and patient wait time data.
operationId: GET:/facilities/all
parameters:
- name: Accept
in: header
required: true
schema:
type: string
enum:
- application/geo+json
- application/vnd.geo+json
- text/csv
example: application/geo+json
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GeoFacilitiesResponse'
application/geo+json:
schema:
$ref: '#/components/schemas/GeoFacilitiesResponse'
application/vnd.geo+json:
schema:
$ref: '#/components/schemas/GeoFacilitiesResponse'
text/csv:
schema:
type: string
example: 'id,name,station_id,latitude,longitude,facility_type,classification,website,physical_address_1,physical_address_2,physical_address_3,physical_city,physical_state,physical_zip,mailing_address_1,mailing_address_2,mailing_address_3,mailing_city,mailing_state,mailing_zip,phone_main,phone_fax,phone_mental_health_clinic,phone_pharmacy,phone_after_hours,phone_patient_advocate,phone_enrollment_coordinator,hours_monday,hours_tuesay,hours_wednesday,hours_thursday,hours_friday,hours_saturday,hours_sunday,mobile,active_status,visn
vc_0101V,Boston Vet Center,0101V,42.3445959000001,-71.0361051099999,vet_center,,,7 Drydock Avenue,Suite 2070,,Boston,MA,2210,,,,,,,857-203-6461 x,,,,,,,800AM-700PM,800AM-800PM,800AM-700PM,800AM-800PM,800AM-600PM,-,-,,,
vba_362b,Houston Regional Benefit Office at Frank Tejeda Outpatient Clinic,362b,29.51690196,-98.59601936,va_benefits_facility,Outbased,NULL,5788 Eckhert Road,,,San Antonio,TX,78240,,,,,,,210-699-5040,210-699-5079,,,,,,,,,,,,,,,
vha_459GH,Saipan VA Clinic,459GH,15.216794,145.729385,va_health_facility,Other Outpatient Services (OOS),,Marina Heights Business Park - Garapan,Medical Associates of the Pacific,MH-II Building Suite 100 and 206,Saipan,MP,96950-9998,,,,,,,670-322-0035 x,670-322-0038 x,"",800-465-8387 x,800-214-1306 x,670-322-0035 x,808-433-7600 x,,,,,,,,false,A,21
'
'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
'406':
description: Requested format unacceptable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'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
/facilities:
get:
tags:
- facilities
summary: Query facilities by location or IDs, with optional filters
description: "Query facilities by bounding box, latitude and longitude, state, visn, or zip code. Bounding box is specified as four `bbox[]` parameters, long1, lat1, long2, lat2. (Relative order is unimportant.)\n\nA query by latitude and longitude returns all facilities in the system, sorted by distance from that location. Providing an optional radius in miles to this query will narrow the scope of the returned facilities to those falling within the specified radius from that location.\n\nAll location queries support filtering by facility type, available services, and mobile status.\n\nOne can also retrieve facilities by ID using a comma-separated list like `?ids=id1,id2`. When requesting multiple facilities by ID, the API will return as many results as it can find matches for, omitting IDs where there is no match. It will not return an HTTP error code if it is unable to match a requested ID. Clients may supply IDs up to the limit their HTTP client enforces for URI path lengths. (Usually 2048 characters.)\n\nResults are paginated. JSON responses include pagination information in the standard JSON API \"links\" and \"meta\" elements. \n\n### Parameter combinations\nYou may optionally specify `page` and `per_page` with any query. You must specify one of the following parameter combinations: \n\n- `bbox[]`, with the option of any combination of `type`, `services[]`, or `mobile`\n\n- `ids`\n\n- `lat` and `long`, with the option of any combination of `radius`, `ids`, `type`, `services[]`, or `mobile`\n\n- `state`, with the option of any combination of `type`, `services[]`, or `mobile`\n\n- `visn`\n\n- `zip`, with the option of any combination of `type`, `services[]`, or `mobile`\n\n Invalid combinations will return `400 Bad Request`. "
operationId: GET:/facilities
parameters:
- name: ids
in: query
description: List of comma-separated facility IDs to retrieve in a single request. Can be combined with lat and long parameters to retrieve facilities sorted by distance from a location.
style: form
schema:
type: array
items:
type: string
examples:
ids:
description: ids
value:
- vha_688
- vha_644
- name: zip
in: query
description: Zip code to search for facilities. More detailed zip codes can be passed in, but only the first five digits are used to determine facilities to return.
schema:
type: string
format: '##### or #####-####'
examples:
zip:
description: zip
value: 80301-1000
- name: state
in: query
description: State in which to search for facilities. Except in rare cases, this is two characters.
schema:
type: string
format: XX
examples:
state:
description: state
value: CO
- name: lat
in: query
description: Latitude of point to search for facilities, in WGS84 coordinate reference system.
schema:
type: number
format: float
examples:
coordinates:
description: coordinates
value: 56.7
- name: long
in: query
description: Longitude of point to search for facilities, in WGS84 coordinate reference system.
style: form
schema:
type: number
format: float
examples:
coordinates:
description: coordinates
value: -123.4
- name: radius
in: query
description: Optional radial distance from specified latitude and longitude to filter facilities search in WGS84 coordinate reference system.
style: form
schema:
type: number
format: float
examples:
distance:
description: distance
value: 75
- name: bbox[]
in: query
description: Bounding box (longitude, latitude, longitude, latitude) within which facilities will be returned. (WGS84 coordinate reference system)
style: form
schema:
maxItems: 4
minItems: 4
type: array
items:
type: number
format: float
examples:
bbox:
description: bbox
value:
- -105.4
- 39.4
- -104.5
- 40.1
- name: visn
in: query
description: VISN search of matching facilities.
schema:
type: number
- name: type
in: query
description: Optional facility type search filter
schema:
type: string
enum:
- health
- cemetery
- benefits
- vet_center
- name: services[]
in: query
description: Optional facility service search filter
style: form
schema:
type: array
items:
type: string
- name: mobile
in: query
description: Optional facility mobile search filter
schema:
type: boolean
- name: page
in: query
description: Page of results to return per paginated response.
schema:
type: integer
format: int64
default: 1
- name: per_page
in: query
description: Number of results to return per paginated response.
schema:
type: integer
format: int64
default: 10
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FacilitiesResponse'
application/geo+json:
schema:
$ref: '#/components/schemas/GeoFacilitiesResponse'
application/vnd.geo+json:
schema:
$ref: '#/components/schemas/GeoFacilitiesResponse'
'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
'406':
description: Requested format unacceptable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'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
/facilities/{id}:
get:
tags:
- facilities
summary: Retrieve a specific facility by ID
operationId: GET:/facilities/{id}
parameters:
- name: id
in: path
description: Facility ID, in the form `<prefix>_<station>`, where prefix is one of "vha", "vba", "nca", or "vc", for health facility, benefits, cemetery, or vet center, respectively.
required: true
schema:
type: string
example: vha_688
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FacilityReadResponse'
application/geo+json:
schema:
$ref: '#/components/schemas/GeoFacilityReadResponse'
application/vnd.geo+json:
schema:
$ref: '#/components/schemas/GeoFacilityReadResponse'
'400':
description: Bad request - invalid or missing query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'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: Facility not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'406':
description: Requested format unacceptable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'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
/ids:
get:
tags:
- facilities
summary: Bulk download of all facility IDs
description: Retrieves all available facility IDs only
operationId: GET:/ids
parameters:
- name: type
in: query
description: Optional facility type search filter
schema:
type: string
enum:
- health
- cemetery
- benefits
- vet_center
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FacilitiesIdsResponse'
'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
'406':
description: Requested format unacceptable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'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
/nearby:
get:
tags:
- facilities
summary: Retrieve all VA health facilities reachable by driving within the specified time period
description: 'Retrieve all VA health facilities that are located within a specified drive time from a specified location based on coordinates (lat and lng). Optional filter parameters include drive_time and services[]. Address (street_address, city, state, and zip) no longer returns results.
The "attributes" element has information about the drive-time band that contains the requested location for each facility in the response. The values of `min_time` and `max_time` are in minutes. For example, a facility returned with a matched `min_time` of 10 and `max_time` of 20 is a 10 to 20 minute drive from the requested location.
To retrieve full details for nearby facilities, see the documentation for `/facilities?ids`.'
operationId: GET:/nearby
parameters:
- name: lat
in: query
description: Latitude of the location from which drive time will be calculated.
schema:
type: number
format: float
examples:
coordinates:
description: coordinates
value: 56.7
- name: lng
in: query
description: Longitude of the location from which drive time will be calculated.
style: form
schema:
type: number
format: float
examples:
coordinates:
description: coordinates
value: -123.4
- name: street_address
in: query
description: Street address of the location from which drive time will be calculated.
schema:
type: string
examples:
address:
description: address
value: 1350 I St. NW
- name: city
in: query
description: City of the location from which drive time will be calculated.
schema:
type: string
examples:
address:
description: address
value: Washington
- name: state
in: query
description: Two character state code of the location from which drive time will be calculated.
schema:
type: string
examples:
address:
description: address
value: DC
- name: zip
in: query
description: Zip code of the location from which drive time will be calculated.
schema:
type: string
description: '##### or #####-####'
examples:
address:
description: address
value: 20005-3305
- name: drive_time
in: query
description: Filter to only include facilities that are within the specified number of drive time minutes from the requested location.
schema:
type: integer
format: int32
default: 90
enum:
- 10
- 20
- 30
- 40
- 50
- 60
- 70
- 80
- 90
- name: services[]
in: query
description: Optional facility service search filter
style: form
schema:
type: array
items:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NearbyResponse'
'400':
description: Missing Required Or Ambiguous Parameters
content:
application/json:
schema:
$ref: '#/components/schemas/GenericError'
'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
'406':
description: Requested format unacceptable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'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
/facilities/{facilityId}:
get:
tags:
- facilities
summary: Retrieve a specific facility by ID
operationId: GET:/facilities/{facilityId}
parameters:
- name: facilityId
in: path
description: Facility ID, in the form `<prefix>_<station>`, where prefix is one of "vha", "vba", "nca", or "vc", for health facility, benefits, cemetery, or vet center, respectively.
required: true
schema:
type: string
example: vha_688
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FacilityReadResponse_2'
'400':
description: Bad request - invalid or missing query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError_2'
'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: Facility not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError_2'
'406':
description: Requested format unacceptable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError_2'
'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
/facilities/{facilityId}/services/{serviceId}:
get:
tags:
- facilities
summary: Query a specific facility service using a service ID and a facility ID.
description: "Query facility services using service parameter. Simply provide the service like `services/cardiology`. \n\nResults are paginated. JSON responses include pagination information in the standard JSON API \"links\" and \"meta\" elements. \n\nYou may optionally specify `page` and `per_page` with any query. "
operationId: GET:/facilities/{facilityId}/services/{serviceId}
parameters:
- name: facilityId
in: path
description: Facility ID, in the form `<prefix>_<station>`, where prefix is one of "vha", "vba", "nca", or "vc", for health facility, benefits, cemetery, or vet center, respectively.
required: true
schema:
type: string
example: vha_688
- name: serviceId
in: path
description: Service ID, unique identifier for service
required: true
schema:
type: string
example: covid19Vaccine
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DetailedServiceResponse'
'400':
description: Bad request - invalid or missing query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError_2'
'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: Facility not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError_2'
'406':
description: Requested format unacceptable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError_2'
'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
/facil
# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va-gov/refs/heads/main/openapi/va-gov-facilities-api-openapi.yml