VA Lighthouse DirectDeposit API

openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver DirectDeposit 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: DirectDeposit
paths:
  /direct-deposit:
    get:
      tags:
      - DirectDeposit
      summary: Get direct deposit account and eligibility and control information.
      description: '  Get direct deposit account and eligibility and control information.

        '
      operationId: GET:/direct-deposit
      parameters:
      - name: icn
        in: query
        description: The authenticated Veteran or beneficiary Master Patient Index (MPI) ICN
        required: true
        schema:
          maxLength: 17
          minLength: 17
          pattern: ^\d{10}V\d{6}$
          type: string
          example: 1000000000V100000
      responses:
        '200':
          description: A Response which indicates a successful Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDepositResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                maxLength: 8000
                minLength: 1
                type: string
                example:
                  message: Invalid authentication credentials
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                maxLength: 8000
                minLength: 1
                type: string
                example:
                  message: You cannot consume this service
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserNotFound'
        '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/UnprocessableEntity'
        '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/InternalServerError'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGateway'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
      security:
      - OAuth: []
    put:
      tags:
      - DirectDeposit
      summary: Create or update direct deposit account information.
      description: '  Create or update direct deposit account information.

        '
      operationId: PUT:/direct-deposit
      parameters:
      - name: icn
        in: query
        description: The authenticated Veteran or beneficiary Master Patient Index (MPI) ICN
        required: true
        schema:
          maxLength: 17
          minLength: 17
          pattern: ^\d{10}V\d{6}$
          type: string
          example: 1000000000V100000
      requestBody:
        description: The Update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequest'
        required: true
      responses:
        '200':
          description: A Response which indicates successfully modified direct deposit information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDepositResponse'
        '201':
          description: A Response which indicates successfully created direct deposit entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDepositResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                maxLength: 8000
                minLength: 1
                type: string
                example:
                  message: Invalid authentication credentials
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                maxLength: 8000
                minLength: 1
                type: string
                example:
                  message: You cannot consume this service
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserNotFound'
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAcceptable'
        '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/UnprocessableEntity'
        '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/InternalServerError'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGateway'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
      security:
      - OAuth: []
components:
  schemas:
    EftInformation:
      type: object
      properties:
        accountType:
          maxLength: 8
          minLength: 7
          type: string
          description: The User Banking Account Type for Direct Deposit (Checking or Savings)
          example: Checking
          enum:
          - CHECKING
          - SAVINGS
        accountNumber:
          maxLength: 17
          minLength: 4
          type: string
          description: 'The User Account Number for Direct Deposit. Minimum 4 and maximum 17 alphanumeric characters are required for this value. '
          example: ABC1234567
        financialInstitutionRoutingNumber:
          type: string
          description: The Routing Number of the User's Bank
          example: '123456789'
        financialInstitutionName:
          type: string
          description: The Name of the User's Bank
          readOnly: true
          example: First National Bank USA
    UnprocessableEntity:
      type: object
      properties:
        type:
          maxLength: 8000
          minLength: 1
          type: string
          description: A URI reference that identifies the problem type.
          example: https://example.net/validation-error
        title:
          maxLength: 8000
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid field value
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          maxLength: 8000
          minLength: 1
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: This error occurred because of...
        instance:
          maxLength: 36
          minLength: 36
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
          example: e6d1119e-dc91-4b4d-b583-0f309de0807b
        errorCodes:
          type: array
          items:
            $ref: '#/components/schemas/ErrorCode'
      example:
        type: https://api.va.gov/services/direct-deposit-management/errors/unable-to-update
        title: Unable To Update
        status: 422
        detail: 'Unable to update: account fraud indicator = true.'
        instance: e48e3aeb-f312-11ec-88e8-f55e56a472a2
        errorCodes:
        - errorCode: payment.restriction.indicators.present
          detail: hasNoBdnPayments is false.
    ControlInformation:
      type: object
      properties:
        canUpdateDirectDeposit:
          type: boolean
          description: "All control information elements from the source system must be true (\"Y\") for update deposit to be set to true (\"Y\"), with the following exception:\none of the three payment type fields must also be true (\"Y\").\n  1. isEduClaimAvailable\n  2. hasCpClaim\n  3. hasCpAward\n\nMore than one of these payment types can be true, but at least one of them must be for update deposit to be set to true (\"Y\")."
          example: true
        isCorpAvailable:
          type: boolean
          description: If user record is found corpAvailInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'.
          example: true
        isEduClaimAvailable:
          type: boolean
          description: If user record is found eduClaimInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'.
          example: true
        hasCpClaim:
          type: boolean
          description: If user record is found cpClaimInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'.
          example: true
        hasCpAward:
          type: boolean
          description: If user record is found authAwdInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'.
          example: true
        isCorpRecFound:
          type: boolean
          description: If user record is found, corpRecFoundInd is set to 'Y', else it is set to 'N' for retrieve operation. In case of update, it is set to 'N' if user record is not found or else it is not populated.
          example: true
        hasNoBdnPayments:
          type: boolean
          description: This indicator only checks for Chapter 18 payments. If the PaymentInformationService has no paymentType for "Benefits for Children of Vietnam Veterans (inc. Spina Bifida)" this indicator is set to 'Y'.
          example: true
        hasIndentity:
          type: boolean
          description: If the user record is found and the last name and birth date matches with the queried parameters, indentityInd is set to 'Y' or else it is set to 'N'.
          example: true
        hasIndex:
          type: boolean
          description: If index record is found on BDN, indexInd is set based on who owns the Index (Award) record. If it is owned by VETSNET, it is set to 'V' and if it is owned by BDN it is set to 'B'. If index record is not found, it is set to 'X'.
          example: true
        isCompetent:
          type: boolean
          description: If person is incompetent, incompetentInd is set to 'Y' or else it is set to 'N'. If the user has an existing fiduciary or is incompetent (by rating or by court), no address information will be displayed or updatable.
          example: true
        hasMailingAddress:
          type: boolean
          description: If the Mailing address exists this field was set to 'Y', else it was set to 'N'.
          example: true
        hasNoFiduciaryAssigned:
          type: boolean
          description: If person record has a fiduciary, fiduciaryInd is set to 'Y' or else it is set to 'N'. If the user has an existing fiduciary, no address information will be displayed or updatable.
          example: true
        isNotDeceased:
          type: boolean
          description: If person record is found and has Date of Death, deathDtInd is set to 'Y' or else it is set to 'N'.
          example: true
        hasPaymentAddress:
          type: boolean
          description: If the Payment Address exists this field is set to 'Y', else it was set to 'N'.
          example: true
    UpdateRequest:
      type: object
      properties:
        paymentAccount:
          $ref: '#/components/schemas/EftInformation'
    DirectDepositResponse:
      required:
      - controlInformation
      - paymentAccount
      type: object
      properties:
        paymentAccount:
          $ref: '#/components/schemas/EftInformation'
        veteranStatus:
          type: string
          example: VETERAN
          enum:
          - VETERAN
          - DEPENDENT
          - NEITHER_VETERAN_NOR_DEPENDENT
          - COULD_NOT_DETERMINE_DUE_TO_EXCEPTION
        controlInformation:
          $ref: '#/components/schemas/ControlInformation'
    NotAcceptable:
      type: object
      properties:
        type:
          maxLength: 8000
          minLength: 1
          type: string
          description: A URI reference that identifies the problem type.
          example: https://example.net/validation-error
        title:
          maxLength: 8000
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid field value
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          maxLength: 8000
          minLength: 1
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: This error occurred because of...
        instance:
          maxLength: 36
          minLength: 36
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
          example: e6d1119e-dc91-4b4d-b583-0f309de0807b
      example:
        type: https://api.va.gov/direct-deposit-management/errors/not-acceptable
        title: Media type not acceptable
        status: 406
        detail: Could not find acceptable representation
        instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
    InternalServerError:
      type: object
      properties:
        type:
          maxLength: 8000
          minLength: 1
          type: string
          description: A URI reference that identifies the problem type.
          example: https://example.net/validation-error
        title:
          maxLength: 8000
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid field value
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          maxLength: 8000
          minLength: 1
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: This error occurred because of...
        instance:
          maxLength: 36
          minLength: 36
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
          example: e6d1119e-dc91-4b4d-b583-0f309de0807b
      example:
        type: https://api.va.gov/services/direct-deposit-management/errors/generic/internal-server-error
        title: Internal Server Error
        status: 500
        detail: Internal Server Error
        instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
    BadRequest:
      type: object
      properties:
        type:
          maxLength: 8000
          minLength: 1
          type: string
          description: A URI reference that identifies the problem type.
          example: https://example.net/validation-error
        title:
          maxLength: 8000
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid field value
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          maxLength: 8000
          minLength: 1
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: This error occurred because of...
        instance:
          maxLength: 36
          minLength: 36
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
          example: e6d1119e-dc91-4b4d-b583-0f309de0807b
        errorCodes:
          type: array
          items:
            $ref: '#/components/schemas/ErrorCode'
      example:
        type: https://api.va.gov/services/direct-deposit-management/errors/constraint-violation
        title: Bad Request
        status: 400
        detail: getDirectDeposit.icn must be between 17 and 17
        instance: e48e3aeb-f312-11ec-88e8-f55e56a472a2
        errorCodes: []
    ErrorCode:
      type: object
      properties:
        errorCode:
          type: string
          example: payment.restriction.indicators.present
        detail:
          type: string
          example: hasNoBdnPayments was false
    BadGateway:
      type: object
      properties:
        type:
          maxLength: 8000
          minLength: 1
          type: string
          description: A URI reference that identifies the problem type.
          example: https://example.net/validation-error
        title:
          maxLength: 8000
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid field value
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          maxLength: 8000
          minLength: 1
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: This error occurred because of...
        instance:
          maxLength: 36
          minLength: 36
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
          example: e6d1119e-dc91-4b4d-b583-0f309de0807b
        debuggingPayload:
          maxLength: 8000
          type: string
          description: Encrypted message to assist with debugging that occur while managing direct deposit information.
          example: VkEgUHJvZmlsZSBDb250YWN0IEluZm9ybWF0aW9uIF...
      example:
        type: https://api.va.gov/services/direct-deposit-management/errors/generic/bad-gateway
        title: Bad Gatewayr
        status: 502
        detail: Bad Gateway
        instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
        debuggingPayload: asdfghjklasdfghjkl
    UserNotFound:
      type: object
      properties:
        type:
          maxLength: 8000
          minLength: 1
          type: string
          description: A URI reference that identifies the problem type.
          example: https://example.net/validation-error
        title:
          maxLength: 8000
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid field value
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          maxLength: 8000
          minLength: 1
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: This error occurred because of...
        instance:
          maxLength: 36
          minLength: 36
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
          example: e6d1119e-dc91-4b4d-b583-0f309de0807b
      example:
        type: https://api.va.gov/services/direct-deposit-management/errors/generic/not-found
        title: Person for ICN not found
        status: 404
        detail: No data found for ICN
        instance: e6d1119e-dc91-4b4d-b583-0f309de0807b
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header