Veterans Affairs Legacy Appeals API
The Legacy Appeals API from Veterans Affairs — 2 operation(s) for legacy appeals.
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-legacy-appeals-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: Va Legacy Appeals API
contact:
name: developer.va.gov
version: '1.0'
description: 'Operations tagged Legacy Appeals across 2 of this provider''s published API definitions: va-decision-reviews-openapi.json, va-legacy-appeals-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://sandbox-api.va.gov/services/appeals/{version}/decision_reviews
description: VA.gov API sandbox environment
variables:
version:
default: v2
- url: https://api.va.gov/services/appeals/{version}/decision_reviews
description: VA.gov API production environment
variables:
version:
default: v2
- url: https://sandbox-api.va.gov/services/appeals/legacy-appeals/{version}
description: VA.gov API sandbox environment
variables:
version:
default: v0
- url: https://api.va.gov/services/appeals/legacy-appeals/{version}
description: VA.gov API production environment
variables:
version:
default: v0
tags:
- name: Legacy Appeals
description: ''
paths:
/legacy_appeals:
get:
summary: Returns eligible appeals in the legacy process for a Veteran.
tags:
- Legacy Appeals
operationId: getLegacyAppeals
security:
- apikey: []
description: Returns eligible legacy appeals for a Veteran. A legacy appeal is eligible if a statement of the case (SOC) or supplemental statement of the case (SSOC) has been declared, and if the date of declaration is within the last 60 days.
parameters:
- in: header
name: X-VA-SSN
required: false
description: 'Either X-VA-SSN or X-VA-File-Number is required. Example X-VA-SSN: 123456789'
example: '706547821'
schema:
$ref: '#/components/schemas/X-VA-SSN'
- in: header
name: X-VA-File-Number
required: false
description: 'Either X-VA-SSN or X-VA-File-Number is required. Example X-VA-File-Number: 123456789'
schema:
$ref: '#/components/schemas/X-VA-File-Number'
- in: header
name: X-VA-ICN
required: false
description: Veteran's ICN
example: 1013062086V794840
schema:
$ref: '#/components/schemas/X-VA-ICN'
responses:
'200':
description: Returns eligible legacy appeals for a Veteran
content:
application/json:
example:
data:
- id: '2760964'
type: legacyAppeal
attributes:
issues:
- summary: Service connection, pancreatitis
veteranFullName: Elda Z Quigley
decisionDate: '2021-05-04T00:00:00.000Z'
latestSocSsocDate: '2021-06-12'
schema:
$ref: '#/components/schemas/legacyAppeals'
'404':
description: Veteran record not found
content:
application/json:
example:
errors:
- status: '404'
code: veteran_not_found
title: Veteran Not Found
schema:
$ref: '#/components/schemas/errorModel'
'422':
description: Header Errors
content:
application/json:
examples:
when X-VA-SSN and X-VA-File-Number are missing:
value:
errors:
- title: Validation error
detail: Validation error
code: '100'
source:
pointer: /
status: '422'
- title: Invalid length
detail: ''''' did not fit within the defined length limits'
code: '142'
source:
pointer: /X-VA-SSN
status: '422'
meta:
max_length: 9
min_length: 9
- title: Invalid pattern
detail: ''''' did not match the defined pattern'
code: '143'
source:
pointer: /X-VA-SSN
status: '422'
meta:
regex: ^[0-9]{9}$
- title: Invalid pattern
detail: ''''' did not match the defined pattern'
code: '143'
source:
pointer: /X-VA-File-Number
status: '422'
meta:
regex: '[^ \f\n\r\t\v\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]'
- title: Invalid length
detail: ''''' did not fit within the defined length limits'
code: '142'
source:
pointer: /X-VA-File-Number
status: '422'
meta:
max_length: 9
min_length: 1
when SSN formatted incorrectly:
value:
errors:
- title: Invalid length
detail: '''12n-~89'' did not fit within the defined length limits'
code: '142'
source:
pointer: /X-VA-SSN
status: '422'
meta:
max_length: 9
min_length: 9
- title: Invalid pattern
detail: '''12n-~89'' did not match the defined pattern'
code: '143'
source:
pointer: /X-VA-SSN
status: '422'
meta:
regex: ^[0-9]{9}$
when ICN formatted incorrectly:
value:
errors:
- title: Invalid length
detail: '''12345'' did not fit within the defined length limits'
code: '142'
source:
pointer: /X-VA-ICN
status: '422'
meta:
max_length: 17
min_length: 17
- title: Invalid pattern
detail: '''12345'' did not match the defined pattern'
code: '143'
source:
pointer: /X-VA-ICN
status: '422'
meta:
regex: ^[0-9]{10}V[0-9]{6}$
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'
'502':
description: Unknown Error
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
properties:
status:
type: string
example: '502'
detail:
type: string
example: Received a 500 response from the upstream server
code:
type: string
example: CASEFLOWSTATUS500
title:
type: string
example: Bad Gateway
servers:
- url: https://sandbox-api.va.gov/services/appeals/{version}/decision_reviews
description: VA.gov API sandbox environment
variables:
version:
default: v2
- url: https://api.va.gov/services/appeals/{version}/decision_reviews
description: VA.gov API production environment
variables:
version:
default: v2
/legacy-appeals:
get:
summary: Returns eligible appeals in the legacy process for a Veteran.
tags:
- Legacy Appeals
operationId: getLegacyAppeals
security:
- productionOauth:
- veteran/LegacyAppeals.read
- representative/LegacyAppeals.read
- system/LegacyAppeals.read
- sandboxOauth:
- veteran/LegacyAppeals.read
- representative/LegacyAppeals.read
- system/LegacyAppeals.read
- bearer_token: []
description: Returns eligible legacy appeals for a Veteran. A legacy appeal is eligible if a statement of the case (SOC) or supplemental statement of the case (SSOC) has been declared, and if the date of declaration is within the last 60 days.
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: Retrieve legacy appeals for the Veteran with the supplied ICN
content:
application/json:
examples:
with a veteran-scoped token (no 'icn' parameter necessary):
value:
data:
- id: '2760964'
type: legacyAppeal
attributes:
issues:
- summary: Service connection, pancreatitis
veteranFullName: Elda Z Quigley
decisionDate: '2021-05-04T00:00:00.000Z'
latestSocSsocDate: '2021-06-12'
with a representative-scoped token ('icn' parameter is necessary):
value:
data:
- id: '2760964'
type: legacyAppeal
attributes:
issues:
- summary: Service connection, pancreatitis
veteranFullName: Elda Z Quigley
decisionDate: '2021-05-04T00:00:00.000Z'
latestSocSsocDate: '2021-06-12'
with a system-scoped token ('icn' parameter is necessary):
value:
data:
- id: '2760964'
type: legacyAppeal
attributes:
issues:
- summary: Service connection, pancreatitis
veteranFullName: Elda Z Quigley
decisionDate: '2021-05-04T00:00:00.000Z'
latestSocSsocDate: '2021-06-12'
schema:
$ref: '#/components/schemas/legacyAppeals'
'400':
description: Missing ICN parameter
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: Access forbidden
content:
application/json:
example:
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: Veteran record not found
content:
application/json:
example:
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:
when ICN is formatted incorrectly:
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'
'502':
description: Unknown upstream error
content:
application/json:
example:
errors:
- title: Bad Gateway
detail: Received an unusable response from Caseflow
code: '502'
status: '502'
schema:
$ref: '#/components/schemas/errorModel'
servers:
- url: https://sandbox-api.va.gov/services/appeals/legacy-appeals/{version}
description: VA.gov API sandbox environment
variables:
version:
default: v0
- url: https://api.va.gov/services/appeals/legacy-appeals/{version}
description: VA.gov API production environment
variables:
version:
default: v0
components:
schemas:
X-VA-SSN:
description: social security number
type: string
minLength: 9
maxLength: 9
pattern: ^[0-9]{9}$
X-VA-ICN:
description: Veteran's Integration Control Number, a unique identifier established via the Master Person Index (MPI)
type: string
minLength: 17
maxLength: 17
pattern: ^[0-9]{10}V[0-9]{6}$
legacyAppeals:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/legacyAppeal'
X-VA-File-Number:
allOf:
- description: VA file number (c-file / css)
- maxLength: 9
- $ref: '#/components/schemas/nonBlankString'
nonBlankString:
type: string
pattern: '[^ \f\n\r\t\v\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]'
legacyAppeal:
properties:
type:
type: string
example: legacyAppeal
id:
type: string
description: ID from VACOLS (Veteran Appeals Control and Locator Service)
example: '3085659'
attributes:
type: object
properties:
issues:
type: array
description: Issues on the Appeal.
items:
type: object
properties:
summary:
type: string
description: Summary of a single Issue.
example: Service connection, hearing loss
veteranFullName:
type: string
example: Junior L Fritsch
decisionDate:
type: string
description: Date of the Appeal's original decision.
example: '2018-09-28T00:00:00.000Z'
latestSocSsocDate:
type: string
description: Date of the Appeal's most recent SOC/SSOC (Statement of Case/Supplemental Statement of Case)
example: '2018-12-29T00:00:00.000Z'
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
securitySchemes:
apikey:
type: apiKey
name: apikey
in: header
bearer_token:
type: http
scheme: bearer
bearerFormat: JWT
productionOauth:
type: oauth2
description: 'The authentication model for the Legacy Appeals API uses OAuth 2.0/OpenID Connect. The following authorization models are supported: [Authorization code flow](https://developer.va.gov/explore/api/legacy-appeals/authorization-code) and [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/legacy-appeals/client-credentials).'
flows:
authorizationCode:
authorizationUrl: https://api.va.gov/oauth2/appeals/v1/authorization
tokenUrl: https://api.va.gov/oauth2/appeals/v1/token
scopes:
veteran/LegacyAppeals.read: Legacy appeals info
veteran/appeals.read: Appeals info
representative/LegacyAppeals.read: Legacy appeals info
representative/appeals.read: Appeals info
clientCredentials:
tokenUrl: To get production access, 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).
scopes:
system/LegacyAppeals.read: Legacy appeals info
system/appeals.read: Appeals info
sandboxOauth:
type: oauth2
description: 'The authentication model for the Legacy Appeals API uses OAuth 2.0/OpenID Connect. The following authorization models are supported: [Authorization code flow](https://developer.va.gov/explore/api/legacy-appeals/authorization-code) and [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/legacy-appeals/client-credentials).'
flows:
authorizationCode:
authorizationUrl: https://sandbox-api.va.gov/oauth2/appeals/v1/authorization
tokenUrl: https://sandbox-api.va.gov/oauth2/appeals/v1/token
scopes:
veteran/LegacyAppeals.read: Legacy appeals info
veteran/appeals.read: Appeals info
representative/LegacyAppeals.read: Legacy appeals info
representative/appeals.read: Appeals info
clientCredentials:
tokenUrl: https://deptva-eval.okta.com/oauth2/auskff5o6xsoQVngk2p7/v1/token
scopes:
system/LegacyAppeals.read: Legacy appeals info
system/appeals.read: Appeals info
x-refined-from:
- va-decision-reviews-openapi.json
- va-legacy-appeals-openapi.json