Veterans Affairs Legacy Appeals API

openapi: 3.0.0
info:
  title: Appealable Issues Legacy Appeals 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: Legacy Appeals
  description: ''
paths:
  /legacy_appeals:
    get:
      summary: Returns eligible appeals in the legacy process for a Veteran.
      tags:
      - Legacy Appeals
      operationId: getLegacyAppeals
      security:
      - apikey: []
      description: Returns eligible legacy appeals for a Veteran. A legacy appeal is eligible if a statement of the case (SOC)  or supplemental statement of the case (SSOC) has been declared, and if the date of declaration is within the last 60 days.
      parameters:
      - in: header
        name: X-VA-SSN
        required: false
        description: 'Either X-VA-SSN or X-VA-File-Number is required. Example X-VA-SSN: 123456789'
        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. Example X-VA-File-Number: 123456789'
        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: Returns eligible legacy appeals for a Veteran
          content:
            application/json:
              example:
                data:
                - id: '2760964'
                  type: legacyAppeal
                  attributes:
                    issues:
                    - summary: Service connection, pancreatitis
                    veteranFullName: Elda Z Quigley
                    decisionDate: '2021-05-04T00:00:00.000Z'
                    latestSocSsocDate: '2021-06-12'
              schema:
                $ref: '#/components/schemas/legacyAppeals'
        '404':
          description: Veteran record not found
          content:
            application/json:
              example:
                errors:
                - status: '404'
                  code: veteran_not_found
                  title: Veteran Not Found
              schema:
                $ref: '#/components/schemas/errorModel'
        '422':
          description: Header Errors
          content:
            application/json:
              examples:
                when X-VA-SSN and X-VA-File-Number are missing:
                  value:
                    errors:
                    - title: Validation error
                      detail: Validation error
                      code: '100'
                      source:
                        pointer: /
                      status: '422'
                    - title: Invalid length
                      detail: ''''' did not fit within the defined length limits'
                      code: '142'
                      source:
                        pointer: /X-VA-SSN
                      status: '422'
                      meta:
                        max_length: 9
                        min_length: 9
                    - title: Invalid pattern
                      detail: ''''' did not match the defined pattern'
                      code: '143'
                      source:
                        pointer: /X-VA-SSN
                      status: '422'
                      meta:
                        regex: ^[0-9]{9}$
                    - title: Invalid pattern
                      detail: ''''' did not match the defined pattern'
                      code: '143'
                      source:
                        pointer: /X-VA-File-Number
                      status: '422'
                      meta:
                        regex: '[^ \f\n\r\t\v\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]'
                    - title: Invalid length
                      detail: ''''' did not fit within the defined length limits'
                      code: '142'
                      source:
                        pointer: /X-VA-File-Number
                      status: '422'
                      meta:
                        max_length: 9
                        min_length: 1
                when SSN formatted incorrectly:
                  value:
                    errors:
                    - title: Invalid length
                      detail: '''12n-~89'' did not fit within the defined length limits'
                      code: '142'
                      source:
                        pointer: /X-VA-SSN
                      status: '422'
                      meta:
                        max_length: 9
                        min_length: 9
                    - title: Invalid pattern
                      detail: '''12n-~89'' did not match the defined pattern'
                      code: '143'
                      source:
                        pointer: /X-VA-SSN
                      status: '422'
                      meta:
                        regex: ^[0-9]{9}$
                when ICN formatted incorrectly:
                  value:
                    errors:
                    - title: Invalid length
                      detail: '''12345'' did not fit within the defined length limits'
                      code: '142'
                      source:
                        pointer: /X-VA-ICN
                      status: '422'
                      meta:
                        max_length: 17
                        min_length: 17
                    - title: Invalid pattern
                      detail: '''12345'' did not match the defined pattern'
                      code: '143'
                      source:
                        pointer: /X-VA-ICN
                      status: '422'
                      meta:
                        regex: ^[0-9]{10}V[0-9]{6}$
              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:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      properties:
                        status:
                          type: string
                          example: '502'
                        detail:
                          type: string
                          example: Received a 500 response from the upstream server
                        code:
                          type: string
                          example: CASEFLOWSTATUS500
                        title:
                          type: string
                          example: Bad Gateway
  /legacy-appeals:
    get:
      summary: Returns eligible appeals in the legacy process for a Veteran.
      tags:
      - Legacy Appeals
      operationId: getLegacyAppeals
      security:
      - productionOauth:
        - veteran/LegacyAppeals.read
        - representative/LegacyAppeals.read
        - system/LegacyAppeals.read
      - sandboxOauth:
        - veteran/LegacyAppeals.read
        - representative/LegacyAppeals.read
        - system/LegacyAppeals.read
      - bearer_token: []
      description: Returns eligible legacy appeals for a Veteran. A legacy appeal is eligible if a statement of the case (SOC)  or supplemental statement of the case (SSOC) has been declared, and if the date of declaration is within the last 60 days.
      parameters:
      - name: icn
        description: Veteran's Master Person Index (MPI) Integration Control Number (ICN). Optional when using a veteran-scoped token. Required when using a representative- or system-scoped token.
        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 legacy appeals for the Veteran with the supplied ICN
          content:
            application/json:
              examples:
                with a veteran-scoped token (no 'icn' parameter necessary):
                  value:
                    data:
                    - id: '2760964'
                      type: legacyAppeal
                      attributes:
                        issues:
                        - summary: Service connection, pancreatitis
                        veteranFullName: Elda Z Quigley
                        decisionDate: '2021-05-04T00:00:00.000Z'
                        latestSocSsocDate: '2021-06-12'
                with a representative-scoped token ('icn' parameter is necessary):
                  value:
                    data:
                    - id: '2760964'
                      type: legacyAppeal
                      attributes:
                        issues:
                        - summary: Service connection, pancreatitis
                        veteranFullName: Elda Z Quigley
                        decisionDate: '2021-05-04T00:00:00.000Z'
                        latestSocSsocDate: '2021-06-12'
                with a system-scoped token ('icn' parameter is necessary):
                  value:
                    data:
                    - id: '2760964'
                      type: legacyAppeal
                      attributes:
                        issues:
                        - summary: Service connection, pancreatitis
                        veteranFullName: Elda Z Quigley
                        decisionDate: '2021-05-04T00:00:00.000Z'
                        latestSocSsocDate: '2021-06-12'
              schema:
                $ref: '#/components/schemas/legacyAppeals'
        '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: Invalid 'icn' parameter
          content:
            application/json:
              examples:
                when ICN is 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:
    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}$
    legacyAppeal:
      properties:
        type:
          type: string
          example: legacyAppeal
        id:
          type: string
          description: ID from VACOLS (Veteran Appeals Control and Locator Service)
          example: '3085659'
        attributes:
          type: object
          properties:
            issues:
              type: array
              description: Issues on the Appeal.
              items:
                type: object
                properties:
                  summary:
                    type: string
                    description: Summary of a single Issue.
                    example: Service connection, hearing loss
            veteranFullName:
              type: string
              example: Junior L Fritsch
            decisionDate:
              type: string
              description: Date of the Appeal's original decision.
              example: '2018-09-28T00:00:00.000Z'
            latestSocSsocDate:
              type: string
              description: Date of the Appeal's most recent SOC/SSOC (Statement of Case/Supplemental Statement of Case)
              example: '2018-12-29T00:00:00.000Z'
    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
    X-VA-SSN:
      description: social security number
      type: string
      minLength: 9
      maxLength: 9
      pattern: ^[0-9]{9}$
    legacyAppeals:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/legacyAppeal'
    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'
  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