Veterans Affairs Contestable Issues API

openapi: 3.2.0
info:
  title: Decision Reviews Contestable Issues API
  version: v2
  contact:
    name: developer.va.gov
  description: "The Decision Reviews API allows you to interact with a Veteran's decision reviews, also known as benefit appeals. This API provides a secure and efficient alternative to paper or fax submissions and follows the AMA process. To view the status of all decision reviews and benefits appeals submitted according to the legacy benefits appeals process, use the [Appeals Status API](/explore/appeals/docs/appeals?version=current).\n\nInformation about the decision reviews process and types of decision reviews is available on the [VA decision reviews and appeals page](https://www.va.gov/decision-reviews/#request-a-decision-review-or-appeal).\n\n### Background\nThe Decision Reviews API passes data through to Caseflow, a case management system. The API converts decision review data into structured data that can be used for processing and reporting.\n\nBecause this application is designed to allow third-parties to request information on behalf of a Veteran, we are not using VA Authentication Federation Infrastructure (VAAFI) headers or Single Sign On External (SSOe).\n\n### Authorization and Access\nTo gain access to the decision reviews API you must [request an API Key](/support/contact-us). API requests are authorized through a symmetric API token which is provided in an HTTP header named `apikey`.\n\n### Test data\nOur sandbox environment is populated with [claimant test data](/explore/api/decision-reviews/test-users) that can be used to test various response scenarios. This sandbox data contains no PII or PHI, but mimics real claimant account information.\n\n### Submission Statuses\n\nUse the correct GET endpoint to check the appeal's submission status. The endpoint returns the current status of the submission to VA but not the status of the appeal in the AMA process.\n\n### Decision Review/Appeal Submission Statuses\n\nThe submission statuses begin with pending and end with complete.\n\n| Status      | What it means |\n| ---        |     ---     |\n| pending      | Initial status of the submission when no supporting documents have been uploaded. |\n| submitting   | Data is transferring to upstream systems but is not yet complete. |\n| submitted   | A submitted status means the data was successfully transferred to the central mail portal.<br /><br />A submitted status is confirmation from the central mail portal that they have received the PDF, but the data is not yet being processed. The Date of Receipt is set when this status is achieved.<br /><br />Submitted is the final status in the sandbox environment.<p> |\n| processing   | Indicates intake has begun, the Intake, Conversion and Mail Handling Services (ICMHS) group is processing the appeal data. |\n| success   | The centralized mail portal, Digital Mail Handling System (DHMS), has received the data. |\n| complete   | Final status. Indicates the document package has been successfully associated with the Veteran and has been received in the correct business area for processing. |\n| error   | An error occurred. See the error code and message for further information. |\n\n#### Status Simulation\n\nSandbox test submissions do not progress through the same statuses as in the Production environment. In the lower environments (i.e. Sandbox or Staging), the final status of a submission is `submitted`. In the lower environments, we allow passing a `Status-Simulation` header on the show endpoints so that you can simulate the other statuses.\n\nStatuses can be simulated for all submissions as well as evidence document uploads.\n\nThe **submission statuses** available for simulation are the statuses listed in the Submission Statuses table above.\n\nThe **evidence upload** statuses available for simulation are the statuses listed in the Evidence Upload Statuses table below (for simulating the status of uploaded evidence documents).\n\n### Evidence Uploads\n\nOur Notice of Disagreement (NOD) and Supplemental Claim (SC) evidence submission endpoints allow a client to upload a document package (documents and metadata) of supporting evidence for their submission by following these steps.\n\n1. Use the POST endpoint `/notice_of_disagreements/evidence_submissions` or `/supplemental_claims/evidence_submissions` to return a JSON service response with the attributes listed below.\n\n- `guid`: An identifier used for subsequent evidence upload status requests (not to be confused with the NOD or SC submission GUID)\n- `location`: A URL to which the actual document package payload can be submitted in the next step. The URL is specific to this upload request, and should not be re-used for subsequent uploads. The URL is valid for 900 seconds (15 minutes) from the time of this response. If the location is not used within 15 minutes, the GUID will expire. Once expired, status checks on the GUID will return a status of `expired`.\n\n2. Client Request: PUT to the location URL returned in step 1.\n\n- Request body should be encoded as binary multipart/form-data, equivalent to that generated by an HTML form submission or using “curl -F…”.\n- No `apikey` authorization header is required for this request, as authorization is embedded in the signed location URL.\n- The metadata.json file uploaded to the location URL with the evidence documents MUST contain all required information.  See example below.\n- The JSON key for the metadata.json file is \"metadata\", the initial file is \"content\". Any subsequent file will be \"attachment1\", \"attachment2\", and so forth.\n\n3. The service response will include:\n\n- HTTP status to indicate whether the evidence document upload was successful.\n- ETag header containing an MD5 hash of the submitted payload. This can be compared to the submitted payload to ensure data integrity of the upload.\n\nExample `metadata.json` file:\n```\n{\n    \"veteranFirstName\": \"Jane\",\n    \"veteranLastName\": \"Doe\",\n    \"fileNumber\": \"012345678\",\n    \"zipCode\": \"94402\",\n    \"source\": \"Vets.gov\",\n    \"docType\": \"316\"\n}\n```\nThe Decision Review API will set the businessLine for your Evidence submission to ensure the documents are routed to the correct group within VA.\nYou may check the status of your evidence document upload by using `GET` `/notice_of_disagreements/evidence_submissions/{uuid}` or `GET` `/supplemental_claims/evidence_submissions/{uuid}`. If, after you've uploaded a document, the status hasn't changed to `uploaded` before 15 minutes has elapsed, we recommend retrying the submission to make sure the document properly reaches our servers.\n\nFor NODs, evidence may only be uploaded within 90 days of the NOD reaching submitted status. After 90 days an error will be returned if evidence uploads related to this NOD are attempted.\nFor Supplemental Claims, evidence must be uploaded immediately after the SC reaching submitted status. After 2 days an error will be returned if evidence uploads related to this SC are attempted.\n\n### Evidence Upload Statuses\n\nThe evidence document upload statuses begin with pending and end with vbms.\n\nNote that until a document status of “received”, “processing”, “success”, or \"vbms\" is returned, a client cannot consider the document as received by VA. In particular a status of “uploaded” means that the document package has been transmitted, but possibly not validated. Any errors with the document package (unreadable PDF, etc) may cause the status to change to “error”.\n\nThe metadata.json file only supports a limited set of characters within the ascii character space. Refer to the `documentUploadMetadata` schema for more details.\n\n| Status    | What it means |\n|-----------|---------------|\n| pending   | This is the initial status. Indicates no document submission has been uploaded yet. |\n| uploaded  | Indicates document submission has been successfully uploaded (PUT) to the API server and is waiting to be sent to VA's mail handling system.<br /><br /> Submission has not yet been validated.<br /><br /> Any errors with the evidence submission, such as having an unreadable PDF, may cause an Error status. |\n| received  | Indicates document submission has been received downstream of the API and is awaiting processing.<br /><br /> Any errors with the document submission, such as having an unreadable PDF, may cause an Error status. |\n| processing | Indicates the evidence package is being validated, processed, and made ready to route and work.<br /><br /> Any errors with the evidence submission, such as having an unreadable PDF, may cause an Error status. |\n| success   | Indicates the evidence submission has been successfully received within VA's mail handling system.<br /><br /> Success is the final status for a small percentage of submissions with exception processes that are not worked in VBMS. A true value in the `finalStatus` attribute will indicate this.<br /><br /> Most submissions reach a Success status within 1 business day.<br /><br /> A small portion will take longer. However, some submissions may take up to 2 weeks to reach a Success status. |\n| vbms      | Indicates the evidence submission was successfully uploaded into a Veteran's eFolder within VBMS.<br /><br /> On average, submissions reach VBMS status within 3 business days. However, processing times vary and some submissions may remain in a Success status for several weeks before reaching a VBMS status.<br /><br /> Some document packages are worked in VA systems other than VBMS. For these submissions, Success is the final status. |\n| error     | Indicates that there was an error. Refer to the error code and detail for further information. |\n\nEvidence submissions have a finalStatus attribute that indicates whether the status of the evidence is final. Submissions with a finalStatus of true will no longer update to a new status.\n\n### Status Caching\n\nDue to current system limitations, data for the status attribute for the following endpoints is cached for one hour.\n\n- GET `/higher_level_reviews/{uuid}`\n- GET `/notice_of_disagreements/{uuid}`\n- GET `/notice_of_disagreements/evidence_submission/{uuid}`\n- GET `/supplemental_claims/{uuid}`\n- GET `/supplemental_claims/evidence_submission/{uuid}`\n\nThe updated_at field indicates the last time the status for a given GUID was updated.\n"
servers:
- url: https://sandbox-api.va.gov/services/appeals/{version}/decision_reviews
  description: VA.gov API sandbox environment
  variables:
    version:
      default: v2
- url: https://api.va.gov/services/appeals/{version}/decision_reviews
  description: VA.gov API production environment
  variables:
    version:
      default: v2
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:
    contestableIssues:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/contestableIssue'
    X-VA-Receipt-Date:
      description: (yyyy-mm-dd) Date to limit the contestable issues
      type: string
      format: date
    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
          - 'null'
        attributes:
          type: object
          properties:
            ratingIssueReferenceId:
              type:
              - string
              - 'null'
              description: RatingIssue ID
              example: '2385'
            ratingIssueProfileDate:
              type:
              - string
              - 'null'
              format: date
              description: (yyyy-mm-dd) RatingIssue profile date
              example: '2006-05-31'
            ratingIssueDiagnosticCode:
              type:
              - string
              - 'null'
              description: RatingIssue diagnostic code
              example: '5005'
            ratingDecisionReferenceId:
              type:
              - string
              - 'null'
              description: The BGS ID for the contested rating decision. This may be populated while ratingIssueReferenceId is nil
              example: null
            decisionIssueId:
              type:
              - integer
              - 'null'
              description: DecisionIssue ID
              example: null
            approxDecisionDate:
              type:
              - string
              - 'null'
              format: date
              description: (yyyy-mm-dd) Approximate decision date
              example: '2006-11-27'
            description:
              type:
              - string
              - 'null'
              description: Description
              example: Service connection for hypertension is granted with an evaluation of 10 percent effective July 24, 2005.
            rampClaimId:
              type:
              - string
              - 'null'
              description: RampClaim ID
              example: null
            titleOfActiveReview:
              type:
              - string
              - 'null'
              description: Title of DecisionReview that this issue is still active on
              example: null
            sourceReviewType:
              type:
              - string
              - 'null'
              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
                      - 'null'
                    - type: integer
                    example: null
                  approxDecisionDate:
                    type:
                    - string
                    - 'null'
                    format: date
                    example: '2006-11-27'
            ratingIssueSubjectText:
              type:
              - string
              - 'null'
              description: Short description of RatingIssue
              example: Hypertension
            ratingIssuePercentNumber:
              type:
              - string
              - 'null'
              description: Numerical rating for RatingIssue
              example: '10'
            isRating:
              type: boolean
              description: Whether or not this is a RatingIssue
              example: true
    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}$
    X-VA-File-Number:
      allOf:
      - description: VA file number (c-file / css)
      - maxLength: 9
      - $ref: '#/components/schemas/nonBlankString'
    nonBlankString:
      type: string
      pattern: '[^ \f\n\r\t\v\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]'
    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
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header