openapi: 3.2.0
info:
  title: Initiate Account Validation Inquiry API
  description: With the Account Validation API you can validate payee details to reduce payment processing errors.
  contact:
    name: Commercial Sales team
    url: https://www.citizensbank.com/corporate-finance/overview.aspx?cmclmkt#next-step
  version: 1.0.13
  x-ibm-name: account-validation
  x-pathalias: accountvalidation-v1
  x-ibm-summary: ''
servers:
- url: https://apis.citizensbank.com/v1/account-validation
security:
- client-id: []
tags:
- name: Initiate Account Validation Inquiry
paths:
  /initiation:
    post:
      tags:
      - Initiate Account Validation Inquiry
      summary: Initiate account validation request with account and bank details
      description: This endpoint allows users to initiate an account inquiry by providing beneficiary name, account details and bank details.
      operationId: getAccountInquiry
      parameters:
      - name: x-fapi-trace-id
        in: header
        description: Unique request id for each request to make it traceable if needed.
        required: true
        style: simple
        schema:
          maxLength: 36
          type: string
      - name: x-fapi-channel-id
        in: header
        description: Identifier used to distinguish between different communication channels or data streams within a client system.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 20
          type: string
      - name: Authorization
        in: header
        description: OAuth 2.0 Authorization Bearer Token
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/AuthorizationHeader'
        example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkhMMkQtYVdmaUxVS1BpUHQ5b2lweWNiYXo4WV9SUzI1NiIsInBpLmF0bSI6InphYXciLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6ImlyOnJlYWQiLCJjaWQiOiIyNzFmYTdkZDI3MDExMTA5Mzc4ZWE5MTU1YzA2ZTcxMSIsImlzcyI6Imh0dHBzOi8vcGYtZmFtLWRldi5pbnRlcm5hbC5jaXRpemVuc2JhbmsuY29tIiwiYXVkIjoiaW5mb3JtYXRpb25fcmVwb3J0aW5nIiwianRpIjoiOHpRMUJVSnlTT0xkWHZmQXJtb1pQSXVpZXBmdkF5WnJwdnc4NVlGY2dDVk1FbyIsInN1YmplY3QiOiJBQ01FLUFQSV9VQVRBTExfTU1HUFMiLCJjbmYiOnsieDV0IjoiOTlmN2Q3ZDQzOGMxZjViMWFiNzc4MDA1YmU3OGNkODY0NDU1YmYyYSJ9LCJleHAiOjE3NTczNTE2NzR9.c6y4ZcVxP8c8dZK8IwMPhVnKkrk7Kyf4h4cUo8GOPxrrR_AYq-59tcO9lzTkr4Kfa5-7q_HbxCV14wUnwz_N1JuehZ5N3wyuJ3wjc2jEfOnto8YwSEhY4qWbFm1TTdU8jqRZMp2KpvBpwa5BKNfjo3t0xAMqQ2til5-1JQHEZyint56OglKq13OzG265jW_RKOhmmmGuTlqDjiC4Mz2AQU-1VZY2i6LZTqKKTr7dvQVy5TKm9-akEkie8s-cXymaQ9Km54-PARdH8orezez8NuJc4LN550m46ulWJ2mNMDs4D9NnKQMr-stla2mQtovU__vNg3WDCvQ8Nrw1db5icA
      requestBody:
        description: The request body must include account identifiers and bank identifiers to initiate account inquiry process.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountStatusInquiryRequest'
        required: true
      responses:
        '200':
          description: Successfully initiated account inquiry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200'
        '400':
          description: Bad request. This may occur if the input data is invalid or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. The user does not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '500':
          description: Internal Server Error. An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
components:
  schemas:
    AccountInquiryResponse_data:
      type: object
      properties:
        referenceIdentifier:
          $ref: '#/components/schemas/AccountInquiryResponse_data_referenceIdentifier'
        inquiryStatus:
          $ref: '#/components/schemas/AccountInquiryResponse_data_inquiryStatus'
    ErrorResponse:
      required:
      - errorDetails
      - result
      - source
      type: object
      properties:
        result:
          maxLength: 7
          type: string
          description: It represents the error status. Its value should be either WARNING or FATAL. * `FATAL` - is an error which represents that something is not correct while processing the request, it could be because of the request or something is not correct with the processing system. * `WARNING` - is a success with some info which means it is not absolute successful transaction, however response will have information about what is needed in order to have absolute successful transaction.
          example: WARNING
          enum:
          - FATAL
          - WARNING
        source:
          maxLength: 100
          type: string
          description: Source system or provider system which causes error.
          example: Account Validation API
        requestId:
          maxLength: 36
          type: string
          description: traceid to track the error in the APM logs.
          example: 685af2c80f9b1a93ca106902937c2e01
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse_errorDetails'
    AccountStatusInquiryRequest:
      type: object
      properties:
        accountIdentifier:
          $ref: '#/components/schemas/AccountIdentifier'
        bankIdentifier:
          $ref: '#/components/schemas/BankIdentifier'
      description: Schema for the request body to initiate an account inquiry. Includes account and bank identifiers.
    ErrorResponse_errorDetails:
      required:
      - code
      - description
      type: object
      properties:
        code:
          maxLength: 10
          type: string
          description: This is the application error code returned by the API layer or the Implementation layer. A list of error codes will be provided in the user guide.
          example: AV-400
        messageDetail:
          maxLength: 250
          type: string
          description: Details about error including stack traces. This will not be populated for any handled error.
          example: Your request cannot be processed. Please refer to the user guide for more information.
    AccountInquiryResponse:
      type: object
      properties:
        message:
          type: string
          description: A brief message about the response.
          example: Successfully processed
        description:
          type: string
          description: Detailed description of the response.
          example: Successfully retrieved inquiry status.
        requestId:
          type: string
          description: Unique identifier for the request.
          example: 6823527217cf82e16df9244b569cf1d2
        requestTime:
          type: string
          description: Timestamp of the request.
          format: date-time
        data:
          $ref: '#/components/schemas/AccountInquiryResponse_data'
        status:
          type: integer
          description: HTTP status code of the response.
          format: int32
          example: 200
      description: Schema for the response of an account inquiry. Includes reference identifier, inquiry status, and metadata.
    AccountInquiryInitiateResponse_data:
      type: object
      properties:
        referenceIdentifier:
          $ref: '#/components/schemas/AccountInquiryResponse_data_referenceIdentifier'
    AccountInquiryResponse_data_referenceIdentifier:
      type: object
      properties:
        referenceId:
          type: string
          description: Unique reference ID for the inquiry.
          example: c9820cbb-ee63-443d-859c-45556514fd3c
    BankIdentifier:
      type: object
      properties:
        idType:
          type: string
          description: Type of bank identifier (e.g., SWIFT, ABA).
          example: USABA
          enum:
          - SWIFT_ID
          - IBAN
          - IFSC
          - CLABE
          - USABA
          - BRAZIL_BANK_CODE
          - CBU
          - CVU
          - CACPA
          - CNAPS
          - ACCOUNT_NUMBER
          - SHID
          - MBNO
          - ZANCC
        idValue:
          type: string
          description: Value of the bank identifier.
          example: '101000019'
      description: Schema for bank identifiers, includes bank id type and bank id value.
    AccountInquiryInitiateResponse:
      type: object
      properties:
        message:
          type: string
          description: A brief message about the response.
          example: Successfully processed
        description:
          type: string
          description: Detailed description of the response.
          example: Account Inquiry Initiated.
        requestId:
          type: string
          description: Unique identifier for the request.
          example: 6823527217cf82e16df9244b569cf1d2
        requestTime:
          type: string
          description: Timestamp of the request.
          format: date-time
        data:
          $ref: '#/components/schemas/AccountInquiryInitiateResponse_data'
        status:
          type: integer
          description: HTTP status code of the response.
          format: int32
          example: 200
      description: Schema for the response of an account inquiry. Includes reference identifier, inquiry status, and metadata.
    InternalServerErrorResponse_errorDetails:
      required:
      - code
      - description
      type: object
      properties:
        code:
          maxLength: 10
          type: string
          description: This is the application error code returned by the API layer or the Implementation layer. A list of error codes will be provided in the user guide.
          example: AV-500
        messageDetail:
          maxLength: 250
          type: string
          description: Details about error including stack traces. This will not be populated for any handled error.
          example: Your request cannot be processed. Please refer to the user guide for more information.
    UnauthorizedErrorResponse:
      required:
      - errorDetails
      - result
      - source
      type: object
      properties:
        result:
          maxLength: 7
          type: string
          description: It represents the error status. Its value should be either WARNING or FATAL. * `FATAL` - is an error which represents that something is not correct while processing the request, it could be because of the request or something is not correct with the processing system. * `WARNING` - is a success with some info which means it is not absolute successful transaction, however response will have information about what is needed in order to have absolute successful transaction.
          example: WARNING
          enum:
          - FATAL
          - WARNING
        source:
          maxLength: 100
          type: string
          description: Source system or provider system which causes error.
          example: Account Validation API
        requestId:
          maxLength: 36
          type: string
          description: traceid to track the error in the APM logs.
          example: 685af2c80f9b1a93ca106902937c2e01
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/UnauthorizedRequestErrorResponse_errorDetails'
    inline_response_200:
      oneOf:
      - $ref: '#/components/schemas/AccountInquiryInitiateResponse'
      - $ref: '#/components/schemas/AccountInquiryResponse'
    AuthorizationHeader:
      title: JWT Access Token
      type: string
    AccountIdentifier:
      type: object
      properties:
        businessName:
          type: string
          description: Business name, if the account is a business account.
          example: ABC CORP
        accountNumber:
          type: string
          description: The account number being validated.
          example: '112234000'
        accountType:
          type: string
          description: The type of account identifer.
          example: ACCOUNT_NUMBER
          enum:
          - IBAN
          - CLABE
          - BBAN
          - ACCOUNT_NUMBER
          - CBU
          - CVU
          - CCI
          - SHID
          - MBNO
        country:
          type: string
          description: Country associated with the account.
          example: US
          enum:
          - US
          - AR
          - BR
          - CA
          - CN
          - CO
          - EU
          - HK
          - IN
          - ID
          - MY
          - MX
          - NP
          - NG
          - PK
          - PE
          - SG
          - ZA
          - KR
          - TW
          - TH
          - AE
          - UY
          - VN
      description: Schema for account identifiers, including personal and account details.
    AccountInquiryResponse_data_inquiryStatus:
      type: object
      properties:
        accountNumber:
          type: string
          description: The account number being validated.
          example: '112234000'
        routingNumber:
          type: string
          description: The routing number associated with the account.
          example: '311079474'
        accountName:
          type: string
          description: Name associated with the account.
          example: ABC CORP
        accountStatus:
          type: string
          description: Status of the account (e.g., OPEN, CLOSED).
          example: OPEN
        accountStatusMessage:
          type: string
          description: Detailed message about the account status.
          example: Open
        accountStatusCode:
          type: string
          description: Code representing the account status.
          example: AC00
        nameMatchStatus:
          type: string
          description: Status of the name match (e.g., FULL, PARTIAL).
          example: FULL
    InternalServerErrorResponse:
      required:
      - errorDetails
      - result
      - source
      type: object
      properties:
        result:
          maxLength: 7
          type: string
          description: It represents the error status. Its value should be either WARNING or FATAL. * `FATAL` - is an error which represents that something is not correct while processing the request, it could be because of the request or something is not correct with the processing system. * `WARNING` - is a success with some info which means it is not absolute successful transaction, however response will have information about what is needed in order to have absolute successful transaction.
          example: WARNING
          enum:
          - FATAL
          - WARNING
        source:
          maxLength: 100
          type: string
          description: Source system or provider system which causes error.
          example: Account Validation API
        requestId:
          maxLength: 36
          type: string
          description: traceid to track the error in the APM logs.
          example: 685af2c80f9b1a93ca106902937c2e01
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/InternalServerErrorResponse_errorDetails'
    UnauthorizedRequestErrorResponse_errorDetails:
      required:
      - code
      - description
      type: object
      properties:
        code:
          maxLength: 10
          type: string
          description: This is the application error code returned by the API layer or the Implementation layer. A list of error codes will be provided in the user guide.
          example: AV-401
        messageDetail:
          maxLength: 250
          type: string
          description: Details about error including stack traces. This will not be populated for any handled error.
          example: Your request cannot be processed. Please refer to the user guide for more information.
  securitySchemes:
    client-id:
      type: apiKey
      name: X-IBM-Client-Id
      in: header
      x-key-type: client_id
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://pf-fam.internal.citizensbank.com/as/token.oauth2
          scopes:
            av:read: Access to read AV data
      x-ibm-oauth-provider: externalpingfederate
externalDocs:
  description: API Documentation
  url: https://developer.citizensbank.com/content/qut/CitizensAccountValidationAPIUserGuide.pdf
x-ibm-configuration:
  cors:
    enabled: true
  type: rest
  phase: realized
  enforced: true
  testable: true
  application-authentication:
    certificate: false
x-ibm-endpoints:
- url: https://apis.citizensbank.com/v1/account-validation