Veterans Affairs Appeals Status API
The Appeals Status API from Veterans Affairs — 1 operation(s) for appeals status.
OpenAPI Specification
openapi: 3.0.0
info:
title: Appealable Issues Appeals Status API
version: v0
contact:
name: developer.va.gov
description: "The Appealable Issues API lets you retrieve a list of a claimant’s appealable issues and any chains of preceding issues. Appealable issues are issues from claims about which VA has made a decision that may be eligible for appeal. Not all appealable issues are guaranteed to be eligible for appeal; for example, claimants may have another appeal in progress for an issue.\n\nTo check the status of all decision reviews and appeals for a specified individual, use the [Appeals Status API](https://developer.va.gov/explore/api/appeals-status/docs).\n\nTo file an appeal or decision review, use one of these APIs: \n* [Higher-Level Reviews API](https://developer.va.gov/explore/api/higher-level-reviews/docs)\n* [Notice of Disagreements API](https://developer.va.gov/explore/api/notice-of-disagreements/docs)\n* [Supplemental Claims API](https://developer.va.gov/explore/api/supplemental-claims/docs)\n\n## Technical overview\nThe Appealable Issues API pulls data from Caseflow, a case management system. It provides decision review and appeal data that can be used for submitting a Higher Level Review, Notice of Disagreement, or Supplemental Claim.\n\n### Authorization and Access\nThe authentication model for the Appealable Issues API uses OAuth 2.0/OpenID Connect. The following authorization models are supported:\n* [Authorization code flow](https://developer.va.gov/explore/api/appealable-issues/authorization-code)\n* [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/appealable-issues/client-credentials)\n\n**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).\n\n### Test data\n\nOur sandbox environment is populated with [Veteran test data](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts/appealable_issues_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.\n"
servers:
- url: https://sandbox-api.va.gov/services/appeals/appealable-issues/{version}
description: VA.gov API sandbox environment
variables:
version:
default: v0
- url: https://api.va.gov/services/appeals/appealable-issues/{version}
description: VA.gov API production environment
variables:
version:
default: v0
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:
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
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'
errorModel:
required:
- errors
properties:
errors:
type: array
items:
additionalProperties: false
required:
- title
properties:
title:
type: string
description: HTTP error title
detail:
type: string
description: HTTP error detail
code:
type: string
description: HTTP error code
source:
type: object
additionalProperties: false
description: Source of error
properties:
pointer:
type: string
description: Pointer to source of error
parameter:
type: string
description: Invalid request parameter
header:
type: string
description: Invalid header
status:
type: string
description: HTTP error code
meta:
type: object
description: Meta infomation
properties:
missing_fields:
type: array
items:
type: string
description: List of missing fields
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:
nullable: true
type: string
example: '6260'
description: The CFR (Code of Federal Regulations) diagnostic code for the issue, if applicable
lastAction:
nullable: true
type: string
description: Most recent decision made on this issue
enum:
- field_grant
- withdrawn
- allowed
- denied
- remand
- cavc_remand
date:
anyOf:
- nullable: true
type: string
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
- appea
# --- 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