KYB
Company search by name or register number, type-ahead suggestions, and the unified company record
- Universe:
- Umbrella
- Status:
- live
- Access:
- Contact IDCanopy for credentials and product access.
- Testing:
- Sandbox test data
Verify businesses by finding the right company, retrieving its register information and exploring officers and ownership. These records can support a broader onboarding journey with personal identification, screening and account checks.
Read about KYB on IDCanopy.com. The technical scope and operations documented below describe the current API.
The KYB API is the Umbrella /kyb/* set of endpoints, version 3.0.0. It uses the same bearer token as
the rest of Umbrella API (POST /auth, valid one hour) and the same base URLs
(Environments). Every key in requests and responses is snake_case; there are no
camelCase aliases.
Three operations: GET /kyb/suggest completes a search box for free, POST /kyb/search returns
candidate companies, POST /kyb/company/details returns the unified record of one candidate.
1. Suggest (type-ahead)
GET /kyb/suggest?q=<text>&country=<ISO2> returns up to 10 suggestions for a search box. q is 3 to
100 characters, country is optional. No paid provider is called, no transaction is created, nothing is
billed or counted against your transaction limit. The limit is 120 requests per minute per customer;
above it the answer is 429 with code RATE_LIMITED and a Retry-After header. Debounce the input.
Each suggestion tells you how to search for it: with an identifier (plus country and, when present,
court), search by identifier; with a provider id and no identifier, search with pick; otherwise search
by name and country. A source that fails or takes longer than 1.5 seconds is skipped and reported in
warnings; the call still answers.
2. Search
POST /kyb/search takes exactly one of name, identifier or pick; any other combination is a 400.
Every result row carries the transaction_id (the same on all rows of one response) and the company_id
that details needs.
By name. name and country (ISO 3166-1 alpha-2) are required. locality is required when
country is not DE, GB, FR or AT. The register or data provider is chosen from country; provider
overrides that choice. A name search that finds nothing also returns free suggestions beside the empty
data, with no second paid call.
{ "name": "Example Holding GmbH", "country": "AT" }By register number. One exact lookup, not a fuzzy list:
{ "identifier": { "scheme": "REGISTRATION_NUMBER", "value": "HRB 00000" }, "country": "DE", "court": "Beispielstadt" }Supported: DE (HRB and HRA numbers; several courts can share a number, so send court), GB
(the company number), AT (Firmenbuch number with its check letter), FR (SIREN, 9 digits). Any other
scheme or country is a 400 naming the expected format. For schemes VAT and EUID the value's prefix
gives the country. Live rows carry matched_by with the canonical value. The legacy field company_no
is forwarded and ignored; do not use it to search by number.
By pick. Selects a suggestion from /kyb/suggest that carries a provider id but no identifier.
Each row has transaction_id, company_id (provider-prefixed, opaque, never build or edit it; a UUID
only in the sandbox), name, status, registration_number, address_line, country and, for an
identifier search, matched_by. metadata.paid_provider_calls says what the search paid for; a name
search never bills a feature. If a provider could not answer and the rows come from stored data,
metadata.warnings carries PROVIDER_UNAVAILABLE_SERVED_FROM_STORAGE; those rows may be out of date.
3. Details, with include
POST /kyb/company/details takes the pair from one search row. A company_id is valid only under the
transaction_id of the search that returned it; any other pairing is a 400 with code
COMPANY_NOT_IN_TRANSACTION. A company_id read from a company you already fetched under the same
transaction_id (an owner, a general partner) is also accepted, so an ownership chain can be walked
without a new search, up to a default depth of 5.
| Field | Required | Description |
|---|---|---|
transaction_id | yes | UUID from the search row. |
company_id | yes | From the search row, or read from a fetched company under the same transaction. |
include | no | Packages to fetch. All default to false. |
visibility | no | minimal (default; basic is an alias) returns resolved values. extended returns each field as {claims, resolved}: every provider's answer with source and time, and the chosen value. |
refresh_policy | no | cached (default) reuses stored provider data younger than 30 days. refresh fetches again and is billed. Anything else is a 400. |
timeout_ms | no | Accepted and ignored. |
What each include flag gates. A section that was not requested is an empty array under its key,
never a missing key and never null; officerships, shareholdings, financials and ubo are always
present. Parties that only an omitted section referenced are left out of parties.
include | Fills |
|---|---|
officers | officerships and their parties. Where enabled for your account, each officership also carries can_represent: whether the role may represent the company at all (yes, no or unknown, with the rule and the legal norm). It is not the number of signatures needed, which stays signature_right. Not enabled in production yet: when it is not enabled the key is absent, so do not require it. |
ownerships | shareholdings, ownership_walk and free_float, including the holding derived from a sole trader's legal form. |
financials | financials, where the provider has figures. |
transparency | ubo, where the provider has a transparency register. |
representation_chain | representation_chain: for a company whose general partner is a company, the partner and the people who sign for it, with the combined signing rule. A billed feature; implies officers. |
addresses, documents | Nothing: addresses are always returned, and documents carries what the provider's company report already contains. |
{
"transaction_id": "11111111-2222-4333-8444-555555555555",
"company_id": "xxxx:co_at_000000000000000a",
"include": { "officers": true, "ownerships": true }
}The response is status, data and metadata. data is the unified company itself: flat, snake_case,
with legal_name, status, legal_form, registration_number, share_capital, addresses,
identifiers, signature_rules, and the id-linked lists parties, officerships, shareholdings,
ubo, financials, documents, filings, relationships. An absent key means unknown; there are no
nulls. Where a field has modeled beside native, read modeled when present. Every enumerated value
in a response is an open set: ignore values you do not know.
metadata carries confidence and completeness (0 to 1), source, generated_at, from_cache,
source_fetched_at, paid_provider_calls (paid provider requests this call made) and
billable_features (for example representation_chain). Read the cost from the last two, not from
from_cache: a reused root company can still come with a freshly fetched slice.
4. Documents
Where the provider's company report includes a register extract, it is in documents[] of the details
response as a provider-hosted link: file_url with file_url_expires: true means the link is
time-limited, so download it when you receive it. There is no separate document download endpoint, and
include.documents gates nothing.
Slow calls and warnings
Details answers within about 25 seconds with everything available. A section still running at that
point is reported as a PENDING_SLICE warning and is completed from storage on a later call, without
buying it twice. Use a client timeout of at least 90 seconds, 600 when you request chains. Other warning
codes: SLICE_FAILED (the provider run failed; not bought again for 24 hours unless refresh_policy is
refresh), OWNERSHIP_PARTIAL (the ownership walk stopped early, completeness is reduced; do not
present the chain as complete), REGISTER_NUMBER_CLASH, REGISTER_DOCUMENT_UNAVAILABLE,
REPRESENTATION_CHAIN_UNRESOLVED. The set is open.
A provider's daily spend limit ends in 429 with code DAILY_LIMIT_REACHED, the provider named and no
Retry-After. Retry after 00:00 UTC; do not loop.
Errors
Branch on the HTTP status and on code when present, never on the text. 400 is validation (the
service's message is passed through), 401 and 403 are token and product access, 429 is a daily spend
limit, the suggest rate limit or the account transaction limit, 502 means the KYB service refused the
gateway (a configuration problem on our side), 503 means the KYB service did not answer. The shapes per
code are in the reference and in Errors.
Sandbox
The sandbox serves a fixed set of invented test companies in the same shape, with documented
differences: ids are UUIDs, completeness is fixed, paid_provider_calls is empty, metadata.sandbox is
true, transient states (PENDING_SLICE, SLICE_FAILED, OWNERSHIP_PARTIAL) and pick are not
simulated. A request that matches no test company is a 400 Failed to retrieve test cases. The test
companies, what each one shows and their ids are on the sandbox test data page.
Reference
Umbrella API reference, KYB group. Specification version 3.0.0, from the KYB team.