openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver Service History 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: Service History
paths:
  /service_history:
    get:
      tags:
      - Service History
      summary: Retrieve service history of authorized Veteran
      description: 'This endpoint provides a veteran''s detailed service history including all

        military service episodes with the first and last name of the Veteran, the branch of

        service, start and end dates, paygrade, discharge status, and separation reason.

        It also provides start and end dates and locations for each deployment within each

        episode of service.

        '
      operationId: GET:/service_history
      responses:
        '200':
          description: Service History retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceHistoryResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerSoapFaultApiError'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                type: string
                example:
                  message: Invalid authentication credentials
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: string
                example:
                  message: You cannot consume this service
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingIcn'
        '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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerApiError'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InaccessibleServiceDefintionErrorApiError'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendServiceApiError'
      deprecated: true
      security:
      - bearer_token: []
    post:
      tags:
      - Service History
      summary: Retrieve the service history of a Veteran using demographics to search for the Veteran.
      description: 'This endpoint provides a Veteran''s detailed service history including all military

        service episodes with the first and last name of the Veteran, the branch of service,

        start and end dates, paygrade, discharge status, and separation reason. It also

        provides start and end dates and locations for each deployment within each episode

        of service.


        Required information:

        * First Name

        * Last Name

        * Date of Birth

        * Street Address

        * City

        * State

        * Country

        * Zipcode


        Optional information:

        * Middle Name

        * Gender


        Tips for finding a match:

        * First and Last Name, Address and DOB are often essential to uniquely identifying a

        Veteran.

        * Home Address is recommended, but it may be beneficial to retry the search with

        additional addresses if they are available and the first attempt is not confirmed.

        * To find a match, it can help to retry with different demographic information,

        such as alternate last names or addresses.

        * It can also help to remove special characters, hyphens, apostrophes, or spaces

        in a name prior to matching.


        NOTE: In the Sandbox only DOB and ZIP are required to identify the test user.

        '
      operationId: POST:/service_history
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VeteranAttributes'
            example:
              first_name: Alfredo
              last_name: Armstrong
              birth_date: '1993-06-08'
              middle_name: M
              gender: M
              street_address_line1: 17020 Tortoise St
              street_address_line2: ''
              street_address_line3: ''
              city: Round Rock
              zipcode: '78664'
              state: TX
              country: USA
        required: true
      responses:
        '200':
          description: Service History retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceHistoryResponse'
              example:
                data:
                - id: 2305d238-dee4-5c98-858a-f912e3c059f8
                  type: service-history-episodes
                  attributes:
                    first_name: Jessie
                    last_name: Price
                    branch_of_service: Air Force
                    service_type: Active Duty
                    start_date: '1991-05-29'
                    end_date: '2011-06-30'
                    pay_grade: E07
                    component_of_service: Air Force
                    discharge_status: honorable
                    separation_reason: SUFFICIENT SERVICE FOR RETIREMENT
                    service_episode_combat_pay: false
                    deployments:
                    - start_date: '1948-10-10'
                      end_date: '1949-10-09'
                      location: KOR
                militarySummary:
                  first_name: Jessie
                  last_name: Price
                  active_duty_status: N
                  combat_service_indicator: true
                  duty_status_code: '02'
                  duty_status_text: 'Not on active duty: '
                  total_number_of_regular_active_duty_days: 444
                  total_number_of_reserve_active_duty_days: 90
                  total_number_of_guard_active_duty_days: 60
                  total_number_of_training_days: 10
        '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/service_history
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenServerError'
              example:
                status: '403'
                error: Token not granted requested scope.
                path: /veteran_verification/v2/service_history
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingIcn'
              example:
                title: Veteran not identifiable.
                detail: No data found for ID or demographics.
                code: '404'
                status: '404'
        '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
        '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/InaccessibleServiceDefintionErrorApiError'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendServiceApiError_2'
        '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:
        - service_history.read
      - productionOauth2:
        - service_history.read
components:
  schemas:
    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'
    ApiErrorDetails_2:
      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
    Deployment:
      required:
      - end_date
      - location
      - start_date
      type: object
      properties:
        start_date:
          type: string
          description: beginning of deployment (YYYY-mm-dd)
          format: date
          nullable: true
          example: '1948-10-10'
        end_date:
          type: string
          description: end of deployment (YYYY-mm-dd)
          format: date
          nullable: true
          example: '1949-10-09'
        location:
          type: string
          description: Three letter ISO country code of deployment location
          nullable: true
          example: KOR
      description: Deployment during a service history episode
      deprecated: true
    ServerSoapFaultApiError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example:
        errors:
        - title: Bad Request
          detail: Bad Request
          code: '400'
          status: '400'
    MissingIcn:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example:
        errors:
        - title: Veteran not identifiable.
          detail: No data found for ID or demographics.
          code: '404'
          status: '404'
    AuthorizationError:
      type: object
      properties:
        status:
          type: string
          example: '401'
        error:
          type: string
          example: Invalid token.
        path:
          type: string
          example: /veteran_verification/v2/{endpoint}
    BackendServiceApiError_2:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails_2'
      example:
        errors:
        - title: Service Unavailable
          detail: Backend Service Unavailable.
          code: '503'
          status: '503'
    ServiceHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ServiceHistoryEpisode'
        military_summary:
          $ref: '#/components/schemas/ServiceHistoryMilitarySummary'
      description: verification service_history endpoint
      deprecated: true
    BadRequest:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails_2'
      example:
        errors:
        - title: Bad Request
          detail: Bad Request
          code: '400'
          status: '400'
    ServiceHistoryEpisode:
      required:
      - attributes
      - id
      - type
      type: object
      properties:
        id:
          type: string
          description: Service History Episode ID
          example: 12312AASDf
        type:
          type: string
          example: service-history-episodes
        attributes:
          $ref: '#/components/schemas/ServiceHistoryAttributes'
      description: Service history for authorized Veteran
    InaccessibleServiceDefintionErrorApiError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
      example:
        errors:
        - title: Bad Gateway
          detail: Upstream Request Error.
          code: '502'
          status: '502'
    BackendServiceApiError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorDetails'
    ServiceHistoryAttributes:
      required:
      - branch_of_service
      - component_of_service
      - discharge_status
      - end_date
      - first_name
      - last_name
      - pay_grade
      - separation_reason
      - service_episode_combat_pay
      - service_type
      - start_date
      type: object
      properties:
        deployments:
          type: array
          items:
            $ref: '#/components/schemas/Deployment'
        first_name:
          type: string
          description: Veteran first name
          nullable: true
          example: Abraham
        last_name:
          type: string
          description: Veteran last name
          nullable: true
          example: Lincoln
        branch_of_service:
          type: string
          description: The branch of service such as National Guard, Coast Guard, Reserves, Army, Navy, Air Force, Marines
          example: Army
        component_of_service:
          type: string
          description: A component of service such as Reserves, National Guard
          example: Reserves
        service_type:
          type: string
          description: If veteran is on active duty or not
          example: Active Duty
        start_date:
          type: string
          description: start date of a service history episode (YYYY-mm-dd)
          format: date
          nullable: true
          example: '1948-04-08'
        end_date:
          type: string
          description: end date of a service history episode (YYYY-mm-dd)
          format: date
          nullable: true
          example: '1950-05-10'
        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.\n\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."
          example: W01
        discharge_status:
          type: string
          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 the Department of Defense classifies as honorable.'
          nullable: true
          example: 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
        separation_reason:
          type: string
          description: Additional text description for separation reason beyond discharge_status value
          example: SUFFICIENT SERVICE FOR RETIREMENT
        service_episode_combat_pay:
          type: boolean
          description: If there is any combat pay in the VA Profile service's CombatPayBio with the same serviceEpisodeIdentifier, then indicate Y
          nullable: true
          example: false
      description: Attributes for service_history endpoint
    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}
    ApiErrorDetails:
      type: object
      properties:
        title:
          type: string
          example: Error title
        detail:
          type: string
          example: Detailed error message
        code:
          type: string
          example: '503'
        status:
          type: string
          example: '503'
    ServiceHistoryMilitarySummary:
      required:
      - active_duty_status
      - combat_service_indicator
      - duty_status_code
      - duty_status_text
      - first_name
      - last_name
      - total_number_of_guard_active_duty_days
      - total_number_of_regular_active_duty_days
      - total_number_of_reserve_active_duty_days
      - total_number_of_training_days
      type: object
      properties:
        first_name:
          type: string
          description: Veteran first name
          nullable: true
          example: Abraham
        last_name:
          type: string
          description: Veteran last name
          nullable: true
          example: Lincoln
        active_duty_status:
          type: string
          description: Indicates the Veteran's current active duty status
          nullable: true
          example: 'false'
        combat_service_indicator:
          type: boolean
          description: Indicates whether the service member has ever been a part of active combat duty
          nullable: true
          example: false
        duty_status_code:
          type: string
          description: Describes the individual's status
          nullable: true
          example: A
        duty_status_text:
          type: string
          description: Relates to an individual's affiliation with the US Military.
          nullable: true
          example: Active Component = full time active duty, not in the Guard or Reserve
        total_number_of_regular_active_duty_days:
          type: integer
          description: Total number of regular active duty days
          format: int32
          nullable: true
          example: 100
        total_number_of_reserve_active_duty_days:
          type: integer
          description: Total number of reserve active duty days
          format: int32
          nullable: true
          example: 100
        total_number_of_guard_active_duty_days:
          type: integer
          description: Total number of guard active duty days
          format: int32
          nullable: true
          example: 100
        total_number_of_training_days:
          type: integer
          description: Total number of training days
          format: int32
          nullable: true
          example: 100
      description: Military Summary for Veteran
    VeteranAttributes:
      required:
      - birth_date
      - city
      - country
      - first_name
      - last_name
      - street_address_line1
      - zipcode
      type: object
      properties:
        gender:
          type: string
          description: For gender, only 'm' or 'f' will help the search currently.
        first_name:
          type: string
          description: '* Some names may require special handling if a Veteran is not found.

            * Try removing special characters, such as hyphens, apostrophes, and spaces prior to

            matching. For example, a submission of ''De''Anna'' can be matched as ''deanna''.

            * In addition, depending on the handling logic of the front end application updating the VA

            record, an inquiry with first name of ''Ann-Marie'' would be standardized to ''AnnMarie'' but

            could be matched against ''AnnMarie'' or ''Ann Marie'' or ''Ann'' or ''Marie''.

            * Therefore, if a Veteran with a hyphenated name is not found, it may be useful to retry the

            hyphenated name without the hyphen and together, then separated, then each individual part

            of the name as in the example with ''Ann-Marie''.

            * Capitalization does not impede match strength.

            '
        middle_name:
          type: string
        last_name:
          type: string
          description: '* Some names may require special handling if a Veteran is not found.

            * Try removing special characters, such as hyphens, apostrophes, and spaces prior to

            matching. For example, a submission of ''O''leary'' can be matched as ''oleary''.

            * In addition, depending on the handling logic of the front end application updating the

            VA record, an inquiry with last name of ''Smith-Jones'' would be standardized to

            ''SmithJones'' but could be matched against ''SmithJones'' or ''Smith Jones'' or ''Smith'' or

            ''Jones''.

            * Therefore, if a Veteran with a hyphenated name is not found, it may be useful to retry

            the hyphenated name without the hyphen and together, then separated, then each

            individual part of the name as in the example with ''Smith-Jones''.

            * Capitalization does not impede match strength.'
        zipcode:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        birth_date:
          type: string
          format: date
        street_address_line1:
          type: string
          description: 'Address line 1 can accept one or more letters (uppercase or

            lowercase), digits, spaces, commas, hashes(#), apostrophes(''),

            periods(.), back slashes(\\), forward slashes(/), or hyphens(-).

            '
        street_address_line2:
          type: string
          description: 'Address line 2 can accept one or more letters (uppercase or

            lowercase), digits, spaces, commas, hashes(#), apostrophes(''),

            periods(.), back slashes(\\), forward slashes(/), or hyphens(-).

            '
        street_address_line3:
          type: string
          description: 'Address line 3 can accept one or more letters (uppercase or

            lowercase), digits, spaces, commas, hashes(#), apostrophes(''),

            periods(.), back slashes(\\), forward slashes(/), or hyphens(-).

            '
        home_phone_number:
          type: string
        birth_place_city:
          type: string
        birth_place_state:
          type: string
        birth_place_country:
          type: string
        mothers_maiden_name:
          type: string
      description: '* Use the current residence address of the Veteran.

        * Some unhoused Veterans can use a local USPS, support organization, or other location

        such as ''the corner of RTE512 and U.S.1''.

        * Aim to match the input against the Veteran''s demographic information in their VA.gov

        profile.

        * Data in the request and the VA record is standardized using the same algorithm prior

        to matching. If the data is close, and enough fields are provided, it will find the

        Veteran most of the time; however, some records will have data that is not in sync and

        may require trying the request again with different addresses, names, or formats.

        * Alternately, the Veteran may need to update their information with the VA if they

        are not found.

        '
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header