Skip to main content
POST
curl
Use this endpoint after POST /v3/kyb/search/ returns candidate companies when you need the ultimate beneficial owners: the shareholders plus the natural persons and corporate parents resolved through the ownership chain (registry_data.ubo_resolution). It is billed at the country’s UBO price (per-country prices). The tier delivered is the highest the country and the registry can serve, and registry_tier_delivered names what was billed: shareholders when the chain could not be resolved, basic when there is no ownership record at all. Available on v3 only. POST /v2/kyb/select/ and POST /v3/kyb/select/ keep their contract and price.

Authorizations

x-api-key
string
header
required

Body

application/json
kyb_response_id
string
required

Candidate handle from POST /v3/kyb/search/ (kyb_registry.companies[].kyb_response_id). Ephemeral — use it shortly after the search that produced it.

Maximum string length: 255
Example:

"69aeeb95febb0f1704042259"

vendor_data
string

Your identifier for this company; echoed back and stored with the business session.

metadata
object | null

Free-form JSON stored with the business session and echoed back.

save_api_request
boolean
default:true

Must be true (the default). KYB registry selects are always persisted so billing and retrieval can be tracked; false returns 400.

Response

Company retrieved and billed. kyb_registry carries the full profile; check data_resolved — when false the registry was still processing and the stored record completes automatically once it resolves.

request_id
string<uuid>

Id of the business session created for this retrieval. The stored record (visible in the console) keeps updating if the registry resolves after the response.

registry_tier_requested
enum<string>

The tier this endpoint sells: basic (Lite) for select, shareholders, ubo.

Available options:
basic,
shareholders,
ubo
registry_tier_delivered
enum<string>

The tier actually delivered and billed. Lower than requested when the country's registries hold no ownership data, or the registry has no ownership record for this company.

Available options:
basic,
shareholders,
ubo
kyb_registry
object

Full registry company profile.

vendor_data
string | null

Echo of the vendor_data you sent.

metadata
object | null

Echo of the metadata you sent.

created_at
string<date-time>