KYB API
Company search, company detail lookup, and document retrieval
The KYB API is the live Umbrella /kyb/* set of endpoints, authenticated the same way as the rest
of Umbrella API (bearer token from POST /auth). It is current, not legacy.
What it returns
A company search by name and jurisdiction, full company detail (directors, ownership, filings) for a resolved company, and retrieval of an individual company document or transparency-register entry.
Request
POST /kyb/search
| Field | Required | Description |
|---|---|---|
country | yes | ISO 3166-1 alpha-2 country code |
name | one of name or companyNo | Company name, fuzzy matched |
companyNo | one of name or companyNo | Official registration number, exact match |
locality | no | City or locality, narrows results |
POST /kyb/company/details
| Field | Required | Description |
|---|---|---|
transactionId | yes | UUID from the /kyb/search response |
companyId | yes | UUID from the /kyb/search response |
include | no | Data packages to retrieve (officers, addresses, ownerships and further packages). All default to false, and each enabled package is priced separately. |
POST /kyb/company/document/retrieve
| Field | Required | Description |
|---|---|---|
transactionId | yes | UUID from the originating search/details call |
companyId | yes | UUID |
linkToken | yes | Opaque token from the documents or transparency list in the details response |
Response
search returns status (boolean) and data, an array of matches. Each match carries
transactionId and companyId, both of which the caller passes to /kyb/company/details, plus
name and status.
details returns status and a data object whose company holds legalName,
tradingNames, status, companyType and the packages requested through include.
document/retrieve returns a binary file stream; the Content-Type header reflects the format,
typically application/pdf. It is scoped to the transactionId and companyId the linkToken
was issued for.
Decision
The caller picks a match from the search array, carries its transactionId and companyId into
details, and asks there only for the packages it needs, since each one is priced separately;
document/retrieve is used only when a specific filing or register document is required.
Test cases
Pending.