VA Lighthouse ACA Coverage API

openapi: 3.2.0
info:
  title: Veteran Service History and Eligibility ACA Coverage API
  description: 'With this API you can

    * Return enrolled benefits for a Veteran.'
  contact:
    name: VA.gov
  version: 2.1.0
servers:
- url: https://sandbox-api.va.gov/services/veteran_verification/{version}
  description: Sandbox
  variables:
    version:
      default: v2
- url: https://api.va.gov/services/veteran_verification/{version}
  description: Production
  variables:
    version:
      default: v2
tags:
- name: ACA Coverage
paths:
  /restricted/aca_coverage:
    post:
      tags:
      - ACA Coverage
      summary: Return a Veteran's enrollment status in minimum essential coverage (MEC) as…
      description: 'This endpoint checks a Veteran''s enrollment status for minimum essential

        coverage (MEC), as defined by the Affordable Care Act (ACA), for a specified

        date range.


        The response includes a code for Veteran''s health benefits status for

        the request''s date range. If the status returned is "APPLICANT_ENROLLED,"

        the response also includes the start and end dates of the coverage. If multiple

        enrollments are found for the requested date range, multiple start and end dates are

        returned (limited to the 12 most recent enrollments).


        The ACA Coverage endpoint requires all of the following data elements in your request:

        * First Name

        * Last Name

        * Date of Birth (format: "yyyy-mm-dd")

        * Social Security Number (format: "000-00-0000")

        * ACA Coverage Search Start Date (format: "yyyy-mm-dd")

        * ACA Coverage Search End Date (format: "yyyy-mm-dd")


        The required data are utilized to match a Veteran in VA records.'
      operationId: POST:/restricted/aca_coverage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VeteranSsnAttributes'
            example:
              person_first_name: Alfredo
              person_last_name: Armstrong
              person_date_of_birth: '1993-06-08'
              person_ssn_identification: 796-01-2476
              aca_coverage_start_date: '2021-09-01'
              aca_coverage_end_date: '2022-12-31'
        required: true
      responses:
        '200':
          description: Enrolled status successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcaCoverageResponse'
              example:
                data:
                  response_code: V0000
                  description: APPLICANT_ENROLLED
                  aca_coverage_periods:
                  - aca_coverage_start_date: '2021-09-01'
                    aca_coverage_end_date: '2021-09-31'
                  - aca_coverage_start_date: '2022-01-01'
                    aca_coverage_end_date: '2022-01-31'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                title: Bad Request
                detail: Bad Request
                code: '400'
                status: '400'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationError'
              example:
                status: '401'
                error: Invalid Token.
                path: /veteran_verification/v2/restricted/aca_coverage
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenServerError'
              example:
                status: '403'
                error: Token not granted requested scope.
                path: /veteran_verification/v2/restricted/aca_coverage
        '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:
              schema:
                $ref: '#/components/schemas/VhaDataError'
              example:
                errors:
                - title: V1000 - Data Error/Invalid Request
                  detail: Required element invalid or missing in request.
                  code: '422'
                  status: '422'
        '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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerApiError'
              example:
                title: Internal server error
                detail: Internal server error
                code: '500'
                status: '500'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VhaSystemError'
              example:
                errors:
                - title: V1002 - System Error
                  detail: System error.
                  code: '502'
                  status: '502'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VhaSystemUnavailable'
              example:
                errors:
                - title: V1001 - Backend Application Unavailable
                  detail: Unable to respond, system unavailable.
                  code: '503'
                  status: '503'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
      security:
      - sandboxOauth2:
        - aca_coverage_restricted.read
      - productionOauth2:
        - aca_coverage_restricted.read
components:
  schemas:
    AuthorizationError:
      type: object
      properties:
        status:
          type: string
          example: '401'
        error:
          type: string
          example: Invalid token.
        path:
          type: string
          example: /veteran_verification/v2/{endpoint}
    VhaDataError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example: "    {\n     \"errors\": [\n                 {\n                  \"title\": \"V1000 - Data Error/Invalid Request\",\n                  \"detail\": \"Required element invalid or missing in\n                  request.\",\n                  \"code\": \"422\",\n                  \"status\": \"422\"\n                 }\n               ]\n     }\n"
    AcaCoverageData:
      type: object
      properties:
        response_code:
          type: string
          description: Returns a response code
          example: V0000
        description:
          type: string
          description: Defines reason for response code
          example: APPLICANT_ENROLLED
        aca_coverage_periods:
          type: array
          description: Returns a list of enrollment coverage periods
          items:
            $ref: '#/components/schemas/AcaCoveragePeriods'
    AcaCoveragePeriods:
      type: object
      properties:
        aca_coverage_start_date:
          type: string
          description: Indicates Enrollment Status Coverage Period start date
          example: '2019-10-09'
        aca_coverage_end_date:
          type: string
          description: Indicates Enrollment Status Coverage Period end date
          example: '2019-10-09'
      description: Returns a list of enrollment coverage periods
    InternalServerApiError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example:
        errors:
        - title: Internal server error
          detail: Internal server error
          code: '500'
          status: '500'
    AcaCoverageResponse:
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AcaCoverageData'
      description: Response codes and descriptions from source system if successful Veteran match is found:<br>V0000 - APPLICANT_ENROLLED<br>V0001 - APPLICANT_NOT_ENROLLED<br>V0002 - APPLICANT_NOT_FOUND<br>V0003 - APPLICANT_DECEASED<br>V0004 - APPLICANT_DECEASED_ENROLLED<br>V0005 - APPLICANT_DECEASED_NOT_ENROLLED<br>
    ApiErrorDetails:
      type: object
      properties:
        title:
          type: string
          example: Error title
        detail:
          type: string
          example: Detailed error message
        code:
          type: string
          example: Error Code
        status:
          type: string
          example: Error Code
    BadRequest:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example:
        errors:
        - title: Bad Request
          detail: Bad Request
          code: '400'
          status: '400'
    ForbiddenServerError:
      type: object
      properties:
        status:
          type: string
          example: '403'
        error:
          type: string
          example: Token not granted requested scope.
        path:
          type: string
          example: /veteran_verification/v2/{endpoint}
    VhaSystemError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example:
        errors:
        - title: V1002 - System Error
          detail: System error.
          code: '502'
          status: '502'
    VhaSystemUnavailable:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example:
        errors:
        - title: V1001 - Backend Application Unavailable
          detail: Unable to respond, system unavailable.
          code: '503'
          status: '503'
    VeteranSsnAttributes:
      required:
      - aca_coverage_end_date
      - aca_coverage_start_date
      - person_date_of_birth
      - person_first_name
      - person_last_name
      - person_ssn_identification
      type: object
      properties:
        person_ssn_identification:
          type: string
        person_first_name:
          type: string
        person_last_name:
          type: string
        person_date_of_birth:
          type: string
          format: date
        aca_coverage_start_date:
          type: string
          format: date
        aca_coverage_end_date:
          type: string
          format: date
  securitySchemes:
    productionOauth2:
      type: oauth2
      description: This API uses OAuth 2.0 with client credentials grant flow and authorization code grant flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.va.gov/oauth2/veteran-verification/system/v1/token
          scopes:
            aca_coverage_restricted.read: Return a Veteran's enrollment status in minimum essential coverage (MEC) as defined by the Affordable Care Act (ACA).  (restricted access).
            disability_rating.read: Retrieve Disability Rating
            disability_rating_summary.read: Retrieve Disability Rating Summary
            disability_rating_restricted.read: For approved federal consumers, view a Veteran's VA disability ratings and their effective dates using Social Security number and demographic information.
            disability_rating_summary_restricted.read: For approved federal consumers, view a Veteran's VA disability rating summary using Social Security number and demographic information.
            enrolled_benefits.read: Retrieve Veteran Enrolled Benefits
            flashes.read: Retrieve Flashes
            launch.read: Retrieve Launch
            permanent_and_total_disability.read: View a Veteran's P&T and IU disability statuses and effective dates.
            permanent_and_total_disability_restricted.read: 'Vew a Veteran''s P&T and IU disability statuses and effective dates, based on restricted user attributes. '
            service_history.read: Retrieve Service History
            status_restricted.read: For approved federal consumers, confirm the Veteran status of an individual using Social Security number and demographic information.
            veteran_status.read: Retrieve Veteran Status
        authorizationCode:
          authorizationUrl: https://api.va.gov/oauth2/veteran-verification/system/v1/authorization
          tokenUrl: https://api.va.gov/oauth2/veteran-verification/system/v1/token
          scopes:
            aca_coverage_restricted.read: Return a Veteran's enrollment status in minimum essential coverage (MEC) as defined by the Affordable Care Act (ACA).  (restricted access).
            disability_rating.read: Retrieve Disability Rating
            disability_rating_summary.read: Retrieve Disability Rating Summary
            disability_rating_restricted.read: For approved federal consumers, view a Veteran's VA disability ratings and their effective dates using Social Security number and demographic information.
            enrolled_benefits.read: Retrieve Veteran Enrolled Benefits
            flashes.read: Retrieve Flashes
            permanent_and_total_disability.read: View a Veteran's P&T and IU disability statuses and effective dates.
            service_history.read: Retrieve Service History
            status_restricted.read: For approved federal consumers, confirm the Veteran status of an individual using Social Security number and demographic information.
            veteran_status.read: Retrieve Veteran Status
    sandboxOauth2:
      type: oauth2
      description: This API uses OAuth 2.0 with client credentials grant flow and authorization code grant flow
      flows:
        clientCredentials:
          tokenUrl: https://api.va.gov/oauth2/veteran-verification/system/v1/token
          scopes:
            aca_coverage_restricted.read: Return a Veteran's enrollment status in minimum essential coverage (MEC) as defined by the Affordable Care Act (ACA).  (restricted access).
            disability_rating.read: Retrieve Disability Rating
            disability_rating_summary.read: Retrieve Disability Rating Summary
            disability_rating_restricted.read: For approved federal consumers, view a Veteran's VA disability ratings and their effective dates using Social Security number and demographic information.
            disability_rating_summary_restricted.read: For approved federal consumers, view a Veteran's VA disability rating summary using Social Security number and demographic information.
            enrolled_benefits.read: Retrieve Veteran Enrolled Benefits
            flashes.read: Retrieve Flashes
            launch.read: Retrieve Launch
            permanent_and_total_disability.read: View a Veteran's P&T and IU disability statuses and effective dates.
            permanent_and_total_disability_restricted.read: 'Vew a Veteran''s P&T and IU disability statuses and effective dates, based on restricted user attributes. '
            service_history.read: Retrieve Service History
            status_restricted.read: For approved federal consumers, confirm the Veteran status of an individual using Social Security number and demographic information.
            veteran_status.read: Retrieve Veteran Status
        authorizationCode:
          authorizationUrl: https://sandbox-api.va.gov/oauth2/veteran-verification/system/v1/authorization
          tokenUrl: https://sandbox-api.va.gov/oauth2/veteran-verification/system/v1/token
          scopes:
            aca_coverage_restricted.read: Return a Veteran's enrollment status in minimum essential coverage (MEC) as defined by the Affordable Care Act (ACA).  (restricted access).
            disability_rating.read: Retrieve Disability Rating
            disability_rating_summary.read: Retrieve Disability Rating Summary
            disability_rating_restricted.read: For approved federal consumers, view a Veteran's VA disability ratings and their effective dates using Social Security number and demographic information.
            enrolled_benefits.read: Retrieve Veteran Enrolled Benefits
            flashes.read: Retrieve Flashes
            permanent_and_total_disability.read: View a Veteran's P&T and IU disability statuses and effective dates.
            service_history.read: Retrieve Service History
            status_restricted.read: For approved federal consumers, confirm the Veteran status of an individual using Social Security number and demographic information.
            veteran_status.read: Retrieve Veteran Status