Skip to content
IBANforge

Bank checks and compliance indicators

This route adds bank-level indicators: screening against the announced lists (OFAC, EU, UN), country/FATF data, SEPA reachability and VoP registration. It does not verify account ownership, account existence or a beneficiary name, and executes no payment. It is not a regulated AML/CFT product.

POST https://api.ibanforge.com/v1/iban/compliance

Call with a key

An API key or x402 payment is required; the keyless single-validation trial does not cover this route. With a key, a call consumes one allowance unit or prepaid credit and cost_usdc is 0. With x402, a call costs 0.02 USDC. See API keys, pricing and x402.

The server-side IBANFORGE_API_KEY environment variable holds your existing key. Values below are documentation examples. Send either iban or bic, never two non-empty values.

curl --fail-with-body --silent --show-error \
  https://api.ibanforge.com/v1/iban/compliance \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IBANFORGE_API_KEY:?}" \
  -d '{"iban":"DE89370400440532013000"}'
curl --fail-with-body --silent --show-error \
  https://api.ibanforge.com/v1/iban/compliance \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IBANFORGE_API_KEY:?}" \
  -d '{"bic":"COBADEFFXXX"}'

The bic path accepts an 8- or 11-character BIC and validates no IBAN. Its envelope contains bic (a string), bic8, valid_format, found, institution, country, compliance, meta, cost_usdc and processing_ms, plus an optional note. found: false means the directory did not name the institution; it does not prevent BIC-based screening. This envelope differs from the IBAN path, where bic is an object when present.

Read the findings before the score

The IBAN path retains the single-validation fields and adds compliance and meta. A 200 can contain an invalid IBAN. When present, checks also separates the checking axes. Missing data does not become a negative finding.

Field in complianceMeaning
sanctions.bank_screenedA bank was compared against loaded lists; true does not guarantee that all announced lists were available.
sanctions.institution_listedtrue: a match was found; false: none in the complete consulted scope; null: no negative finding can be established because no bank was screened or a list was unavailable.
sanctions.bank_sanctioned, matched_listsLegacy result fields. Do not interpret false or an empty list without the coverage fields and flags.
sanctions.payee_screenedAlways false: no account-holder name screening.
sanctions.country_sanctionedDatabase country signal, separate from a bank designation and from a legal assessment of a transaction.
sanctions.fatf_statusmember, suspended, grey_list, black_list or non_member. Non-membership is not a risk-list designation.
reachability.screenedThe route established an answer through a bank register or a country outside SEPA scope.
reachability.sct, sdd, sepa_instantScheme indicators; without a check, false values are defaults.
reachability.listed_in_epc_registersAt least one available scheme; null if not established. Also read screened and provenance.
vop.screened, register_statusRegister status: active, pending, inactive, not_listed, or null if not established.
vop.participant, statusLegacy fields: participant is true for active; status still uses not_found. This is not a name/IBAN match.
reachability.source, as_of; vop.source, as_ofEPC credit and extraction date when the bank register was consulted; absent when the country answers. Date is null when unknown.
finma_registerValid Swiss IBAN only. listed: the bank was matched by identifiers in a dated copy of the public FINMA register, with the official labels as published. not_verified: no answer, and reason says why; it never means unauthorised. Not part of the score.
risk_scoreEditorial 0–100 score and category; null / unassessable for an invalid IBAN. Neither a fraud probability nor an authorization.
risk_levellow (0–19), medium (20–39), elevated (40–59), high (60–79), critical (80–100), unassessable.
flagsMachine-readable findings and limits, including unavailable sources. Not every flag adds points.

Distinguish the cases

An invalid IBAN returns risk_score: null, risk_level: "unassessable" and the iban_invalid flag. If the IBAN is valid but a source cannot be read, other readable axes may still answer; inspect coverage, null values and *_unavailable flags. A numeric score can therefore accompany incomplete screening.

Numeric categories are low (0–19), medium (20–39), elevated (40–59), high (60–79) and critical (80–100). A low result is not permission to release a payment. In particular, unavailable SEPA or VoP registers do not add score points: read those flags separately. The response documents a review; it does not replace account or beneficiary checks.

Scope and provenance

finma_register is matched by identifiers only (IID, BIC, LEI, Swiss UID), never by a name. It reads a dated copy, collected by OpenSwissData, and is not a service of FINMA; check finma.ch before any decision. A copy older than 14 days answers not_verified. The file gives neither a licence date nor a status, so the field states neither. It covers Swiss IBANs on this route, not the direct BIC check.

Bank matching normally uses the exact BIC8. For a Russian bank, the default SWIFT BICs of entries sharing its licence are compared on their first six characters. Secondary BICs are not compared. With no usable BIC, the bank axis remains unscreened; a designation without a BIC or under a different prefix can be missed.

Field in metaMeaning
scope, disclaimerbank_bic_only and the text limitation; retain them with the report.
sourcesLoaded sources, as a comma-separated string or null; not evidence that every axis was queried for this call.
sanctions_as_ofCompliance-data refresh date or null; not a guarantee of uniform freshness across lists.
fatf_as_ofMonth of the represented plenary, or null.
country_risk_as_of, country_risk_scopeDate and explanation of the editorial country axis, separate from FATF status.

A refresh schedule does not replace these served dates. Also retain source credits and any attribution block on the IBAN path. A bank’s VoP registration does not initiate a payee-verification request: see our VoP guide and the EPC scheme overview.

Errors and next steps

Status / codeMeaning
400 invalid_jsonMalformed JSON.
400 invalid_requestNo non-empty IBAN/BIC string, or both values are non-empty.
400 invalid_bic_formatThe supplied BIC is outside the expected format.
402Insufficient access or units; inspect the response body.
429Wait for Retry-After; this is not the monthly quota.

Do not turn an HTTP failure or unavailable source into “no risk”. See the error reference, recipes, onboarding and data sources.