VA Lighthouse Direct Deposit API

openapi: 3.2.0
info:
  title: Management Direct Deposit API
  description: 'Internal, front-end VA applications can use

    this API to let eligible Veterans or their

    beneficiaries manage direct deposit information

    for VA disability, pension, and education benefit payments.'
  contact:
    name: VA.gov
  version: 0.0.1
servers:
- url: https://sandbox-api.va.gov/services/direct-deposit-management/{version}
  description: Sandbox
  variables:
    version:
      default: v1
- url: https://api.va.gov/services/direct-deposit-management/{version}
  description: Production
  variables:
    version:
      default: v1
tags:
- name: Direct Deposit
paths:
  /direct-deposit:
    get:
      tags:
      - Direct Deposit
      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:
      - Direct Deposit
      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:
    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
    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.
    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
    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: []
    UpdateRequest:
      type: object
      properties:
        paymentAccount:
          $ref: '#/components/schemas/EftInformation'
    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
    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'
    ErrorCode:
      type: object
      properties:
        errorCode:
          type: string
          example: payment.restriction.indicators.present
        detail:
          type: string
          example: hasNoBdnPayments was false
    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
  securitySchemes:
    OAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.va.gov/oauth2/direct-deposit-management/system/v1/token
          scopes:
            direct-deposit-management.read: The veteran's access to direct deposit management that provides viewing of current EFT settings.
            direct-deposit-management.write: The veteran's access to direct deposit management that provides updating of current EFT settings.