{"openapi":"3.0.0","info":{"version":"0.0.1","title":"Appeals","description":"The Appeals Status API allows you to request the statuses of all decision reviews for a Veteran, including decision reviews following the AMA process and legacy benefit appeals. The statuses are returned as read only. If you need to manage or submit a Veteran’s decision review request, use the [Decision Reviews API](/explore/appeals/docs/decision_reviews?version=current). \n\n## Background\n\nThe Appeals API passes data through to Caseflow, a case management system. Caseflow accepts a header with the Veteran’s SSN and returns the current status of their decision reviews and/or benefits appeals.\n\nBecause this application is designed to allow third-parties to request information on behalf of a Veteran, we are not using VA Authentication Federation Infrastructure (VAAFI) headers or Single Sign On External (SSOe).\n\n\n## Design\n\n### Authorization and Access\n\nTo gain access to the Appeals Status API you must [request an API Key](/support/contact-us). API requests are authorized through a symmetric API token which is provided in an HTTP header named `apikey`.\n\n1. Client Request: GET https://sandbox-api.va.gov/services/appeals/v0/appeals\n    * Provide the Veteran's SSN as the X-VA-SSN header\n    * Provide the VA username of the person requesting the appeals status as the X-VA-User header\n\n2. Service Response: A JSON API object with the current status of appeals\n","termsOfService":"https://developer.va.gov/terms-of-service","contact":{"name":"Vets.gov"}},"tags":[{"name":"Appeals Status","description":"Caseflow appeals status API"}],"servers":[{"url":"https://sandbox-api.va.gov/services/appeals/{version}","description":"Sandbox","variables":{"version":{"default":"v0"}}},{"url":"https://api.va.gov/services/appeals/{version}","description":"Production","variables":{"version":{"default":"v0"}}}],"paths":{"/appeals":{"get":{"tags":["Appeals Status"],"summary":"Retrieve appeals status for the Veteran with the supplied SSN","description":"Returns a list of all known appeal records for the given Veteran. Includes details of each appeal's current status, priority, and history of updates.","operationId":"GET:/appeals","security":[{"apikey":[]}],"parameters":[{"in":"header","name":"X-VA-SSN","required":true,"example":"796130115","schema":{"type":"string"},"description":"SSN of Veteran to retrieve appeals statuses for"},{"in":"header","name":"X-VA-User","required":true,"example":"va.api.user+idme.001@gmail.com","schema":{"type":"string"},"description":"VA username of the person making the request"}],"responses":{"200":{"description":"Appeals retrieved successfully","content":{"application/json":{"schema":{"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Appeals"}}}}}},"400":{"description":"Missing SSN header"},"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":"No appeals found for supplied SSN"},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"422":{"description":"invalid SSN"},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal server error"},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}}}}},"components":{"securitySchemes":{"apikey":{"type":"apiKey","name":"apikey","in":"header"}},"schemas":{"Appeals":{"type":"array","items":{"$ref":"#/components/schemas/Appeal"}},"Appeal":{"type":"object","properties":{"id":{"type":"string","description":"ID from VACOLS (Veteran Appeals Control and Locator Service) or Caseflow","example":"7387389"},"type":{"type":"string","description":"The decision review option chosen by the appellant","example":"legacyAppeal","enum":["legacyAppeal","appeal","supplementalClaim","higherLevelReview"]},"attributes":{"type":"object","properties":{"appealIds":{"type":"array","description":"An array of the individual IDs that are combined into this appeal","items":{"type":"string","example":"1234567"}},"updated":{"type":"string","format":"date-time","example":"2018-01-03T09:30:15-05:00","description":"The timestamp for the last refresh of the data"},"active":{"type":"boolean","description":"Indicates whether the appeal is ongoing or closed","example":true},"incompleteHistory":{"type":"boolean","example":false,"description":"Indicates whether this response contains a complete history of this appeal"},"aoj":{"type":"string","description":"Agency of Original Jurisdiction, vba is Veterans Benefits Administration, vha is Veterans Health Administration, and nca is National Cemetery Administration.","example":"vba","enum":["vba","vha","nca","other"]},"programArea":{"type":"string","example":"pension","enum":["compensation","pension","insurance","loan_guaranty","education","vre","medical","burial","bva","fiduciary","other","multiple"]},"description":{"type":"string","description":"Description of the appeal","example":"Service connection, tinnitus, and 3 others"},"type":{"type":"string","description":"Indicates the type of Appeal. CAVC is the Court of Appeals for Veterans Claims","enum":["original","post_remand","post_cavc_remand","reconsideration","cue"]},"aod":{"type":"boolean","example":false,"description":"Advanced on Docket, whether this appeal was prioritized due to Veteran age or urgency."},"location":{"type":"string","example":"bva","description":"Indicates who currently has the appeal AOJ (Agency of Original Jurisdiction) or BVA (Board of Veterans Appeals)","enum":["aoj","bva"]},"status":{"type":"object","description":"This appeal's position in the appeal process","properties":{"type":{"type":"string","description":"Indicates the current position in the appeal process","enum":["scheduled_hearing","pending_hearing_scheduling","on_docket","pending_certification_ssoc","pending_certification","pending_form9","pending_soc","stayed","at_vso","bva_development","decision_in_progress","bva_decision","field_grant","withdrawn","ftr","ramp","death","reconsideration","other_close","remand_ssoc","remand","merged","evidentiary_period","ama_remand","post_bva_dta_decision","bva_decision_effectuation","sc_received","sc_decision","sc_closed","hlr_received","hlr_dta_error","hlr_decision","hlr_closed","statutory_opt_in"]},"details":{"type":"object","description":"Further information about appeal's timeline","properties":{"lastSocDate":{"type":"string","example":"2018-05-15","description":"the date of the last SOC (statement of case) or SSOC (supplemental statement of case)"},"certificationTimeliness":{"type":"array","example":[2,12],"items":{"type":"integer"},"description":"the range of months it typically takes to certify an appeal"},"ssocTimeliness":{"type":"array","example":[7,20],"items":{"type":"integer"},"description":"the range of months it typically takes to create an SSOC (supplemental statement of case)"},"decisionTimeliness":{"type":"array","example":[1,2],"items":{"type":"integer"},"description":"the range of months it typically takes to mail a decision after the appeal has been first assigned to an attorney"},"remandTimeliness":{"type":"array","example":[16,29],"items":{"type":"integer"},"description":"the range of months it typically takes to either create an SSOC (supplemental statement of case), field grant, or return to the Board a remand"},"socTimeliness":{"type":"array","example":[10,16],"items":{"type":"integer"},"description":"the range of months it typically takes to create an SOC (statement of case) or field grant"},"remandSsocTimeliness":{"type":"array","example":[3,11],"items":{"type":"integer"},"description":"the range of months it typically takes to create a second SSOC (supplemental statement of case) on a remand"},"returnTimeliness":{"type":"array","example":[1,2],"items":{"type":"integer"},"description":"the range of months it typically takes to return a remand to the Board after creating an SSOC (supplemental statement of case)"}}}}},"docket":{"type":"object","description":"Represents the appeals' position in line for a decision and the expected timing of the decision","properties":{"type":{"type":"string","description":"Indicates the docket of the appeal","enum":["directReview","evidenceSubmission","hearingRequest","legacy"],"example":"hearingRequest"},"month":{"type":"string","format":"date","example":"2016-08-01"},"docketMonth":{"type":"string","format":"date","example":"2014-06-01"},"front":{"type":"boolean","example":false},"total":{"type":"integer","example":206900},"totalAllDockets":{"type":"integer","example":420012},"ahead":{"type":"integer","example":109203},"ready":{"type":"integer","example":22109},"eta":{"$ref":"#/components/schemas/Eta"},"eligibleToSwitch":{"type":"boolean","example":true},"switchDueDate":{"type":"string","format":"date","example":"2020-06-01"}}},"issues":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}}}}}},"Eta":{"type":"object","description":"Estimated decision dates for each docket.","properties":{"directReview":{"format":"date","example":"2020-02-01"},"evidenceSubmission":{"format":"date","example":"2024-06-01"},"hearing":{"format":"date","example":"2024-06-01"}}},"Alert":{"type":"object","description":"Notification of a request for more information or of a change in the appeal status that requires action.","properties":{"type":{"type":"string","description":"Enum of notifications for an appeal. Acronyms used include cavc (Court of Appeals for Veteran Claims), vso (Veteran Service Organization), and dro (Decision Review Officer).","example":"form9_needed","enum":["form9_needed","scheduled_hearing","hearing_no_show","held_for_evidence","cavc_option","ramp_eligible","ramp_ineligible","decision_soon","blocked_by_vso","scheduled_dro_hearing","dro_hearing_no_show","evidentiary_period","ama_post_decision"]},"details":{"description":"Further information about the alert","type":"object"}}},"Event":{"type":"object","description":"Event during the appeals process","properties":{"type":{"type":"string","example":"soc","description":"Enum of possible event types. Acronyms used include, nod (Notice of Disagreement), soc (Statement of Case), ssoc (Supplemental Statement of Case), ftr (Failed to Report), bva (Board of Veteran Appeals), cavc (Court of Appeals for Veteran Claims), and dro (Decision Review Officer).","enum":["claim_decision","nod","soc","form9","ssoc","certified","hearing_held","hearing_no_show","bva_decision","field_grant","withdrawn","ftr","ramp","death","merged","record_designation","reconsideration","vacated","other_close","cavc_decision","ramp_notice","transcript","remand_return","ama_nod","docket_change","distributed_to_vlj","bva_decision_effectuation","dta_decision","sc_request","sc_decision","sc_other_close","hlr_request","hlr_decision","hlr_dta_error","hlr_other_close","statutory_opt_in"]},"date":{"type":"string","format":"date","description":"Date the event occurred","example":"2016-05-30"},"details":{"description":"Further information about the event","type":"object"}}},"Issue":{"type":"object","description":"Issues on appeal","properties":{"active":{"type":"boolean","example":true,"description":"Whether the issue is presently under contention."},"description":{"type":"string","example":"Service connection, tinnitus","description":"Description of the Issue"},"diagnosticCode":{"type":"string","example":"6260","description":"The CFR (Code of Federal Regulations) diagnostic code for the issue, if applicable"},"lastAction":{"type":"string","description":"Most recent decision made on this issue","enum":["field_grant","withdrawn","allowed","denied","remand","cavc_remand"]},"date":{"type":"string","format":"date","description":"The date of the most recent decision on the issue","example":"2016-05-30"}}},"Evidence":{"type":"object","description":"Documentation and other evidence that has been submitted in support of the appeal","properties":{"description":{"type":"string","example":"Service treatment records","description":"Short text describing what the evidence is"},"date":{"type":"string","format":"date","description":"Date the evidence was added to the case","example":"2017-09-30"}}}}}}