{ "openapi": "3.0.0", "info": { "title": "Account Validation", "description": "With the Account Validation API you can validate payee details to reduce payment processing errors. You can validate Account Number, Routing Number, and Beneficiary. Many payments are made in real-time and are irrevocable, confirming those payments go to the right counterparty is essential. The following functions are available:\n\n - Verify a bank account based on account number and routing number.\n - Verify the account status (open, closed, unverified, incorrect, rejected, open credits only).\n - Verify a beneficiary name match status (partial, full, no match).\n

\n\nThe **Account Validation Services** offer the following key features:\n\n1. **Initiate Account Inquiry API**:\n - This endpoint initiates an account validation request by submitting the account details, bank details, and beneficiary name. Upon successful submission, a unique reference ID is returned, which can be used to track the status of the inquiry. If status is available immediately, /initiation API response includes reference Id along with account inquiry status and name match status.\n - **Endpoint**: `v1/account-validation/initiation` (POST)\n - **Purpose**: To initiate an account validation request.\n\n2. **Get Account Inquiry Status API**:\n - This endpoint retrieves the status of an account inquiry request by providing the reference ID returned during the initiation step. This API checks if the validation is still in progress, completed, or has failed, along with any relevant status messages. Once the account inquiry is completed, the status can be requested up to three times.\n - **Endpoint**: `v1/account-validation/status` (GET)\n - **Purpose**: To retrieve account validation result using the reference ID.\n", "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": "" }, "externalDocs": { "description": "API Documentation", "url": "https://developer.citizensbank.com/content/qut/CitizensAccountValidationAPIUserGuide.pdf" }, "security": [ { "client-id": [] } ], "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" } } } } } } }, "/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": { "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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." }, "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." }, "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." }, "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": { "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." }, "inline_response_200": { "oneOf": [ { "$ref": "#/components/schemas/AccountInquiryInitiateResponse" }, { "$ref": "#/components/schemas/AccountInquiryResponse" } ] }, "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." } } }, "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." } } }, "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." } } }, "AccountInquiryResponse_data_referenceIdentifier": { "type": "object", "properties": { "referenceId": { "type": "string", "description": "Unique reference ID for the inquiry.", "example": "c9820cbb-ee63-443d-859c-45556514fd3c" } } }, "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" } } }, "AccountInquiryResponse_data": { "type": "object", "properties": { "referenceIdentifier": { "$ref": "#/components/schemas/AccountInquiryResponse_data_referenceIdentifier" }, "inquiryStatus": { "$ref": "#/components/schemas/AccountInquiryResponse_data_inquiryStatus" } } }, "AccountInquiryInitiateResponse_data": { "type": "object", "properties": { "referenceIdentifier": { "$ref": "#/components/schemas/AccountInquiryResponse_data_referenceIdentifier" } } }, "AuthorizationHeader": { "title": "JWT Access Token", "type": "string" } }, "parameters": { "x-fapi-trace-id": { "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" } }, "x-fapi-channel-id": { "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" } }, "authorization": { "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" } }, "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" } } }, "x-ibm-configuration": { "cors": { "enabled": true }, "type": "rest", "phase": "realized", "enforced": true, "testable": true, "application-authentication": { "certificate": false } }, "servers": [ { "url": "https://apis.citizensbank.com/v1/account-validation" } ], "x-ibm-endpoints": [ { "url": "https://apis.citizensbank.com/v1/account-validation" } ] }