openapi: 3.2.0
info:
  title: Account Validation Get Account Inquiry Status 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: Get Account Inquiry Status
paths:
  /status:
    get:
      tags:
      - Get Account Inquiry Status
      summary: Retrieve account inquiry status by reference ID
      description: This endpoint retrieves the status of an account inquiry using a reference ID.
      operationId: getAccountInquiryByRefId
      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
      - name: referenceId
        in: query
        description: The unique reference ID associated with the account inquiry.
        required: true
        style: form
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved the account inquiry status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountInquiryResponse'
        '401':
          description: Unauthorized. The user does not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequestErrorResponse'
        '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'
    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.
    AccountInquiryResponse_data_referenceIdentifier:
      type: object
      properties:
        referenceId:
          type: string
          description: Unique reference ID for the inquiry.
          example: c9820cbb-ee63-443d-859c-45556514fd3c
    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.
    AuthorizationHeader:
      title: JWT Access Token
      type: string
    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
    UnauthorizedRequestErrorResponse:
      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'
    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