Veterans Affairs Appealable Issues API

openapi: 3.0.0
info:
  title: Appealable 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: Appealable Issues
  description: ''
paths:
  /appealable-issues/{decisionReviewType}:
    get:
      summary: Returns all appealable issues for a specific Veteran.
      tags:
      - Appealable Issues
      operationId: getAppealableIssues
      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:
      - productionOauth:
        - veteran/AppealableIssues.read
        - representative/AppealableIssues.read
        - system/AppealableIssues.read
      - sandboxOauth:
        - veteran/AppealableIssues.read
        - representative/AppealableIssues.read
        - system/AppealableIssues.read
      - bearer_token: []
      parameters:
      - name: decisionReviewType
        description: Scoping of appeal type for associated issues
        example: higher-level-reviews
        required: true
        schema:
          type: string
          enum:
          - higher-level-reviews
          - notice-of-disagreements
          - supplemental-claims
        in: path
      - name: benefitType
        description: Required if decision review type is Higher-Level Reviews or Supplemental Claims
        example: compensation
        schema:
          type: string
          enum:
          - compensation
          - pensionSurvivorsBenefits
          - fiduciary
          - lifeInsurance
          - veteransHealthAdministration
          - veteranReadinessAndEmployment
          - loanGuaranty
          - education
          - nationalCemeteryAdministration
        in: query
      - name: receiptDate
        description: (yyyy-mm-dd) In order to determine appealability of issues, the receipt date of a hypothetical Decision Review must be specified.
        example: '2022-01-01'
        required: true
        schema:
          type: string
          format: date
        in: query
      - name: icn
        description: Veteran's Master Person Index (MPI) Integration Control Number (ICN)
        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 all appealable issues for a Veteran
          content:
            application/json:
              examples:
                with a veteran-scoped token (no 'icn' parameter necessary):
                  value:
                    data:
                    - type: appealableIssue
                      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
                    - type: appealableIssue
                      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
                    - type: appealableIssue
                      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
                with a representative-scoped token ('icn' parameter is necessary):
                  value:
                    data:
                    - type: appealableIssue
                      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
                    - type: appealableIssue
                      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
                    - type: appealableIssue
                      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
                with a system-scoped token ('icn' parameter is necessary):
                  value:
                    data:
                    - type: appealableIssue
                      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
                    - type: appealableIssue
                      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
                    - type: appealableIssue
                      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
              schema:
                $ref: '#/components/schemas/appealableIssues'
        '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: Parameter Errors
          content:
            application/json:
              examples:
                'decisionReviewType must be one of: higher-level-reviews, notice-of-disagreements, supplemental-claims':
                  value:
                    errors:
                    - title: Invalid option
                      detail: '''invalid'' is not an available option'
                      code: '141'
                      source:
                        pointer: /decisionReviewType
                      status: '422'
                      meta:
                        available_options:
                        - higher-level-reviews
                        - notice-of-disagreements
                        - supplemental-claims
                Bad receipt date for HLR:
                  value:
                    errors:
                    - status: '422'
                      code: '422'
                      title: Invalid Receipt Date
                      detail: '"2019-02-18" is before AMA Activation Date (2019-02-19).'
                ICN parameter 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'
components:
  schemas:
    appealableIssues:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/appealableIssue'
    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
    appealableIssue:
      type: object
      description: An appealable issue (to appeal this, you include it as a RequestIssue when creating a HigherLevelReview, SupplementalClaim, or Appeal)
      properties:
        type:
          type: string
          enum:
          - appealableIssue
        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 appealable 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
            latestIssuesInChain:
              type: array
              description: Shows the chain of decision and rating issues that preceded this issue. Only the most recent issue can be appealed (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
  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