API Documentation

Programmatic access to global business registry data.

Quick start

Make your first request in seconds. All you need is an API key.

curl -H "X-API-Key: b2t_your_key" \
  "https://b2trust.com/api/v1/search?q=CD+Projekt"

Authentication

Authenticate every request by including your API key in the X-API-Key header.

X-API-Key: b2t_your_key

API keys are prefixed with b2t_. Keep your key secret and never expose it in client-side code.

Endpoints

GET/api/v1/search

Search for companies across all registries by name, tax ID, VAT number, or registry number.

Parameter	Type	Description
q	string	Required. Company name, tax ID, VAT number, or registry number.
mode	enum	`name` (default) or `taxid`. Hints the confidence scorer; with `taxid`, default `status` becomes `all`.
country	string	ISO 3166-1 alpha-2 country code, comma-separated for multiple (e.g. `PL,DE`). Note UK is `GB`.
status	enum	`active` (default for `mode=name`), `suspended`, `dissolved`, `inactive`, or `all`.
legal_form	string	Filter by legal form, comma-separated. Case-insensitive partial match.
city	string	Filter by registered-address city. Case-insensitive partial match.
date_from	ISO date	Earliest registration date, format `YYYY-MM-DD`.
date_to	ISO date	Latest registration date, format `YYYY-MM-DD`.
sort	enum	`relevance` (default), `newest`, `oldest`, `name_asc`, `name_desc`, `country`, `confidence`.
page	number	Page number, default `1`.
limit	number	Results per page. Default `50`, max `500`.
locale	string	Response locale hint (e.g. `en`, `pl`). Default `en`.

Returns up to 10 source registries per country. UK uses GB; other notable codes: CZ, DE, NO, FR, US, AU, NZ, BR, FI.

GET/api/v1/company/{country_code}-{national_id}

Retrieve a full company profile by its unique identifier (cache + live enrichment + BII + VIES cross-check).

curl -H "X-API-Key: b2t_your_key" \
  "https://b2trust.com/api/v1/company/PL-7342867148"

The path identifier is {country_code}-{national_id}. UK companies use GB (e.g. GB-12345678).

GET/api/v1/company/{id}/verify-bank

Verify whether a bank IBAN is registered against this company in PL Biała Lista (Poland only).

curl -H "X-API-Key: b2t_your_key" \
  "https://b2trust.com/api/v1/company/PL-7342867148/verify-bank?iban=PL00000000000000000000000000"

Response schema

All responses follow a consistent envelope format. /search returns an array; /company/{id} returns a single object.

Search response

{
  "status": "ok",
  "query": "CD Projekt",
  "mode": "name",
  "data": [
    {
      "country_code": "PL",
      "national_id": "7342867148",
      "registry_number": "0000317499",
      "company_name": "CD Projekt S.A.",
      "legal_form": "Spółka Akcyjna",
      "status": "active",
      "registered_address": {
        "street": "ul. Jagiellońska 74",
        "city": "Warszawa",
        "postal_code": "03-301",
        "country": "PL"
      },
      "registration_date": "2002-02-01",
      "registry_count": 3,
      "vat_number": "PL7342867148",
      "source_registries": ["PL_KRS", "PL_GUS", "EU_VIES"],
      "fetched_at": "2026-04-30T00:23:02.602Z",
      "confidence": {
        "score": 92,
        "label": "High",
        "color": "green",
        "factors": ["Exact name match", "Verified by 3 registries"]
      },
      "lookup_count": 17,
      "first_indexed_at": "2025-11-10T08:14:00.000Z",
      "vies_status": "valid",
      "vies_note": null
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "total_pages": 1,
    "query_time_ms": 412,
    "cache_hit": true,
    "countries": ["PL"],
    "country_counts": { "PL": 1 },
    "legal_forms": ["Spółka Akcyjna"]
  }
}

Company response

Full profile includes directors, beneficial_owners, shareholders, activity_codes, and (for PL) bank_accounts from PL Biała Lista.

Notes on `meta.country_counts`

When country= is supplied, country_counts reflects only the filtered country (post-filter counts). Without country=, it reports counts across every country present in the result set. meta.countries follows the same source — it is always Object.keys(country_counts).

Rate limits

Plan	Per minute	Per day	Validity
Trial (`b2t_trial_*`)	3	20	14 days

Limits are enforced per API key. Exceeding either limit returns a 429 status with a Retry-After header. Higher tiers are issued on request — contact contact@b2trust.com.

Error codes

Code	Status	Description
400	Bad Request	Missing or invalid query parameters
401	Unauthorized	Missing or invalid API key
404	Not Found	Company or resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Code examples

Python

import requests

response = requests.get(
    "https://b2trust.com/api/v1/search",
    params={"q": "CD Projekt"},
    headers={"X-API-Key": "b2t_your_key"}
)

data = response.json()
for company in data["data"]:
    print(company["company_name"], company["country_code"])

JavaScript

const response = await fetch(
  "https://b2trust.com/api/v1/search?q=CD+Projekt",
  {
    headers: { "X-API-Key": "b2t_your_key" }
  }
);

const { data } = await response.json();
data.forEach(company => {
  console.log(company.company_name, company.country_code);
});

curl

curl -H "X-API-Key: b2t_your_key" \
  "https://b2trust.com/api/v1/search?q=CD+Projekt&country=PL&limit=5"