> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # KYB Registry Select > Retrieve the full registry profile of one candidate returned by `POST /v3/kyb/search/` — company details, officers, beneficial owners, addresses, industries, filings, and the complete raw registry payload. **Pairing with search.** Pass the candidate's `kyb_response_id` exactly as returned by the search. The handle is ephemeral and scoped to that search — select promptly, and re-search for a fresh handle rather than storing it. **Billing.** Each select is billed at the KYB registry price (search is free). The balance is checked before any registry call (`403` when short) and the charge is recorded against the created business session. **Persistence is mandatory.** Every select creates a business session (its id is the `request_id`) so billing and retrieval can be tracked; it appears in the console. `save_api_request` is accepted for symmetry but must be `true` (the default) — sending `false` returns `400`. **Resolution.** The API polls the registry for the full profile before responding. If the registry is still processing after polling, the response comes back with `fetch_status: "pending"` / `data_resolved: false` and sparse fields; the stored record completes automatically once the registry resolves (the business session status updates with it) — re-check it in the Business Console or by polling `GET /v3/session/{request_id}/decision/` (business sessions resolve through the same decision endpoint). **Status.** `kyb_registry.status` is Didit's assessment of the registry check: companies that are not active in the registry, or whose officers/ownership could not be derived, are routed to `In Review`; clean active companies are `Approved`. `registry_status` is the company's own status at the registry (e.g. `active`, `dissolved`). **Sandbox.** Keys from sandbox applications return a static resolved company without contacting any registry and without billing. Use this endpoint after `POST /v3/kyb/search/` returns candidate companies. Selecting a company is billable. It retrieves the full registry profile, stores the request as a Manual Check in the Business Console, and returns a `request_id` you can use to retrieve the saved business verification result. Didit waits for the source registry to finish before responding, so `fetch_status` is `resolved` in most responses. If a slow registry keeps the profile pending past that wait, the response returns `fetch_status: pending` with `data_resolved: false`, and Didit completes the saved check automatically as soon as the provider finishes — re-read the saved verification result instead of repeating the search, since a new search issues new `kyb_response_id` values. ## OpenAPI ````yaml POST /v3/kyb/select/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/select/: post: tags: - Standalone APIs summary: KYB registry company select (standalone) description: >- Retrieve the full registry profile of one candidate returned by `POST /v3/kyb/search/` — company details, officers, beneficial owners, addresses, industries, filings, and the complete raw registry payload. **Pairing with search.** Pass the candidate's `kyb_response_id` exactly as returned by the search. The handle is ephemeral and scoped to that search — select promptly, and re-search for a fresh handle rather than storing it. **Billing.** Each select is billed at the KYB registry price (search is free). The balance is checked before any registry call (`403` when short) and the charge is recorded against the created business session. **Persistence is mandatory.** Every select creates a business session (its id is the `request_id`) so billing and retrieval can be tracked; it appears in the console. `save_api_request` is accepted for symmetry but must be `true` (the default) — sending `false` returns `400`. **Resolution.** The API polls the registry for the full profile before responding. If the registry is still processing after polling, the response comes back with `fetch_status: "pending"` / `data_resolved: false` and sparse fields; the stored record completes automatically once the registry resolves (the business session status updates with it) — re-check it in the Business Console or by polling `GET /v3/session/{request_id}/decision/` (business sessions resolve through the same decision endpoint). **Status.** `kyb_registry.status` is Didit's assessment of the registry check: companies that are not active in the registry, or whose officers/ownership could not be derived, are routed to `In Review`; clean active companies are `Approved`. `registry_status` is the company's own status at the registry (e.g. `active`, `dissolved`). **Sandbox.** Keys from sandbox applications return a static resolved company without contacting any registry and without billing. operationId: post_v3_kyb_select parameters: [] requestBody: required: true content: application/json: schema: type: object required: - kyb_response_id properties: kyb_response_id: type: string maxLength: 255 description: >- Candidate handle from `POST /v3/kyb/search/` (`kyb_registry.companies[].kyb_response_id`). Ephemeral — use it shortly after the search that produced it. example: 69aeeb95febb0f1704042259 vendor_data: type: string description: >- Your identifier for this company; echoed back and stored with the business session. metadata: type: object nullable: true description: >- Free-form JSON stored with the business session and echoed back. save_api_request: type: boolean default: true description: >- Must be `true` (the default). KYB registry selects are always persisted so billing and retrieval can be tracked; `false` returns `400`. responses: '200': description: >- 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. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- 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. kyb_registry: type: object description: Full registry company profile. properties: uuid: type: string format: uuid description: Didit's id for this company record. node_id: type: string example: feature_kyb_registry status: type: string enum: - Not Finished - Approved - Declined - In Review description: >- Didit's assessment of the registry check (e.g. `In Review` when the company is not active in the registry or ownership data could not be derived). registry_status: type: string nullable: true enum: - active - dissolved - deregistered - see full details - authorised - appointed representative - unauthorised - inactive - no longer authorised - closed - struck off description: Normalized company status as reported by the registry. data_resolved: type: boolean description: >- `true` once the registry returned the full profile. `false` when the registry was still processing after polling — the stored record completes automatically once the registry resolves. company_name: type: string example: Tesco PLC registration_number: type: string nullable: true example: '00445790' country_code: type: string description: ISO 3166-1 alpha-2. example: GB region: type: string nullable: true description: >- Subdivision code when the registry is regional (e.g. `CA` for `US-CA`); empty otherwise. company_type: type: string nullable: true example: Public Limited Company incorporation_date: type: string format: date nullable: true example: '1947-11-27' registered_address: type: string nullable: true example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: type: string nullable: true example: GB412 8925 93 risk_level: type: string nullable: true description: Registry-reported risk level, when available. verification_status: type: string nullable: true description: Registry verification status, when available. is_from_registry: type: boolean description: >- Always `true` for this endpoint — the profile was retrieved from an official registry. fetch_status: type: string enum: - pending - resolved description: Registry fetch lifecycle. Mirrored by `data_resolved`. alternative_names: type: string nullable: true description: Previous/alternative registered names, when reported. nature_of_business: type: string nullable: true description: >- Activity description or classification code, when reported. registered_capital: type: string nullable: true registered_capital_amount: type: string nullable: true description: Decimal amount as a string, when reported. registered_capital_currency: type: string nullable: true description: ISO 4217 code, when reported. website: type: string nullable: true example: https://www.tesco.com/ email: type: string nullable: true example: customer.service@tesco.co.uk phone: type: string nullable: true example: '03301231688' legal_entity_identifier: type: string nullable: true description: LEI, when reported. location_of_registration: type: string nullable: true description: >- Registry/jurisdiction the company is registered with, when reported. vat_number: type: string nullable: true description: >- EU VAT number, when collected during the hosted registry step or edited afterwards. At select time this is typically not yet set — VIES validation runs when the end user submits the registry step in the hosted flow. vat_validation_status: type: string enum: - valid - invalid - could_not_validate - not_applicable description: >- Result of the EU VIES check run at registry submit. `not_applicable` when no VAT number was provided or the company is outside the EU VAT area (EU-27 plus Northern Ireland). vat_validated_name: type: string nullable: true description: >- Trader name registered with VIES, when the member state discloses it. Only set when the VAT number is `valid`. vat_validated_address: type: string nullable: true description: >- Trader address registered with VIES, when the member state discloses it. Only set when the VAT number is `valid`. vat_checked_at: type: string format: date-time nullable: true description: Timestamp of the VIES check. `null` when no check ran. financial_summary: type: object nullable: true description: >- Registry-reported share/capital details (currency, total shares, share classes), when available. officers: type: array items: type: object properties: uuid: type: string format: uuid name: type: string example: MELISSA BETHELL designation: type: string nullable: true description: >- Raw registry designation (e.g. `Director`, `Secretary`). role: type: string description: >- Normalized role derived from the designation. Full 17-value model set; registry parsing on this endpoint typically emits director, non_executive_director, secretary, chairman, or company_officer. enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - company_officer - settlor - protector - investor - other nationality: type: string nullable: true is_active: type: boolean description: >- `false` when the registry marks the appointment as resigned. kyc_status: type: string nullable: true enum: - Approved - Declined - Pending description: >- Status of an associated KYC session, when one was started for this officer. `null` otherwise. kyc_session_url: type: string nullable: true description: >- Verification URL of the associated KYC session, when one exists. description: >- Directors, secretaries, and other officers extracted from the registry. beneficial_owners: type: array items: type: object properties: uuid: type: string format: uuid name: type: string first_name: type: string nullable: true last_name: type: string nullable: true entity_type: type: string enum: - person - company description: >- Whether the owner is a natural person or a corporate entity. roles: type: array items: type: string description: Normalized roles (e.g. `ubo`, `shareholder`). ownership_min_shares: type: string nullable: true description: >- Lower bound of the ownership band reported by the registry (e.g. `25%`). ownership_max_shares: type: string nullable: true description: >- Upper bound of the ownership band reported by the registry. is_active: type: boolean kyc_status: type: string enum: - Approved - Declined - Pending nullable: true kyc_session_url: type: string nullable: true effective_ownership_percent: type: number nullable: true description: >- Parsed ownership percentage (max bound, falling back to min bound). description: >- Beneficial owners / persons with significant control extracted from the registry. Can be empty when the registry does not expose ownership. addresses: type: array nullable: true items: type: object properties: address: type: string type: type: string description: type: string description: All addresses reported by the registry. industries: type: array nullable: true items: type: object description: Industry classifications, when reported. accounts: type: object nullable: true description: >- Filing/accounts dates reported by the registry (e.g. `last_account`, `next_account`, `due_by_date`). registry_data: type: object nullable: true description: >- The complete raw registry payload (people, filings, announcements, identifiers, …) for audit and custom parsing. user_provided_data: type: object nullable: true description: >- Always `null` on this endpoint (used by the hosted KYB flow when end users edit registry data). confirmed_by_user_at: type: string format: date-time nullable: true description: Always `null` on this endpoint. last_console_edit_at: type: string format: date-time nullable: true description: Set when a console reviewer edits the record later. is_editable: type: boolean description: >- Whether the registry-sourced data can still be edited in the hosted flow/console. vendor_data: type: string nullable: true description: Echo of the `vendor_data` you sent. metadata: type: object nullable: true description: Echo of the `metadata` you sent. created_at: type: string format: date-time examples: Resolved company: summary: Full registry profile (officer list truncated for brevity) value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d node_id: feature_kyb_registry status: In Review registry_status: active data_resolved: true company_name: Tesco PLC registration_number: '00445790' country_code: GB region: '' company_type: Public Limited Company incorporation_date: '1947-11-27' registered_address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: GB412 8925 93 risk_level: low risk verification_status: verified is_from_registry: true fetch_status: resolved alternative_names: TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: https://www.tesco.com/ email: customer.service@tesco.co.uk phone: '03301231688' legal_entity_identifier: null location_of_registration: null financial_summary: currency: Pound (£) total_number_of_shares: '8174378721' meta_detail: Class_Of_Share: Ordinary officers: - uuid: a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b name: CHRISTOPHER JON TAYLOR designation: Secretary role: secretary nationality: null is_active: true kyc_status: null kyc_session_url: null - uuid: b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c name: MELISSA BETHELL designation: Director role: director nationality: British is_active: true kyc_status: null kyc_session_url: null beneficial_owners: [] addresses: - address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA type: legal_entity_registry_address description: registered office address industries: null accounts: last_account: 26 February 2025 next_account: 26 February 2026 due_by_date: 26 August 2026 registry_data: name: Tesco PLC registration_number: '00445790' status: active type: Public Limited Company incorporation_date: '1947-11-27' tax_number: GB412 8925 93 country_code: GB fetch_status: resolved industries_detail: - code: '47110' name: >- Retail Sale In Non-specialised Stores With Food, Beverages Or Tobacco Predominating description: null meta_detail: [] user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' Pending (registry still resolving): summary: >- Select stayed pending after polling — sparse fields, auto-completes server-side value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: 7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d node_id: feature_kyb_registry status: Not Finished registry_status: null data_resolved: false company_name: Tesco PLC registration_number: '00445790' country_code: GB region: null company_type: null incorporation_date: null registered_address: null tax_number: null risk_level: null verification_status: null is_from_registry: true fetch_status: pending alternative_names: null nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: null email: null phone: null legal_entity_identifier: null location_of_registration: null financial_summary: {} officers: [] beneficial_owners: [] addresses: null industries: null accounts: null registry_data: {} user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' '400': description: Validation error. Field-level problems use DRF's standard envelope. content: application/json: examples: Missing kyb_response_id: summary: '`kyb_response_id` is required' value: kyb_response_id: - This field is required. save_api_request=false rejected: summary: Selects are always persisted value: save_api_request: - >- KYB registry select must be saved so billing and retrieval can be tracked. '403': description: >- Permission denied. Returned when the `x-api-key` header is missing, malformed, revoked, or belongs to another environment — and also when the calling organization's balance cannot cover the call. Authentication failures return `403` with `{"detail": ...}`; this API never returns `401`. Credit shortfalls return `403` with `{"error": ...}` before any screening or provider call happens. content: application/json: examples: Missing or invalid API key: summary: No `x-api-key` header, or the key is invalid/revoked value: detail: You do not have permission to perform this action. Not enough credits: summary: Organization balance cannot cover the call value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Rate limit exceeded. All POST/PATCH/DELETE endpoints share a budget of 300 write requests per minute per API key. The response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` headers. content: application/json: examples: Write rate limit exceeded: summary: More than 300 write requests in the current minute value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/kyb/select/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" }' - lang: python label: Python source: >- import os, requests search = requests.post( "https://verification.didit.me/v3/kyb/search/", headers={"x-api-key": os.environ["DIDIT_API_KEY"]}, json={"country_code": "GB", "name": "Tesco"}, timeout=60, ).json() kyb_response_id = search["kyb_registry"]["companies"][0]["kyb_response_id"] resp = requests.post( "https://verification.didit.me/v3/kyb/select/", headers={"x-api-key": os.environ["DIDIT_API_KEY"]}, json={"kyb_response_id": kyb_response_id, "vendor_data": "company-1234"}, timeout=90, # waits for the registry to resolve the full profile ) resp.raise_for_status() company = resp.json()["kyb_registry"] print(company["company_name"], company["registry_status"], company["status"]) - lang: javascript label: JavaScript source: >- const res = await fetch('https://verification.didit.me/v3/kyb/select/', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ kyb_response_id: '69aeeb95febb0f1704042259', vendor_data: 'company-1234', }), }); const data = await res.json(); console.log(data.kyb_registry.company_name, data.kyb_registry.registry_status); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````