VA Lighthouse Claims API

openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver Claims 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: Claims
  description: 'Allows authenticated and authorized users to access claims data for a single claim by ID, or for all claims based on claimant data. No data is returned if the user is not authenticated and authorized.

    '
paths:
  /claims:
    get:
      summary: Find all benefits claims for a VA claimant
      tags:
      - Claims
      operationId: GET:/claims
      security:
      - productionOauth:
        - claim.read
      - sandboxOauth:
        - claim.read
      - bearer_token: []
      description: Uses the Veteran’s metadata in headers to retrieve all claims for that Veteran. An authenticated Veteran making a request with this endpoint will return their own claims, if any.
      parameters:
      - in: header
        name: X-VA-SSN
        required: false
        description: Claimant SSN if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-First-Name
        required: false
        description: Claimant first name if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-Last-Name
        required: false
        description: Claimant last name if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-Birth-Date
        required: false
        description: Claimant birthdate if consumer is representative, in iso8601 format
        schema:
          type: string
      responses:
        '200':
          description: claim response
          content:
            application/json:
              example:
                data:
                - id: '600354175'
                  type: evss_claims
                  attributes:
                    evss_id: 600354175
                    open: false
                    waiver_submitted: false
                    requested_decision: false
                    claim_type: Compensation
                    date_filed: '2022-12-01'
                    min_est_date: null
                    max_est_date: null
                    development_letter_sent: false
                    decision_letter_sent: false
                    documents_needed: false
                    status: Complete
                - id: '600354178'
                  type: evss_claims
                  attributes:
                    evss_id: 600354178
                    open: false
                    waiver_submitted: false
                    requested_decision: false
                    claim_type: Compensation
                    date_filed: '2022-12-01'
                    min_est_date: null
                    max_est_date: null
                    development_letter_sent: false
                    decision_letter_sent: false
                    documents_needed: false
                    status: Complete
                - id: '600311927'
                  type: evss_claims
                  attributes:
                    evss_id: 600311927
                    open: false
                    waiver_submitted: false
                    requested_decision: false
                    claim_type: Compensation
                    date_filed: '2022-06-23'
                    min_est_date: null
                    max_est_date: null
                    development_letter_sent: false
                    decision_letter_sent: true
                    documents_needed: false
                    status: Complete
                - id: '600309680'
                  type: evss_claims
                  attributes:
                    evss_id: 600309680
                    open: false
                    waiver_submitted: false
                    requested_decision: false
                    claim_type: Compensation
                    date_filed: '2022-06-09'
                    min_est_date: null
                    max_est_date: null
                    development_letter_sent: false
                    decision_letter_sent: true
                    documents_needed: false
                    status: Complete
                - id: '600308831'
                  type: evss_claims
                  attributes:
                    evss_id: 600308831
                    open: false
                    waiver_submitted: false
                    requested_decision: false
                    claim_type: Compensation
                    date_filed: '2022-06-06'
                    min_est_date: null
                    max_est_date: null
                    development_letter_sent: false
                    decision_letter_sent: true
                    documents_needed: false
                    status: Complete
              schema:
                $schema: http://json-schema.org/draft-04/schema#
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      required:
                      - id
                      - type
                      - attributes
                      additionalProperties: false
                      description: Claim with some details for the given Veteran info
                      properties:
                        id:
                          type: string
                          description: Claim ID from EVSS
                          example: '8347210'
                        type:
                          type: string
                          example: evss_claims
                        attributes:
                          type: object
                          additionalProperties: false
                          required:
                          - evss_id
                          - date_filed
                          - max_est_date
                          - open
                          - waiver_submitted
                          - documents_needed
                          - development_letter_sent
                          - status
                          - requested_decision
                          - claim_type
                          properties:
                            evss_id:
                              type: integer
                              description: Upstream service identifier
                            date_filed:
                              type: string
                              format: date
                              description: Date in YYYY-MM-DD the claim was first filed
                              example: '2018-06-04'
                            min_est_date:
                              type:
                              - string
                              - 'null'
                              format: date
                              description: Minimum Estimated Claim Completion Date
                              example: '2019-06-04'
                            max_est_date:
                              type:
                              - string
                              - 'null'
                              format: date
                              description: Maximum Estimated Claim Completion Date
                              example: '2019-09-04'
                            open:
                              type: boolean
                              description: Has the claim been resolved
                              example: 'true'
                            waiver_submitted:
                              type: boolean
                              description: Requested Decision or Waiver 5103 Submitted
                              example: 'false'
                            documents_needed:
                              type: boolean
                              description: Does the claim require additional documents to be submitted
                              example: 'false'
                            development_letter_sent:
                              type: boolean
                              description: Indicates if a Development Letter has been sent to the Claimant regarding a benefit claim
                              example: 'false'
                            decision_letter_sent:
                              type: boolean
                              description: Indicates if a Decision Letter has been sent to the Claimant regarding a benefit claim
                              example: 'false'
                            status:
                              type: string
                              description: Current status of the claim
                              enum:
                              - Claim received
                              - Initial review
                              - Evidence gathering, review, and decision
                              - Preparation for notification
                              - Complete
                              example: Claim received
                            requested_decision:
                              type: boolean
                              description: The claim filer has requested a claim decision be made
                              example: 'false'
                            claim_type:
                              type: string
                              description: The type of claim originally submitted
                              example: Compensation
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                errors:
                - title: Not authorized
                  detail: Not authorized
                  code: '401'
                  status: '401'
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      additionalProperties: false
                      required:
                      - title
                      - detail
                      - code
                      - status
                      properties:
                        title:
                          type: string
                          description: HTTP error title
                        detail:
                          type: string
                          description: HTTP error detail
                        code:
                          type: string
                          description: HTTP error code
                        status:
                          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
        '404':
          description: Resource Not Found
          content:
            application/json:
              example:
                errors:
                - title: Resource not found
                  detail: The Resource was not found.
                  code: '404'
                  status: '404'
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      additionalProperties: false
                      required:
                      - title
                      - detail
                      - code
                      - status
                      properties:
                        title:
                          type: string
                          description: HTTP error title
                        detail:
                          type: string
                          description: HTTP error detail
                        code:
                          type: string
                          description: HTTP error code
                        status:
                          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
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: API rate limit exceeded
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
  /claims/{id}:
    get:
      summary: Find Claim by ID
      tags:
      - Claims
      operationId: GET:/claims/{id}
      security:
      - productionOauth:
        - claim.read
      - sandboxOauth:
        - claim.read
      - bearer_token: []
      parameters:
      - name: id
        in: path
        description: The ID of the claim being requested
        required: true
        schema:
          type: string
      - in: header
        name: X-VA-SSN
        required: false
        description: Claimant SSN if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-First-Name
        required: false
        description: Claimant first name if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-Last-Name
        required: false
        description: Claimant last name if consumer is representative
        schema:
          type: string
      - in: header
        name: X-VA-Birth-Date
        required: false
        description: Claimant birthdate if consumer is representative, in iso8601 format
        schema:
          type: string
      description: Returns data such as processing status for a single claim by ID.
      responses:
        '200':
          description: claims response
          content:
            application/json:
              example:
                data:
                  id: 00000000-0000-0000-0000-000000000010
                  type: claims_api_claim
                  attributes:
                    evss_id: 600118851
                    open: false
                    waiver_submitted: false
                    requested_decision: false
                    claim_type: Compensation
                    date_filed: '2017-12-08'
                    min_est_date: null
                    max_est_date: null
                    development_letter_sent: false
                    decision_letter_sent: false
                    documents_needed: false
                    contention_list: []
                    events_timeline:
                    - type: phase7
                      date: '2018-06-12'
                    - type: completed
                      date: '2018-06-12'
                    - type: filed
                      date: '2017-12-08'
                    va_representative: AMERICAN LEGION
                    status: Complete
                    supporting_documents:
                    - id: 00000000-0000-0000-0000-000000000011
                      type: claim_supporting_document
                      md5: 84e997702baca501734d4e23dae0f9af
                      header_hash: c2714a50560affd76bfc376a90ec4e52d49e1a09d073456b7a1594452fd7ccc7
                      filename: custom_file_name.pdf
                      uploaded_at: '2024-01-01T00:00:00.000Z'
              schema:
                $schema: http://json-schema.org/draft-04/schema#
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    additionalProperties: false
                    required:
                    - id
                    - type
                    - attributes
                    properties:
                      id:
                        type: string
                        description: Claim ID from EVSS
                      type:
                        type: string
                      attributes:
                        type: object
                        additionalProperties: false
                        required:
                        - date_filed
                        - max_est_date
                        - open
                        - waiver_submitted
                        - documents_needed
                        - development_letter_sent
                        - status
                        - requested_decision
                        - claim_type
                        - contention_list
                        - va_representative
                        - events_timeline
                        - supporting_documents
                        properties:
                          evss_id:
                            type: integer
                            nullable: true
                            description: Upstream service identifier
                          date_filed:
                            type: string
                            format: date
                            description: Date in YYYY-MM-DD the claim was first filed
                            example: '2018-06-04'
                          min_est_date:
                            type:
                            - string
                            - 'null'
                            format: date
                            description: Minimum Estimated Claim Completion Date
                            example: '2019-06-04'
                          max_est_date:
                            type:
                            - string
                            - 'null'
                            format: date
                            description: Maximum Estimated Claim Completion Date
                            example: '2019-09-04'
                          open:
                            type: boolean
                            description: Has the claim been resolved
                          waiver_submitted:
                            type: boolean
                            description: Requested Decision or Waiver 5103 Submitted
                          documents_needed:
                            type: boolean
                            description: Does the claim require additional documents to be submitted
                          development_letter_sent:
                            type: boolean
                            description: Indicates if a Development Letter has been sent to the Claimant regarding a benefit claim
                          decision_letter_sent:
                            type: boolean
                            description: Indicates if a Decision Letter has been sent to the Claimant regarding a benefit claim
                          status:
                            type: string
                            description: Current status of the claim
                            enum:
                            - pending
                            - Claim received
                            - Initial review
                            - Evidence gathering, review, and decision
                            - Preparation for notification
                            - Complete
                          requested_decision:
                            type: boolean
                            description: The claim filer has requested a claim decision be made
                          claim_type:
                            type: string
                            description: The type of claim originally submitted
                          contention_list:
                            type: array
                            items:
                              type: string
                          va_representative:
                            type: string
                            description: Current VA Representative Organization
                          events_timeline:
                            type: array
                            items:
                              anyOf:
                              - type: object
                                additionalProperties: false
                                required:
                                - type
                                - date
                                properties:
                                  type:
                                    type: string
                                    description: Different types of event statuses
                                  date:
                                    type: string
                                    format: date
                                    description: Date of Event
                              - type: object
                                additionalProperties: false
                                required:
                                - tracked_item_id
                                - file_type
                                - document_type
                                - filename
                                - upload_date
                                - type
                                - date
                                properties:
                                  tracked_item_id:
                                    type:
                                    - string
                                    - 'null'
                                    description: Tracked Item ID given by VBMS
                                  file_type:
                                    type: string
                                    description: Type of File being submitted/requested
                                  document_type:
                                    type: string
                                    description: Type of document submitted
                                  filename:
                                    type: string
                                    description: Name of file submitted
                                  upload_date:
                                    type: string
                                    format: date
                                    description: Date original upload of file occured
                                  type:
                                    type: string
                                    description: Type of Tracked Item submitted
                                  date:
                                    type: string
                                    format: date
                                    description: Date of Event
                          supporting_documents:
                            type: array
                            items:
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of document
                                type:
                                  type: string
                                md5:
                                  type: string
                                  description: Hashed representation of document
                                header_hash:
                                  type: string
                                  description: Hashed representation of document header
                                filename:
                                  type: string
                                  description: Name of document
                                uploaded_at:
                                  type: string
                                  format: date
                                  description: Date and time document was uploaded
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                errors:
                - title: Not authorized
                  detail: Not authorized
                  code: '401'
                  status: '401'
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      additionalProperties: false
                      required:
                      - title
                      - detail
                      - code
                      - status
                      properties:
                        title:
                          type: string
                          description: HTTP error title
                        detail:
                          type: string
                          description: HTTP error detail
                        code:
                          type: string
                          description: HTTP error code
                        status:
                          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
        '404':
          description: Record Not Found
          content:
            application/json:
              example:
                errors:
                - title: Resource not found
                  detail: Claim not found
                  code: '404'
                  status: '404'
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      additionalProperties: false
                      required:
                      - title
                      - detail
                      - code
                      - status
                      properties:
                        title:
                          type: string
                          description: HTTP error title
                        detail:
                          type: string
                          description: HTTP error detail
                        code:
                          type: string
                          description: HTTP error code
                        status:
                          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
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              example:
                errors:
                - title: Unprocessable Entity
                  detail: Unknown EVSS Async Error
                  code: '422'
                  status: '422'
              schema:
                required:
                - errors
                properties:
                  errors:
               

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/va-gov/refs/heads/main/openapi/va-gov-claims-api-openapi.yml