Va

Benefits Intake

The Benefits Intake API allows authorized third-party systems used by Veteran Service Organizations (VSOs), agencies, and Veterans to digitally submit VA…

Government & public#openapi#open-data

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Benefits Intake API allows authorized third-party systems used by Veteran Service Organizations (VSOs), agencies, and Veterans to digitally submit VA benefits claim documents directly to the Veterans Benefits Administration's (VBA) claims intake process. This API handles documents related to the following benefit claim types:

  • Compensation
  • Pension/Survivors Benefits
  • Education
  • Fiduciary
  • Insurance
  • Veteran Readiness & Employment (VRE)
  • Board of Veteran Appeals (BVA)

This API also provides submission status updates until documents are successfully established for VBA claim processing, eliminating the need for users to switch between systems to manually check whether documents have been successfully uploaded.

Background

This API provides a secure, efficient, and tracked alternative to mail or fax for VA benefit claim document submissions. Documents are uploaded directly to the VBA so they can be processed as quickly as possible.

Technical overview

The Benefits Intake API first provides an upload location and unique submission identifier, and then accepts a payload consisting of a document in PDF format, zero or more optional attachments in PDF format, and some JSON metadata.

The metadata describes the document and attachments, and identifies the person for whom it is being submitted. This payload is encoded as binary multipart/form-data (not base64). The unique identifier supplied with the payload can subsequently be used to request the processing status of the uploaded document package.

To avoid errors and processing delays, API consumers are encouraged to validate the zipcode,fileNumber, veteranFirstName, veteranLastName and businessLine fields before submission according to their description in the DocumentUploadMetadata model and use the 'businessLine' attribute for the most efficient processing. Additionally, please ensure no PDF user passwords are used in submitted PDFs.

Attachment & file size limits

There is no limit on the number of files a payload can contain, but size limits do apply.

  • Uploaded documents cannot be larger than 21" x 21"
  • The entire payload cannot exceed 5 GB
  • No single file in a payload can exceed 100 MB

Date of receipt

The date that documents are successfully submitted through the Benefits Intake API is used as the official VA date of receipt. However, note that until a document status of received, processing, success, or vbms is returned, a client cannot consider the document received by VA.

A status of received means that the document package has been transmitted, but may not be validated. Any errors with the document package, such as unreadable PDFs or a Veteran not found, will cause the status to change to error.

If the document status is error, VA has not received the submission and cannot honor the submission date as the date of receipt.

Authentication and Authorization

API requests are authorized through a symmetric API token, provided in an HTTP header with name 'apikey'. Request an API key.

Testing in the sandbox environment

In the sandbox environment, the final status of a submission is received and submissions do not actually progress to the central mail repository or VBMS.

Progress beyond the received status can be simulated for testing. We allow passing in a Status-Override header on the /uploads/{id} endpoint so that you can change the status of your submission to simulate the various scenarios.

The available statuses are pending, uploaded, received, processing, success, vbms, and error. The meaning of the various statuses is listed below in Models under DocumentUploadStatusAttributes.

Test data

We use mock test data in the sandbox environment. Data is not sent upstream and it is not necessary to align submitted test data with any other systems' data.

Validating documents

Use the POST /uploads/validate_document endpoint to make sure your documents will pass system file requirements and
validations before you send them through the submissions process. This step is optional but decreases the likelihood
of individual document errors during the submission process.

Validations performed:

  • Document is a valid PDF (Note: Content-Type header value must be "application/pdf")
  • Document does not have a user password (an owner password is acceptable)
  • File size does not exceed 100 MB
  • Page size does not exceed 21" x 21"

Upload operation

Allows a client to upload a multi-part document package (form + attachments + metadata).

  1. Client Request: POST https://sandbox-api.va.gov/services/vba_documents/v1/
  • No request body or parameters required
  1. Service Response: A JSON API object with the following attributes:
  • guid: An identifier used for subsequent status requests
  • location: A URL to which the actual document package payload can be submitted in the next step. The URL is specific to this upload request,…

Endpoints 6

VBA Documents

  • PUTAccepts document upload./pathAccepts document metadata, document binary, and attachment binaries. Full URL, including query parameters, provided from POST /document_uploads. Example…
  • POSTGet a location for subsequent document upload PUT request/uploads
  • POSTGet a bulk status report for a list of previous uploads/uploads/report
  • POSTValidate an individual document against system file requirements/uploads/validate_documentUsing this endpoint will decrease the likelihood of errors associated with individual documents during the submission process. Validations performed: *…
  • GETGet status for a previous benefits document upload/uploads/:id
  • GETDownload zip of "what the server sees"/uploads/:id/downloadAn 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…

API details

Base URL
https://sandbox-api.va.gov/services/vba_documents/{version}
https://api.va.gov/services/vba_documents/{version}
Authentication
An API key in the apikey header
Operations
6 operations on 6 pathsPOST 3GET 2PUT 1
Main resources
VBA Documents 6
Response formats
application/json application/xml application/zip
Description format
OpenAPI 3.0.0, API version 1.0.0
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the Benefits Intake in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Benefits Intake collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the apikey header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Accepts document upload.” (PUT /path), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Benefits Intake?

The Benefits Intake API allows authorized third-party systems used by Veteran Service Organizations (VSOs), agencies, and Veterans to digitally submit VA… It is listed under Government & public and has 6 endpoints.

Who publishes the Benefits Intake?

It is listed from Va's public API description (an OpenAPI document), not published by Va on Swastik Codes. Anyone who controls va.gov can claim the profile by adding a DNS TXT record.

What is the base URL of the Benefits Intake?

Its description lists 2 base URLs: https://sandbox-api.va.gov/services/vba_documents/{version}, https://api.va.gov/services/vba_documents/{version}. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Benefits Intake?

With an API key in the apikey header.

How many endpoints does the Benefits Intake have?

6 operations on 6 paths (3 POST, 2 GET, 1 PUT). The largest groups are VBA Documents.

Is forking the Benefits Intake free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.