Veterans Affairs Contestable Issues API

openapi: 3.0.0
info:
  title: Appealable Issues Contestable Issues 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: Contestable Issues
  description: ''
paths:
  /contestable_issues/{decision_review_type}:
    get:
      summary: Returns all contestable issues for a specific veteran.
      tags:
      - Contestable Issues
      operationId: getContestableIssues
      description: Returns all issues associated with a Veteran that have been decided as of the `receiptDate`. Not all issues returned are guaranteed to be eligible for appeal.
      security:
      - apikey: []
      parameters:
      - name: decision_review_type
        in: path
        required: true
        description: Scoping of appeal type for associated issues
        schema:
          type: string
          enum:
          - higher_level_reviews
          - notice_of_disagreements
          - supplemental_claims
        example: higher_level_reviews
      - name: benefit_type
        in: query
        description: Required if decision review type is Higher Level Review or Supplemental Claims.
        schema:
          type: string
          enum:
          - compensation
          - pensionSurvivorsBenefits
          - fiduciary
          - lifeInsurance
          - veteransHealthAdministration
          - veteranReadinessAndEmployment
          - loanGuaranty
          - education
          - nationalCemeteryAdministration
        example: compensation
      - 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-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-File-Number
        required: false
        description: Veteran's file number
        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: JSON:API response returning all contestable issues for a specific veteran.
          content:
            application/json:
              example:
                data:
                - type: contestableIssue
                  attributes:
                    ratingIssueSubjectText: right knee
                    ratingIssuePercentNumber: '10'
                    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:
                    ratingIssueSubjectText: ptsd
                    ratingIssueReferenceId: '826209441170'
                    ratingIssueProfileDate: '2019-02-22'
                    ratingIssueDiagnosticCode: null
                    description: PTSD
                    isRating: true
                    latestIssuesInChain:
                    - id: null
                      approxDecisionDate: '2019-02-25'
                    decisionIssueId: null
                    ratingDecisionReferenceId: null
                    approxDecisionDate: '2019-02-25'
                    rampClaimId: null
                    titleOfActiveReview: null
                    sourceReviewType: null
                    timely: true
                    activeReview: false
                - 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-24'
                    decisionIssueId: null
                    ratingDecisionReferenceId: null
                    approxDecisionDate: '2019-02-24'
                    rampClaimId: null
                    titleOfActiveReview: null
                    sourceReviewType: null
                    timely: true
                    activeReview: false
              schema:
                $ref: '#/components/schemas/contestableIssues'
        '404':
          description: Veteran not found
          content:
            application/json:
              example:
                errors:
                - status: '404'
                  title: Veteran not found
                  detail: A veteran with that SSN was not found in our systems.
              schema:
                $ref: '#/components/schemas/errorModel'
        '422':
          description: Parameter Errors
          content:
            application/json:
              examples:
                'decision_review_type must be one of: higher_level_reviews, notice_of_disagreements, supplemental_claims':
                  value:
                    errors:
                    - title: Unprocessable Entity
                      code: unprocessable_entity
                      detail: 'decision_review_type must be one of: higher_level_reviews, notice_of_disagreements, supplemental_claims'
                      status: '422'
                Invalid receipt date:
                  value:
                    errors:
                    - title: Validation error
                      detail: Receipt date cannot be before 2019-02-20
                      source:
                        header: X-VA-Receipt-Date
                      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 error
          content:
            application/json:
              example:
                errors:
                - title: Bad Gateway
                  detail: Received a 500 response from the upstream server
                  code: CASEFLOWSTATUS500
                  source: No method error
                  status: '502'
components:
  schemas:
    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}$
    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
    contestableIssues:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/contestableIssue'
    X-VA-SSN:
      description: social security number
      type: string
      minLength: 9
      maxLength: 9
      pattern: ^[0-9]{9}$
    contestableIssue:
      type: object
      description: A contestable issue (to contest this, you include it as a RequestIssue when creating a HigherLevelReview, SupplementalClaim, or Appeal)
      properties:
        type:
          type: string
          enum:
          - contestableIssue
        id:
          type: string
          nullable: true
        attributes:
          type: object
          properties:
            ratingIssueReferenceId:
              type: string
              nullable: true
              description: RatingIssue ID
              example: '2385'
            ratingIssueProfileDate:
              type: string
              nullable: true
              format: date
              description: (yyyy-mm-dd) RatingIssue profile date
              example: '2006-05-31'
            ratingIssueDiagnosticCode:
              type: string
              nullable: true
              description: RatingIssue diagnostic code
              example: '5005'
            ratingDecisionReferenceId:
              type: string
              nullable: true
              description: The BGS ID for the contested rating decision. This may be populated while ratingIssueReferenceId is nil
              example: null
            decisionIssueId:
              type: integer
              nullable: true
              description: DecisionIssue ID
              example: null
            approxDecisionDate:
              type: string
              nullable: true
              format: date
              description: (yyyy-mm-dd) Approximate decision date
              example: '2006-11-27'
            description:
              type: string
              nullable: true
              description: Description
              example: Service connection for hypertension is granted with an evaluation of 10 percent effective July 24, 2005.
            rampClaimId:
              type: string
              nullable: true
              description: RampClaim ID
              example: null
            titleOfActiveReview:
              type: string
              nullable: true
              description: Title of DecisionReview that this issue is still active on
              example: null
            sourceReviewType:
              type: string
              nullable: true
              description: The type of DecisionReview (HigherLevelReview, SupplementalClaim, Appeal) the issue was last decided on (if any)
              example: null
            timely:
              type: boolean
              description: An issue is timely if the receipt date is within 372 dates of the decision date.
              example: false
            activeReview:
              type: boolean
              description: Indicates whether this issue is already part of an active Decision Review that is being processed by VA. Submitting a Decision Review that includes a listed issue with an activeReview of true may result in VA rejecting the submission.
              example: false
            latestIssuesInChain:
              type: array
              description: Shows the chain of decision and rating issues that preceded this issue. Only the most recent issue can be contested (the object itself that contains the latestIssuesInChain attribute).
              items:
                type: object
                properties:
                  id:
                    oneOf:
                    - type: string
                      nullable: true
                    - type: integer
                    example: null
                  approxDecisionDate:
                    type: string
                    nullable: true
                    format: date
                    example: '2006-11-27'
            ratingIssueSubjectText:
              type: string
              nullable: true
              description: Short description of RatingIssue
              example: Hypertension
            ratingIssuePercentNumber:
              type: string
              nullable: true
              description: Numerical rating for RatingIssue
              example: '10'
            isRating:
              type: boolean
              description: Whether or not this is a RatingIssue
              example: true
    nonBlankString:
      type: string
      pattern: '[^ \f\n\r\t\v\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]'
    X-VA-File-Number:
      allOf:
      - description: VA file number (c-file / css)
      - maxLength: 9
      - $ref: '#/components/schemas/nonBlankString'
    X-VA-Receipt-Date:
      description: (yyyy-mm-dd) Date to limit the contestable issues
      type: string
      format: date
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
    productionOauth:
      type: oauth2
      description: 'The authentication model for the Appealable Issues API uses OAuth 2.0/OpenID Connect. The following authorization models are supported: [Authorization code flow](https://developer.va.gov/explore/api/appealable-issues/authorization-code) and [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/appealable-issues/client-credentials).'
      flows:
        authorizationCode:
          authorizationUrl: https://api.va.gov/oauth2/appeals/v1/authorization
          tokenUrl: https://api.va.gov/oauth2/appeals/v1/token
          scopes:
            veteran/AppealableIssues.read: Appealable issues info
            veteran/appeals.read: Appeals info
            representative/AppealableIssues.read: Appealable issues 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/AppealableIssues.read: Appealable issues info
            system/appeals.read: Appeals info
    sandboxOauth:
      type: oauth2
      description: 'The authentication model for the Appealable Issues API uses OAuth 2.0/OpenID Connect. The following authorization models are supported: [Authorization code flow](https://developer.va.gov/explore/api/appealable-issues/authorization-code) and [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/appealable-issues/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/AppealableIssues.read: Appealable issues info
            veteran/appeals.read: Appeals info
            representative/AppealableIssues.read: Appealable issues info
            representative/appeals.read: Appeals info
        clientCredentials:
          tokenUrl: https://deptva-eval.okta.com/oauth2/auskff5o6xsoQVngk2p7/v1/token
          scopes:
            system/AppealableIssues.read: Appealable issues info
            system/appeals.read: Appeals info