Veterans Affairs Higher-Level Reviews API
The Higher-Level Reviews API from Veterans Affairs — 10 operation(s) for higher-level reviews.
OpenAPI Specification
openapi: 3.0.0
info:
title: Appealable Issues Higher-Level Reviews 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: 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
/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'
/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
# --- truncated at 32 KB (253 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va/refs/heads/main/openapi/va-higher-level-reviews-api-openapi.yml