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/complianceCall 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 compliance | Meaning |
|---|---|
sanctions.bank_screened | A bank was compared against loaded lists; true does not guarantee that all announced lists were available. |
sanctions.institution_listed | true: 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_lists | Legacy result fields. Do not interpret false or an empty list without the coverage fields and flags. |
sanctions.payee_screened | Always false: no account-holder name screening. |
sanctions.country_sanctioned | Database country signal, separate from a bank designation and from a legal assessment of a transaction. |
sanctions.fatf_status | member, suspended, grey_list, black_list or non_member. Non-membership is not a risk-list designation. |
reachability.screened | The route established an answer through a bank register or a country outside SEPA scope. |
reachability.sct, sdd, sepa_instant | Scheme indicators; without a check, false values are defaults. |
reachability.listed_in_epc_registers | At least one available scheme; null if not established. Also read screened and provenance. |
vop.screened, register_status | Register status: active, pending, inactive, not_listed, or null if not established. |
vop.participant, status | Legacy 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_of | EPC credit and extraction date when the bank register was consulted; absent when the country answers. Date is null when unknown. |
finma_register | Valid 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_score | Editorial 0–100 score and category; null / unassessable for an invalid IBAN. Neither a fraud probability nor an authorization. |
risk_level | low (0–19), medium (20–39), elevated (40–59), high (60–79), critical (80–100), unassessable. |
flags | Machine-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 meta | Meaning |
|---|---|
scope, disclaimer | bank_bic_only and the text limitation; retain them with the report. |
sources | Loaded sources, as a comma-separated string or null; not evidence that every axis was queried for this call. |
sanctions_as_of | Compliance-data refresh date or null; not a guarantee of uniform freshness across lists. |
fatf_as_of | Month of the represented plenary, or null. |
country_risk_as_of, country_risk_scope | Date 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 / code | Meaning |
|---|---|
400 invalid_json | Malformed JSON. |
400 invalid_request | No non-empty IBAN/BIC string, or both values are non-empty. |
400 invalid_bic_format | The supplied BIC is outside the expected format. |
| 402 | Insufficient access or units; inspect the response body. |
| 429 | Wait 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.