Caseflow APIs - department-of-veterans-affairs/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, MPI API and 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"}

MPI

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

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

GET /idt/api/v2/appeals

GET /idt/api/v2/appeals/:appeal_id

GET /idt/api/v2/appeals/:appeal_id/documents

GET /idt/api/v2/appeals/:appeal_id/documents/:document_id

POST /idt/api/v2/appeals/:appeal_id/outcode

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 and the Issues 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.

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

Issues API

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.

GET /api/v3/issues/ama/find_by_veteran/:participant_id

GET /api/v3/issues/vacols/find_by_veteran (passing in passing in ssn/vfn as a header)

V3 Documentation

Yaml Files

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).

Metrics Dashboards

Performance metrics are gathered for the Issues API via three metrics dashboards across Kibana UAT, Kibana Prod, and DataDog.

Kibana Prod & Kibana UAT

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

DataDog

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

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.

Events API

The Events API end point is used by the appeals-consumer to POST the Records and EventRecords from the Kafka Consumer Messages.

v1

DecisionReviewCreated

  • 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