Veterans Affairs Appeals Status API
The Appeals Status API from Veterans Affairs — 1 operation(s) for appeals status.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/va-appeals-status-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Appeals Status API
version: v1
contact:
name: developer.va.gov
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.
To retrieve a list of a claimant’s active contestable issues or legacy appeals, use one of these APIs:
* [Appealable Issues API](https://developer.va.gov/explore/api/appealable-issues/docs)
* [Legacy Appeals API](https://developer.va.gov/explore/api/legacy-appeals/docs)
To file an appeal or decision review, use one of these APIs:
* [Higher-Level Reviews API](https://developer.va.gov/explore/api/higher-level-reviews/docs)
* [Notice of Disagreements API](https://developer.va.gov/explore/api/notice-of-disagreements/docs)
* [Supplemental Claims API](https://developer.va.gov/explore/api/supplemental-claims/docs)
## Background
The Appeals API passes data through to Caseflow, a case management system. Caseflow returns the current status of the Veteran’s decision reviews and/or benefits appeals.
Because 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).
## Technical overview
### Authentication and Authorization
The authentication model for the Appeals Status API uses OAuth 2.0/OpenID Connect. The following authorization models are supported:
* [Authorization code flow](https://developer.va.gov/explore/api/appeals-status/authorization-code)
* [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/appeals-status/client-credentials)
**Important:** To get production access using client credentials grant, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us).
### Test data
Our sandbox environment is populated with [Veteran test data](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts/appeals_status_test_accounts.md) that can be used to test various response scenarios. This sandbox data contains no PII or PHI, but mimics real Veteran account information.
'
servers:
- url: https://sandbox-api.va.gov/services/appeals/appeals-status/{version}
description: VA.gov API sandbox environment
variables:
version:
default: v1
- url: https://api.va.gov/services/appeals/appeals-status/{version}
description: VA.gov API production environment
variables:
version:
default: v1
tags:
- name: Appeals Status
description: ''
paths:
/appeals:
get:
summary: Retrieve appeals status for the Veteran with the supplied ICN
tags:
- Appeals Status
operationId: getAppealStatus
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.
security:
- productionOauth:
- veteran/AppealsStatus.read
- representative/AppealsStatus.read
- system/AppealsStatus.read
- sandboxOauth:
- veteran/AppealsStatus.read
- representative/AppealsStatus.read
- system/AppealsStatus.read
- bearer_token: []
parameters:
- name: icn
description: Veteran's Master Person Index (MPI) Integration Control Number (ICN). Optional when using a veteran-scoped token. Required when using a representative- or system-scoped token.
example: 1012832025V743496
schema:
type: string
pattern: ^[0-9]{10}V[0-9]{6}$
minLength: 17
maxLength: 17
in: query
required: false
responses:
'200':
description: Successfully fetching appeals
content:
application/json:
examples:
with a veteran-scoped token (no 'icn' parameter necessary):
value:
data:
- attributes:
appealIds: []
active: false
alerts: []
aod: false
aoj: vba
description: ''
docket: null
events:
- date: '2002-09-23'
type: claim_decision
- date: '2003-01-06'
type: nod
- date: '2003-06-18'
type: soc
- date: '2003-09-30'
type: ftr
evidence: []
incompleteHistory: false
issues:
- active: false
date: '2003-09-30'
description: Service connection, lumbosacral strain
diagnosticCode: '5295'
lastAction: withdrawn
location: bva
programArea: compensation
status:
details: {}
type: ftr
type: original
updated: '2018-01-19T10:20:42-05:00'
id: '1196201'
type: legacyAppeal
- attributes:
appealIds: []
active: true
alerts: []
aod: false
aoj: vba
description: ''
docket: null
events:
- date: '2008-04-24'
type: claim_decision
- date: '2008-06-11'
type: nod
- date: '2010-09-10'
type: soc
- date: '2010-11-08'
type: form9
- date: '2014-01-03'
type: ssoc
- date: '2014-07-28'
type: certified
- date: '2015-04-17'
type: hearing_held
- date: '2015-07-24'
type: bva_decision
- date: '2015-10-06'
type: ssoc
- date: '2016-05-03'
type: bva_decision
- date: '2018-01-16'
type: ssoc
evidence: []
incompleteHistory: false
issues:
- active: true
date: '2016-05-03'
description: Increased rating, migraines
diagnosticCode: '8100'
lastAction: remand
- active: true
date: '2016-05-03'
description: Increased rating, limitation of leg motion
diagnosticCode: '5260'
lastAction: remand
- active: true
date: '2016-05-03'
description: 100% rating for individual unemployability
diagnosticCode: null
lastAction: remand
- active: false
date: null
description: Service connection, ankylosis of hip
diagnosticCode: '5250'
lastAction: null
- active: true
date: '2015-07-24'
description: Service connection, degenerative spinal arthritis
diagnosticCode: '5242'
lastAction: remand
- active: false
date: null
description: Service connection, hearing loss
diagnosticCode: '6100'
lastAction: null
- active: true
date: '2015-07-24'
description: Service connection, sciatic nerve paralysis
diagnosticCode: '8520'
lastAction: remand
- active: false
date: null
description: Service connection, arthritis due to trauma
diagnosticCode: '5010'
lastAction: null
- active: false
date: '2015-07-24'
description: New and material evidence for service connection, degenerative spinal arthritis
diagnosticCode: '5242'
lastAction: allowed
location: aoj
programArea: compensation
status:
details: {}
type: remand_ssoc
type: post_remand
updated: '2018-01-19T10:20:42-05:00'
id: '3294289'
type: legacyAppeal
- attributes:
appealIds: []
active: false
alerts: []
aod: false
aoj: other
description: ''
docket: null
events:
- date: '2010-08-11'
type: claim_decision
- date: '2010-09-17'
type: nod
- date: '2013-09-26'
type: soc
- date: '2013-10-02'
type: form9
- date: '2014-07-28'
type: certified
- date: '2015-02-26'
type: merged
evidence: []
incompleteHistory: false
issues: []
location: bva
programArea: null
status:
details: {}
type: other_close
type: original
updated: '2018-01-19T10:20:42-05:00'
id: '2348605'
type: legacyAppeal
with a representative-scoped token ('icn' parameter is necessary):
value:
data:
- attributes:
appealIds: []
active: false
alerts: []
aod: false
aoj: vba
description: ''
docket: null
events:
- date: '2002-09-23'
type: claim_decision
- date: '2003-01-06'
type: nod
- date: '2003-06-18'
type: soc
- date: '2003-09-30'
type: ftr
evidence: []
incompleteHistory: false
issues:
- active: false
date: '2003-09-30'
description: Service connection, lumbosacral strain
diagnosticCode: '5295'
lastAction: withdrawn
location: bva
programArea: compensation
status:
details: {}
type: ftr
type: original
updated: '2018-01-19T10:20:42-05:00'
id: '1196201'
type: legacyAppeal
- attributes:
appealIds: []
active: true
alerts: []
aod: false
aoj: vba
description: ''
docket: null
events:
- date: '2008-04-24'
type: claim_decision
- date: '2008-06-11'
type: nod
- date: '2010-09-10'
type: soc
- date: '2010-11-08'
type: form9
- date: '2014-01-03'
type: ssoc
- date: '2014-07-28'
type: certified
- date: '2015-04-17'
type: hearing_held
- date: '2015-07-24'
type: bva_decision
- date: '2015-10-06'
type: ssoc
- date: '2016-05-03'
type: bva_decision
- date: '2018-01-16'
type: ssoc
evidence: []
incompleteHistory: false
issues:
- active: true
date: '2016-05-03'
description: Increased rating, migraines
diagnosticCode: '8100'
lastAction: remand
- active: true
date: '2016-05-03'
description: Increased rating, limitation of leg motion
diagnosticCode: '5260'
lastAction: remand
- active: true
date: '2016-05-03'
description: 100% rating for individual unemployability
diagnosticCode: null
lastAction: remand
- active: false
date: null
description: Service connection, ankylosis of hip
diagnosticCode: '5250'
lastAction: null
- active: true
date: '2015-07-24'
description: Service connection, degenerative spinal arthritis
diagnosticCode: '5242'
lastAction: remand
- active: false
date: null
description: Service connection, hearing loss
diagnosticCode: '6100'
lastAction: null
- active: true
date: '2015-07-24'
description: Service connection, sciatic nerve paralysis
diagnosticCode: '8520'
lastAction: remand
- active: false
date: null
description: Service connection, arthritis due to trauma
diagnosticCode: '5010'
lastAction: null
- active: false
date: '2015-07-24'
description: New and material evidence for service connection, degenerative spinal arthritis
diagnosticCode: '5242'
lastAction: allowed
location: aoj
programArea: compensation
status:
details: {}
type: remand_ssoc
type: post_remand
updated: '2018-01-19T10:20:42-05:00'
id: '3294289'
type: legacyAppeal
- attributes:
appealIds: []
active: false
alerts: []
aod: false
aoj: other
description: ''
docket: null
events:
- date: '2010-08-11'
type: claim_decision
- date: '2010-09-17'
type: nod
- date: '2013-09-26'
type: soc
- date: '2013-10-02'
type: form9
- date: '2014-07-28'
type: certified
- date: '2015-02-26'
type: merged
evidence: []
incompleteHistory: false
issues: []
location: bva
programArea: null
status:
details: {}
type: other_close
type: original
updated: '2018-01-19T10:20:42-05:00'
id: '2348605'
type: legacyAppeal
with a system-scoped token ('icn' parameter is necessary):
value:
data:
- attributes:
appealIds: []
active: false
alerts: []
aod: false
aoj: vba
description: ''
docket: null
events:
- date: '2002-09-23'
type: claim_decision
- date: '2003-01-06'
type: nod
- date: '2003-06-18'
type: soc
- date: '2003-09-30'
type: ftr
evidence: []
incompleteHistory: false
issues:
- active: false
date: '2003-09-30'
description: Service connection, lumbosacral strain
diagnosticCode: '5295'
lastAction: withdrawn
location: bva
programArea: compensation
status:
details: {}
type: ftr
type: original
updated: '2018-01-19T10:20:42-05:00'
id: '1196201'
type: legacyAppeal
- attributes:
appealIds: []
active: true
alerts: []
aod: false
aoj: vba
description: ''
docket: null
events:
- date: '2008-04-24'
type: claim_decision
- date: '2008-06-11'
type: nod
- date: '2010-09-10'
type: soc
- date: '2010-11-08'
type: form9
- date: '2014-01-03'
type: ssoc
- date: '2014-07-28'
type: certified
- date: '2015-04-17'
type: hearing_held
- date: '2015-07-24'
type: bva_decision
- date: '2015-10-06'
type: ssoc
- date: '2016-05-03'
type: bva_decision
- date: '2018-01-16'
type: ssoc
evidence: []
incompleteHistory: false
issues:
- active: true
date: '2016-05-03'
description: Increased rating, migraines
diagnosticCode: '8100'
lastAction: remand
- active: true
date: '2016-05-03'
description: Increased rating, limitation of leg motion
diagnosticCode: '5260'
lastAction: remand
- active: true
date: '2016-05-03'
description: 100% rating for individual unemployability
diagnosticCode: null
lastAction: remand
- active: false
date: null
description: Service connection, ankylosis of hip
diagnosticCode: '5250'
lastAction: null
- active: true
date: '2015-07-24'
description: Service connection, degenerative spinal arthritis
diagnosticCode: '5242'
lastAction: remand
- active: false
date: null
description: Service connection, hearing loss
diagnosticCode: '6100'
lastAction: null
- active: true
date: '2015-07-24'
description: Service connection, sciatic nerve paralysis
diagnosticCode: '8520'
lastAction: remand
- active: false
date: null
description: Service connection, arthritis due to trauma
diagnosticCode: '5010'
lastAction: null
- active: false
date: '2015-07-24'
description: New and material evidence for service connection, degenerative spinal arthritis
diagnosticCode: '5242'
lastAction: allowed
location: aoj
programArea: compensation
status:
details: {}
type: remand_ssoc
type: post_remand
updated: '2018-01-19T10:20:42-05:00'
id: '3294289'
type: legacyAppeal
- attributes:
appealIds: []
active: false
alerts: []
aod: false
aoj: other
description: ''
docket: null
events:
- date: '2010-08-11'
type: claim_decision
- date: '2010-09-17'
type: nod
- date: '2013-09-26'
type: soc
- date: '2013-10-02'
type: form9
- date: '2014-07-28'
type: certified
- date: '2015-02-26'
type: merged
evidence: []
incompleteHistory: false
issues: []
location: bva
programArea: null
status:
details: {}
type: other_close
type: original
updated: '2018-01-19T10:20:42-05:00'
id: '2348605'
type: legacyAppeal
schema:
type: object
properties:
data:
$ref: '#/components/schemas/appeals'
required:
- data
'400':
description: Missing parameters
content:
application/json:
examples:
with a representative-scoped token and no 'icn' parameter:
value:
errors:
- title: Missing parameter
detail: The 'icn' parameter is required with this request
code: '108'
status: '400'
with a system-scoped token and no 'icn' parameter:
value:
errors:
- title: Missing parameter
detail: The 'icn' parameter is required with this request
code: '108'
status: '400'
schema:
$ref: '#/components/schemas/errorModel'
'403':
description: Forbidden requests
content:
application/json:
examples:
with a veteran-scoped token and an optional 'icn' parameter that does not match the Veteran's ICN:
value:
errors:
- title: Forbidden
detail: 'Invalid ''icn'' parameter: Veterans may access only their own records'
code: '403'
status: '403'
schema:
$ref: '#/components/schemas/errorModel'
'404':
description: Not Found
content:
application/json:
examples:
Not Found:
value:
errors:
- title: Resource not found
detail: A matching Veteran was not found in our systems
code: '404'
status: '404'
schema:
$ref: '#/components/schemas/errorModel'
'422':
description: Invalid 'icn' parameter
content:
application/json:
examples:
with an incorrectly formatted 'icn' parameter:
value:
errors:
- title: Unprocessable Entity
detail: '''icn'' parameter has an invalid format. Pattern: /^[0-9]{10}V[0-9]{6}$/'
code: '422'
status: '422'
schema:
$ref: '#/components/schemas/errorModel'
'500':
description: Internal Server Error
content:
application/json:
example:
errors:
- title: Internal server error
detail: Internal server error
code: '500'
status: '500'
schema:
$ref: '#/components/schemas/errorModel'
components:
schemas:
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'
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
- 'null'
example: '6260'
description: The CFR (Code of Federal Regulations) diagnostic code for the issue, if applicable
lastAction:
type:
- string
- 'null'
description: Most recent decision made on this issue
enum:
- field_grant
- withdrawn
- allowed
- denied
- remand
- cavc_remand
date:
anyOf:
- type:
- string
- 'null'
format: date
description: The date of the most recent decision on the issue
example: '2016-05-30'
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
- 'null'
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
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va/refs/heads/main/openapi/va-appeals-status-api-openapi.yml