VA Lighthouse Veteran Verification API

openapi: 3.2.0
info:
  version: 0.0.1
  title: Veteran Verification API
  description: The Veteran Verification API allows you to confirm the Veteran status for a given person, or retrieve a Veteran's service history or disability rating.
  termsOfService: ''
  contact:
    name: VA.gov
servers:
- url: https://sandbox-api.va.gov/services/veteran_verification/{version}
  description: Sandbox
  variables:
    version:
      default: v0
- url: https://api.va.gov/services/veteran_verification/{version}
  description: Production
  variables:
    version:
      default: v0
tags:
- name: Veteran Verification
paths:
  /status:
    get:
      tags:
      - Veteran Verification
      summary: Get confirmation about an individual's Veteran status according to the VA
      operationId: GET:/status
      security:
      - bearer_token: []
      responses:
        '200':
          description: Confirmation status successfully retrieved
          content:
            application/json:
              schema:
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/VeteranStatusConfirmation'
        '401':
          description: Not authorized
        '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
        '502':
          description: eMIS failed to respond or responded in a way we cannot handle.
  /disability_rating:
    get:
      tags:
      - Veteran Verification
      summary: Retrieve disability rating of authorized Veteran
      operationId: GET:/disability_rating
      security:
      - bearer_token: []
      responses:
        '200':
          description: Disability Rating retrieved successfully
          content:
            application/json:
              schema:
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/DisabilityRating'
            application/jwt:
              schema:
                $ref: '#/components/schemas/DisabilityRatingToken'
        '401':
          description: Not authorized
        '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
        '502':
          description: BGS service responded with something other than the expected disability rating response.
  /service_history:
    get:
      tags:
      - Veteran Verification
      summary: Retrieve service history of authorized Veteran
      operationId: GET:/service_history
      security:
      - bearer_token: []
      responses:
        '200':
          description: Service History retrieved successfully
          content:
            application/json:
              schema:
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceHistoryEpisode'
            application/jwt:
              schema:
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceHistoryToken'
        '401':
          description: Not authorized
        '404':
          description: No service history found
        '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
components:
  schemas:
    Deployment:
      description: 'Deployment during a service history episode

        '
      type: object
      required:
      - start_date
      - end_date
      - location
      properties:
        start_date:
          type:
          - string
          - 'null'
          format: date
          description: beginning of deployment (YYYY-mm-dd)
          example: '1948-10-10'
        end_date:
          type:
          - string
          - 'null'
          format: date
          description: end of deployment (YYYY-mm-dd)
          example: '1949-10-09'
        location:
          type:
          - string
          - 'null'
          description: Three letter ISO country code of deployment location
          example: KOR
    DisabilityRatingToken:
      description: 'A token containing signed claims about a Veteran''s disability rating percentage

        '
      type: string
      example: eyJhbGciOiJSUzI1NiIsImtpZCI6IjA4OGQyNDIzMmZmNmZhYTRjZDRjZmVjMTI2YWQwNDMxZGZmMWVhMDI4YWZkYjFjODZiMzcxOGQ3MDE3MWFlZDYifQ.eyJkYXRhIjp7ImlkIjoxMjMwMywidHlwZSI6ImRvY3VtZW50X3VwbG9hZCIsImF0dHJpYnV0ZXMiOnsiZGVjaXNpb24iOiJTZXJ2aWNlIENvbm5lY3RlZCIsImVmZmVjdGl2ZV9kYXRlIjoiMjAxOC0wMy0yN1QyMTowMDo0MS4wMDArMDAwMCIsInJhdGluZ19wZXJjZW50YWdlIjo1MH19fQ.z3EeYFixwdmG_4_LFdzy6fdF2Y7nj3y9uOPRTwLqsXVcLNUDIN72atn0SSI-hkF-rRkbFdyzLDaY2AWtQ-LmBPdeWqyv4U2ZnjynAwlCnG0VNG3x4Wz2qSW7BW1cQVBx0yvWag_NmQ74AfOBNz7K2qz8aEOvYIJaicRr2hSAu7A
    VeteranStatusConfirmation:
      description: 'Veteran status confirmation for an individual

        '
      type: object
      properties:
        id:
          type: string
          description: Confirmation UUID
          example: 833c6ffc-efef-4775-9355-f836b4f57501
        type:
          type: string
          example: veteran_status_confirmations
        attributes:
          type: object
          properties:
            veteran_status:
              type: string
              description: 'Whether the system could confirm the Veteran status of the authorized individual

                '
              enum:
              - confirmed
              - not confirmed
    DisabilityRatingAttributes:
      description: 'Body of the disability rating response

        '
      required:
      - combined_disability_rating
      - combined_effective_date
      - legal_effective_date
      - individual_ratings
      properties:
        combined_disability_rating:
          description: Overall severity rating determined by VA calculation of each service related conditions. Used to help determine disability compensation (pay) and related benefits.
          type:
          - integer
          - 'null'
          example: 100
        combined_effective_date:
          description: The effective date of the latest combined disability rating for the Veteran
          type:
          - datetime
          - 'null'
          example: 2018-03-27T21:00:41.000+0000
        legal_effective_date:
          description: When the Veteran could begin claiming benefits for combined disability rating
          type:
          - datetime
          - 'null'
          example: 2018-03-27T21:00:41.000+0000
        individual_ratings:
          description: list of individual service connected disabilty ratings
          type: array
          items:
            $ref: '#/components/schemas/individual_ratings'
    DisabilityRating:
      description: 'The disability rating percentage applied to the Veteran.

        '
      required:
      - id
      - type
      - atttributes
      properties:
        id:
          description: JSON API identifier
          type: string
          example: 12303
        type:
          description: JSON API type specification
          type: string
          example: disability-rating
        attributes:
          $ref: '#/components/schemas/DisabilityRatingAttributes'
    individual_ratings:
      description: list of service connected disability ratings
      required:
      - decision
      - effective_date
      - rating_percentage
      properties:
        decision:
          description: Whether the disability is service connected or not.
          type:
          - string
          - 'null'
          example: Service Connected
        effective_date:
          description: When the Veteran could begin claiming benefits related to this disability
          type:
          - string
          - 'null'
          format: datetime
          example: 2018-03-27T21:00:41.000+0000
        rating_percentage:
          description: Severity rating determined by VA that indicates how disabling an illness or injury is for the Veteran. Used to help determine disability compensation (pay) and related benefits.
          type:
          - number
          - 'null'
          example: 50
    ServiceHistoryToken:
      description: 'A token containing signed claims about a Veteran''s service history

        '
      type: string
      example: eyJhbGciOiJSUzI1NiIsImtpZCI6IjA4OGQyNDIzMmZmNmZhYTRjZDRjZmVjMTI2YWQwNDMxZGZmMWVhMDI4YWZkYjFjODZiMzcxOGQ3MDE3MWFlZDYifQ.eyJkYXRhIjp7ImlkIjoiMTIzMTJBQVNEZiIsInR5cGUiOiJzZXJ2aWNlLWhpc3RvcnktZXBpc29kZXMiLCJhdHRyaWJ1dGVzIjp7InN0YXJ0X2RhdGUiOiIxOTQ4LTA0LTA4IiwiZW5kX2RhdGUiOiIxOTUwLTA1LTEwIiwiYnJhbmNoIjoiQWlyIEZvcmNlIiwiZGlzY2hhcmdlX3N0YXR1cyI6Imhvbm9yYWJsZSIsImRlcGxveW1lbnRzIjpbeyJzdGFydF9kYXRlIjoiMTk0OC0xMC0xMCIsImVuZF9kYXRlIjoiMTk0OS0xMC0wOSIsImxvY2F0aW9uIjoiS09SIn1dfX19.S39hmL-5nxvdJnJ_PSHdfiP744dTcGzrUKsqcVQa1FomUU15Dr2A2gQMF7XWO2DCLrdM0bCtIS8mCSwI00nqQFqXGjZVGQTIyzQJDPHxV6jnYwwaXD1vzbxlsycWF2ZQ_5Wx6TIhnXiEkbn_rzW_VleVnHjLCRQwzmpwGGDsL_I
    ServiceHistoryEpisode:
      description: 'Service History for authorized Veteran

        '
      required:
      - id
      - attributes
      type: object
      properties:
        id:
          type: string
          description: Service History Episode ID
          example: 12312AASDf
        type:
          type: string
          example: service-history-episodes
        attributes:
          type: object
          required:
          - first_name
          - last_name
          - start_date
          - end_date
          - branch_of_service
          - pay_grade
          - discharge_status
          - separation_reason
          - deployments
          properties:
            first_name:
              type: string
              description: Veteran first name
              example: Abraham
            last_name:
              type: string
              description: Veteran last name
              example: Lincoln
            start_date:
              type:
              - string
              - 'null'
              format: date
              description: start date of a service history episode (YYYY-mm-dd)
              example: '1948-04-08'
            end_date:
              type:
              - string
              - 'null'
              format: date
              description: end date of a service history episode (YYYY-mm-dd)
              example: '1950-05-10'
            branch_of_service:
              type: string
              description: Branch of military including National Guard or Reserve status
              example: Air Force
            pay_grade:
              type: string
              description: "Defines the level of compensation for a position, normalized across military branches\n\nPossible values include the concatenation of Pay Plan Code and Pay Grade Code.\nPay Plan Code is represented as a two-character code, and can be one of five values:\n - CC (Commissioned Corps)\n - MC (Cadet)\n - ME (Enlisted)\n - MO (Officer)\n - MW (Warrant Officer)\n\nPay Grade Code is a value between 01 and 10.\nPay Plan Code is concatenated with Pay Grade Code to determine the full Pay Grade value, with the leading character (M or C) stripped from Pay Plan Code.\n"
              example: W01
            discharge_status:
              type:
              - string
              - 'null'
              description: 'Character of discharge from service episode. Possible values are:


                Both "honorable-for-va-purposes" and "dishonorable-for-va-purposes" represent a change in character of discharge based on an administrative decision, for purposes of VA benefits administration. The original character of discharge for other purposes was either "bad-conduct" or "other-than-honorable". "honorable-absence-of-negative-report" represents an unreported character of service that DoD classifies as honorable.

                '
              enum:
              - honorable
              - general
              - bad-conduct
              - other-than-honorable
              - dishonorable
              - honorable-absence-of-negative-report
              - honorable-for-va-purposes
              - dishonorable-for-va-purposes
              - uncharacterized
              - unknown
              example: honorable
            separation_reason:
              type: string
              description: Additional text description for separation reason beyond discharge_status value
              example: SUFFICIENT SERVICE FOR RETIREMENT
            deployments:
              type: array
              items:
                $ref: '#/components/schemas/Deployment'
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT