Account Verification (AV)

Confirm a bank account (IBAN) belongs to a given identity, and get a clear match / no-match result.

Integration guide

Goal: Verify that a bank account (IBAN) matches a supplied identity document, and get a clear match / no-match result.

Estimated time: 15 minutes

Prerequisites

Sandbox credentials (App ID, API key) and an access token
An IBAN plus an identity value to check against

Account Verification Pro Beneficiary Verification

When to use

KYC enhancement during customer onboarding
Verifying a payout account belongs to the expected person or business
Reducing misdirected-payment and fraud risk before you transfer funds

What it confirms

Account Verification (AV) checks whether an IBAN is validly associated with an identity document, and returns a single boolean.

Request inputs

Field	Description
`iban`	The IBAN to validate
`idType`	The kind of identity document being matched (e.g. national ID, residency ID, or commercial registration)
`idValue`	The identity number to match against the account

Response

Field	Description
`isAccountValid`	`true` when the IBAN matches the supplied identity, `false` otherwise

Flow

Integration summary

Authenticate

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

Call the ID-match endpoint

Send the IBAN and identity to the account-verification endpoint with your Bearer token:

curl -X POST https://sandbox.sparefinancial.sa/api/v2.0/av/AccountVerification/IdMatch \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "iban": "...", "idType": "NATID", "idValue": "..." }'

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v2.0/av/AccountVerification/IdMatch",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      iban: "...",
      idType: "NATID",
      idValue: "...",
    }),
  },
);

const { isAccountValid } = await res.json();

import requests

res = requests.post(
    "https://sandbox.sparefinancial.sa/api/v2.0/av/AccountVerification/IdMatch",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "iban": "...",
        "idType": "NATID",
        "idValue": "...",
    },
)

data = res.json()
is_account_valid = data["isAccountValid"]

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": "...", "idType": "NATID", "idValue": "..." }
    """;

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

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

// Parse the JSON response and read the isAccountValid field
JsonNode data = new ObjectMapper().readTree(response.body());
boolean isAccountValid = data.get("isAccountValid").asBoolean();

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.0/av/AccountVerification/IdMatch");
request.Headers.Add("Authorization", $"Bearer {accessToken}");
request.Content = new StringContent(
    "{ \"iban\": \"...\", \"idType\": \"NATID\", \"idValue\": \"...\" }",
    Encoding.UTF8,
    "application/json");

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

using var doc = JsonDocument.Parse(body);
var isAccountValid = doc.RootElement.GetProperty("isAccountValid").GetBoolean();

package main

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

payload := []byte(`{ "iban": "...", "idType": "NATID", "idValue": "..." }`)

req, err := http.NewRequest(
	http.MethodPost,
	"https://sandbox.sparefinancial.sa/api/v2.0/av/AccountVerification/IdMatch",
	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 data struct {
	IsAccountValid bool `json:"isAccountValid"`
}
json.NewDecoder(res.Body).Decode(&data)

isAccountValid := data.IsAccountValid

Handle the result

Read isAccountValid. Treat false as a no-match and hold the payout, and handle error responses (invalid input, auth failure) explicitly.

Sandbox testing

The sandbox provides match and no-match test combinations for both retail and corporate accounts.

Key takeaways

AV answers one question: does this IBAN belong to this identity? The result is a single isAccountValid boolean.
Use it before a payout or during onboarding to catch misdirected payments and impersonation.
For beneficiary name lookup or a combined retail/corporate check, use Beneficiary Verification or AV Pro.

Continue learning

Account Verification Pro

Adds beneficiary details and a corporate flow.

Verification concept

How AV compares to the other services.