Veterans Affairs Higher-Level Reviews API
The Higher-Level Reviews API from Veterans Affairs — 10 operation(s) for higher-level reviews.
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-higher-level-reviews-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 Higher-Level Reviews API
contact:
name: developer.va.gov
version: '1.0'
description: 'Operations tagged Higher-Level Reviews across 2 of this provider''s published API definitions: va-decision-reviews-openapi.json, va-higher-level-reviews-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/higher-level-reviews/{version}
description: VA.gov API sandbox environment
variables:
version:
default: v0
- url: https://api.va.gov/services/appeals/higher-level-reviews/{version}
description: VA.gov API production environment
variables:
version:
default: v0
tags:
- name: Higher-Level Reviews
description: ''
paths:
/higher_level_reviews:
post:
summary: Creates a new Higher-Level Review
description: Submits an appeal of type Higher Level Review. This endpoint is the same as submitting [VA Form 20-0996](https://www.va.gov/decision-reviews/higher-level-review/request-higher-level-review-form-20-0996) via mail or fax directly to the Board of Veterans’ Appeals.
tags:
- Higher-Level Reviews
operationId: createHlr
security:
- apikey: []
parameters:
- in: header
name: X-VA-SSN
required: true
description: Veteran's SSN
example: '706547821'
schema:
$ref: '#/components/schemas/X-VA-SSN'
- in: header
name: X-VA-ICN
required: false
description: Veteran's ICN
example: 1013062086V794840
schema:
$ref: '#/components/schemas/X-VA-ICN'
- in: header
name: X-VA-First-Name
required: true
description: Veteran's first name
example: Cara
schema:
$ref: '#/components/schemas/X-VA-First-Name'
- in: header
name: X-VA-Middle-Initial
required: false
description: Veteran's middle initial
schema:
$ref: '#/components/schemas/X-VA-Middle-Initial'
- in: header
name: X-VA-Last-Name
required: true
description: Veteran's last name
example: Bartlett
schema:
$ref: '#/components/schemas/X-VA-Last-Name'
- in: header
name: X-VA-Birth-Date
required: true
description: Veteran's birth date
example: '1975-02-14'
schema:
$ref: '#/components/schemas/X-VA-Birth-Date'
- in: header
name: X-VA-File-Number
required: false
description: Veteran's file number
schema:
$ref: '#/components/schemas/X-VA-File-Number'
- in: header
name: X-VA-Insurance-Policy-Number
required: false
description: Veteran's insurance policy number
schema:
$ref: '#/components/schemas/X-VA-Insurance-Policy-Number'
- in: header
name: X-VA-NonVeteranClaimant-First-Name
required: false
description: Non-Veteran claimant's first name
schema:
$ref: '#/components/schemas/X-VA-NonVeteranClaimant-First-Name'
- in: header
name: X-VA-NonVeteranClaimant-Middle-Initial
required: false
description: Non-Veteran claimant's middle initial
schema:
$ref: '#/components/schemas/X-VA-NonVeteranClaimant-Middle-Initial'
- in: header
name: X-VA-NonVeteranClaimant-Last-Name
required: false
description: Non-Veteran claimant's last name
schema:
$ref: '#/components/schemas/X-VA-NonVeteranClaimant-Last-Name'
- in: header
name: X-VA-NonVeteranClaimant-SSN
required: false
description: Non-Veteran claimant's SSN
schema:
$ref: '#/components/schemas/X-VA-NonVeteranClaimant-SSN'
- in: header
name: X-VA-NonVeteranClaimant-Birth-Date
required: false
description: Non-Veteran claimant's Birth Date
schema:
$ref: '#/components/schemas/X-VA-NonVeteranClaimant-Birth-Date'
- in: header
name: X-Consumer-Username
required: false
description: Consumer User Name (passed from Kong)
schema:
type: string
- in: header
name: X-Consumer-ID
required: false
description: Consumer GUID
schema:
type: string
responses:
'200':
description: Info about a single Higher-Level Review
content:
application/json:
examples:
minimum fields used:
value:
data:
id: 00000000-1111-2222-3333-444444444444
type: higherLevelReview
attributes:
status: pending
updatedAt: '2020-01-02T03:04:05.067Z'
createdAt: '2020-01-02T03:04:05.067Z'
formData:
data:
type: higherLevelReview
attributes:
informalConference: false
benefitType: lifeInsurance
veteran:
homeless: false
address:
addressLine1: 123 Some St.
city: Sometown
countryCodeISO2: US
zipCode5: '12345'
socOptIn: true
included:
- type: contestableIssue
attributes:
issue: left shoulder
decisionDate: '1920-12-01'
all fields used:
value:
data:
id: 00000000-1111-2222-3333-444444444444
type: higherLevelReview
attributes:
status: pending
updatedAt: '2020-01-02T03:04:05.067Z'
createdAt: '2020-01-02T03:04:05.067Z'
formData:
data:
type: higherLevelReview
attributes:
benefitType: education
veteran:
homeless: true
address:
addressLine1: 123 Main St
addressLine2: 'Suite #1200'
addressLine3: Box 4
city: New York
countryCodeISO2: US
stateCode: NY
zipCode5: '30012'
phone:
countryCode: '34'
areaCode: '555'
phoneNumber: '8001111'
phoneNumberExt: '2'
email: bob@bobbytablesemail.com
timezone: America/Chicago
claimant:
address:
addressLine1: 456 First St
addressLine2: Apt 5
addressLine3: Box 1
city: Detroit
countryCodeISO2: US
stateCode: MI
zipCode5: '48070'
phone:
countryCode: '1'
areaCode: '555'
phoneNumber: '8111100'
phoneNumberExt: '4'
email: claimant@email.com
timezone: America/Detroit
socOptIn: true
informalConference: true
informalConferenceContact: veteran
informalConferenceTime: 800-1200 ET
informalConferenceRep:
firstName: Helen
lastName: Holly
email: holly@hellohellenholly.com
phone:
countryCode: '1'
areaCode: '555'
phoneNumber: '8001111'
phoneNumberExt: '2'
included:
- type: contestableIssue
attributes:
issue: '123456789'
decisionDate: '1900-01-01'
decisionIssueId: 1
ratingIssueReferenceId: '2'
ratingDecisionReferenceId: '3'
socDate: '2020-04-30'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left eyee
decisionDate: '1900-01-02'
disagreementArea: '123456789'
- type: contestableIssue
attributes:
issue: right eye
decisionDate: '1900-01-03'
- type: contestableIssue
attributes:
issue: left ear
decisionDate: '1900-01-04'
socDate: '2019-05-15'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right ear
decisionDate: '1900-01-05'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: migraines
decisionDate: '1900-01-06'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left knee
decisionDate: '1900-01-07'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right knee
decisionDate: '1900-01-08'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left foot
decisionDate: '1900-01-09'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right foot
decisionDate: '1900-01-10'
socDate: '2021-01-08'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left hand
decisionDate: '1900-01-11'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right hand
decisionDate: '1900-01-12'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: fever
decisionDate: '1900-01-13'
disagreementArea: Service connection
- type: contestableIssue
attributes:
issue: lupus
decisionDate: '1900-01-14'
socDate: '2020-09-23'
- type: contestableIssue
attributes:
issue: cooties
decisionDate: '1900-01-15'
disagreementArea: Service connection
schema:
$ref: '#/components/schemas/hlrShow'
'422':
description: Violates JSON schema
content:
application/json:
example:
errors:
- title: Missing required fields
detail: One or more expected fields were not found
code: '145'
source:
pointer: /data/attributes
status: '422'
meta:
missing_fields:
- informalConference
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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/hlrCreate'
examples:
minimum fields used:
value:
data:
type: higherLevelReview
attributes:
informalConference: false
benefitType: lifeInsurance
veteran:
homeless: false
address:
addressLine1: 123 Some St.
city: Sometown
countryCodeISO2: US
zipCode5: '12345'
socOptIn: true
included:
- type: contestableIssue
attributes:
issue: left shoulder
decisionDate: '1920-12-01'
all fields used:
value:
data:
type: higherLevelReview
attributes:
benefitType: education
veteran:
homeless: true
address:
addressLine1: 123 Main St
addressLine2: 'Suite #1200'
addressLine3: Box 4
city: New York
countryCodeISO2: US
stateCode: NY
zipCode5: '30012'
phone:
countryCode: '34'
areaCode: '555'
phoneNumber: '8001111'
phoneNumberExt: '2'
email: bob@bobbytablesemail.com
timezone: America/Chicago
claimant:
address:
addressLine1: 456 First St
addressLine2: Apt 5
addressLine3: Box 1
city: Detroit
countryCodeISO2: US
stateCode: MI
zipCode5: '48070'
phone:
countryCode: '1'
areaCode: '555'
phoneNumber: '8111100'
phoneNumberExt: '4'
email: claimant@email.com
timezone: America/Detroit
socOptIn: true
informalConference: true
informalConferenceContact: veteran
informalConferenceTime: 800-1200 ET
informalConferenceRep:
firstName: Helen
lastName: Holly
email: holly@hellohellenholly.com
phone:
countryCode: '1'
areaCode: '555'
phoneNumber: '8001111'
phoneNumberExt: '2'
included:
- type: contestableIssue
attributes:
issue: '123456789'
decisionDate: '1900-01-01'
decisionIssueId: 1
ratingIssueReferenceId: '2'
ratingDecisionReferenceId: '3'
socDate: '2020-04-30'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left eyee
decisionDate: '1900-01-02'
disagreementArea: '123456789'
- type: contestableIssue
attributes:
issue: right eye
decisionDate: '1900-01-03'
- type: contestableIssue
attributes:
issue: left ear
decisionDate: '1900-01-04'
socDate: '2019-05-15'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right ear
decisionDate: '1900-01-05'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: migraines
decisionDate: '1900-01-06'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left knee
decisionDate: '1900-01-07'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right knee
decisionDate: '1900-01-08'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left foot
decisionDate: '1900-01-09'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right foot
decisionDate: '1900-01-10'
socDate: '2021-01-08'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: left hand
decisionDate: '1900-01-11'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: right hand
decisionDate: '1900-01-12'
disagreementArea: Rating
- type: contestableIssue
attributes:
issue: fever
decisionDate: '1900-01-13'
disagreementArea: Service connection
- type: contestableIssue
attributes:
issue: lupus
decisionDate: '1900-01-14'
socDate: '2020-09-23'
- type: contestableIssue
attributes:
issue: cooties
decisionDate: '1900-01-15'
disagreementArea: Service connection
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
/higher_level_reviews/{uuid}:
get:
summary: Shows a specific Higher-Level Review. (a.k.a. the Show endpoint)
description: Returns all of the data associated with a specific Higher-Level Review.
tags:
- Higher-Level Reviews
operationId: showHlr
security:
- apikey: []
parameters:
- name: uuid
in: path
description: Higher-Level Review UUID
example: 44e08764-6008-46e8-a95e-eb21951a5b68
required: true
schema:
type: string
responses:
'200':
description: Info about a single Higher-Level Review
content:
application/json:
example:
data:
id: 00000000-1111-2222-3333-444444444444
type: higherLevelReview
attributes:
status: pending
updatedAt: '2020-01-02T03:04:05.067Z'
createdAt: '2020-01-02T03:04:05.067Z'
schema:
$ref: '#/components/schemas/hlrShow'
'404':
description: Higher-Level Review not found
content:
application/json:
example:
errors:
- code: '404'
detail: HigherLevelReview with uuid invalid not found
status: '404'
title: Record not found
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'
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
/higher_level_reviews/contestable_issues/{benefit_type}:
get:
summary: Returns all contestable issues for a specific veteran.
tags:
- Higher-Level Reviews
operationId: hlrContestableIssues
description: Returns all issues associated with a Veteran that have been decided by a Higher-Level Review as of the receiptDate and bound by benefitType. Not all issues returned are guaranteed to be eligible for appeal. Associate these results when creating a new Higher-Level Review.
security:
- apikey: []
parameters:
- name: benefit_type
in: path
description: 'benefit type - Available values: compensation'
required: true
schema:
type: string
- in: header
name: X-VA-SSN
required: false
description: Either X-VA-SSN or X-VA-File-Number is required
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
schema:
$ref: '#/components/schemas/X-VA-File-Number'
- in: header
name: X-VA-Receipt-Date
required: true
description: (yyyy-mm-dd) In order to determine contestability of issues, the receipt date of a hypothetical Decision Review must be specified. This date must be after 2019-02-19, the Appeals Modernization Act (AMA) Activation Date.
example: '2022-01-01'
schema:
$ref: '#/components/schemas/X-VA-Receipt-Date'
- in: header
name: X-VA-ICN
required: false
description: Veteran's ICN
example: 1013062086V794840
schema:
$ref: '#/components/schemas/X-VA-ICN'
responses:
'200':
description: JSON:API response returning all contestable issues for a specific veteran.
content:
application/json:
example:
data:
- type: contestableIssue
attributes:
ratingIssueSubjectText: Left knee
ratingIssueReferenceId: '826209597423'
ratingIssueProfileDate: '2019-02-22'
ratingIssueDiagnosticCode: null
description: Left knee
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2019-02-26'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2019-02-26'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: null
timely: true
activeReview: false
- type: contestableIssue
attributes:
ratingIssueSubjectText: Right knee
ratingIssueReferenceId: '826209920000'
ratingIssueProfileDate: '2019-02-22'
ratingIssueDiagnosticCode: null
description: Right knee
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2019-02-26'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2019-02-26'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: null
timely: true
activeReview: false
- type: contestableIssue
attributes:
ratingIssueReferenceId: '826209441170'
ratingIssueProfileDate: '2019-02-22'
ratingIssueDiagnosticCode: null
description: PTSD
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2019-02-26'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2019-02-26'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: null
timely: true
activeReview: false
- type: contestableIssue
attributes:
ratingIssueReferenceId: in-active-review-ref-id
ratingIssueProfileDate: '2019-02-22'
ratingIssueDiagnosticCode: null
description: This rating is in active review
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2019-02-26'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2019-02-26'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: null
timely: true
activeReview: true
- type: contestableIssue
attributes:
ratingIssueReferenceId: '826209942179'
ratingIssueProfileDate: '2019-02-22'
ratingIssueDiagnosticCode: null
description: I am on a completed Higher Level Review
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2019-02-26'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2019-02-26'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: HigherLevelReview
timely: true
activeReview: false
- type: contestableIssue
attributes:
ratingIssueReferenceId: before_ama_ref_id
ratingIssueProfileDate: '2019-02-09'
ratingIssueDiagnosticCode: null
description: Issue before AMA not from a RAMP Review
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2019-02-14'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2019-02-14'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: null
timely: true
activeReview: false
- type: contestableIssue
attributes:
ratingIssueReferenceId: ramp_reference_id
ratingIssueProfileDate: '2019-02-09'
ratingIssueDiagnosticCode: null
description: Issue before AMA from a RAMP Review
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2019-02-14'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2019-02-14'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: null
timely: true
activeReview: false
- type: contestableIssue
attributes:
ratingIssueReferenceId: '826209918301'
ratingIssueProfileDate: '2018-12-12'
ratingIssueDiagnosticCode: null
description: Old injury
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2018-12-17'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '2018-12-17'
rampClaimId: null
titleOfActiveReview: null
sourceReviewType: null
timely: true
activeReview: false
- type: contestableIssue
attributes:
ratingIssueReferenceId: before_test_ama_ref_id
ratingIssueProfileDate: '2017-10-12'
ratingIssueDiagnosticCode: null
description: Issue before test AMA not from a RAMP Review
isRating: true
latestIssuesInChain:
- id: null
approxDecisionDate: '2017-10-17'
decisionIssueId: null
ratingDecisionReferenceId: null
approxDecisionDate: '20
# --- truncated at 32 KB (257 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va/refs/heads/main/openapi/va-higher-level-reviews-api-openapi.yml