openapi: 3.0.1

info:
#---------------------------------------------------
# Information to contact the Service provider
#-------------------------------------------------
  title: Account Validation v2 API
  description: Use the Account Validation API to verify an account and its owner with confidence. This API evaluates account owner data through an inquiry request and response process.
  contact:
    name: "KeyBank Developer Support"
    email: 'developers@keybank.com'
  version: 2.0.4
  
servers:
#---------------------------------------------------
# List of environments for the API
#---------------------------------------------------
 - url: https://partner-api-qv.key.com
 - url: https://partner-api.key.com
 
paths:
#---------------------------------------------------
# List of Environments for the API 
#---------------------------------------------------
  /accounts/validations/v2/healthCheck:
    get:
        tags: # Apigee Product: Logical group based on functionality
          - HealthCheck 
        summary: Health check
        description: Verify you can connect to the API service. A bearer token is required.
        operationId: healthCheck
        security:
          - bearerAuth: []
        responses:
          '200':
            description: Successful response
            headers:
              X-CorrelationId:
                schema:
                  type: string
                description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/healthResponse'
                example:
                 Status: Ok
                 Source: Roundtrip
                 Timestamp: '2022-09-15T04:49:03'
                 ClientIp: 156.77.111.28
                 X-Forwarded-For: '[156.77.111.28]'
  /accounts/validations/v2/verifyAccount:
    post:
      summary: Verify an account
      description: Verify that an account owner's name, address, and other identifying elements match the account information in the National Shared Database Resource and that they are authorized to transact on the account. The National Shared Database Resource is the financial industry's leading source of up-to-date, collaborative financial data.
      operationId: verifyAccount
      security:
          - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/accountValidation_POST_bodyParameters'
            example:
              accountValidationV2Request:
                AOARequest:
                  Inquiry:
                    serviceType: Owner
                    secondaryId: KeyCli03
                    additionalId: AddCli04
                    routingNumber: '122199983'
                    accountNumber: '89455'
                    AcctOwner:
                      firstName: Paul
                      lastName: wilson
                      middleName: Dan
                      namePrefix: Mr
                      nameSuffix: Lal
                      businessName: ''
                      addressLine1: 206 GOODWIN ST
                      addressLine2: Land
                      city: MERRIT
                      state: MI
                      zipCode: '49667'
                      homePhone: '3077553623'
                      workPhone: '3077555330'
                      ssn: '666082367'
                      dob: '19730801'
                      idType: ''
                      idNo: '590909812'
                      idState: AL
                    Client:
                      clientDate: '2022-12-03'
                      clientTime: '14:00:00'
                      userDefined: ''
        required: true
      responses:
        '200':
          description: Successful response
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountValidation_POST_response'
              example:
                accountValidationV2Response:
                  AOAResponse:
                    Result:
                      errorCode: '000'
                      systemRecordId: '2360130828140884'
                      primaryId: TROM122101
                      secondaryId: KeyCli03
                      routingNumber: '122199983'
                      accountNumber: '89455'
                      feeAttrib: HH
                      AcctOwner:
                        conditionCode: '000'
                        nameMatch: 'Y'
                        firstNameMatch: 'Y'
                        lastNameMatch: 'Y'
                        middleNameMatch: 'N'
                        namePrefixMatch: U
                        nameSuffixMatch: U
                        addressMatch: 'Y'
                        cityMatch: 'Y'
                        stateMatch: 'Y'
                        zipCodeMatch: 'Y'
                        ssnMatch: 'Y'
                        dobMatch: 'Y'
                        idNoMatch: 'Y'
                        idStateMatch: 'Y'
                        overallMatchScore: '85'
                      AcctStatus:
                        primaryStatusCode: '699'
                        primMessage: Open Valid
                      Client:
                        clientDate: '2022-12-31'
                        clientTime: '14:00:80'
                        userDefined: ''
                  errorResponse:
                    businessFault:
                      errorDescription: "Description if an error is found."

        '400':
          description: Missing mandatory information
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                X-CorrelationId: "abcgd133"
                TransactionTime: "2021-06-11T16:31:34.041Z"
                Api-Url: "/accounts/validations/v2/verifyAccount"
                ServiceError: 
                  AOAResponse: 
                    Result: 
                      errorCode: "104"
        '401':
          description:  Unauthorized request
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:               
                ErrorMessage: "Received request is unauthorized, please provide valid credentials"
                X-CorrelationId: "abcgd133"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                TransactionTime: "2021-06-11T16:31:34.041Z"    
                Api-Url: "/accounts/validations/v2/verifyAccount"
        '403':
          description: Forbidden request access
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Access Denied for client ip"
                X-CorrelationId: "abcgd133"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"         
                TransactionTime: "2021-06-11T16:31:34.041Z"  
                Api-Url: "/accounts/validations/v2/verifyAccount"
        '404':
          description: Resource not found
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested resource is not found, please verify the resource then resubmit the request"
                X-CorrelationId: "abcgd133"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"         
                TransactionTime: "2021-06-11T16:31:34.041Z"
                Api-Url: "/accounts/validations/v2/verifyAccount"
        '415':
          description: Invalid request type
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested media type is not allowed, please verify the media type and resubmit the request"
                X-CorrelationId: "abcgd133"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                TransactionTime: "2021-06-11T16:31:34.041Z"
                Api-Url: "/accounts/validations/v2/verifyAccount"
        '429':
          description: Request timeout
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Number requests threshold reached, please resubmit the request after sometime"
                X-CorrelationId: "abcgd133"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                TransactionTime: "2021-06-11T16:31:34.041Z"
                Api-Url: "/accounts/validations/v2/verifyAccount"
        '500':
          description: Unknown error
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Runtime error occurred in the service, please check with application support team before resubmitting the request"
                X-CorrelationId: "abcgd133"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"         
                TransactionTime: "2021-06-11T16:31:34.041Z"
                Api-Url: "/accounts/validations/v2/verifyAccount"
        '502':
          description: Bad gateway
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service"
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                TransactionTime: "2021-06-11T16:31:34.041Z" 
                Api-Url: "/accounts/validations/v2/verifyAccount"
                ServiceError: 
                  ConnectError: "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"               
        '503':
          description: Unavailable service
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service"
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                TransactionTime: "2021-06-11T16:31:34.041Z"
                Api-Url: "/accounts/validations/v2/verifyAccount"
                ServiceError: 
                  ConnectError: "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."                                       
        '504':
          description: Unable to process request
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service"
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"       
                TransactionTime: "2021-06-11T16:31:34.041Z"  
                Api-Url: "/accounts/validations/v2/verifyAccount"
                ServiceError: 
                  ConnectError: "Request could not be processed on time (GatewayTimeout), please wait a moment and resubmit the request"
      
components:
#---------------------------------------------------
# Data Definitions
#---------------------------------------------------
  securitySchemes:
    bearerAuth:   # security scheme for authentication based on F5 APM token
      type: http
      scheme: bearer
  schemas:
    healthResponse:
      type: object
      title: healthResponse
      properties:
        Status:
          type: string
          description: Status of the health check response.
        Source:
          type: string
          description: Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
        Timestamp:
          type: string
          description: Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
        ClientIp:
          type: string
          description: Client IP address the gateway receives from the request.
        X-Forwarded-For:
          type: string
          description: Sequence of IP addresses for systems between the client and the gateway.
    exception:
      type: object
      title: exceptionSchema
      properties:
        ErrorMessage: 
          type: string
          description: A human-readable message that describes the type or source of the error.
          example: "Requested resource is not found, please verify the resource then resubmit the request."
        TransactionId:
          type: string
          description: A unique transaction ID returned with the response, useful for traceability.
          example: "rrt-7354978519411102852-c-gce-30597-7590748-1"
        X-CorrelationId:
          type: string
          description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. 
          example: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
        TransactionTime: 
          type: string
          description: Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
        Api-Url:
          type: string
          description: The API URL path of the call that generated the response.
        ServiceError:
          type: object
          title: ServiceError
          description: Detailed service-level error details, if available.
          oneOf:
          - $ref: '#/components/schemas/serviceErrorData'
          - $ref: '#/components/schemas/connectError'
    connectError:
      type: object
      properties:
        ConnectError:
          type: string
          description: API connectivity error information, if available.
    serviceErrorData:
      type: object
      properties:
        AOAResponse:
          type: object
          properties:
            Result:
              type: object
              properties:
                errorCode:
                  type: string
                  maxLength: 3
                  description: Three-digit error code. Returns a "000" when no errors are present.
    accountValidationV2Request:
      type: object
      properties:
        AOARequest:
          $ref: '#/components/schemas/AOARequest'
    Inquiry:
      type: object
      required:
        - accountNumber
        - routingNumber
        - serviceType
        - secondaryId
      description: Contains the account inquiry request fields
      properties:
        serviceType:
          type: string
          enum:
          - Owner
          description: Represents the type of request made to the API. This value is case-sensitive and must be set to "Owner".
        secondaryId:
          type: string
          minLength: 1
          maxLength: 10
          pattern: "^[a-zA-Z0-9]*$"
          description: Secondary client ID provided by KeyBank. No special characters are allowed. This value is different from your client credentials.
        additionalId:
          type: string
          maxLength: 10
          description: This ID is rarely used. If it is required, the value is provided during onboarding.
        routingNumber:
          type: string
          maxLength: 9
          pattern: "^[0-9]*$"
          description: Nine-digit routing number for the account, including leading zeroes.
        accountNumber:
          type: string
          minLength: 1
          maxLength: 17
          description: Full bank account number, without separators or leading zeroes. The length and format depends on the bank. This field cannot exceed 17 characters.
        AcctOwner:
          $ref: '#/components/schemas/AcctOwner'
        Client:
          $ref: '#/components/schemas/Client'
    AOARequest:
      type: object
      description: Contains the request payload for the account validation endpoint.
      properties:
        Inquiry:
          $ref: '#/components/schemas/Inquiry'
    AOAResponse:
      type: object
      description: Contains the response payload for the account validation endpoint.
      properties:
        Result:
          $ref: '#/components/schemas/Result'
    errorResponse:
      type: object
      description: Error response with related business or system fault related information. 
      properties:
        businessFault:
          $ref: '#/components/schemas/businessFault'
        systemFault:
          $ref: '#/components/schemas/systemFault'
    AcctOwner_1:
      type: object
      properties:
        conditionCode:
          type: string
          maxLength: 3
          description: Three-digit system response code that reflects the state of the account owner provided.
        nameMatch:
          type: string
          maxLength: 1
          description: 'First name, middle name, and last name match status. Valid values: Y, N, U'
        firstNameMatch:
          type: string
          maxLength: 1
          description: 'First name match status. Valid values: Y, N, U'
        lastNameMatch:
          type: string
          maxLength: 1
          description: 'Last name match status. Valid values: Y, N, U'
        middleNameMatch:
          type: string
          maxLength: 1
          description: 'Middle name or initial match status. Valid values: Y, N, U'
        namePrefixMatch:
          type: string
          maxLength: 1
          description: Name prefix match status. U will always be returned for a name prefix if included in the request.
        nameSuffixMatch:
          type: string
          maxLength: 1
          description: Name suffix match status. U will always be returned for a name suffix if included in the request.
        businessNameMatch:
          type: string
          maxLength: 1
          description: 'Business name match status. Valid values: Y, N, U'
        addressMatch:
          type: string
          maxLength: 1
          description: 'Combined address line one and two match status. Valid values: Y, N, U'
        cityMatch:
          type: string
          maxLength: 1
          description: 'City match status. Valid values: Y, N, U'
        stateMatch:
          type: string
          maxLength: 1
          description: 'State match status. Valid values: Y, N, U'
        zipCodeMatch:
          type: string
          maxLength: 1
          description: 'ZIP code match status. Valid values: Y, N, U'
        homePhoneMatch:
          type: string
          maxLength: 1
          description: 'Home phone number match status. Valid values: Y, N, U'
        workPhoneMatch:
          type: string
          maxLength: 1
          description: 'Work phone number match status. Valid values: Y, N, U'
        ssnMatch:
          type: string
          maxLength: 1
          description: "SSN/TIN or last four digits of SSN match status. If you are a merchant provider, the value returned will always be 'U'. Valid values: Y, N, U"
        dobMatch:
          type: string
          maxLength: 1
          description: 'Date of birth match status. Valid values: Y, N, U'
        idTypeMatch:
          type: string
          maxLength: 1
          description: 'ID type match status. Valid values: Y, N, U'
        idNoMatch:
          type: string
          maxLength: 1
          description: 'ID number match status. Valid values: Y, N, U'
        idStateMatch:
          type: string
          maxLength: 1
          description: 'State or place of issuance match status. Valid values: Y, N, U'
        overallMatchScore:
          type: string
          minLength: 1
          maxLength: 3
          description: 'The measure of how closely the inquiry request attributes match the actual account ownership data. This number is calculated based on the analysis of all information sent. Valid values: 0-100'
    Result:
      type: object
      description: Contains the response results for the account owner inquiry
      properties:
        errorCode:
          type: string
          maxLength: 3
          description: Three-digit error code. Returns a "000" when no errors are present.
        systemRecordId:
          type: string
          minLength: 1
          maxLength: 16 
          description: Unique, system-generated transaction ID.
        primaryId:
          type: string
          minLength: 1
          maxLength: 10
          description: Primary client ID returned via a KeyBank lookup. This is a KeyBank ID.
        secondaryId:
          type: string
          minLength: 1
          maxLength: 10
          description: Secondary client ID provided in the original request.
        additionalId:
          type: string
          minLength: 1
          maxLength: 10
          description: Additional client ID, if provided in the original request. This is rarely used. 
        routingNumber:
          type: string
          maxLength: 9
          description: Nine-digit routing number for the account provided in the original request.
        accountNumber:
          type: string
          minLength: 1
          maxLength: 17
          description: Full bank account number provided in the original request.
        feeAttrib:
          type: string
          maxLength: 2
          description: Two-character code that represents how a transaction took place. Currently, the only value reported is "HH", which represents an ACH transaction.
        AcctOwner:
          $ref: '#/components/schemas/AcctOwner_1'
        AcctStatus:
          $ref: '#/components/schemas/AcctStatus'
        Client:
          $ref: '#/components/schemas/Client_1'
    systemFault:
      type: object
      properties:
        errorDescription:
          type: string
          description: Descriptive error message that identifies if it is a system issue or business fault.
    AcctStatus:
      type: object
      description: Contains the account status details.
      properties:
        primaryStatusCode:
          type: string
          description: Primary three-digit account status code. This is an informational response code that represents the status of an account.
        primMessage:
          type: string
          description: Message associated with the primary status code.
    accountValidation_POST_bodyParameters:
      required:
      - accountValidationV2Request
      type: object
      properties:
        accountValidationV2Request:
          $ref: '#/components/schemas/accountValidationV2Request'
    businessFault:
      type: object
      properties:
        errorDescription:
          type: string
          description: Contains business system messages generated if there is an issue.
    Client:
      type: object
      description: Contains the client-provided date, time, and description of the inquiry request.
      properties:
        clientDate:
          type: string
          maxLength: 10
          format: date
          description: 'Client-provided date the inquiry request was made. Format: YYYY-MM-DD'
        clientTime:
          type: string
          maxLength: 8
          pattern: "^$|[12][890][0-9][0-9]-[01][0-9]-[0-3][0-9]"
          format: time
          description: 'Client-provided time the inquiry request was made. Format: HH:MM:SS'
        userDefined:
          type: string
          maxLength: 255
          description: Client-provided descriptive text about the inquiry request. This field cannot exceed 255 characters.
    accountValidation_POST_response:
      required:
      - accountValidationV2Response
      type: object
      properties:
        accountValidationV2Response:
          $ref: '#/components/schemas/accountValidationV2Response'
    accountValidationV2Response:
      required:
      - errorResponse
      type: object
      properties:
        AOAResponse:
          $ref: '#/components/schemas/AOAResponse'
        errorResponse:
          $ref: '#/components/schemas/errorResponse'
    Client_1:
      type: object
      description: Contains the client-provided date, time, and description of the inquiry request.
      properties:
        clientDate:
          type: string
          maxLength: 10
          format: date
          description: 'Client-provided date the inquiry request was made. Format: YYYY-MM-DD'
        clientTime:
          type: string
          maxLength: 8
          format: time
          description: 'Client-provided time the inquiry request was made. Format: HH:MM:SS'
        userDefined:
          type: string
          maxLength: 255
          description: Client-provided descriptive text about the inquiry request. This field cannot exceed 255 characters.
    AcctOwner:
      type: object
      description: Contains details about the account owner to for a more advanced inquiry.
      properties:
        firstName:
          type: string
          minLength: 1
          maxLength: 40
          description: First name of the account owner. Required with lastName for a personal inquiry.
        lastName:
          type: string
          minLength: 1
          maxLength: 40
          description: Last name of the account owner. Required with firstName for a personal inquiry.
        middleName:
          type: string
          maxLength: 40
          pattern: "^[a-zA-Z]*$"
          description: Middle initial or name of the account owner. If the middle initial is provided do not include a period. 
        namePrefix:
          type: string
          minLength: 1
          maxLength: 4
          description: 'Optional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.' 
        nameSuffix:
          type: string
          minLength: 1
          maxLength: 4
          description: 'Optional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD'
        businessName:
          type: string
          minLength: 1
          maxLength: 87
          description: "Business name or the individual's full name (first and last name) that owns the account. This is a required field for a business inquiry."
        addressLine1:
          type: string
          minLength: 1
          maxLength: 40
          description: First line of the address on the account. This field cannot exceed 40 characters.
        addressLine2:
          type: string
          minLength: 1
          maxLength: 40
          description: Second line of the address on the account. For international addresses, combine province, country, and postal code in this second address line.
        city:
          type: string
          minLength: 1
          maxLength: 25
          description: The city of the account owner if in the US. Keep this field blank for international addresses. 
        state:
          type: string
          maxLength: 2
          description: The two-character state abbreviation if in the US. Keep this field blank for international addresses.
        zipCode:
          type: string
          minLength: 5
          maxLength: 10
          pattern: "^$|^[0-9]{5}(-?[0-9]{4})?$"
          description: "ZIP code of the account if in the US. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space. Possible examples: 52255, 522551313, or 52255-1313. Keep this field blank for international addresses."
        homePhone:
          type: string
          maxLength: 10
          pattern: "^$|^\\d{10}$"
          description: 10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
        workPhone:
          type: string
          maxLength: 10
          pattern: "^$|^\\d{10}$"
          description: 10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
        ssn:
          type: string
          description: Full social security/tax ID number or the last four digits of the social security number of the account owner.
          minLength: 4
          maxLength: 9 
        dob:
          type: string
          maxLength: 8
          pattern: "^$|[12][890][0-9][0-9][01][0-9][0-3][0-9]"
          description: 'Date of birth for the individual on the account. Format: YYYYMMDD'
        idType:
          type: string
          enum: [
            "0","1","2","3","4","5","6","7","8","9","A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z",""]
          maxLength: 1
          description: "One-character code that represents the type of identification used to verify the account owner. Valid values: 0-9, A-Z"
        idNo:
          type: string
          minLength: 1
          maxLength: 28
          description: "ID number for the account owner's form of identification. This field cannot exceed 28 characters."
        idState:
          type: string
          minLength: 2
          maxLength: 6
          pattern: "^$|^([a-zA-Z0-9]{2}|[a-zA-Z0-9]{6})$"
          description: "Two-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field must be between 2-6 characters in length."