Sign up

Use case · KYB

KYB onboarding: verify a business customer in 30 lines

KYB onboarding is the checks you run on a business customer before you accept it: the company exists, who runs it, no sanctions, no insolvency. Automate them with the KYB API in 30 lines of code. NIF, SIREN, company_number → full registry profile + sanctions screening in a single REST call.

The problem

Onboarding a B2B counterparty in regulated EU finance means proving four things before you transact: the company legally exists, you know who controls it, none of those parties are sanctioned, and there's no obvious adverse signal. The standard tooling for this is fragmented — one vendor for Spanish data, another for French, a third for UK Companies House, a fourth for sanctions, often a fifth for adverse-media. Each contract is annual, opaque-priced, and requires a sales call.

For a fintech onboarding a few hundred B2B customers a month, that vendor stack is overkill, expensive, and slow to integrate. The Prometiam API replaces the registry + sanctions legs with one REST endpoint and predictable usage-based pricing.

The 30-second integration

Three endpoints cover the KYB-registry-and-sanctions flow. Run them in this order:

# 1. Resolve the counterparty by NIF (Spain), SIREN (France), or company_number (UK)
curl 'https://api.prometiam.com/functions/v1/risk-api/companies/search?company_number=A78053147&country=ES' \
  -H 'Authorization: Bearer rk_live_...'

# 2. Pull the full company profile (officers, capital, registry coordinates)
curl 'https://api.prometiam.com/functions/v1/risk-api/companies/812044' \
  -H 'Authorization: Bearer rk_live_...'

# 3. Screen the legal-entity name and each officer name against sanctions
curl 'https://api.prometiam.com/functions/v1/risk-api/sanctions/screen?name=Telefonica&threshold=85' \
  -H 'Authorization: Bearer rk_live_...'

That's the entire KYB-registry surface for a single counterparty. Wrap it in a function, call it from your onboarding form, and you have a working integration in under an hour. The company lookup API page covers every identifier and how to validate it, and a company autocomplete field lets the customer pick the counterparty on the form instead of typing it.

A real Python example

import os, requests

API = 'https://api.prometiam.com/functions/v1/risk-api'
HEAD = {'Authorization': f'Bearer {os.environ["PROMETIAM_API_KEY"]}'}

def kyb_check(nif: str, country: str = 'ES'):
    # Resolve company
    s = requests.get(f'{API}/companies/search', params={'company_number': nif, 'country': country}, headers=HEAD).json()
    if not s.get('data'): return {'status': 'not_found'}
    company = s['data'][0]

    # Full detail (officers + registry coordinates)
    detail = requests.get(f'{API}/companies/{company["id"]}', headers=HEAD).json()['data']

    # Sanctions on the legal entity
    legal_hits = requests.get(f'{API}/sanctions/screen',
                              params={'name': detail['company_name'], 'threshold': 85},
                              headers=HEAD).json()['data']

    # Sanctions on each current officer
    officer_hits = []
    for c in detail.get('contacts', []):
        if not c.get('is_current'): continue
        h = requests.get(f'{API}/sanctions/screen',
                         params={'name': c['full_name'], 'threshold': 85, 'entity_type': 'person'},
                         headers=HEAD).json()['data']
        if h: officer_hits.append({'officer': c['full_name'], 'matches': h})

    return {
        'status': 'verified' if (not legal_hits and not officer_hits) else 'review',
        'company': detail,
        'sanctions': {'legal': legal_hits, 'officers': officer_hits},
    }

30 lines including the imports. A typical KYB application built on this returns a verified-or-review verdict in well under a second on cached results.

What you actually get back

The /companies/{id} response includes everything a KYB officer needs to fill an onboarding file:

  • Identity: legal name, NIF/SIREN/company_number, legal form, address, founding date
  • Registry coordinates: exact tomo / libro / folio / hoja for Spain, registration office for France, Companies House registration for UK
  • Officers: current and historical appointments — name, role, appointment date, end date
  • Status: active, dissolved, in liquidation, etc., updated daily
  • Capital and purpose: registered capital (capital_amount + capital_currency) and the official activity description (activity_description, with activity_code and its classification in activity_code_scheme)

The /sanctions/screen endpoint is beta; its response returns matches with confidence scores (0–100), source list (EU / UN / OFAC / UK / Australia (DFAT) / FR gels / US CSL), and any aliases. You set a threshold per call to control false-positive rate.

Customer dashboard screenshot: a company profile with identifiers and signalsCustomer dashboard screenshot: a company profile with identifiers and signals
The same record in the dashboard: identifiers, registered office, and the insolvency, sanctions (beta) and register signals on one page. Shown for a UK company. Open it in the dashboard

Retention-ready evidence file

What to store for each KYB check, so the file stands up later.

KeepWhere it comes from
The request: method, path and parametersYour system.
Request idThe X-Request-Id response header.
Credits chargedThe X-Credits-Cost response header.
When you retrieved itYour clock. The response body carries no retrieval time today; the dashboard export adds fetched_at.
Register and last update of the recordThe register and updated_at fields on the record, with the attribution the response carries.
The response bodyStore it whole. For tamper evidence, hash it (SHA-256) when you store it; we do not add a hash today.
The decision, who took it and whenYour system. The API supplies evidence; the decision is yours.
The limits that appliedThe limits in the control map above, such as UK owners only or sanctions in beta.

A sample evidence file with placeholder values.

{
  "_note": "Sample with placeholder values. Replace each with what you stored for the check.",
  "check_id": "kyb-000123",
  "retrieved_at": "2026-01-15T09:30:12Z",
  "request": {
    "method": "GET",
    "path": "/companies/search",
    "params": {
      "country": "GB",
      "company_number": "00000000",
      "limit": 1
    }
  },
  "response": {
    "x_request_id": "<value of the X-Request-Id header>",
    "x_credits_cost": "1",
    "body_sha256": "<SHA-256 you computed over the stored response body>"
  },
  "record": {
    "id": "<record id>",
    "register": "<register named on the record>",
    "updated_at": "<updated_at on the record>",
    "status": "<status on the record>"
  },
  "limits_applied": [
    "Beneficial owners: UK register only",
    "Sanctions screening: beta"
  ],
  "decision": {
    "outcome": "pass | review | reject",
    "decided_by": "<your analyst id>",
    "decided_at": "2026-01-15T09:41:00Z"
  }
}

Retention

Keep the file for the period your policy and the law that applies to you require. The EU anti-money-laundering rules most often cited ask for five years (AMLD5, Article 40); check the rule for your case.

KYB control map

Pricing fit

For a fintech onboarding 500 B2B counterparties / month, the typical KYB call shape is ~5 API calls per counterparty (search + detail + 3 sanctions screens for legal + top officers). That's 2,500 calls/month, about 5,500 credits (11 per counterparty: 1 for the search, 1 for the detail, 3 for each screen) — well inside the Professional tier (€29.99/mo, 10,000 credits/month), which also covers the sanctions screens this flow uses. At 4,000 counterparties/month (~44,000 credits), the Scale tier (€99.99/mo, 50,000 credits/month) fits comfortably.

Creditsafe and Iberinform don’t publish pricing for equivalent volume — it comes from a sales engagement and an annual contract.

Implementation patterns

Cache hot lookups. Most B2B fintechs onboard the same parent companies repeatedly. Cache the /companies/{id} response for 24 hours; refresh on demand or via a daily background refresh.

Watchlist mode. Combine KYB with the counterparty-monitoring pattern: store the company_id of every onboarded counterparty and run /company-events/timeline daily to detect post-onboarding events (director changes, capital reductions, dissolution) that should trigger review.

Sanctions threshold tuning. Start at 85 (the default), then tune per false-positive cost. For high-stakes onboarding (lending, payment processing), 80 is the safer choice. For low-stakes (newsletter signup, free-tier verification), 90 reduces noise.

FAQ

What is KYB?
Know Your Business — verifying a corporate counterparty before transacting. Confirms legal existence, beneficial ownership, sanctions exposure, and adverse media.

Which countries does Prometiam KYB cover?
Spain (BORME), France (BODACC), the United Kingdom (Companies House), Ireland (CRO, company-level), Poland (KRS, company-level), Norway (Brønnøysundregistrene, companies and officers), Finland (PRH/YTJ), Sweden (Bolagsverket), Belgium (KBO), Croatia (Sudski registar), Denmark (CVR), Estonia (e-Business Register), Slovakia (RPO), Switzerland (Zefix), Latvia (Register of Enterprises), Cyprus (DRCOR) and Romania (ONRC) and the United States; Finland, Sweden, Belgium, Croatia, Denmark, Estonia, Slovakia, Switzerland, Latvia, Cyprus, Romania, Lithuania, Canada, Australia, Japan, Israel, Singapore, Colombia, Taiwan, Germany, Ukraine, Serbia, Ecuador, Chile, Mexico, the Netherlands, Brazil and the United States are company records only. Use ?country=ES|FR|GB|IE|PL|NO|FI|SE|BE|HR|DK|EE|SK|CH|LV|CY|RO|US|LT|CA|AU|JP|IL|SG|CO|TW|BR|CZ|DE|AR|UA|RS|EC|NL|CL|NL|MX.

How fast is integration?
First call typically under 60 seconds from signup. End-to-end production integration is usually a half-day's work.

Does it include beneficial ownership / UBO?
For UK companies via PSC (Persons with Significant Control), yes — embedded in /companies/{id} and /people/{id}. Spanish and French UBO disclosures are at the registry level the API serves, but full UBO chains require a national UBO register query (Spain's RBR, France's RBE) which we don't yet expose.

How does Prometiam compare to Creditsafe or Iberinform for KYB?
For multi-country scope, typically 50–95% cheaper at SMB and mid-market scale. See Creditsafe alternative and Iberinform alternative.

Is the data fresh enough for real-time onboarding?
BORME and BODACC are updated daily; UK Companies House is monthly bulk + daily delta. /coverage returns latest_filing per country.

Related