Account Verification Pro

Verify a bank account and retrieve beneficiary information for retail or corporate accounts in one call.

Integration guide

Goal: Confirm a bank account (IBAN) and its beneficiary for either a retail identity or a corporate entity.

Estimated time: 20 minutes

Prerequisites

Sandbox credentials and an access token
An IBAN plus a retail identity or corporate registration to match

Account Verification (AV)Beneficiary Verification

When to use

Account Verification Pro checks the account, identity, and beneficiary name in one request. It supports both individuals and businesses.

Use it when you need to confirm two things together:

The IBAN belongs to the person or business you provided.
The beneficiary name matches the name held by the bank.

How it differs from basic AV

Basic Account Verification checks whether an IBAN belongs to a person or business. It has separate ID Match and Corporate endpoints.

Account Verification Pro combines Account Verification and Beneficiary Verification. It performs the account and identity check, then also checks the beneficiary name in the same request.

Endpoint	For	Required inputs	Optional inputs
Match (Retail)	Individuals	`iban`, `idValue`	`idType`, `beneficiaryName`
Corporate	Businesses	`iban`, plus at least one of `companyRegistrationNumber` or `unn`	`beneficiaryName`

For the retail endpoint, idType is NATIONAL_ID, IQAMA, COMPANY_REGISTRATION_NUMBER, or UNN.

For the Corporate endpoint, provide at least one company identifier: companyRegistrationNumber or unn. You can provide both. beneficiaryName is optional and accepts up to 255 characters.

What you get back

Both endpoints use the same response structure. On success, the verification result comes in the data property of the response:

Field	Description
`data.requestId`	A unique reference for this verification. Keep it for reconciliation and support
`data.result`	`MATCH`, `NO_MATCH`, or `ERROR`
`data.beneficiaryName`	The account holder as registered with the bank
`data.inputBeneficiaryName`	The beneficiary name you sent in the request
`data.accountStatus`	The current account status returned by the bank
`data.accountIdentifier`	The verified account identifier. Returned by the retail Match endpoint
`data.bank`	Bank details, including the English and Arabic names, bank code, and SWIFT code
`data.errorDescription`	The reason for a no-match or error. Empty when the result is a match
`data.idType` / `data.idValue`	The identity that was checked
`data.executionDate`	The date and time when the check was performed, in ISO 8601 format

A successful response returns HTTP 200. To determine whether the result is MATCH, NO_MATCH, or ERROR, use data.result rather than the HTTP status code. If the result is NO_MATCH or ERROR, read data.errorDescription for more information.

The possible descriptions are listed in the Basic AV guide under Match and No-Match Results and Error Results.

Integration summary

Authenticate

Exchange your API credentials for a Bearer access token. See Quick Start Setup.

Choose the right endpoint

Use Match for an individual. Use Corporate for a business.

Match (Retail)

curl -X POST https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "iban": "SA0230825947458020058295",
        "idType": "NATIONAL_ID",
        "idValue": "1083886659",
        "beneficiaryName": "HAITHAM AL AYED"
      }'

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      iban: "SA0230825947458020058295",
      idType: "NATIONAL_ID",
      idValue: "1083886659",
      beneficiaryName: "HAITHAM AL AYED",
    }),
  },
);

const { data } = await res.json();
// data.result is "MATCH", "NO_MATCH", or "ERROR"

import requests

res = requests.post(
    "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "iban": "SA0230825947458020058295",
        "idType": "NATIONAL_ID",
        "idValue": "1083886659",
        "beneficiaryName": "HAITHAM AL AYED",
    },
)

data = res.json()["data"]
result = data["result"]

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

String body = """
    {
      "iban": "SA0230825947458020058295",
      "idType": "NATIONAL_ID",
      "idValue": "1083886659",
      "beneficiaryName": "HAITHAM AL AYED"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

JsonNode data = new ObjectMapper().readTree(response.body()).get("data");
String result = data.get("result").asText();

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match");
request.Headers.Add("Authorization", $"Bearer {accessToken}");
request.Content = new StringContent(
    "{ \"iban\": \"SA0230825947458020058295\", \"idType\": \"NATIONAL_ID\", \"idValue\": \"1083886659\", \"beneficiaryName\": \"HAITHAM AL AYED\" }",
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

using var doc = JsonDocument.Parse(body);
var data = doc.RootElement.GetProperty("data");
var result = data.GetProperty("result").GetString();

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

payload := []byte(`{
	"iban": "SA0230825947458020058295",
	"idType": "NATIONAL_ID",
	"idValue": "1083886659",
	"beneficiaryName": "HAITHAM AL AYED"
}`)

req, err := http.NewRequest(
	http.MethodPost,
	"https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match",
	bytes.NewReader(payload),
)
if err != nil {
	panic(err)
}

req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

var body struct {
	Data struct {
		RequestID       string `json:"requestId"`
		Result          string `json:"result"`
		BeneficiaryName string `json:"beneficiaryName"`
	} `json:"data"`
}
json.NewDecoder(res.Body).Decode(&body)

result := body.Data.Result

Corporate

curl -X POST https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Corporate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "iban": "SA0255794102713415121120",
        "companyRegistrationNumber": "1083886658",
        "beneficiaryName": "SAUDI A.PAK.INDUSTRY"
      }'

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Corporate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      iban: "SA0255794102713415121120",
      companyRegistrationNumber: "1083886658",
      beneficiaryName: "SAUDI A.PAK.INDUSTRY",
    }),
  },
);

const { data } = await res.json();
// data.result is "MATCH", "NO_MATCH", or "ERROR"

import requests

res = requests.post(
    "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Corporate",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "iban": "SA0255794102713415121120",
        "companyRegistrationNumber": "1083886658",
        "beneficiaryName": "SAUDI A.PAK.INDUSTRY",
    },
)

data = res.json()["data"]
result = data["result"]

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

String body = """
    {
      "iban": "SA0255794102713415121120",
      "companyRegistrationNumber": "1083886658",
      "beneficiaryName": "SAUDI A.PAK.INDUSTRY"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Corporate"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

JsonNode data = new ObjectMapper().readTree(response.body()).get("data");
String result = data.get("result").asText();

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Corporate");
request.Headers.Add("Authorization", $"Bearer {accessToken}");
request.Content = new StringContent(
    "{ \"iban\": \"SA0255794102713415121120\", \"companyRegistrationNumber\": \"1083886658\", \"beneficiaryName\": \"SAUDI A.PAK.INDUSTRY\" }",
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

using var doc = JsonDocument.Parse(body);
var data = doc.RootElement.GetProperty("data");
var result = data.GetProperty("result").GetString();

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

payload := []byte(`{
	"iban": "SA0255794102713415121120",
	"companyRegistrationNumber": "1083886658",
	"beneficiaryName": "SAUDI A.PAK.INDUSTRY"
}`)

req, err := http.NewRequest(
	http.MethodPost,
	"https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Corporate",
	bytes.NewReader(payload),
)
if err != nil {
	panic(err)
}

req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

var body struct {
	Data struct {
		RequestID       string `json:"requestId"`
		Result          string `json:"result"`
		BeneficiaryName string `json:"beneficiaryName"`
	} `json:"data"`
}
json.NewDecoder(res.Body).Decode(&body)

result := body.Data.Result

Handle the result

Use data.result to determine the outcome:

MATCH: the account and identity match. If you sent a beneficiary name, it also matches the bank's record.
NO_MATCH: one or more details do not match. Do not continue with the payout until you review data.errorDescription.
ERROR: the check could not be completed. Read data.errorDescription, then retry later or review the request manually.

Store data.requestId for reconciliation and support. Handle request-level failures (400 invalid input, 401 authentication failure, 403 forbidden, 429 too many requests) separately from a successful response with data.result set to NO_MATCH.

Sandbox testing

The sandbox provides match and no-match combinations for individuals and businesses. AV Pro also checks the beneficiary name, so each row includes the expected name.

Match (retail)

Identity	ID	IBAN	Name
National ID	1083886659	SA02 3082 5947 4580 2005 8295	HAITHAM AL AYED
Iqama ID	2526303150	SA02 0548 2877 1759 4474 3614	MAHMOUD AL-MASAA

Match (corporate)

UNN	CRN	IBAN	Name
7007599983	1083886658	SA02 5579 4102 7134 1512 1120	SAUDI A.PAK.INDUSTRY
7001393799	7007599983	SA02 1021 7220 3012 9444 5123	السعودية أ.باك.صناعة

No-match (retail)

Identity	ID	IBAN	Name
National ID	1009590330	SA02 1012 0407 6563 5517 3154	KHAMIS AL-JAFALI
Iqama ID	2210802912	SA02 1090 1704 8587 4890 0789	RAED AL MUHAIDIB

No-match (corporate)

UNN	CRN	IBAN	Name
7001393799	7007599883	SA02 1021 7220 3012 9444 5123	شركة الرياض للصناعات الغذائي
7033051019	7007599983	SA02 6003 2360 6513 2733 6863	ZAIN KSA

Run the KSA API in Postman

Import the latest KSA collection and call both AV Pro endpoints without writing code.

Open in Postman

Key takeaways

AV Pro combines Account Verification and Beneficiary Verification in one request.
Use Match for individuals. Use Corporate for businesses, and provide at least one of companyRegistrationNumber or unn.
A successful response returns HTTP 200. Use data.result to determine whether the outcome is MATCH, NO_MATCH, or ERROR.

Continue learning

Account Verification Pro API

Full request and response schema.

Account Verification (AV)

Account and identity checks for individuals and businesses.

Commercial Registration

Full company record lookup.

On this page