Caseflow APIs
Caseflow provides HTTP APIs for consumption by external services. Generally these APIs expose Caseflow data in a read-only pattern via specific queries, although some API endpoints do allow for modifying Caseflow data (e.g. Caseflow Jobs, IDT, Decision Review API).
All API responses are in JSON format.
All API requests prefer to keep sensitive PII out of URLs and instead inside HTTP headers. This helps prevent leaking PII into logs and unauthorized communication channels.
Only actively maintained APIs are documented here. See the Git log history of this document for details.
All API requests require a valid API key token, which is passed in the Authorization
HTTP header. See the curl
examples below for the proper syntax.
If you need an API key, you can request one via YourIT.
If you are a Caseflow administrator, you can create a key in the Caseflow Rails console:
irb> api_key = ApiKey.create!(consumer_name: "Some Application")
irb> api_key.key_string
# the key string is what you pass in the HTTP header
Most, but not all APIs / endpoints are scoped under a version number: v1, v2, or v3.
The version 1 namespace includes the Caseflow Jobs API, MPI API and IDT API.
You may POST /api/v1/jobs
with the job_type
body parameter in order to create a new Shoryuken-based job.
The list of job types available is in
the controller.
% curl -XPOST -H 'Authorization: Token your-sekrit-key' \
https://appeals.cf.ds.va.gov/api/v1/jobs -d 'job_type=sync_intake'
On success you would receive a response with HTTP code 200
and body like:
{"success":true, "job_id":"5beec69d-a777-497e-b65d-2ac488b507ba"}
On failure you would receive a response with HTTP code 422
and body like:
{"error_code":"Unable to start unrecognized job"}
or if the API key was missing or not found, a HTTP code 401
and body like:
{"status":"unauthorized"}
The Master Patient Index (MPI) API would allow for updates from the MPI to be passed through to Caseflow.
You may POST /api/v1/mpi
with the veterans_id
, and deceased_time
body parameters in order to create a new veterans update.
% curl -XPOST -H 'Authorization: Token your-sekrit-key' \
https://appeals.cf.ds.va.gov/api/v1/mpi -d 'veterans_id=111001111&deceased_ind=False&deceased_time=nil'
On success you would receive a response with HTTP code 200
and body like:
{"success":true}
or if the API key was missing or not found, a HTTP code 401
and body like:
{"status":"unauthorized"}
The Interactive Decision Template (IDT) is a set of Microsoft Word macros that allow for authoring and publishing BVA decisions natively in Word. The IDT API allows Word to pre-populate the document with Veteran data from VACOLS/Caseflow.
There are several endpoints available in the IDT API.
Returns a one-time key and token for subsequent requests.
% curl -H 'Authorization: Token your-sekrit-key' \
https://appeals.cf.ds.va.gov/idt/api/v1/token
On success returns a 200
HTTP code and a body like:
{
"one_time_key" : "a-long-128-byte-string",
"token" : "another-long-128-byte-string"
}
Activates an IDT session based on a one-time key. The default IDT session is 7 days.
NOTE this is typically done via a web browser since it requires an active authenticated Caseflow browser session to link with a Caseflow user account.
% curl -H 'Authorization: Token your-sekrit-key' \
https://appeals.cf.ds.va.gov/idt/auth?one_time_key=a-long-128-byte-string
On success returns a 200
HTTP code and body like:
{"message":"Success!"}
On error returns a 400
code with an error message like:
{"message":"Invalid key."}
Once the IDT session is activated, the token
is passed in subsequent requests.
% curl -H 'TOKEN: your-idt-token' \
-H 'FILENUMBER: veteran-file-number' \
https://appeals.cf.ds.va.gov/idt/api/v1/appeals
% curl -H 'TOKEN: your-idt-token' \
https://appeals.cf.ds.va.gov/idt/api/v1/appeals/uuid_or_vacols_id
% curl -H 'TOKEN: your-idt-token' \
https://appeals.cf.ds.va.gov/idt/api/v1/judges
% curl -H 'TOKEN: your-idt-token' \
https://appeals.cf.ds.va.gov/idt/api/v1/user
% curl -H 'TOKEN: your-idt-token' \
-H 'FILENUMBER: veteran-file-number' \
https://appeals.cf.ds.va.gov/idt/api/v1/veterans
The version 2 namespace includes the va.gov Appeals Status API, and the VETText / Hearings API.
The Appeals Status feature of va.gov allows Veterans to see details about their cases.
Additional documentation is available.
You may GET /api/v2/appeals
with the Veteran Social Security Number (SSN) in the ssn
HTTP header
and a source
string of your choosing.
% curl -H 'Authorization: Token your-sekrit-key' \
-H 'ssn: 987654321' \
-H 'source: white house hotline' \
https://appeals.cf.ds.va.gov/api/v2/appeals
On success you would receive a 200
HTTP code and a body like:
{
"data" : [
{
"attributes" : {
"active" : false,
"alerts" : [],
"aoj" : "vba",
"appealIds" : [
"HLR2"
],
"description" : "1 issue",
"events" : [
{
"date" : "2018-04-01",
"type" : "hlr_request"
},
{
"date" : "2019-06-04",
"type" : "hlr_other_close"
}
],
"evidence" : [],
"incompleteHistory" : false,
"issues" : [],
"location" : "aoj",
"programArea" : null,
"status" : {
"details" : {},
"type" : "hlr_closed"
},
"updated" : "2019-06-05T15:37:37-04:00"
},
"id" : "HLR2",
"type" : "higherLevelReview"
},
{
"attributes" : {
"active" : true,
"alerts" : [],
"aod" : true,
"aoj" : "vba",
"appealIds" : [
"2760964"
],
"description" : "Service connection, pancreatitis",
"docket" : null,
"events" : [
{
"date" : "2014-01-29",
"type" : "claim_decision"
},
{
"date" : "2014-11-01",
"type" : "nod"
},
{
"date" : "2015-08-19",
"type" : "soc"
},
{
"date" : "2015-09-22",
"type" : "form9"
},
{
"date" : "2018-09-25",
"type" : "ssoc"
},
{
"date" : "2018-10-03",
"type" : "certified"
},
{
"date" : "2019-02-08",
"type" : "bva_decision"
},
{
"date" : "2019-05-27",
"type" : "hearing_held"
}
],
"evidence" : [],
"incompleteHistory" : false,
"issues" : [
{
"active" : true,
"date" : "2019-02-08",
"description" : "Service connection, pancreatitis",
"diagnosticCode" : "7347",
"lastAction" : "remand"
}
],
"location" : "aoj",
"programArea" : "compensation",
"status" : {
"details" : {
"issues" : [
{
"description" : "Service connection, pancreatitis",
"disposition" : "remanded"
}
],
"remand_timeliness" : [
16,
29
]
},
"type" : "remand"
},
"type" : "original",
"updated" : "2019-06-05T15:37:37-04:00"
},
"id" : "2760964",
"type" : "legacyAppeal"
}
]
}
If you provide an invalid SSN, the response would be a 422
HTTP code and a body like:
{
"errors" : [
{
"detail" : "Please enter a valid 9 digit SSN in the 'ssn' header",
"status" : "422",
"title" : "Invalid SSN"
}
]
}
Other invalid request parameters would receive similarly formatted error responses.
The Hearings API returns all the hearings scheduled for a given day.
% curl -H 'Authorization: Token your-sekrit-key' \
https://appeals.cf.ds.va.gov/api/v2/hearings/2019-06-07
On success returns 200
HTTP code and a body like:
{
"hearings": [
{
"address": "15 New Sudbury Street JFK Federal Building",
"appeal": "182fd411-c770-44c8-8491-0de36ac6f92c",
"city": "Boston",
"facility_id": "vba_301",
"first_name": "John",
"last_name": "Veteran",
"participant_id": "12345",
"hearing_location": "Boston",
"is_virtual": false,
"room": "123",
"scheduled_for": "2019-07-24T13:30:00.000-04:00",
"ssn": "666456999",
"state": "MA",
"timezone": "America/New_York",
"zip_code": "02203"
},
{
"address": "123 Main St.",
"appeal": "d69d7c3f-fd68-45aa-9bb9-556622fd557b",
"city": "Providence",
"facility_id": "vba_999",
"first_name": "Jane",
"last_name": "Veteran",
"participant_id": "23456",
"hearing_location": "Providence",
"is_virtual": false,
"room": "456",
"scheduled_for": "2019-07-24T13:30:00.000-04:00",
"ssn": "666456000",
"state": "RI",
"timezone": "America/New_York",
"zip_code": "12345"
}
]
}
The version 3 namespace is reserved for the Decision Review API and the Issues API
As a complement to the claims assistants' intake UI, Caseflow Intake, the Decision Review API provides a way for users outside of the VA (veterans, VSOs, etc) to create, edit, view, delete, and check the status of decision reviews.
The Decision Review API depends heavily on the existing controllers/models/classes that support Caseflow Intake, but diverges where necessary to support the different audience of the API. The Decision Review API is actively being developed with an MVP of supporting a va.gov front end for veterans to submit their own decision reviews.
Some model attributes are renamed to shield a consumer of the Decision Review API from unnecessary complexity or verbosity. Examples:
-
vacols_id
tolegacyAppealId
-
vacols_sequence_id
tolegacyAppealIssueId
-
rating_issue_reference_id
toratingIssueId
VBMS will be taking over the intake process for Higher Level Reviews and Supplemental Claims with benefit types: Compensation, Pension, and Fiduciary. The Issues API will allow users at VBMS to view Request Issue and Decision Issue, and if applicable, VACOLS data for a specific Veteran.
The Issues API is not live in production. It is only available through UAT.
{
"page": 1,
"total_number_of_pages": 1,
"total_request_issues_for_vet": 1,
"max_request_issues_per_page": 10,
"veteran_participant_id": "000900015",
"legacy_appeals_present": true,
"request_issues": [{
"id": 8675,
"benefit_type": "compensation",
"closed_at": null,
"closed_status": null,
"contention_reference_id": null,
"contested_decision_issue_id": null,
"contested_issue_description": null,
"contested_rating_decision_reference_id": null,
"contested_rating_issue_diagnostic_code": "5008",
"contested_rating_issue_profile_date": "2024-04-30",
"contested_rating_issue_reference_id": "rating_issue753",
"corrected_by_request_issue_id": null,
"correction_type": null,
"created_at": "2024-04-30T18:25:23.509Z",
"decision_date": "2024-04-30",
"decision_review_id": 3760,
"decision_review_type": "Appeal",
"edited_description": null,
"end_product_establishment_id": null,
"ineligible_due_to_id": null,
"ineligible_reason": null,
"is_unidentified": null,
"nonrating_issue_bgs_id": null,
"nonrating_issue_bgs_source": null,
"nonrating_issue_category": null,
"nonrating_issue_description": null,
"notes": null,
"ramp_claim_id": null,
"split_issue_status": null,
"unidentified_issue_text": null,
"untimely_exemption": null,
"untimely_exemption_notes": null,
"updated_at": "2024-04-30T18:25:23.514Z",
"vacols_id": "2760964",
"vacols_sequence_id": 1,
"verified_unidentified_issue": null,
"veteran_participant_id": "000900015",
"caseflow_considers_decision_review_active": false,
"caseflow_considers_issue_active": true,
"caseflow_considers_title_of_active_review": null,
"caseflow_considers_eligible": true,
"claimant_participant_id": "000900015",
"claim_id": null,
"claim_errors": [],
"decision_issues": [{
"id": 3430,
"caseflow_decision_date": "2024-04-25",
"created_at": "2024-04-30T18:25:23.519Z",
"decision_text": null,
"deleted_at": null,
"description": "description officiis eum quia debitis",
"diagnostic_code": "9999",
"disposition": "allowed",
"end_product_last_action_date": null,
"percent_number": null,
"rating_issue_reference_id": null,
"rating_profile_date": null,
"rating_promulgation_date": null,
"subject_text": null,
"updated_at": "2024-04-30T18:25:23.519Z"
}]
}]
}
{
"page": 1,
"total_number_of_pages": 1,
"total_vacols_issues_for_vet": 1,
"max_vacols_issues_per_page": 10,
"veteran_participant_id": "000900015",
"veteran_file_number": "000900015",
"vacols_issues": [
{
"id": "2760964",
"notice_of_disagreement_date": "2019-03-09T00:00:00.000Z",
"legacy_appeal_status": "Remand",
"legacy_appeal_soc_date": "2019-12-25T00:00:00.000Z",
"legacy_appeal_ssoc_dates": ["2023-01-31T00:00:00.000Z"],
"legacy_appeal_eligible_for_opt_in": false,
"legacy_appeal_eligible_for_soc_opt_in_with_exemption": true,
"vacols_id": "2760964",
"vacols_sequence_id": 1,
"eligible_for_soc_opt_in": true,
"eligible_for_soc_opt_in_with_exemption": true,
"description": "Service connection, pancreatitis",
"disposition": "remanded",
"close_date": "2023-06-16T00:00:00.000Z",
"note": "Itaque adipisci aut ullam voluptas recusandae possimus facilis."
}
]
}
The authoritative v3 documentation is maintained in yaml files
The Decision Review API is maintained in:
app/controllers/api/docs/v3/decision_reviews.yaml
The AMA Issues API is maintained in:
app/controllers/api/docs/v3/ama_issues.yaml
The VACOLS Issues API is maintained in:
app/controllers/api/docs/v3/vacols_issues.yaml
which are served via the v3 documentation endpoint.
The easiest way of viewing the documentation is via the http://dev-developer.va.gov/explore/appeals/docs docs for Decision Reviews and AMA Issues which pull yaml from Caseflow (using the documentation endpoint) and renders it in an easy-to-read format with css, collapsible sections, etc.
The second easiest would be pasting the text of decision_review.yaml
or ama_issues.yaml
into: http://editor.swagger.io/
decision_review.yaml
and ama_issues.yaml
use the OpenAPI specification (Swagger).
Performance metrics are gathered for the Issues API via three metrics dashboards across Kibana UAT, Kibana Prod, and DataDog.
Dashboard: Issue Eligibility
Metrics Tracked:
- [Line Graph] All Requests:
- All endpoint requests made to both Issue Eligibility Endpoints within a specified timeframe
- [Metric] [Cumulative] All Requests:
- Amount of all endpoint requests made to both Issue Eligibility Endpoints
- [Gauge] 500 Responses:
- Amount of 500 responses sent from both Issue Eligibility Endpoints
- [Gauge] 404 Responses:
- Amount of 404 responses sent from both Issue Eligibility Endpoints
- [Gauge] 401 Responses:
- Amount of 401 responses sent from both Issue Eligibility Endpoints
- [Line Graph] AMA Responses by Response Type:
- All endpoint requests by response type made to the AMA Issue Eligibility Endpoint within a specified timeframe
- [Line Graph] VACOLS Responses by Response Type:
- All endpoint requests by response type made to the VACOLS Issue Eligibility Endpoint within a specified timeframe
- [Bar Graph] VACOLS Successful vs Failed Requests:
- All endpoint requests shown by successful (200) vs failed (401, 404, 500) made to the VACOLS Issue Eligibility Endpoint within a specified timeframe
- [Bar Graph] AMA Successful vs Failed Requests:
- All endpoint requests shown by successful (200) vs failed (401, 404, 500) made to the AMA Issue Eligibility Endpoint within a specified timeframe
Dashboards: Issue Eligibility [UAT] & Issue Eligibility [Prod]
Metrics Tracked:
- [Metric] [Avg] AMA Endpoint Request Latency
- The average amount of seconds that passes between the request being received to a response being sent for the AMA Eligibility Endpoint within a specified timeframe
- [Metric] [Avg] VACOLS Endpoint Request Latency
- The average amount of seconds that passes between the request being received to a response being sent for the VACOLS Eligibility Endpoint within a specified timeframe
- [Line Graph] [Sum] AMA and VACOLS Endpoint Request Attempts:
- All requests made to both of the Issue Eligibility Endpoints within a specified timeframe
- [Line Graph] [Sum] VACOLS Endpoint Request Attempts vs Request Failures:
- All endpoint requests shown by successful (200) vs failed (401, 404, 500) made to the VACOLS Issue Eligibility Endpoint within a specified timeframe
- [Line Graph] [Sum] AMA Endpoint Request Attempts vs Request Failures:
- All endpoint requests shown by successful (200) vs failed (401, 404, 500) made to the AMA Issue Eligibility Endpoint within a specified timeframe
- Stands for Veterans Appeals Control and Location System (or Service)
- Is an Oracle database with cURL ability via a Powerbuilder application that stores files related to current appeals which is stored in VA systems (non-cloud)
- There are a total of 3 Powerbuilder applications that interact with VACOLS
- Goal is to deprecate VACOLS in 2 - 3 yrs
- Queue is designed to replace the VACOLS UI and support both legacy (pre-AMA) and new (RAMP - Rapid Appeals Modernization Program or AMA - Appeals Modernization Act) appeals
- Intake is designed to process AMA appeals and will not touch VACOLS, only operating in the AWS environment
- Stands for Veterans Benefits Management System
- VBMS stores all documents that a veteran provides to support an appeal and is stored in VA systems as well as tracks the state of appeals and end product
- Maintained by Booz Allen Hamilton Caseflow Reader is built to deprecate the VBMS UI
- Reader connects to eFolder Express which currently queries VBMS for documents and stores them in Amazon S3
- Goal is to eventually move all of VBMS to the Amazon cloud
- Stands for Benefits Gateway Services
- Is an API for the VA’s corpDB
- Stores all Veteran contact info
- VBMS is dependent on BGS and when BGS goes down, the other services may go down as well
- BGS outages affect all regional VA offices
- Only operates during working hours (8am - 5pm)
- Stands for Virtual VA (legacy content manager)
- Goes down frequently, does not operate between 7pm - 8am or weekends
- Caseflow connects to VVA via eFolder Express
- Amazon DB storing up to a petabyte designed for analytics services
- The Redshift DB will replicate VACOLS, Caseflow & efolder Express
- Provides a way to efficiently run SQL queries and run reports
- Also allows for joins across the other databases
- The only source it does not currently connect to is BGS
The Decision Review API is documented in:
app/controllers/api/docs/v3/decision_reviews.yaml
using the OpenAPI specification (Swagger).
This file is served via:
GET /api/docs/v3/decision_reviews
Note: the route isn't:
GET /api/v3/docs/decision_reviews
(or any other variation). This directory structure is a precendent set by other APIs within the Lighthouse project.
This endpoint does not require an API key.
The metadata endpoint (GET api/metadata
) is used by the Lighthouse developer portal to fetch metadata (version, health-check, documentation path) about the Decision Review API.
The Events API end point is used by the appeals-consumer to POST the Records and EventRecords from the Kafka Consumer Messages.
- DecisionReviewCreatedError end point is used to show a response that the Decision Review Created had an Error. The route is:
POST /api/events/v1/decision_review_created_error
- Home
- Acronyms and Glossary
- Caseflow products
- Caseflow Intake
- Caseflow Queue
- Caseflow Reader
- Caseflow eFolder
- Caseflow Hearings
- Caseflow Certification
- Caseflow APIs
- Appeal Status API
- Caseflow Dispatch
-
CSUM Roles
- System Admin
- VHA Team Management
- Active Record Queries Resource
- External Integrations
- Caseflow Demo
- Caseflow ProdTest
- Background
- Stuck Jobs
- VA Notify
- Caseflow-Team
- Frontend Best Practices
- Accessibility
- How-To
- Debugging Tips
- Adding a Feature Flag with FeatureToggle
- Editing AMA issues
- Editing a decision review
- Fixing task trees
- Investigating and diagnosing issues
- Data and Metric Request Workflow
- Exporting and Importing Appeals
- Explain page for Appeals
- Record associations and Foreign Keys
- Upgrading Ruby
- Stuck Appeals
- Testing Action Mailer Messages Locally
- Re-running Seed Files
- Rake Generator for Legacy Appeals
- Manually running Scheduled Jobs
- System Admin UI
- Caseflow Makefile
- Upgrading Postgresql from v11.7 to v14.8 Locally
- VACOLS VM Trigger Fix M1
- Technical Talks