VA Lighthouse Appeals Status API

openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver Appeals Status API
  description: "The Address Validation API accepts and validates an address and standardizes it for mailing. It can also help you process an address by:\n* Inferring missing or incorrect address components\n* Supplementing an address with additional information, such as geocode, latitude and longitude, and postal service metadata (when available)\n## Technical Overview\nThe Address Validation API returns validated addresses as they appear in the USPS database for domestic addresses. It validates by separating the address into individual components and then providing component-level validation checks.\n\nThis API is certified by the United States Postal Service (USPS) Coding Accuracy Support System (CASS) and adheres to [United States Postal Service (USPS) Publication 28 standards](https://pe.usps.com/text/pub28/welcome.htm) for domestic, military, and US territory addresses.\n\nFor international addresses, validation relies on Universal Postal Union (UPU) standards. \n\n## Validation\nIf an address is found, it is considered valid based on metadata returned by the Address Validation service, such as the confidence score and the [Delivery Point Validation (DPV)](https://postalpro.usps.com/address-quality/dpv).\n\nIf an address is found, there are multiple checks performed on the validated address. The address can fail validation for a variety of reasons, such as the inability to deliver (for domestic mailing addresses) or the format. For specific reasons why an address failed, refer to the error messages returned.\n\nIf an address is not found, it automatically fails validation.\n\n## Address override indicator\nSometimes an entered address is accurate for a Veteran but does not pass validation rules. These instances can occur when an address is newer than what is in the CASS software or in regions where address data is less accurate.\n\nSystems can accept these addresses despite the lack of address validation by submitting an \"accepted address\" (usually confirmed by the Veteran) to the Contact Information API (see Requirements below). An address is considered accepted after the address has been sent to the validation API and has failed validation, but the Veteran has confirmed the address is correct as entered. The accepted address can then be passed to the Contact Information API using an address override indicator set to show that the validation was overridden. To set an override indicator, the original address and the `overrideValidationKey` returned in the validation API response must be provided to the Contact Information API, in order to prove that a validation attempt has been made before overriding.\n\n## Version Interoperability\n\nTo ensure interoperability between APIs and eliminate the need for transforming data as one API feeds into the other, we strongly recommend using versions of the following APIs that are compatible.\n\n|     <h3>If Using</h3>           | <h3>Then Use...</h3>                           |\n| :------------------------------:|:----------------------------------------------:|\n| Address Validation API v1/v2    | Contact Information API v1<br><br>Profile Service API v1/v2 |\n| Address Validation API v3       | Contact Information API v2<br><br>Profile Service API v3    |\n\n## Authorization\nAPI requests are authorized through a symmetric API token provided in an HTTP header with name apikey.\n\n**Important**: 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)."
  license:
    name: Creative Commons
    url: https://developer.va.gov/terms-of-service
  version: '3'
servers:
- url: https://sandbox-api.va.gov/services/address-validation/{version}
  description: Sandbox
  variables:
    version:
      default: v3
- url: https://api.va.gov/services/address-validation/{version}
  description: Production
  variables:
    version:
      default: v3
security:
- apikey: []
tags:
- name: Appeals Status
  description: Caseflow appeals status API
paths:
  /appeals:
    get:
      tags:
      - Appeals Status
      summary: Retrieve appeals status for the Veteran with the supplied SSN
      description: Returns a list of all known appeal records for the given Veteran. Includes details of each appeal's current status, priority, and history of updates.
      operationId: GET:/appeals
      security:
      - apikey: []
      parameters:
      - in: header
        name: X-VA-SSN
        required: true
        example: '796130115'
        schema:
          type: string
        description: SSN of Veteran to retrieve appeals statuses for
      - in: header
        name: X-VA-User
        required: true
        example: va.api.user+idme.001@gmail.com
        schema:
          type: string
        description: VA username of the person making the request
      responses:
        '200':
          description: Appeals retrieved successfully
          content:
            application/json:
              schema:
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Appeals'
        '400':
          description: Missing SSN header
        '401':
          description: Authorization information not provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: No API key found in request
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: You cannot consume this service
        '404':
          description: No appeals found for supplied SSN
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '422':
          description: invalid SSN
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: API rate limit exceeded
        '500':
          description: Internal server error
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
components:
  schemas:
    Eta:
      type: object
      description: Estimated decision dates for each docket.
      properties:
        directReview:
          format: date
          example: '2020-02-01'
        evidenceSubmission:
          format: date
          example: '2024-06-01'
        hearing:
          format: date
          example: '2024-06-01'
    Appeal:
      type: object
      properties:
        id:
          type: string
          description: ID from VACOLS (Veteran Appeals Control and Locator Service) or Caseflow
          example: '7387389'
        type:
          type: string
          description: The decision review option chosen by the appellant
          example: legacyAppeal
          enum:
          - legacyAppeal
          - appeal
          - supplementalClaim
          - higherLevelReview
        attributes:
          type: object
          properties:
            appealIds:
              type: array
              description: An array of the individual IDs that are combined into this appeal
              items:
                type: string
                example: '1234567'
            updated:
              type: string
              format: date-time
              example: '2018-01-03T09:30:15-05:00'
              description: The timestamp for the last refresh of the data
            active:
              type: boolean
              description: Indicates whether the appeal is ongoing or closed
              example: true
            incompleteHistory:
              type: boolean
              example: false
              description: Indicates whether this response contains a complete history of this appeal
            aoj:
              type: string
              description: Agency of Original Jurisdiction, vba is Veterans Benefits Administration, vha is Veterans Health Administration, and nca is National Cemetery Administration.
              example: vba
              enum:
              - vba
              - vha
              - nca
              - other
            programArea:
              type: string
              example: pension
              enum:
              - compensation
              - pension
              - insurance
              - loan_guaranty
              - education
              - vre
              - medical
              - burial
              - bva
              - fiduciary
              - other
              - multiple
            description:
              type: string
              description: Description of the appeal
              example: Service connection, tinnitus, and 3 others
            type:
              type: string
              description: Indicates the type of Appeal. CAVC is the Court of Appeals for Veterans Claims
              enum:
              - original
              - post_remand
              - post_cavc_remand
              - reconsideration
              - cue
            aod:
              type: boolean
              example: false
              description: Advanced on Docket, whether this appeal was prioritized due to Veteran age or urgency.
            location:
              type: string
              example: bva
              description: Indicates who currently has the appeal AOJ (Agency of Original Jurisdiction) or BVA (Board of Veterans Appeals)
              enum:
              - aoj
              - bva
            status:
              type: object
              description: This appeal's position in the appeal process
              properties:
                type:
                  type: string
                  description: Indicates the current position in the appeal process
                  enum:
                  - scheduled_hearing
                  - pending_hearing_scheduling
                  - on_docket
                  - pending_certification_ssoc
                  - pending_certification
                  - pending_form9
                  - pending_soc
                  - stayed
                  - at_vso
                  - bva_development
                  - decision_in_progress
                  - bva_decision
                  - field_grant
                  - withdrawn
                  - ftr
                  - ramp
                  - death
                  - reconsideration
                  - other_close
                  - remand_ssoc
                  - remand
                  - merged
                  - evidentiary_period
                  - ama_remand
                  - post_bva_dta_decision
                  - bva_decision_effectuation
                  - sc_received
                  - sc_decision
                  - sc_closed
                  - hlr_received
                  - hlr_dta_error
                  - hlr_decision
                  - hlr_closed
                  - statutory_opt_in
                details:
                  type: object
                  description: Further information about appeal's timeline
                  properties:
                    lastSocDate:
                      type: string
                      example: '2018-05-15'
                      description: the date of the last SOC (statement of case) or SSOC (supplemental statement of case)
                    certificationTimeliness:
                      type: array
                      example:
                      - 2
                      - 12
                      items:
                        type: integer
                      description: the range of months it typically takes to certify an appeal
                    ssocTimeliness:
                      type: array
                      example:
                      - 7
                      - 20
                      items:
                        type: integer
                      description: the range of months it typically takes to create an SSOC (supplemental statement of case)
                    decisionTimeliness:
                      type: array
                      example:
                      - 1
                      - 2
                      items:
                        type: integer
                      description: the range of months it typically takes to mail a decision after the appeal has been first assigned to an attorney
                    remandTimeliness:
                      type: array
                      example:
                      - 16
                      - 29
                      items:
                        type: integer
                      description: the range of months it typically takes to either create an SSOC (supplemental statement of case), field grant, or return to the Board a remand
                    socTimeliness:
                      type: array
                      example:
                      - 10
                      - 16
                      items:
                        type: integer
                      description: the range of months it typically takes to create an SOC (statement of case) or field grant
                    remandSsocTimeliness:
                      type: array
                      example:
                      - 3
                      - 11
                      items:
                        type: integer
                      description: the range of months it typically takes to create a second SSOC (supplemental statement of case) on a remand
                    returnTimeliness:
                      type: array
                      example:
                      - 1
                      - 2
                      items:
                        type: integer
                      description: the range of months it typically takes to return a remand to the Board after creating an SSOC (supplemental statement of case)
            docket:
              type: object
              description: Represents the appeals' position in line for a decision and the expected timing of the decision
              properties:
                type:
                  type: string
                  description: Indicates the docket of the appeal
                  enum:
                  - directReview
                  - evidenceSubmission
                  - hearingRequest
                  - legacy
                  example: hearingRequest
                month:
                  type: string
                  format: date
                  example: '2016-08-01'
                docketMonth:
                  type: string
                  format: date
                  example: '2014-06-01'
                front:
                  type: boolean
                  example: false
                total:
                  type: integer
                  example: 206900
                totalAllDockets:
                  type: integer
                  example: 420012
                ahead:
                  type: integer
                  example: 109203
                ready:
                  type: integer
                  example: 22109
                eta:
                  $ref: '#/components/schemas/Eta'
                eligibleToSwitch:
                  type: boolean
                  example: true
                switchDueDate:
                  type: string
                  format: date
                  example: '2020-06-01'
            issues:
              type: array
              items:
                $ref: '#/components/schemas/Issue'
            alerts:
              type: array
              items:
                $ref: '#/components/schemas/Alert'
            events:
              type: array
              items:
                $ref: '#/components/schemas/Event'
            evidence:
              type: array
              items:
                $ref: '#/components/schemas/Evidence'
    Appeals:
      type: array
      items:
        $ref: '#/components/schemas/Appeal'
    Alert:
      type: object
      description: Notification of a request for more information or of a change in the appeal status that requires action.
      properties:
        type:
          type: string
          description: Enum of notifications for an appeal. Acronyms used include cavc (Court of Appeals for Veteran Claims), vso (Veteran Service Organization), and dro (Decision Review Officer).
          example: form9_needed
          enum:
          - form9_needed
          - scheduled_hearing
          - hearing_no_show
          - held_for_evidence
          - cavc_option
          - ramp_eligible
          - ramp_ineligible
          - decision_soon
          - blocked_by_vso
          - scheduled_dro_hearing
          - dro_hearing_no_show
          - evidentiary_period
          - ama_post_decision
        details:
          description: Further information about the alert
          type: object
    Evidence:
      type: object
      description: Documentation and other evidence that has been submitted in support of the appeal
      properties:
        description:
          type: string
          example: Service treatment records
          description: Short text describing what the evidence is
        date:
          type: string
          format: date
          description: Date the evidence was added to the case
          example: '2017-09-30'
    Issue:
      type: object
      description: Issues on appeal
      properties:
        active:
          type: boolean
          example: true
          description: Whether the issue is presently under contention.
        description:
          type: string
          example: Service connection, tinnitus
          description: Description of the Issue
        diagnosticCode:
          type: string
          example: '6260'
          description: The CFR (Code of Federal Regulations) diagnostic code for the issue, if applicable
        lastAction:
          type: string
          description: Most recent decision made on this issue
          enum:
          - field_grant
          - withdrawn
          - allowed
          - denied
          - remand
          - cavc_remand
        date:
          type: string
          format: date
          description: The date of the most recent decision on the issue
          example: '2016-05-30'
    Event:
      type: object
      description: Event during the appeals process
      properties:
        type:
          type: string
          example: soc
          description: Enum of possible event types. Acronyms used include, nod (Notice of Disagreement), soc (Statement of Case), ssoc (Supplemental Statement of Case), ftr (Failed to Report), bva (Board of Veteran Appeals), cavc (Court of Appeals for Veteran Claims), and dro (Decision Review Officer).
          enum:
          - claim_decision
          - nod
          - soc
          - form9
          - ssoc
          - certified
          - hearing_held
          - hearing_no_show
          - bva_decision
          - field_grant
          - withdrawn
          - ftr
          - ramp
          - death
          - merged
          - record_designation
          - reconsideration
          - vacated
          - other_close
          - cavc_decision
          - ramp_notice
          - transcript
          - remand_return
          - ama_nod
          - docket_change
          - distributed_to_vlj
          - bva_decision_effectuation
          - dta_decision
          - sc_request
          - sc_decision
          - sc_other_close
          - hlr_request
          - hlr_decision
          - hlr_dta_error
          - hlr_other_close
          - statutory_opt_in
        date:
          type: string
          format: date
          description: Date the event occurred
          example: '2016-05-30'
        details:
          description: Further information about the event
          type: object
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header