Veterans Affairs Supplemental Claims API
The Supplemental Claims API from Veterans Affairs — 15 operation(s) for supplemental claims.
OpenAPI Specification
openapi: 3.0.0
info:
title: Appealable Issues Supplemental Claims 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: Supplemental Claims
description: ''
paths:
/supplemental_claims:
post:
summary: Creates a new Supplemental Claim
tags:
- Supplemental Claims
operationId: createSc
description: 'Submits an appeal of type Supplemental Claim. This endpoint is the same as submitting [VA form 200995](https://www.vba.va.gov/pubs/forms/VBA-20-0995-ARE.pdf) via mail or fax directly to the Board of Veterans’ Appeals.
<br /><br />
<b>Note about the 5103 Notice of Acknowledgement</b>
<br /><br />
The 5103 Notice regarding new & relevant evidence must be acknowledged when the issue(s) being contested is a Disability Compensation issue. The notice can be found here: [http://www.va.gov/disability/how-to-file-claim/evidence-needed](http://www.va.gov/disability/how-to-file-claim/evidence-needed). If the issue(s) being submitted are Disability Compensation and ''No'' is selected, the API will return an error. Please ensure the Veteran reviews the content about the 5103 Notice at the link above.
<br /><br />
Supplemental Claims submitted via other avenues that do NOT select ''Yes'' for the 5103 Notice are subject to a 30 day suspense so the 5103 Notice can be mailed to the Veteran.
'
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-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-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
- in: header
name: X-Alternate-Signer-First-Name
required: false
description: Alternate signer's first name
schema:
$ref: '#/components/schemas/X-Alternate-Signer-First-Name'
- in: header
name: X-Alternate-Signer-Middle-Initial
required: false
description: Alternate signer's middle initial
schema:
$ref: '#/components/schemas/X-Alternate-Signer-Middle-Initial'
- in: header
name: X-Alternate-Signer-Last-Name
required: false
description: Alternate signer's last name
schema:
$ref: '#/components/schemas/X-Alternate-Signer-Last-Name'
responses:
'200':
description: Info about a single Supplemental Claim
content:
application/json:
examples:
minimum fields used:
value:
data:
id: 00000000-1111-2222-3333-444444444444
type: supplementalClaim
attributes:
status: pending
updatedAt: '2020-01-02T03:04:05.067Z'
createdAt: '2020-01-02T03:04:05.067Z'
formData:
data:
type: supplementalClaim
attributes:
benefitType: fiduciary
claimantType: veteran
veteran:
address:
addressLine1: 123 Main St
city: New York
countryCodeISO2: US
zipCode5: '30012'
phone:
areaCode: '555'
phoneNumber: '8001111'
email: josie@example.com
timezone: America/Chicago
socOptIn: false
evidenceSubmission:
evidenceType:
- upload
included:
- type: contestableIssue
attributes:
issue: right shoulder
decisionDate: '1900-01-06'
all fields used:
value:
data:
id: 00000000-1111-2222-3333-444444444444
type: supplementalClaim
attributes:
status: pending
updatedAt: '2020-01-02T03:04:05.067Z'
createdAt: '2020-01-02T03:04:05.067Z'
formData:
data:
type: supplementalClaim
attributes:
benefitType: compensation
claimantType: other
claimantTypeOtherValue: Veteran Attorney
homeless: true
homelessLivingSituation:
- I LIVE OR SLEEP IN A PLACE THAT IS NOT MEANT FOR REGULAR SLEEPING
- I LIVE IN A SHELTER
- I AM STAYING WITH A FRIEND OR FAMILY MEMBER, BECAUSE I AM UNABLE TO OWN A HOME RIGHT NOW
- IN THE NEXT 30 DAYS, I WILL HAVE TO LEAVE A FACILITY, LIKE A HOMELESS SHELTER
- IN THE NEXT 30 DAYS, I WILL LOSE MY HOME
- NONE OF THESE SITUATIONS APPLY TO ME
- OTHER
homelessLivingSituationOther: 'random words for other living situation '
homelessPointOfContact: Shawn Hobkens Veteran Care Network
mstUpcomingEventDisclosure: NOT APPLICABLE AND/OR NOT ENROLLED IN VHA HEALTHCARE
homelessPointOfContactPhone:
areaCode: '777'
phoneNumber: '9957023'
veteran:
address:
addressLine1: 123 Main St
addressLine2: 'Suite #1200'
addressLine3: Box 4
city: New York
countryCodeISO2: US
stateCode: NY
zipCode5: '30012'
phone:
countryCode: '03'
areaCode: '555'
phoneNumber: '8001111'
email: bobsemail@bobbytablesemail.com
timezone: America/Chicago
claimant:
address:
addressLine1: 456 First St
addressLine2: Apt 5
addressLine3: Box 1
city: Montreal
countryCodeISO2: CA
zipCode5: '00000'
internationalPostalCode: A9999AAA
phone:
countryCode: '1'
areaCode: '555'
phoneNumber: '8111100'
phoneNumberExt: '4'
email: joe@email.com
timezone: America/Detroit
socOptIn: true
form5103Acknowledged: true
evidenceSubmission:
treatmentLocations:
- PRIVATE HEALTH CARE PROVIDER
- VA VET CENTER
- COMMUNITY CARE
- VA MEDICAL CENTERS (VAMC) AND COMMUNITY-BASED OUTPATIENT CLINICS (CBOC)
- DEPARTMENT OF DEFENSE (DOD) MILITARY TREATMENT FACILITY(IES) (MTF)
treatmentLocationOther: hospital that is not standard other more words more words hospital that is not standard other more words more words
evidenceType:
- upload
- retrieval
retrieveFrom:
- type: retrievalEvidence
attributes:
locationAndName: X-Ray VAMC
evidenceDates:
- startDate: '2020-04-10'
endDate: '2020-04-10'
- startDate: '2020-01-02'
endDate: '2020-02-01'
- startDate: '2020-02-20'
endDate: '2020-02-22'
- startDate: '2019-02-02'
endDate: '2020-02-03'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: Blood Lab VA Facility
evidenceDates:
- startDate: '2020-02-20'
endDate: '2020-02-22'
- startDate: '2020-02-02'
endDate: '2020-02-07'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: Doctor's Notes VAMC
evidenceDates:
- startDate: '2020-04-10'
endDate: '2020-04-10'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: CT scan VA Medical Facility
evidenceDates:
- startDate: '2020-07-19'
endDate: '2020-07-19'
- startDate: '2018-03-06'
endDate: '2019-02-12'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: Lab work VAMC
evidenceDates:
- startDate: '2018-03-06'
endDate: '2018-03-06'
- startDate: '2018-01-15'
endDate: '2018-01-15'
noTreatmentDates: false
included:
- type: contestableIssue
attributes:
issue: right shoulder
decisionDate: '2000-01-08'
socDate: '2020-04-30'
- type: contestableIssue
attributes:
issue: lower back
decisionDate: '1900-01-06'
socDate: '2021-02-24'
- type: contestableIssue
attributes:
issue: torn rotator cuff
decisionDate: '1989-03-07'
socDate: '2020-04-30'
- type: contestableIssue
attributes:
issue: hearing loss
decisionDate: '1930-10-20'
socDate: '2016-05-30'
- type: contestableIssue
attributes:
issue: sciatica
decisionDate: '2007-01-19'
socDate: '2012-01-02'
- type: contestableIssue
attributes:
issue: bowel obstruction
decisionDate: '1999-12-29'
socDate: '2019-08-13'
- type: contestableIssue
attributes:
issue: right eye
decisionDate: '1920-04-02'
socDate: '2019-11-19'
- type: contestableIssue
attributes:
issue: left index finger
decisionDate: '2018-08-17'
socDate: '2021-03-20'
- type: contestableIssue
attributes:
issue: spinal compression
decisionDate: '2013-09-11'
socDate: '2020-08-24'
schema:
$ref: '#/components/schemas/scCreateResponse'
'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:
- form5103Acknowledged
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/scCreate'
examples:
minimum fields used:
value:
data:
type: supplementalClaim
attributes:
benefitType: fiduciary
claimantType: veteran
veteran:
address:
addressLine1: 123 Main St
city: New York
countryCodeISO2: US
zipCode5: '30012'
phone:
areaCode: '555'
phoneNumber: '8001111'
email: josie@example.com
timezone: America/Chicago
socOptIn: false
evidenceSubmission:
evidenceType:
- upload
included:
- type: contestableIssue
attributes:
issue: right shoulder
decisionDate: '1900-01-06'
all fields used:
value:
data:
type: supplementalClaim
attributes:
benefitType: compensation
claimantType: other
claimantTypeOtherValue: Veteran Attorney
homeless: true
homelessLivingSituation:
- I LIVE OR SLEEP IN A PLACE THAT IS NOT MEANT FOR REGULAR SLEEPING
- I LIVE IN A SHELTER
- I AM STAYING WITH A FRIEND OR FAMILY MEMBER, BECAUSE I AM UNABLE TO OWN A HOME RIGHT NOW
- IN THE NEXT 30 DAYS, I WILL HAVE TO LEAVE A FACILITY, LIKE A HOMELESS SHELTER
- IN THE NEXT 30 DAYS, I WILL LOSE MY HOME
- NONE OF THESE SITUATIONS APPLY TO ME
- OTHER
homelessLivingSituationOther: 'random words for other living situation '
homelessPointOfContact: Shawn Hobkens Veteran Care Network
mstUpcomingEventDisclosure: NOT APPLICABLE AND/OR NOT ENROLLED IN VHA HEALTHCARE
homelessPointOfContactPhone:
areaCode: '777'
phoneNumber: '9957023'
veteran:
address:
addressLine1: 123 Main St
addressLine2: 'Suite #1200'
addressLine3: Box 4
city: New York
countryCodeISO2: US
stateCode: NY
zipCode5: '30012'
phone:
countryCode: '03'
areaCode: '555'
phoneNumber: '8001111'
email: bobsemail@bobbytablesemail.com
timezone: America/Chicago
claimant:
address:
addressLine1: 456 First St
addressLine2: Apt 5
addressLine3: Box 1
city: Montreal
countryCodeISO2: CA
zipCode5: '00000'
internationalPostalCode: A9999AAA
phone:
countryCode: '1'
areaCode: '555'
phoneNumber: '8111100'
phoneNumberExt: '4'
email: joe@email.com
timezone: America/Detroit
socOptIn: true
form5103Acknowledged: true
evidenceSubmission:
treatmentLocations:
- PRIVATE HEALTH CARE PROVIDER
- VA VET CENTER
- COMMUNITY CARE
- VA MEDICAL CENTERS (VAMC) AND COMMUNITY-BASED OUTPATIENT CLINICS (CBOC)
- DEPARTMENT OF DEFENSE (DOD) MILITARY TREATMENT FACILITY(IES) (MTF)
treatmentLocationOther: hospital that is not standard other more words more words hospital that is not standard other more words more words
evidenceType:
- upload
- retrieval
retrieveFrom:
- type: retrievalEvidence
attributes:
locationAndName: X-Ray VAMC
evidenceDates:
- startDate: '2020-04-10'
endDate: '2020-04-10'
- startDate: '2020-01-02'
endDate: '2020-02-01'
- startDate: '2020-02-20'
endDate: '2020-02-22'
- startDate: '2019-02-02'
endDate: '2020-02-03'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: Blood Lab VA Facility
evidenceDates:
- startDate: '2020-02-20'
endDate: '2020-02-22'
- startDate: '2020-02-02'
endDate: '2020-02-07'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: Doctor's Notes VAMC
evidenceDates:
- startDate: '2020-04-10'
endDate: '2020-04-10'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: CT scan VA Medical Facility
evidenceDates:
- startDate: '2020-07-19'
endDate: '2020-07-19'
- startDate: '2018-03-06'
endDate: '2019-02-12'
noTreatmentDates: true
- type: retrievalEvidence
attributes:
locationAndName: Lab work VAMC
evidenceDates:
- startDate: '2018-03-06'
endDate: '2018-03-06'
- startDate: '2018-01-15'
endDate: '2018-01-15'
noTreatmentDates: false
included:
- type: contestableIssue
attributes:
issue: right shoulder
decisionDate: '2000-01-08'
socDate: '2020-04-30'
- type: contestableIssue
attributes:
issue: lower back
decisionDate: '1900-01-06'
socDate: '2021-02-24'
- type: contestableIssue
attributes:
issue: torn rotator cuff
decisionDate: '1989-03-07'
socDate: '2020-04-30'
- type: contestableIssue
attributes:
issue: hearing loss
decisionDate: '1930-10-20'
socDate: '2016-05-30'
- type: contestableIssue
attributes:
issue: sciatica
decisionDate: '2007-01-19'
socDate: '2012-01-02'
- type: contestableIssue
attributes:
issue: bowel obstruction
decisionDate: '1999-12-29'
socDate: '2019-08-13'
- type: contestableIssue
attributes:
issue: right eye
decisionDate: '1920-04-02'
socDate: '2019-11-19'
- type: contestableIssue
attributes:
issue: left index finger
decisionDate: '2018-08-17'
socDate: '2021-03-20'
- type: contestableIssue
attributes:
issue: spinal compression
decisionDate: '2013-09-11'
socDate: '2020-08-24'
/supplemental_claims/{uuid}:
get:
summary: Shows a specific Supplemental Claim. (a.k.a. the Show endpoint)
tags:
- Supplemental Claims
operationId: showSc
description: Returns all of the data associated with a specific Supplemental Claim.
security:
- apikey: []
parameters:
- name: uuid
in: path
description: Supplemental Claim UUID
example: 7efd87fc-fac1-4851-a4dd-b9aa2533f57f
required: true
schema:
type: string
responses:
'200':
description: Info about a single Supplemental Claim
content:
application/json:
example:
data:
id: 00000000-1111-2222-3333-444444444444
type: supplementalClaim
attributes:
status: pending
updatedAt: '2020-01-02T03:04:05.067Z'
createdAt: '2020-01-02T03:04:05.067Z'
schema:
$ref: '#/components/schemas/scCreateResponse'
'404':
description: Supplemental Claim not found
content:
application/json:
example:
errors:
- code: '404'
detail: SupplementalClaim 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'
/supplemental_claims/schema:
get:
summary: Gets the Supplemental Claims JSON Schema.
tags:
- Supplemental Claims
operationId: scSchema
description: Returns the [JSON Schema](https://json-schema.org/) for the `POST /supplemental_claims` endpoint.
security:
- apikey: []
responses:
'200':
description: the JSON Schema for POST /supplemental_claims
content:
application/json:
example: '{"$schema":"http://json-schema.org/draft-07/schema#","description":"JSON Schema for VA Form 20-0995","$ref":"#/definitions/scCreate","definitions":{"address":{"type":"object","properties":{"addressLine1":{"type":"string","minLength":1,"maxLength":60},"addressLine2":{"type":"string","minLength":1,"maxLength":30},"addressLine3":{"type":"string","minLength":1,"maxLength":10},"city":{"type":"string","minLength":1,"maxLength":60},"stateCode":{"type":"string","enum":["AL","AK","AS","AZ","AR","AA","AE","AP","CA","CO","CT","DE","DC","FM","FL","GA","GU","HI","ID","IL","IN","IA","KS","KY","LA","ME","MH","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","MP","OH","OK","OR","PW","PA","PR","RI","SC","SD","TN","TX","UT","VT","VI","VA","WA","WV","WI","WY"]},"countryCodeISO2":{"type":"string","pattern":"^[A-Z]{2}$","minLength":2,"maxLength":2},"zipCode5":{"type":"string","description":"5-digit zipcode. Use \"00000\" if address is outside the United States","pattern":"^[0-9]{5}$","minLength":5,"maxLength":5},"internationalPostalCode":{"type":"string","minLength":1,"maxLength":16}},"required":["addressLine1","city","countryCodeISO2","zipCode5"]},"phone":{"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[0-9]+$","minLength":1,"maxLength":3},"areaCode":{"type":"string","pattern":"^[0-9]{1,4}$","minLength":1,"maxLength":4},"phoneNumber":{"type":"string","pattern":"^[0-9]{1,14}$","minLength":1,"maxLength":14},"phoneNumberExt":{"type":"string","pattern":"^[a-zA-Z0-9]{1,10}$","minLength":1,"maxLength":10}},"required":["phoneNumber"]},"timezone":{"type":"string","enum":["Africa/Abidjan","Africa/Accra","Africa/Addis_Ababa","Africa/Algiers","Africa/Asmara","Africa/Asmera","Africa/Bamako","Africa/Bangui","Africa/Banjul","Africa/Bissau","Africa/Blantyre","Africa/Brazzaville","Africa/Bujumbura","Africa/Cairo","Africa/Casablanca","Africa/Ceuta","Africa/Conakry","Africa/Dakar","Africa/Dar_es_Salaam","Africa
# --- truncated at 32 KB (255 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va/refs/heads/main/openapi/va-supplemental-claims-api-openapi.yml