Caseflow APIs - TISTATechnologies/caseflow GitHub Wiki

Overview

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.

API Keys

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.

v1

The version 1 namespace includes the Caseflow Jobs API, and the IDT API.

Caseflow Jobs

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"}

IDT

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.

`GET /idt/api/v1/token`

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"
}

`GET /idt/auth?one_time_key=:your-one-time-key`

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.

`GET /idt/api/v1/appeals`

% curl -H 'TOKEN: your-idt-token' \
       -H 'FILENUMBER: veteran-file-number' \
       https://appeals.cf.ds.va.gov/idt/api/v1/appeals

`GET /idt/api/v1/appeals/:appeal_id`

% curl -H 'TOKEN: your-idt-token' \
       https://appeals.cf.ds.va.gov/idt/api/v1/appeals/uuid_or_vacols_id

`POST /idt/api/v1/appeals/:appeal_id/outcode`

`POST /idt/api/v1/appeals/:appeal_id/upload_document`

`GET /idt/api/v1/judges`

% curl -H 'TOKEN: your-idt-token' \
       https://appeals.cf.ds.va.gov/idt/api/v1/judges

`GET /idt/api/v1/user`

% curl -H 'TOKEN: your-idt-token' \
       https://appeals.cf.ds.va.gov/idt/api/v1/user

`GET /idt/api/v1/veterans`

% curl -H 'TOKEN: your-idt-token' \
       -H 'FILENUMBER: veteran-file-number' \
       https://appeals.cf.ds.va.gov/idt/api/v1/veterans

v2

The version 2 namespace includes the va.gov Appeals Status API, and the VETText / Hearings API.

va.gov Appeals Status

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.

VETText / Hearings

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"
      }
   ]
}

v3

The version 3 namespace is reserved for the Decision Review API

Decision Review 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.

Documentation

The authorative documentation for the Decision Review API's endpoints is maintained in a single file

app/controllers/api/docs/v3/decision_reviews.yaml

which is served via the v3 documentation endpoint.

The easiest way of viewing the documentation is via https://dev-developer.va.gov/explore/appeals/docs/decision_reviews which pulls decision_review.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 into: http://editor.swagger.io/

decision_review.yaml uses the OpenAPI specification (Swagger).

Implementation Notes

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.

Renaming of Fields

Some model attributes are renamed to shield a consumer of the Decision Review API from unnecessary complexity or verbosity. Examples:

vacols_id to legacyAppealId
vacols_sequence_id to legacyAppealIssueId
rating_issue_reference_id to ratingIssueId

other APIs / endpoints

VACOLS

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

VBMS

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

BGS

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)

VVA

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

Redshift DB

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

docs

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.

metadata endpoint

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.