VA Lighthouse Forms API

openapi: 3.2.0
info:
  version: 0.0.0
  title: VA Forms API
  description: Use the VA Forms API to search for VA forms, get the form's PDF link and metadata, and check for new versions.
  contact:
    name: va.gov
servers:
- url: https://sandbox-api.va.gov/services/va_forms/{version}
  description: Sandbox
  variables:
    version:
      default: v0
- url: https://api.va.gov/services/va_forms/{version}
  description: Production
  variables:
    version:
      default: v0
basePath: /services/va_forms/v0
consumes:
- application/json
produces:
- application/json
tags:
- name: Forms
paths:
  /forms:
    get:
      security:
      - apikey: []
      summary: Returns all VA Forms and their last revision date
      description: Returns an index of all available VA forms. Optionally, pass a query parameter to filter forms by form number or title.
      operationId: GET:/forms
      produces:
      - application/json
      tags:
      - Forms
      parameters:
      - name: query
        in: query
        description: Returns form data based on entered form name.
        required: false
        type: string
      responses:
        '200':
          description: VA Forms index response
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FormsIndex'
        '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
        '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
  /forms/{form_name}:
    get:
      security:
      - apikey: []
      summary: Find form by form name
      description: Returns a single form and the full revision history
      operationId: GET:/forms/{form_name}
      tags:
      - Forms
      parameters:
      - name: form_name
        in: path
        description: The VA form_name of the form being requested. The exact form name must be passed, including proper placement of prefixes and/or hyphens.
        required: true
        example: 10-10EZ
        schema:
          type: string
      responses:
        '200':
          description: VA Form Show response
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/FormShow'
        '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: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      properties:
                        message:
                          type: string
                          example: Form not 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
        '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:
    FormShow:
      description: Data for a particular VA form, including form version history.
      properties:
        id:
          description: JSON API identifier
          type: string
          example: 10-10-EZ
        type:
          description: JSON API type specification
          type: string
          example: va_form
        attributes:
          properties:
            form_name:
              description: Name of the VA Form
              type: string
              example: 10-10EZ
            url:
              description: Web location of the form
              type: string
              example: https://www.va.gov/vaforms/medical/pdf/10-10EZ-fillable.pdf
            title:
              description: Title of the form as given by VA
              type: string
              example: Instructions and Enrollment Application for Health Benefits
            first_issued_on:
              description: The date the form first became available
              type:
              - string
              - 'null'
              example: '2016-07-10'
              format: date
            last_revision_on:
              description: The date the form was last updated
              type:
              - string
              - 'null'
              example: '2020-01-17'
              format: date
            created_at:
              description: Internal field for VA.gov use
              type:
              - string
              - 'null'
              example: '2021-03-30T16:28:30.338Z'
              format: date-time
            pages:
              description: Number of pages contained in the form
              type: integer
              example: 5
            sha256:
              description: A sha256 hash of the form contents
              type:
              - string
              - 'null'
              example: 5fe171299ece147e8b456961a38e17f1391026f26e9e170229317bc95d9827b7
            valid_pdf:
              description: A flag indicating whether the form url was confirmed as a valid download
              type: boolean
              example: 'true'
            form_usage:
              description: A description of how the form is to be used
              type:
              - string
              - 'null'
              example: <p>Use VA Form 10-10EZ if you’re a Veteran and want to apply for VA health care. You must be enrolled in...</p>
            form_tool_intro:
              description: Introductory text describing the VA online tool for this form
              type:
              - string
              - 'null'
              example: You can apply online instead of filling out and sending us the paper form.
            form_tool_url:
              description: Location of the online tool for this form
              type:
              - string
              - 'null'
              example: https://www.va.gov/health-care/apply/application/introduction
            form_details_url:
              description: Location on www.va.gov of the info page for this form
              type:
              - string
              - 'null'
              example: https://www.va.gov/find-forms/about-form-10-10ez
            form_type:
              description: VA Type of the form
              type:
              - string
              - 'null'
              example: benefit
            language:
              description: Language code of the form
              type:
              - string
              - 'null'
              example: en
            deleted_at:
              description: The timestamp at which the form was deleted
              type:
              - string
              - 'null'
              example: null
              format: date-time
            related_forms:
              description: A listing of other forms that relate to current form
              type:
              - array
              - 'null'
              items:
                type: string
                example: 10-10EZR
            benefit_categories:
              description: Listing of benefit categories and match
              type:
              - array
              - 'null'
              items:
                properties:
                  name:
                    description: Name of the benefit category of the form
                    type: string
                    example: Health care
                  description:
                    description: Description of the benefit category of the form
                    type: string
                    example: VA health care
            va_form_administration:
              description: The VA organization that administers the form
              type:
              - string
              - 'null'
              example: Veterans Health Administration
            versions:
              type:
              - array
              - 'null'
              description: The version history of revisions to the form
              items:
                properties:
                  sha256:
                    description: A sha256 hash of the form contents for that version
                    type: string
                    example: 5fe171299ece147e8b456961a38e17f1391026f26e9e170229317bc95d9827b7
                  revision_on:
                    description: The date the sha256 hash was calculated
                    type: string
                    example: '2012-01-01'
                    format: date
    FormsIndex:
      description: A listing of available VA forms and their location.
      properties:
        id:
          description: JSON API identifier
          type: string
          example: '5403'
        type:
          description: JSON API type specification
          type: string
          example: va_form
        attributes:
          properties:
            form_name:
              description: Name of the VA Form
              type: string
              example: 10-10EZ
            url:
              description: Web location of the form
              type: string
              example: https://www.va.gov/vaforms/medical/pdf/10-10EZ-fillable.pdf
            title:
              description: Title of the form as given by VA
              type: string
              example: Instructions and Enrollment Application for Health Benefits
            first_issued_on:
              description: The date the form first became available
              type:
              - string
              - 'null'
              example: '2016-07-10'
              format: date
            last_revision_on:
              description: The date the form was last updated
              type:
              - string
              - 'null'
              example: '2020-01-17'
              format: date
            pages:
              description: Number of pages contained in the form
              type: integer
              example: 5
            sha256:
              description: A sha256 hash of the form contents
              type:
              - string
              - 'null'
              example: 6e6465e2e1c89225871daa9b6d86b92d1c263c7b02f98541212af7b35272372b
            last_sha256_change:
              description: The date of the last sha256 hash change
              type:
              - string
              - 'null'
              example: '2019-05-30'
              format: date
            valid_pdf:
              description: A flag indicating whether the form url was confirmed as a valid download
              type: boolean
              example: 'true'
            form_usage:
              description: A description of how the form is to be used
              type:
              - string
              - 'null'
              example: <p>Use VA Form 10-10EZ if you’re a Veteran and want to apply for VA health care. You must be enrolled in...</p>
            form_tool_intro:
              description: Introductory text describing the VA online tool for this form
              type:
              - string
              - 'null'
              example: You can apply online instead of filling out and sending us the paper form.
            form_tool_url:
              description: Location of the online tool for this form
              type:
              - string
              - 'null'
              example: https://www.va.gov/health-care/apply/application/introduction
            form_details_url:
              description: Location on www.va.gov of the info page for this form
              type:
              - string
              - 'null'
              example: https://www.va.gov/find-forms/about-form-10-10ez
            form_type:
              description: VA Type of the form
              type:
              - string
              - 'null'
              example: benefit
            language:
              description: Language code of the form
              type: string
              example: en
            deleted_at:
              description: The timestamp at which the form was deleted
              type:
              - string
              - 'null'
              example: 'null'
              format: date-time
            related_forms:
              description: A listing of other forms that relate to current form
              type:
              - array
              - 'null'
              items:
                type: string
                example: 10-10EZR
            benefit_categories:
              description: Listing of benefit categories and match
              type:
              - array
              - 'null'
              items:
                properties:
                  name:
                    description: Name of the benefit category of the form
                    type: string
                    example: Health care
                  description:
                    description: Description of the benefit category of the form
                    type: string
                    example: VA health care
            va_form_administration:
              description: The VA organization that administers the form
              type:
              - string
              - 'null'
              example: Veterans Health Administration
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header