# Get resolved billing notification config (defaults merged)
Source: https://docs.topograph.co/api-reference/billing-notifications/get-resolved-billing-notification-config-defaults-merged
get /v2/billing/notifications/config
# Get resolved workspace billing notification view (override + account)
Source: https://docs.topograph.co/api-reference/billing-notifications/get-resolved-workspace-billing-notification-view-override-+-account
get /v2/billing/notifications/workspaces/{workspaceId}/config
# List recent billing notification events
Source: https://docs.topograph.co/api-reference/billing-notifications/list-recent-billing-notification-events
get /v2/billing/notifications/recent
# Remove workspace high-usage override
Source: https://docs.topograph.co/api-reference/billing-notifications/remove-workspace-high-usage-override
delete /v2/billing/notifications/workspaces/{workspaceId}/config
# Upsert billing notification config
Source: https://docs.topograph.co/api-reference/billing-notifications/upsert-billing-notification-config
patch /v2/billing/notifications/config
# Upsert workspace high-usage override
Source: https://docs.topograph.co/api-reference/billing-notifications/upsert-workspace-high-usage-override
patch /v2/billing/notifications/workspaces/{workspaceId}/config
# Get the current account credit balance
Source: https://docs.topograph.co/api-reference/billing/get-the-current-account-credit-balance
get /v2/billing/balance
Returns the account's remaining credit balance, a derived health status, the auto-topup posture, and the configured low-balance thresholds. This is the remaining balance — for consumption use GET /v2/workspaces/usage.
# Download Company Extract as PDF
Source: https://docs.topograph.co/api-reference/data/download-company-extract-pdf
get /v2/company/{requestId}/pdf
Render the result of a company data request as a one-file PDF extract: company profile, legal representatives, shareholders, ultimate beneficial owners, other key persons, establishments and the ownership graph, whichever of those the request asked for and received.
This endpoint is free and is never billed. It renders data the request already paid for, so a PDF can be re-downloaded as often as needed and never triggers a new fetch.
Completeness: by default the extract renders whatever has arrived, matching `GET /v2/company/{requestId}`, which also returns partial results while a request runs. A partial extract says so on its own face: a "Data completeness" section at the end of the extract lists every requested datapoint and whether it was included, is still being retrieved, or failed, and the `X-Topograph-Data-Status` response header carries `complete` or `partial`. Pass `requireComplete=true` to get a 409 instead of a partial file, for an archival export that must not be a snapshot of a half-finished request.
Only datapoints decide completeness. Documents are delivered as separate files and never appear in the extract, so a document still downloading does not hold the PDF back.
# Get Company Data and Documents
Source: https://docs.topograph.co/api-reference/data/get-company-data-and-documents
post /v2/company
Retrieve company data and documents for a specific company.
You can either:
1. Create a new request by providing countryCode, id, dataPoints, optional mode, and optional document IDs.
2. Re-fetch a previous request by providing requestId (returns cached data and is not billed again).
Available datapoints include:
- company: core company information
- legalRepresentatives: directors, managers, and signing officers
- otherKeyPersons: auditors, board members, and similar roles when available
- establishments: branches and secondary locations when available
- shareholders: shareholder structure
- subsidiaries: downstream equity holdings when available
- ultimateBeneficialOwners: beneficial owner information
- availableDocuments: list of available official documents
- graph: ownership graph traversal (verification mode only)
Legacy companyProfile is still accepted and maps to company + legalRepresentatives for billing.
Modes:
- verification (default): authoritative live registry sources. Countries served only by a non-authoritative source are prefill-only, and fail here with authoritative_source_unavailable.
- prefill: cheapest compatible fast source; unsupported datapoints fail with fast_source_unavailable. The graph datapoint has no fast source and always fails this way in prefill mode.
To retrieve documents, first request availableDocuments to discover document IDs, then pass those IDs in the documents field of a follow-up request.
# Get Company Request Result
Source: https://docs.topograph.co/api-reference/data/get-company-request-result
get /v2/company/{requestId}
Retrieve the result of a previous company data request by its ID. Returns the latest available data including all subrequests (documents, additional datapoints).
This endpoint is free and will not be billed again. Use it to poll for results after creating a request via POST /v2/company.
# Get Onboarding Data (Deprecated)
Source: https://docs.topograph.co/api-reference/data/get-onboarding-data-deprecated
post /v2/onboarding
Deprecated: Use POST /v2/company with mode: "prefill" instead.
This endpoint is internally routed as a company request with mode: "prefill" and a 50-cent budget cap. The result status is reported under dataStatus.dataPoints.company.
# Add monitoring for a company
Source: https://docs.topograph.co/api-reference/monitors/add-monitoring-for-a-company
post /v2/monitors
# Get monitor change logs
Source: https://docs.topograph.co/api-reference/monitors/get-monitor-change-logs
get /v2/monitors/{id}/logs
# Get monitor details
Source: https://docs.topograph.co/api-reference/monitors/get-monitor-details
get /v2/monitors/{id}
# List monitored companies
Source: https://docs.topograph.co/api-reference/monitors/list-monitored-companies
get /v2/monitors
# Stop monitoring a company
Source: https://docs.topograph.co/api-reference/monitors/stop-monitoring-a-company
delete /v2/monitors/{id}
# Get pricing for a country
Source: https://docs.topograph.co/api-reference/pricing/get-pricing-for-a-country
get /v2/pricing
Returns pricing for a specific country.
The response includes:
- blocks: SKUs, datapoint coverage, verification and prefill mode prices (with an authoritative hint), and optional includedDocuments
- Flat fields: per-datapoint availability and prices (legacy companyProfile included)
- Company search and availableDocuments listing are free
Prices are in credits (account balance units). Rates may vary by subscription plan.
# Find a company across countries from its name
Source: https://docs.topograph.co/api-reference/search/global-search
post /v2/search/global
Takes what you know about a company in one free-text `query` (the name plus a city, a country, a registration number, a website…) and returns candidates across the countries Topograph covers, best first, each with a registration number you can pass to `/v2/company`, a match strength and an explanation of the evidence.
The search is agentic and bounded: it reads the legal form and any address, checks Topograph's index, asks the web when the name and that data are not enough, confirms in the most likely registers (US states included), and stops as soon as one candidate is a strong match. At most 15 live and web searches, at most 100 seconds.
**Countries.** `countries` limits the search to some countries: `["US"]` searches every US state and nothing else, `["US-DE", "US-NY"]` two states, `["CA"]` every Canadian jurisdiction (the federal register `CA-FED` and the provinces and territories, `CA-ON`, `CA-QC`…), `["DE", "AT", "CH"]` three countries. Nothing outside them is searched or returned.
**Status.** `resolved`: one strong match, the candidate with `selected: true`, which you can use without a person checking. `ambiguous`: several plausible candidates (the same name in two countries, two namesakes in one register, a US company whose state is not established), all returned with their evidence. `not_found`: nothing acceptable; `reason` says why, and `likelyCountryCode` names the country the evidence pointed to even when Topograph does not cover it or it is outside `countries`.
**Company status.** A candidate's `isActive` is indicative only and may be out of date; read `company.status` from `/v2/company` before relying on it.
**Alpha.** The request and response shapes may still change.
**Billing.** A search is billed only when it succeeds: `status: resolved`, one good candidate. Ambiguous and not-found searches, inputs rejected as not a legal entity, failures and timeouts are not billed. `usage.priceCents` shows what was charged; the price is on the pricing page.
**Streaming.** With `stream: true` and `Accept: text/event-stream`, the endpoint emits `progress` events (what the search is doing right now, and the candidates found so far), then one `complete` event with the final response, or an `error` event.
# Search for companies
Source: https://docs.topograph.co/api-reference/search/search-for-companies
get /v2/search
This endpoint allows you to search for companies based on a country code and a query string.
The search can be performed using either a company legal name, commercial name, historical name, or registration number. Capabilities vary by country. A Legal Entity Identifier (LEI) is accepted as the query in every country and returns the company it designates.
**Standard Mode (stream=false or omitted):**
Returns JSON array of results once all search sources have completed.
**Streaming Mode (stream=true):**
Returns Server-Sent Events (SSE) with progressive results as each search source completes. The endpoint emits named events:
- `progress`: Partial results from completed sources
- `complete`: Final results when all sources finish
- `error`: If the search fails
Streaming is beneficial for countries with multiple search sources (e.g., Germany queries both Unternehmensregister and Handelsregister), providing faster time-to-first-result.
Response times vary by country: from sub-second to up to 10 seconds.
# Create or replace a credential
Source: https://docs.topograph.co/api-reference/vault/create-or-replace-a-credential
put /v2/workspaces/{name}/vault/{sourceKey}
Payload shape depends on the sourceKey's format. Hit `GET /v2/vault/sources` for the list of accepted fields. Each PUT bumps the entry version.
# Delete a credential
Source: https://docs.topograph.co/api-reference/vault/delete-a-credential
delete /v2/workspaces/{name}/vault/{sourceKey}
# Get one vault entry by sourceKey (metadata only)
Source: https://docs.topograph.co/api-reference/vault/get-one-vault-entry-by-sourcekey-metadata-only
get /v2/workspaces/{name}/vault/{sourceKey}
# List supported credential sources
Source: https://docs.topograph.co/api-reference/vault/list-supported-credential-sources
get /v2/vault/sources
Returns every sourceKey accepted by `PUT /v2/workspaces/:name/vault/:sourceKey`, with the required payload fields and their `secret` flags.
# List vault entries on the workspace (metadata only)
Source: https://docs.topograph.co/api-reference/vault/list-vault-entries-on-the-workspace-metadata-only
get /v2/workspaces/{name}/vault
# Create a new workspace
Source: https://docs.topograph.co/api-reference/workspaces/create-a-new-workspace
post /v2/workspaces
# Delete a workspace
Source: https://docs.topograph.co/api-reference/workspaces/delete-a-workspace
delete /v2/workspaces/{name}
# Get usage report per workspace
Source: https://docs.topograph.co/api-reference/workspaces/get-usage-report-per-workspace
get /v2/workspaces/usage
# List all workspaces
Source: https://docs.topograph.co/api-reference/workspaces/list-all-workspaces
get /v2/workspaces
# Update a workspace
Source: https://docs.topograph.co/api-reference/workspaces/update-a-workspace
patch /v2/workspaces/{name}
# Changelog
Source: https://docs.topograph.co/changelog
Stay updated with the latest changes and improvements to Topograph
Every release below is published to an RSS feed at [www.topograph.co/changelog/rss.xml](https://www.topograph.co/changelog/rss.xml), one entry per week, delivered once the week is complete, back to the very first release. Point a feed reader at it, or run `/feed subscribe https://www.topograph.co/changelog/rss.xml` in a Slack channel to get each release posted there.
## UBO identification through ownership and control
[Ownership graphs](/essentials/ownership-graph#ubo-calculation) identify individuals through majority-control chains and mixed ownership and control structures, alongside accumulated ownership.
A person holding 51% of a company that owns 40% of the target qualifies through control, while their economic ownership remains 20.4%. The response identifies the qualifying method in `flags.uboCalculationMethod`.
This covers control established from ownership percentages. Voting agreements, board appointment powers and veto rights are not assessed.
## Quebec activity codes
Quebec company records return the register’s economic activity codes under `company.activities.CAE_QC`, preserving the primary and secondary assignments. The key identifies Quebec’s classification; it does not identify Portugal’s CAE or assert an edition absent from the record.
## Optional strict active-company search
Use `strictActiveOnly=true` on country or worldwide search to exclude unknown statuses as well as inactive companies. The default search behavior is unchanged. The Topograph MCP search tools expose the same option as `strict_active_only`.
An active search result reflects the search source’s status and freshness. Use a company lookup when you need a current verification.
## 🇩🇪 Germany: fallback beneficial owners flagged
When no natural person owns or controls a German company, the law lists its legal representatives or managing partners as beneficial owners instead (*fiktive wirtschaftlich Berechtigte*, § 3 Abs. 2 S. 5 GwG). Each beneficial owner now carries `control.isFallback`: `true` for these fallback owners, `false` for owners the register records through shares, voting rights or other control.
The `Fictitious UBO (§ 3 Abs. 2 S. 5 GwG)` description prefix is unchanged, so existing integrations keep working. Beneficial owners delivered for accounts without their own register access now also carry the prefix and the flag, return the register's own wording in `control.description`, and no longer state a direct or indirect `nature` the register does not give. See the [Germany country guide](https://www.topograph.co/countries/de#ultimate-beneficial-owners).
## The Topograph MCP: company data in your AI agent
AI agents can now look up companies through Topograph. Connect Claude, ChatGPT, Cursor, VS Code, Gemini CLI or your own agent to `https://mcp.topograph.co/mcp`, sign in with your Topograph account or use an API key, and ask in plain English: who runs this company, who owns it, which official documents exist.
The agent searches the register for free, checks the price for free, and only then runs the paid lookup. Requests are billed like the API, from the same wallet, and appear in your request history. Paid tools ask for your confirmation in most clients, every result states what it cost, and document orders only go through at the price you were shown.
Each person can spend up to 1,000 credits a month through the MCP. Development environments have their own server, `https://mcp.sandbox.topograph.co/mcp`, with generated data and no cap. See [Use Topograph from your AI agent](/guides/mcp).
## The Designer MCP is now the Topograph Wizard
The integration helper that gives your coding agent live coverage, pricing, docs and code samples is now called the Topograph Wizard, at `https://mcp.topograph.co/wizard`. The previous address keeps working, so existing setups need no change.
The Claude Code plugin now installs both servers, plus a `/topograph:lookup` command for company lookups. Update the plugin from `/plugin` in Claude Code to get both. See [Topograph Wizard](/guides/topograph-mcp).
## AI agents page in the app
The new [AI agents page](https://app.topograph.co/agents) lists every supported client with one-click install links and ready-to-copy setup, for live and development environments. It also shows what you have spent through the MCP this month and your recent agent lookups.
## One activity key per classification and revision
Company and establishment activity responses now return one canonical spelling for each classification and edition. Source aliases are merged, preserving distinct codes and removing duplicates. Different revisions stay separate.
The published OpenAPI schema lists every authorized activity key and excludes additional spellings. The [complete key list](/essentials/activity-codes#authorized-response-keys) documents the revision each key identifies.
If you read `NAFREV2` or `NAFRev2`, switch to `NAF_REV2`; use `WZ_2008`, `WZ_2025` and `ATECO_2025` in place of spellings without underscores. The international standards use only `ISIC` (Rev. 5) and `NACE` (Rev. 2.1). `SBI` has no guaranteed edition; the duplicate `SBI_2025` spelling is removed. See the [complete migration table](/guides/standardization#revision-explicit-keys) before updating your integration.
## 🇧🇷 Brazil: CNPJ data in prefill mode
Brazil adds legal and commercial name search, exact numeric and alphanumeric CNPJ lookup, company details, published officers and eligible equity partners from periodic public registration data. Use `"mode": "prefill"`; authoritative verification, official documents and certified UBO are unavailable. See the [Brazil guide](https://www.topograph.co/countries/br).
Public-issuer shareholder disclosures supplement QSA where equity owners are not published, including reported percentages and share counts when available. Holdings retain their filing provenance and exclude indirect ownership links and anonymous market totals.
Reporting issuers can also return executive officers, board and committee members, and disclosed company participations under `subsidiaries`. These participations retain dated filing provenance without inferring control or a direct or consolidated ownership percentage.
Brazilian activity codes use the new `CNAE_BR` key. The serving publication does not state an edition for each record, so this key does not guarantee a revision. Spain continues to use `CNAE_2009`.
## LEI in company identifiers
The `company` datapoint now returns `company.identifiers.lei` when an existing company identifier uniquely matches a registration or validation reference in GLEIF. Existing identifiers stay available. Country coverage pages list GLEIF as the supplementary source for this identifier. Coverage varies by jurisdiction and entity; an absent field does not prove that the company has no LEI. See [Legal Entity Identifier](/essentials/retrieve_company#legal-entity-identifier-lei).
## Compliance flags: country coverage in pricing and MCP
Country pricing details and the [Topograph Wizard](/guides/topograph-mcp) describe the compliance flags each country covers, what they mean locally, and which datapoint and request mode return them.
Each covered flag lists its available fields and whether the register explicitly reports `active: false`. An empty coverage list means no flags are covered for that country. See [Compliance signals](/essentials/compliance-signals#country-specific-coverage).
## 🇧🇪 Belgium: UBO compliance flags
Requesting `company` in verification mode returns an explicit BCE notice for non-compliance with UBO obligations under `company.complianceFlags.uboAdministrativeStrikingOff`, with its effective date and observation time when available.
The notice can coexist with an active company and a normal legal situation. It does not mean the company is dissolved. A missing flag means no formal statement is available, rather than confirmation that the company complies.
Requesting `ultimateBeneficialOwners` in verification mode also returns `company.complianceFlags.uboConfirmationOverdue`. The Belgian UBO Register explicitly reports overdue or valid annual confirmation, with its last confirmation date and observation time when available.
The confirmation flag is included even without a company profile and remains independent of any BCE administrative notice.
The request overview displays only compliance flags explicitly returned for that request, with their register statement, source and dates. Explicit negative statements remain visible; missing evidence does not create a warning or imply compliance. Both Belgian signals are documented in the [Belgium country guide](https://www.topograph.co/countries/be#compliance-flags) and covered by weekly monitoring.
## Global search: search the United States only, or the countries you choose
[Global search](/guides/global-search#searching-only-some-countries) takes a `countries` filter. `["US"]` searches every US state and nothing else: the state is looked for in public sources first, then the state registers are asked, the usual incorporation states first. `["US-DE", "US-NY"]` limits it to two states, `["DE", "AT", "CH"]` to three countries. Unlike the `countries` hint, nothing outside the filter is searched or returned. When nothing is found there and the evidence places the company elsewhere, the search ends `not_found` with the new reason `outside_countries`, and `likelyCountryCode` says where.
A candidate now carries `selected: true` when it is the company: at most one, the first, exactly when `status` is `resolved`, so you can use it without anyone checking. Two companies with the same name in one register, with nothing to tell them apart, now end `ambiguous` (and are not billed) instead of `resolved` on one of them. A US search that asked the state registers and found nothing now ends `no_register_match`, not `country_not_covered`. See [The company: `selected`](/guides/global-search#the-company-selected).
The response is also simpler. Global search is in alpha, and these changes break the previous shape:
* The request is `query` alone, plus `countries`, `activeOnly` and `stream`: `name` and `hints` are gone. Put everything you know in `query` ("Bamberger GmbH, Wien, FN 370916s"); a request that still sends `name` or `hints` is refused with `400 invalid_request`.
* `query` in the response is now a flat reading of your text: `name`, `latinName`, `legalForm`, `address`, `identifier`, `website`, `mentionedCountries` and `sourceCountry`, instead of a `hints` object.
* `steps` and `countries` are gone from the response. While streaming, `progress` events carry `activity`, what the search is doing right now as sentences to show, instead of `steps` and `countries`.
* `likelyCountryCode` moves from `query` to the top level, `query.text` and `candidates[].rank` are gone (candidates come best first).
* Each response has an `id`. Quote it when you contact support about a search.
* `isActive` on a candidate is now documented as indicative: it may be out of date. Read `company.status` from `/v2/company` before relying on it.
## Development environments: company ids as production returns them
A development environment now hands out the company ids production does, and refuses the ones production refuses.
* **🇩🇪 Germany:** companies come back under their full registration, court, register type and number (`München HRB 228960`): in search results, for companies you define, and as shareholders and subsidiaries. A bare register number such as `228960` fails every datapoint with `invalid_request`, as it does in production. A search for a number alone returns it under a full id, as a partial match.
* **🇵🇱 Poland:** companies come back under their `krs-` id (`krs-0000028860`).
Each generated company now has identifiers of its own. Where a country builds its EUID or VAT number from the registration number, the sandbox builds it the same way, and German and French VAT numbers and French SIRETs carry valid check digits. Every company in a country used to share one example value.
Shareholders and subsidiaries carry ids in the country's own format, so `/v2/company` resolves them, and no generated date is later than 30 September 2026. Generated data stays deterministic, but these values change once: if your tests pin them, update the expected values.
## 🇲🇹 Malta: published roles, and the company's area of activity
Company statuses now use a fixed mapping, without AI. A status outside the known list preserves the register wording, returns `UNKNOWN`, and omits `active`. See the [Malta status mapping](https://www.topograph.co/countries/mt#company-status).
Malta roles now come from a closed list, published with the [Malta coverage](https://www.topograph.co/countries/mt). Each role the Malta Business Registry records always returns the same `englishTranslation` and `standardized` value; secretaries and auditors are standardized as `Secretary` and `Auditor`.
Some roles moved between lists to follow Maltese law:
* **Judicial representatives** are returned under `otherKeyPersons`. They represent the company in court proceedings only and cannot bind it.
* **Liquidators**, **foundation administrators** and the **partners vested with the administration** of a partnership are returned under `legalRepresentatives`. These entities used to come back with no legal representative.
`activityDescription` now holds the area of activity the company declared to the register. `activities.NACE_REV2` carries its NACE Rev. 2 code as declared, and `NACE` and `ISIC` the same activity standardized to NACE Rev. 2.1 and ISIC. Entities that declared none return neither; `activityDescription` used to repeat the legal form.
Malta legal forms gain ISO 20275 codes for foundations, associations, cooperatives, the Societas Europaea and the EEIG. See the [Malta guide](https://www.topograph.co/countries/mt).
Malta documents now always land in the same group, following the filing type the register records. Alterations to the Memorandum and Articles are returned under `articlesOfAssociation`, annual accounts under `financialStatements`, and annual returns under `annualReturns`. The same filing used to move between groups from one request to the next.
## Consistent legal-form and role values
The country catalogue and development environments now use the same standardized legal-form and role values as the API schema. Values such as `LimitedLiabilityCompany` and `VicePresident` become `Limited Liability Company` and `Vice President`. The correction also applies to live responses that use these country lists.
Other key persons use their own role categories, including `Board Member` and `Registered Agent`. Local role names and legal-form names stay available alongside the standardized values. If your integration maps the old strings, update those mappings.
Known role labels use published translations and standardized values, including the Italian office list, Danish management functions and Chinese representative headings. UK officer roles use the registered office even when a separate occupation names another job. Limited partners, supervisory-only officers and people authorised only to accept service are returned under `otherKeyPersons`.
Polish management board offices and procurators now use fixed role values, including `Authorized Signatory` for prokura. Swiss offices keep their recorded signing context. Luxembourg returns supervisory and other non-signing office holders under `otherKeyPersons`, while legal representatives retain recorded signing restrictions and permanent representatives of corporate office holders.
Irish company profiles now include declared NACE Rev. 2 activity codes from CRO Open Data where recorded, with formal conversions to current NACE and ISIC. Registered business names are excluded. Legal forms in Hungary, Lithuania, Slovenia, the Isle of Man and the Marshall Islands gain precise ISO 20275 codes where GLEIF publishes a matching form.
Spanish office-only appointments now appear under `otherKeyPersons` alongside the existing legal-representative roster. Known compound offices keep their separate capacities. Norway distinguishes an ordinary board appointment from an individual signing mandate, and returns fixed owner, manager, accountant and board-chair values.
Moldova, Portugal, Jersey and California now return available non-representative offices under `otherKeyPersons`. France retains holders whose office code is missing, and returns a secretary general without a separate signing mandate under `otherKeyPersons`.
Role titles alone do not establish an individual signing mandate. Texas and DC qualify partnership and management roles by the recorded entity context; foreign entities receive no assumed domestic authority or domicile.
Activity codes retain their register edition where established: Estonia preserves EMTAK 2008 and 2025 assignments; Belgium respects each NACE-BEL stamp; Iceland retains ÍSAT 2008 national subclasses; Bosnia and Herzegovina preserves KD BiH 2010. Unknown editions retain native codes without a guessed standard revision. California, Kentucky, Hawaii and Vermont retain available registered business activity or purpose text separately from legal form. See [Standardization](/guides/standardization).
## Expected delivery windows for beneficial owners ordered through a local partner
Where beneficial-owner data is ordered by hand through a local partner, the catalog now states the expected delivery window in business days.
It is 1–2 business days for China, Croatia, Portugal, Serbia, Slovakia and Slovenia, 3–5 for Czechia and Germany, and 14–20 for Cyprus and Romania. Ukraine's certified register extract, which carries the beneficial owners, is 1–2 business days.
The window appears on each country's pricing page and in a separate "Business days (est.)" column of the price-list workbook's Speed tab. In `/v2/catalog` it is `manualDeliveryEstimate` on data blocks and documents, and the Topograph Wizard returns it as `estimatedBusinessDays`.
These are estimates, kept apart from the measured response times, which are unchanged.
## Search by LEI, in every country
A Legal Entity Identifier is now a search query. Send the 20-character LEI to `GET /v2/search` and the answer is the company it designates, under the registration number `/v2/company` takes: `96950066U5XAAIRCPA78` returns La Banque Postale, `421100645`.
It returns that company or nothing, never a list of similar names. A result is an `id` match when the register holds the company under the registration number published for the LEI, and an `exactLegalName` match when the LEI carries no number for that register and the company was found under its legal name.
The LEI decides the country, so a German LEI sent with `country=FR` returns the German company. [Global search](/guides/global-search#searching-by-lei) reads an LEI the same way, as the whole query or as the `identifier` hint, and goes straight to the right register.
Funds, pension schemes and trusts that hold an LEI but sit in no company register return an empty list. LEI records come from GLEIF and are refreshed daily. See [Search by LEI](/essentials/search#search-by-lei).
## Identifier formats now cover every id search returns
The identifier formats in `/v2/catalog` and on the country pages now describe every id `/v2/search` returns. Each country and US state was checked against its search results and the register's own documentation. Formats that missed a legacy series, a prefix or a length are corrected, a letter is given a meaning only where the register publishes one, and the examples are real identifiers. If you validate ids with rules built from the catalogue, rebuild them.
Search and `/v2/company` now accept every id search returns:
* **🇺🇸 Missouri:** a result the register lists without its charter number used to carry a number `/v2/company` could not resolve. It now carries an id such as `MOBSD-551157`, which search and `/v2/company` accept, and the company comes back under its charter number (`FL0029123`).
* **🇺🇸 New Mexico:** `/v2/company` accepts partnership ids such as `LPD2005092001`.
* **Search by number** now also recognises Montana `N` ids (`N560315`), New Hampshire `B` ids (`B02109`), District of Columbia `US-DC-` ids, Virginia ids under any letter (`L0007460`), Indiana ids such as `193046A080`, Maltese ids such as `OS/1116/NT`, Hong Kong numbers such as `C1300723`, Chinese credit codes such as `911000001000013428`, Isle of Man ids such as `000006I`, and Polish ids with their `krs-`, `nip-` or `regon-` prefix.
For an id match, `matchReason.identifier` now uses the same key as `company.identifiers`. If your code reads the old key, switch to the new one:
| Country | Before | Now |
| - | - | - |
| 🇺🇸 Missouri | `bin` | `entityId` |
| 🇺🇸 North Dakota | `controlId` | `entityId` |
| 🇺🇸 New Hampshire | `businessId` | `entityId` |
| 🇺🇸 Michigan | `idNumber` | `miIdNumber` |
| 🇺🇸 Illinois | `topographId` | `fileNumber`, without the `C` or `L` that starts the `id` |
| 🇺🇸 Vermont | `recordNumber` | `entityId` |
| 🇺🇸 Texas | `fileNumber` | `sosFileNumber` |
| 🇷🇺 Russia | `OGRN`, `OGRNIP`, `INN` | `ogrn`, `ogrnip`, `inn` |
In Norway, `matchReason` now gives the organisation number as 9 digits (`975387003`), as `id` does, instead of `975.387.003`. See [match types](/essentials/search#match-types).
In development environments, generated ids follow the corrected examples: Swiss UIDs are compact (`CHE408600128`), California entity numbers have no `C` prefix (`806592`), Hawaii file numbers have no space (`112127D1`), Cypriot numbers use the Greek prefix (`ΗΕ433437`), and Chinese ids are valid credit codes.
## 🇧🇦 Bosnia and Herzegovina: Republika Srpska companies, beneficial owners and extracts
Companies registered in Republika Srpska are now covered, read from the Republika Srpska Business Register.
* **Company data:** legal representatives with the scope of their authority, shareholders with their subscribed amount and share, capital, every registered activity, and branches as establishments.
* **Beneficial owners:** `ultimateBeneficialOwners` from the Republika Srpska beneficial ownership register, on its own SKU (`bih-rs-ubo-data`). The Federation of BiH and Brčko District have no public beneficial ownership register.
* **Documents:** the register's trade register extract, and a UBO extract, a dated capture of the register's beneficial ownership page for the company.
Republika Srpska ids carry the company's JIB, for example `RS 3-35-00 4402503100008`, because that register can give one MBS to two companies. Search returns ids in this form, and an id without the JIB is still accepted. See the [Bosnia and Herzegovina guide](https://www.topograph.co/countries/ba).
In the Federation of BiH, many older short-format numbers are also held by two companies, because each court assigns them separately. Those companies now get their own ids, for example `FBiH 1-1082 4227225650003`, with the JIB added, or the register's record number (`FBiH 1-1088-00 #21092281`) when it shows no JIB. Every other id is unchanged. Search by name or by number returns these ids, and each looks up exactly its company. Looking up a shared number without the suffix is refused with `invalid_request` rather than answered with one of the two. See [the company id names its register](https://www.topograph.co/countries/ba#the-company-id-names-its-register).
## 🇧🇪 Belgium: signing powers from agentic enrichment
With `agenticEnrichment: true`, Belgian legal representatives now also come back with their signing powers. The representation clause of the articles, which says who can bind the company towards third parties, alone or jointly, is read from the most recent Moniteur Belge publication that restates it. Each representative gets the sentences that apply to their role verbatim in `signingPowers.localText`, with an English translation, and an AI reading in `signingAuthority`: `sole`, `sole_within_limits`, `joint` or `unclear`, with one rule per scope and the excerpt it was read from. When one mode covers the representative's general representation, for example "every director represents the company", `representationMode` is set too, so integrations that read only that field get Belgium. Corporate directors are covered as well as individuals. A representative the clause does not address gets no signing powers rather than a guess. See [Person Enrichment](https://www.topograph.co/countries/be#person-enrichment).
## 🇧🇪 Belgium: director birth dates from the UBO register
Recent Belgian founding acts print a director's birth details as "(…)", so agentic enrichment rarely found a birth date for a newly incorporated company. When the director is also a beneficial owner, enrichment now copies the birth date, nationality and residence address the UBO register holds onto their `legalRepresentatives` entry (and their `otherKeyPersons` and `shareholders` entries). It reads them from the `ultimateBeneficialOwners` of the same request, or, when you did not ask for UBOs, from the latest UBO read your account made for the company, birth date and nationality only. No UBO lookup is made for this, nothing is copied when UBO access is turned off for the workspace, and these copied values alone are not billed as enrichment. They are attributed per field in `dataSources`, for example `individual.birthDate`, to `ubo_register`. See [Person Enrichment](https://www.topograph.co/countries/be#person-enrichment).
The request page now also shows a person's birth place under their birth date.
## 🇷🇸 Serbia: onboarding mode, and faster search
Serbia now supports `mode: "onboarding"`. The `company` datapoint comes back in milliseconds from the open-data companies file that the Serbian Business Registers Agency (APR) publishes every month: legal name, registration number, legal form, status, founding date, main activity code and municipality. Verification mode is unchanged and still queries APR live, with officers, owners and the full address.
The file lists companies only. For an entrepreneur, an association or a foundation, onboarding mode answers `datapoint_not_applicable` with a message to retry without onboarding mode, and the answer is not charged. The same applies to a company registered since the last monthly publication.
Search uses the same file. A search by registration number (MBR) for a company in the file returns in milliseconds. Company names written in Cyrillic now also match their Latin spelling. See the [Serbia guide](https://www.topograph.co/countries/rs#retrieval-modes).
## 🇫🇮 Finland: activity codes follow the edition the register assigned
The Finnish register still holds companies classified under four editions of the TOL classification: 2025, 2008, 2002 and 1995. Every TOL code was published under `TOL_2025`, and the NACE code derived from it assumed a single edition.
`TOL` keeps the register's code as before, and the revision-explicit key now names its edition: `TOL_2025`, `TOL_2008`, `TOL_2002` or `TOL_1995`. For a TOL 2025 code, `NACE` is now the register's own NACE Rev. 2.1 class, which corrects the class for about thirty codes. For a code from the 2002 or 1995 edition, `NACE` and `ISIC` no longer come from the code itself. See [activity codes](/guides/standardization).
## 🇸🇪 Sweden: open-data search, and activity codes from Statistics Sweden
Swedish search now also reads the register's weekly open-data file from Bolagsverket: every registered organisation and sole trader, including those struck off, and a company is also found by its secondary business names. A company registered since the latest weekly file is still found by the live register search.
With `activeOnly=true`, struck-off and bankrupt companies found in that file are now filtered out of name searches too.
Activity codes now come from Statistics Sweden's business register when it classifies the company: `SNI_2025` with the main activity first, and the NACE Rev. 2.1 and ISIC codes they correspond to, no longer inferred from the business description. A company Statistics Sweden does not classify still gets inferred codes, flagged `isAIInferred`. See [activity codes](/guides/standardization).
## France and Spain: legal forms, roles and statuses
The France and Spain lists of legal forms, roles and statuses on the pricing pages and in `/v2/catalog` now match the API value for value, and Spain's are published for the first time. `standardized` is listed exactly as returned (`Managing Director`, not `ManagingDirector`). If you built a mapping from the earlier lists, rebuild it.
* **🇫🇷 France:** every INSEE legal-form code is now mapped. Companies with a code that was missing, such as 9900 (Autre personne morale de droit privé), used to come back with no legal form. Eight more RNE roles are recognised, and the people holding them, who were left out, are now returned. An SA now carries its own ISO 20275 code (`K65D` à conseil d'administration, `5VCF` à directoire) instead of the SARL one, along with 23 other corrected codes. In `otherKeyPersons`, `role.standardized` is always one of its documented values: partners, treasurers and similar roles are `Other`, with their meaning in `localName` and `englishTranslation`. Associations get a legal form only the register confirms (otherwise "Association déclarée") and a standardized category. The status list is published.
* **🇫🇷 France, second pass:** the legal forms now publish their ISO 20275 code, and 127 more codes are corrected, each INPI sub-form now carrying the code of its INSEE parent form. Five roles from INPI's June 2026 nomenclature are recognised; a person the register records with a second role is returned once per role; and a role code newer than the published list is returned as "Autre" instead of being left out. A Président du conseil d'administration who is not also directeur général is now under `otherKeyPersons` (the directeur général represents the company), and an administrateur provisoire under `legalRepresentatives`.
* **🇪🇸 Spain:** each legal form is returned under one name, such as "Sociedad Limitada", where some companies used to get the register's category ("Sociedades de responsabilidad limitada"). Each office is returned under one label, such as "Administrador único", whatever spelling the register used, and officer entries are no longer cut short ("Miembro de la Comisión de Control" was returned as "Control").
* **🇪🇸 Spain, second pass:** a company in insolvency proceedings returns "En situación concursal" (the register shows "Concurso"), and a BORME record no longer overwrites the register's "Liquidada" with "Vigente". A G-prefixed NIF that is not a foundation (savings banks, many economic interest groupings and UTEs) now returns its company data instead of not found. Savings banks and credit cooperatives have their own legal forms, a form missing from both the name and the register category is read from the NIF's first letter, and the foundation register's role spellings ("Presidenta", "Vicepresidente 1º") are returned under the listed labels.
## Global search (alpha): find a company without knowing its country
`POST /v2/search/global` finds a company from its name when you do not know the country, or know the wrong one. Send what you have in one line of text, like `"Bamberger GmbH, Wien"` or `"MFG Investments EOOD, from a UK filing"`. The name and the hints (a city, a country, the register the name came from, a registration number, a website) are read out of the text for you.
The answer ranks candidates across every country Topograph covers. Each one comes with its country and registration number, ready for `/v2/company`, whether it is a strong or a possible match, and a sentence explaining why it matched: the register that returned it, a public source, the address or the legal form.
Give an address and it counts: the register of that country is asked first, and when it has the company at or near that address, the search stops there. Same-name companies are ranked by distance from your address.
`status` tells you where you stand. `resolved` means one strong match, `ambiguous` means several plausible ones (the same name exists in Germany and Austria), and `not_found` comes with a `reason`. For American companies the search also finds the state of incorporation, so a bare "Inc." resolves to Virginia or Delaware rather than stopping at the country.
With `stream: true` the search streams its progress step by step ("Asking the register in Austria"), and each candidate as soon as a register confirms it. A search is billed only when it resolves to one good candidate. Global search is also in the app, under **Global search** in the sidebar, where any candidate can be ordered directly, as from the country search. See the [Global Search guide](/guides/global-search).
## Search: active companies only
`GET /v2/search` accepts `activeOnly=true` to leave out companies the register reports as dissolved, struck off, deregistered or otherwise inactive. A company whose status the search source does not report is kept rather than hidden. Each country's catalog entry now has a `search` object that says whether its search can return inactive companies and how completely the filter applies there. See [Active companies only](/essentials/search#active-companies-only).
## Every error code, with its retry delay
Failed datapoints and documents now carry `retryAfterSeconds` next to `retryable` in `dataStatus`: the minimum wait before resubmitting the same request. Five codes are retryable (`service_unavailable`, `source_unavailable`, `processing_failed`, `request_cancelled`, `processing_interrupted`). Every other code is a final answer, and the [Reliability & Errors guide](/guides/reliability-and-errors#datapoint-and-document-error-codes) now lists all of them with what to change instead.
The same list is the `PublicErrorCode` enum in the OpenAPI spec, with the retry contract in each value's description, so generated clients get a real enum rather than a string. `balance_negative`, returned when a wallet is below zero, joins the published vocabulary. In a development environment, `BALANCE_NEGATIVE` triggers it like every other code.
## European Unique Identifiers in company responses
`company.identifiers.euid` is available for supported companies in 28 countries. Coverage includes additional countries across the EU and EEA, with country-specific legal-form and request-mode limits detailed in the [EUID guide](/essentials/euid).
The field is optional and depends on the company's legal form and available source record. Some countries derive it from the national register number; others return the register's published value. It is an output identifier, not a supported search input or a per-request BRIS validation certificate.
## 🇧🇦 Bosnia and Herzegovina: company ids now name their register
Bosnia has three independent court registers: the Federation of BiH, the Brčko District and Republika Srpska. **Each numbers its entities separately**, The same registration number (MBS) therefore identifies different companies in different registers. `3-70` is a live example: in the Federation it is *"MALA PRIČA" Opšta zadruga Živinice*, in Brčko it is a café. Two real companies, one number.
Treating that number as unique meant one of the two could silently displace the other in search results. `company.id` for Bosnia is now the MBS **prefixed with its register**, which is unique:
| `company.id` | register |
| - | - |
| `FBiH 65-01-0620-08` | Federation of BiH |
| `Brčko 1-369` | Brčko District |
| `RS 3-35-00` | Republika Srpska |
This is the same approach Germany uses, where a company is identified by its court (`München HRB 228960`).
### A bare number still works, and is now honest about being ambiguous
Searching a bare MBS returns **every** company holding that number, each with its own register-qualified `id`, reported as `matchType: partialId` rather than `id`. Nothing is dropped and nothing is chosen for you.
`/v2/company` is the exception worth knowing: it cannot return several companies, so a bare MBS held in more than one register still resolves to one of them (currently the Brčko entity) with nothing marking the ambiguity. Roughly 100–200 companies, all short-format. **Search first, then call `/v2/company` with the qualified `id`**, which is the recommended pattern for every country anyway.
The register token is case-insensitive on input, and `Brcko` is accepted for `Brčko`, so an id that lost its diacritic in transit still resolves.
### `identifiers` is unchanged
`identifiers.mbs` still carries the register's own number, bare and unprefixed. The register prefix belongs to `company.id`, not to the number the register issues. `identifiers.jib` is unchanged and remains the field to join on across registers: 13 digits, issued at state level, unique nationwide and stable when a company moves register.
If you store Bosnian `company.id` values, re-resolve them through `/v2/search`; the bare number you hold will find the company and return its qualified id.
See [Bosnia and Herzegovina](https://www.topograph.co/countries/ba#the-company-id-names-its-register).
## Batches: from a spreadsheet to register data without writing code
The product app has a new section, **Batches**. Drop a CSV or XLSX of companies, and Topograph finds each one in its national register, fetches the data points you choose and hands you back one file with everything alongside your original columns.
* **Import any layout.** Topograph reads your headers and a sample of rows, then proposes which columns hold the country, identifier, legal name and address. Confirm the mapping once; a column of US states, a fallback country for rows without one, and combined or split address columns are all handled. Up to 50,000 rows per file.
* **Matching you can audit.** Rows with a unique identifier or exact legal name match are trusted on their own. Rows selected by a weaker rule (a partial identifier, a name that differs only by its legal form, a name-and-address comparison) are marked as suggested, with the evidence spelled out: which fields agree, which differ, and why the suggestion was made. Ambiguous rows wait in a review queue you can work through with the keyboard, or trust in one click when the suggestions look right.
* **Data in bulk, at your pace.** Choose the data points and the mode, see the price per country and an upper bound before you start, and let the run continue while you close the tab. Rows that could not be completed keep whatever was retrieved and say what is missing.
* **Statistics you can report from.** Match rate and the share of companies with each data point, by country and by legal form, plus which documents are ready to order (listing them is free). Rates are measured against what exists: data a country does not offer, or that does not exist for a legal form, never counts as a miss.
* **A fixed export.** One row per company you imported, in your order, with the match, one JSON column per data point, and the reason for any row that failed. Identifiers survive the trip through a spreadsheet as text.
Every lookup and data request a batch makes is an ordinary request: it shows in your history, is billed in credits as usual, and opens on its own page. Batches also work in a development environment on generated data. See the [Batches guide](/guides/batches).
## 🇯🇪 Jersey: identifiers now combine registration number and entity id
**Breaking change.** A Jersey registration number on its own is not unique: the register assigns numbers per entity type, each starting its own series from 1, so the same number can belong to several entities. Registration number `3499`, for example, identifies both a company dissolved in 1968 and an active limited partnership. The register prints the same "Registration Number: 3499" on both entity pages, with nothing to tell them apart.
`/v2/company` now requires the full identifier: the registration number and the JFSC entity id, joined by a hyphen (e.g. `3499-3005057`). A bare registration number is refused with `400 Bad Request`. It remains a valid `/v2/search` query, and search now returns every entity that carries it, each with its own composite `id`.
**Migration:** resolve any bare Jersey registration number you hold through `/v2/search`, and store the composite `id` it returns going forward.
## Reconstructed shareholders: an unconfirmed number is no longer returned under the country's own identifier key
Corporate shareholders reconstructed from filings (France, United Kingdom, Belgium, Iceland) sometimes carry a registration number we read off the document. Where we could confirm that number against the national register, it is returned under the country's own key as before -- `companiesHouseNumber`, `siren`, `ondernemingsnummer`, `kennitala`. Where we could not, it is now returned under the generic `registrationNumber` instead.
The country's own key is an assertion that **that** register issued the number, and a number printed on a filing often belongs elsewhere: a foreign parent's registration in its own country, or another register in the same country -- the UK Mutuals register and the Charity Commission both issue numbers that are not Companies House numbers. Returning those under the local key dead-ended ownership chains at company numbers that do not exist.
Nothing is dropped: every number we have still reaches you, and the key now tells you how far we got. About 0.9% of reconstructed corporate shareholder identifiers move key.
**Migration:** if you read the local key on reconstructed shareholders, read `registrationNumber` as well. Treat the local key as directly resolvable and `registrationNumber` as a lead to confirm through `/v2/search`. See [Shareholders extraction](/essentials/shareholders-extraction#corporate-shareholder-identifiers).
## Activity codes: a corrected ISIC Rev. 5 / NACE Rev. 2.1 correspondence
The table that turns a NACE Rev. 2.1 class into an ISIC Rev. 5 class, and back, is now derived from the two official structures on their headings rather than on matching digits. The two standards only share codes down to the division: ISIC `1103` is beer while NACE `11.03` is cider, ISIC `4671` is fuels while NACE `46.71` is motor vehicles. Every affected `ISIC` value changes accordingly, and `ISIC` descriptions are now the official ISIC titles. Where one ISIC class holds several NACE classes, `NACE` derived from it now answers the shared group rather than guessing one class.
## NACE that was already Rev. 2.1 is no longer re-transitioned
Italy (ATECO 2025), Romania, Croatia (NKD 2025) and Hungary (TEÁOR'25) serve NACE Rev. 2.1 codes already. Those were being transitioned as if they were Rev. 2, which changes the meaning of 23 classes that Rev. 2.1 renumbered (`46.71` became `46.81`, motor vehicles read as fuels). Each of those registers is now read in the revision it actually uses, per code where the register stamps it. Hungary's extract stamps each activity `'08` or `'25`, so `TEAOR_2008` and `TEAOR_2025` now carry the codes per stamp.
## 🇱🇻 Latvia: the register's own NACE revision, per code
`NACE_REV2`, `NACE_REV11` and `NACE_REV1` carry the Enterprise Register's codes exactly as stamped. A pre-2008 code that cannot be placed in the current nomenclature is kept under its own key instead of being dropped. See [Latvia](https://www.topograph.co/countries/lv#activity-code-mapping).
## US NAICS: the main part of a split code
Where the Census Bureau splits a NAICS code across several ISIC classes, `ISIC` and `NACE` derived from `NAICS` now take the code's main scope rather than its first carve-out: gasoline stations map to fuel retail, not convenience stores; line-haul railroads to freight rail, not interurban passenger rail. 141 NAICS codes change.
## Subsidiaries: preserve disclosed ownership intervals
For France, Belgium, Germany and the United Kingdom, `subsidiaries` can return a disclosed ownership interval in `sharePercentageRange`. Its `lower` and `upper` bounds preserve the range, with optional `lowerInclusive` and `upperInclusive` flags to distinguish "more than 25%" from "at least 25%".
Exact percentages continue to use `sharePercentage`. When only an interval is disclosed, no midpoint or endpoint estimate is returned as an exact percentage. When ownership is disclosed without a percentage, both fields are omitted and the company can still appear in the list.
See [Subsidiaries](/essentials/subsidiaries-extraction#ownership-intervals-and-missing-percentages) for the response format and how to apply ownership thresholds to a range.
## 🇲🇺 Mauritius: one canonical identifier, and search resolves the rest
Mauritian companies carry several numbers, and the ones printed on the documents you are likely to hold are not the register's own key. `/v2/company` now accepts exactly one identifier for Mauritius: the **CBRD File No.**, a register track letter followed by up to 6 digits, `^[A-Za-z]\d{2,6}$` (e.g. `C117853`, `C61811`).
Anything else returns `400 Bad Request` naming the expected format, immediately and without being billed. Previously an unusable identifier came back as a retryable `source_unavailable`, which read as "the Mauritian register is down", so retrying looked like the right thing to do and never was.
### Search resolves what `/v2/company` will not accept
`/v2/search` now takes the shapes customers actually hold and returns the canonical File No. as the result `id`:
| what you have | search returns |
| - | - |
| `61811 C1/GBL`, an FSC global-business licence number | `C61811` |
| `217346GBC`, the File No. with its licence category appended | `C217346` |
| `221058`, the File No. without its letter prefix | `C221058` |
| `C07068818`, a Business Registration Number | the company's File No. |
Search first, then call `/v2/company` with the `id` it returns. That `id` is always the File No.
**Always search first.** Resolving an identifier through `/v2/search` before calling `/v2/company` is the recommended integration pattern for every country, and Mauritius is the clearest illustration of why: a Mauritian company carries several numbers, and the ones printed on the documents you receive are usually not the register's key.
A Business Registration Number (`125473`, or `C07068818`) is a search input rather than a company key. It identifies a *business registration* under the Business Registration Act, and a company with several registered businesses has several of them. Search resolves it to the File No., the same value `identifiers.brn` has always returned, so a single pass through search gives you a value you can store permanently.
We also corrected our own documentation: the File No. and the BRN were described as "the same number", and they are not. RT Knits has File No. `C067973` and BRN `C07068818`. Different numbers, different lengths, two separate lookups on the register's own search. The response field is still spelled `identifiers.brn` for backwards compatibility, and it has always carried the File No.
## 🇨🇭 Switzerland: key persons now come from the cantonal trade register extract
Swiss `legalRepresentatives` used to be extracted from **SOGC gazette publications** — the stream of change notices ZEFIX republishes. ZEFIX has no structured officer roster, so that was the only machine-readable option, but a gazette is a history of amendments rather than a statement of who currently holds office, and it showed: officers were occasionally missed, and appointment dates were often the date of the wrong notice.
Switzerland now reads the **official cantonal trade register extract** instead — the same document you can order through `/v2/documents`, whose person table is the register's authoritative current state. All 26 cantons are covered, across both cantonal portal families. If a cantonal portal is temporarily unavailable, the answer falls back to the previous SOGC extraction rather than failing.
### New: `otherKeyPersons` for Switzerland
Switzerland now serves the `otherKeyPersons` datapoint, on the existing `che-company-data` block — **no new charge**, and nothing extra to pay if you already request `company` or `legalRepresentatives`. It returns the people the register lists **without signing authority**:
* the **statutory auditor** (Revisionsstelle / organe de révision), almost always an audit firm, returned with its own Swiss UID;
* **board members without signing authority**, common on larger companies.
If ZEFIX publishes no cantonal extract link for a company, the datapoint returns `no_document_available` and is **not billed**, rather than returning an empty list.
### Breaking: board members without signing authority moved to `otherKeyPersons`
If you parse `legalRepresentatives` for Switzerland, read this.
`legalRepresentatives` now means exactly **"can bind the company"**: it contains only people the register grants signing authority, and every entry carries a non-null `representationMode`. Board members the extract lists as *"without signing authority"* now appear in `otherKeyPersons` instead. On a large Swiss company that can move ten or more people between the two arrays.
### New field: `corporateBody`, on every key person
Because that split is by signing authority, a board can span both arrays. Every legal representative and other key person now carries an optional **`corporateBody`** naming the body they hold a seat on — `board`, `supervisoryBoard`, `management` or `audit` — so you can reassemble a governing body in one pass:
```js theme={null}
const board = [...response.legalRepresentatives, ...response.otherKeyPersons]
.filter((person) => person.corporateBody === 'board');
```
The field is **absent** for someone who sits on no body, such as an authorized signatory (Prokurist, fondé de procuration) who holds a power of attorney rather than a seat. It is optional and additive, so it breaks nothing; it is populated for Switzerland today and will roll out to other countries.
Two standardized role values were added alongside it: **Vice Chairman of the Board**, and **Chairman of the Board** for other key persons.
## Legal form codes are now GLEIF ELF v1.6
`legalForm.iso20275Code` now comes from **version 1.6** of the GLEIF ISO 20275 Entity Legal Forms code list, published 19 February 2026. We were on v1.5, from September 2023.
v1.6 adds **169 codes across 12 new countries** and retires 18 whose legal forms were abolished. Two additions worth naming, because customers asked for them:
* **Spain**, `UFBW` for a *Comunidad de Bienes*, and `2W1A` for a *Sociedad Civil*.
* **Germany**, `PDNU` for an *eingetragene Gesellschaft bürgerlichen Rechts* (eGbR). It previously came back as `FR3V`, the code for a plain unregistered GbR. The unregistered form still returns `FR3V`.
Other countries gaining codes include Austria's Flexible Kapitalgesellschaft, Denmark's Personligt ejet Mindre Virksomhed, the UK's Private Fund Limited Partnership, and municipality forms in Norway and Sweden.
**Nothing was renamed, removed, or changed in shape.** `iso20275Code` is the same optional string it has always been, and a code you have already stored stays valid — ELF never renumbers or deletes a code, it only retires it. If you parse legal forms today, your integration is unaffected and needs no change.
### You can now see which version you are getting
The list version was previously knowable only by asking us, which is not a reasonable answer. Each country page and the country manifest behind `/v2/catalog` now name the exact edition their legal forms were mapped against, so it is something you can check rather than ask.
For roles, that edition is **ISO 5009 v1.0.0 of June 2023**. That is not us lagging: it is the only edition GLEIF has ever published, and it did not change when the legal-form list moved to v1.6. One consequence worth knowing is that none of the 169 new legal forms has role codes behind it yet.
### Corrections
Auditing our mapping against v1.6 turned up codes we were publishing that exist in no edition of the standard. ISO 20275 is a closed registry, so these were not near-misses:
* The standardization guide gave `54RD` for a German GmbH. The real code is `2HBR`.
* Its role table gave one ISO 5009 code for France, Germany and Italy alike. A role code is scoped to a specific legal form, so one code cannot serve three countries; the table now shows the real per-form codes and says which legal form each belongs to.
* Romania, Singapore, Malta and around twenty US states carried placeholder codes in the pricing manifest and country guides. These never appeared in an API response, because invalid codes are dropped before they reach you, so responses do not change. What changes is that we no longer advertise a code we would not have delivered.
* Where a jurisdiction genuinely has no code, we now publish none rather than invent one. Moldova is the clearest case: GLEIF has never assigned it any code.
## Development environments
Every account can now create **development environments**: isolated sandboxes that answer for **every country we support** with generated data, bill nothing real, and never touch a register.
An environment has its own API key, its own webhook endpoints and signing secret, its own request history, and its own members and roles. Create one from **Developer** in the app, or over the sandbox API — one per developer, or one per CI run:
```bash theme={null}
curl -X POST https://api.sandbox.topograph.co/v2/environments \
-H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY" -H "Content-Type: application/json" \
-d '{"name": "ci"}'
```
Development environments run on their own deployment, **`api.sandbox.topograph.co`**, with its own database and no access to any register. Swap the key and the base URL; everything else is identical: same endpoints, same request bodies, same response shapes, same webhooks. Development keys are prefixed `sk_dev_`.
### It behaves like the real thing, including when it fails
The data is generated from each country's own manifest, so identifiers are in that country's real format, under that country's real identifier keys, with its real legal forms, roles, activity codes and document catalog. The same identifier always returns the same company.
**Every public error code has a magic identifier** — use `SOURCE_UNAVAILABLE`, `INSUFFICIENT_FUNDS`, `ONBOARDING_TIMEOUT` and the rest as the company id and you get that exact error, with the live message, the live HTTP status and the live retryability. There are also identifiers for delivery delays, dissolved and inactive companies, ownership structures, search result sets and match reasons, and the data shapes integrations actually break on: `SPARSE`, `UNICODE`, `LONG_NAMES`, `MANY_RESULTS`. `RATE_LIMITED` returns a genuine `429` with `Retry-After`.
### Billing you can exercise, with virtual credits
Requests are priced at the **real catalog rates** and paid for from a virtual wallet, so you see what an integration would cost. Set the balance yourself and watch it deplete into a genuine `insufficient_funds` from the same billing path production uses:
```bash theme={null}
curl -X PUT https://api.sandbox.topograph.co/v2/sandbox/wallet \
-H "x-api-key: sk_dev_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"balanceInCreditCents": 120, "autoRefill": false}'
```
Nothing reaches Stripe, and no card is ever charged.
### Companies you define, and a clean slate
Generated data covers everything, which is the wrong tool when you need one *specific* company — to reproduce a bug, build a demo, or assert on your own matching logic. Define one, and everything you leave out stays generated:
```bash theme={null}
curl -X POST https://api.sandbox.topograph.co/v2/sandbox/companies \
-H "x-api-key: sk_dev_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"countryCode": "FR", "company": {"legalName": "Acme Trading SAS"}}'
```
`PATCH` it and the next request returns the new version, which is what a monitoring integration needs to see a real change detected. `POST /v2/sandbox/reset` clears an environment's history and restores its wallet between CI runs.
### Coverage gaps are honest
A datapoint a country does not support fails in a development environment exactly as it does live. A sandbox that answers everything would let you ship an integration that breaks in production, so this one does not.
Full details in the [development environments guide](/guides/development-environment).
## The TEST country is deprecated
[`TEST`](/guides/test-country) keeps working and is not going away without notice, but development environments supersede it: they cover every country rather than one placeholder, in that country's real formats, and they understand the same magic identifiers plus many more. New integrations should start with a development environment.
## France: your NACE class is now the one INSEE assigned the company, and the NAF 2025 code is published
INSEE has published NAF 2025, the French implementation of NACE Rev. 2.1, and already assigns every active company its NAF 2025 code in Sirene ahead of the 1 January 2027 cutover. A NAF 2025 code is a NACE Rev. 2.1 class with one French letter appended, so the company's exact 4-digit class is right there. `NACE` and `NACE_REV21` now read that assignment directly instead of converting the old APE code, which no table can do as well: INSEE recodes each company on its actual activity, so a consultancy filed as `62.02A` can come back as `73.12` (media representation) where a conversion would have said `62.20`.
The code itself is published under a new field, **`NAF_2025`** (e.g. `86.93Y`, with INSEE's official label). It is present whenever INSEE has assigned one, which in a live sample was 99.5 % of active companies; the remainder are units still coded in a pre-2008 nomenclature, almost all ceased, which keep the correspondence-based `NACE` described below. Responses cached before this release keep their previous codes until they expire.
## French activity codes resolve to a precise NACE class more often
The letter on a French APE/NAF code (`8690F`, `6420Z`) is a national subdivision of the NACE class, and until now we dropped it before standardizing. That cost precision: a holding company declared as `6420Z` came back as NACE `64.2`, the group, because the bare class `64.20` splits into `64.21` and `64.22` in Rev. 2.1 and the code alone cannot say which.
France's APE codes are now resolved through INSEE's own *Table de correspondances NAF rev. 2 -> NAF 2025*, which names a single NACE Rev. 2.1 class for 541 of the 732 French sub-classes:
| APE code | Before | Now |
| - | - | - |
| `6420Z` Activites des societes holding | `64.2` | `64.21` |
| `8690A` Ambulances | `86.9` | `86.92` |
| `4329A` Travaux d'isolation | `43.2` | `43.23` |
| `1071B` Cuisson de produits de boulangerie | `10.71` (food manufacturing) | `47.24` (retail) |
Eighteen sub-classes change: thirteen gain a full 4-digit class, and five were pointing at the wrong class entirely — in-store baking, ambulance-adjacent transport and three others move to the class INSEE actually assigns them. Where a sub-class genuinely straddles several Rev. 2.1 classes the group-level answer stands, so nothing gets less precise, and the register's own APE code is still published in full under `activities.NAFREV2` — now carrying INSEE's official French label instead of a placeholder.
## A 4-digit NACE class on every French company: `NACE_REV2`
Upconverting to NACE Rev. 2.1 has a hard limit that no mapping can fix: **Rev. 2.1 deleted some Rev. 2 classes.** `86.90` has no Rev. 2.1 successor of its own, so the most precise honest answer is the group `86.9`. For 17 further classes the successors scatter across unrelated divisions and there is no Rev. 2.1 code at all, so `activities.NACE` was simply absent — including for construction of residential buildings, car sales and laundry.
French companies now also carry **`NACE_REV2`**: the NACE Rev. 2 class the register itself recorded. NAF rév. 2 *is* the French implementation of NACE Rev. 2, so an APE code's first four digits are that class — nothing is converted or guessed, and the key is present on every French company whose APE code we hold.
```json theme={null}
"activities": {
"NAFREV2": [{ "code": "8690F", "description": "Activités de santé humaine non classées ailleurs" }],
"NACE_REV2": [{ "code": "86.90", "description": "Other human health activities" }],
"NACE": [{ "code": "86.9", "description": "Other human health activities" }],
"NACE_REV21": [{ "code": "86.9", "description": "Other human health activities" }]
}
```
Read `NACE_REV2` if your parser needs four digits for every company; read `NACE` / `NACE_REV21` if you need one revision comparable across countries. They are different revisions of the same classification, so do not mix them in a single field: `86.90` is not a Rev. 2.1 code and `86.9` is not a Rev. 2 class. Existing keys are unchanged.
## Hungary: a fast mode at 0.50 credits
Hungarian company data previously had one path: the certified *Cégkivonat*, bought from the register per lookup at a variable price that usually landed near 5 credits. Screening at volume paid certified-document prices for answers that did not need to be certified.
`mode: "onboarding"` now reads the stored company extract (*Tárolt cégkivonat*) that the Ministry of Justice publishes on Cégportál, at a flat **0.50 credits**, and returns the same five datapoints: `company`, `legalRepresentatives`, `shareholders`, `otherKeyPersons` and `establishments`.
```bash theme={null}
curl -X POST https://api.topograph.co/v2/company \
-H "x-api-key: $TOPOGRAPH_API_KEY" -H "Content-Type: application/json" \
-d '{"countryCode": "HU", "companyId": "1809110530", "mode": "onboarding",
"dataPoints": ["company", "legalRepresentatives", "shareholders"]}'
```
The register refreshes that stored extract periodically, not on every change, so onboarding mode is **not authoritative**. A recent filing may not appear yet, and no certified document is issued. `mode: "verification"` is unchanged: same certified extract, same price, still the default.
## Hungary: ownership percentages are no longer estimated
Hungarian extracts describe member participation in words rather than as a figure. *"A szavazati jog mértéke minősített többségű befolyást biztosít"* means the voting right confers qualified-majority influence, at least 75%. Where the register publishes no capital contribution per member, `sharePercentage` is now **omitted** instead of being reported as a number derived from that wording.
Shareholders are still returned with their identity; only the percentage is absent, and it is present whenever the register publishes enough to compute it. If you were reading `sharePercentage` for Hungarian companies, treat it as optional rather than assuming a value.
## Italy: share capital now travels with the shareholder list
The Italian register does not publish share capital on the company record. It files it with the **shareholder list**, which is a separate, separately priced record.
In `mode: "verification"`, `company.capital` for Italy is now returned when that shareholder record has been retrieved for the company, and omitted when it has not:
| Your request | `company.capital` |
| - | - |
| `company` and/or `legalRepresentatives` alone | Omitted |
| `company` together with `shareholders` | Returned |
| `company` alone, within 24h of a `shareholders` request for the same company | Returned |
| `mode: "onboarding"` | Returned, as before |
**If you need share capital on every Italian lookup, add `shareholders` to `dataPoints`.** You then get the ownership breakdown and the capital figure together, and the capital costs nothing on top of the shareholders block.
Why we changed it: filling in that one field meant ordering the shareholder record on most Italian company lookups, at the price of a second block. Worse, a request that asked for both `company` and `shareholders` ran the two in parallel and ordered the same record twice. We have stopped ordering it speculatively.
We deliberately did **not** close the gap with a third-party source. Share capital is available from aggregators that resell register data, and in `mode: "onboarding"` that is exactly where it comes from. But in verification mode every field we return comes from the register itself, and we would rather omit a field than quietly downgrade where it came from without telling you.
Italian prices are unchanged. Full detail on the [Italy page](https://www.topograph.co/countries/it#share-capital-in-verification-mode).
## Workspaces can now turn off UBO data access
Every workspace can request ultimate beneficial owner (UBO) data, on by default. Turn it off per workspace with the new `uboEnabled` field on the [workspace endpoints](/essentials/workspaces#ubo-data-access):
```bash theme={null}
curl -X PATCH "https://api.topograph.co/v2/workspaces/acme-paris" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"uboEnabled": false}'
```
You can also set it when creating a workspace. A workspace with UBO access turned off gets `datapoint_not_supported` when `ultimateBeneficialOwners` is requested.
Only keep UBO data access enabled for a workspace whose legal entity is AML-obliged. UBO data carries regulatory obligations under AML law, and we may revoke a workspace's UBO access if the entity attached to it is not AML-obliged.
## Activity codes now tell you which classification revision you are holding
A code like SIC `62012` or SBI `62010` means different things in different revisions of its classification, and until now `company.activities` gave you the code without saying which revision it belonged to. Every key that can answer that question now has a revision-explicit sibling:
```json theme={null}
"activities": {
"NACE": [{ "code": "62.10", "description": "Computer programming activities" }],
"NACE_REV21": [{ "code": "62.10", "description": "Computer programming activities" }],
"SIC": [{ "code": "62012", "description": "Business and domestic software development" }],
"SIC_2007": [{ "code": "62012", "description": "Business and domestic software development" }]
}
```
The pair holds the same items. Read the revision-explicit key when the revision matters, the original when it does not.
**Nothing was renamed, removed, or changed.** `activities.NACE`, `activities.SIC` and every other existing key keep exactly the contents they have always had. This is additive: if you parse activities today, your integration is unaffected and needs no change.
Two revisions are fixed platform-wide and never vary by country: `ISIC_REV5` (ISIC Rev. 5) and `NACE_REV21` (NACE Rev. 2.1). A register that publishes NACE Rev. 2 is upconverted before we publish it, so `NACE_REV21` is Rev. 2.1 even where the source is not.
The national keys name whichever revision the register actually serves. We checked each one against the register rather than against the national statistics office, because the two routinely disagree — and in both directions. Several countries moved during 2025 and 2026: the Dutch Handelsregister converted every active registration to SBI 2025, Denmark's CVR moved to Dansk Branchekode 2025, Finland's YTJ to TOL 2025, and Greece's nomenclature to KAD 2025.
Where a register mixes revisions under one field, you get a key per revision rather than one averaged answer. Belgium stamps every activity row with its own version, so a company can return `NACE_BEL_2003`, `NACE_BEL_2008` or `NACE_BEL_2025`; Croatia's court register does the same, giving `NKD_1994`, `NKD_2007` or `NKD_2025`, and a single company filed across revisions returns one key for each.
And where a register genuinely does not record which revision a code belongs to, we publish **no** revision-explicit key rather than guess one. That is the honest answer for US `NAICS` (each state records the vintage current when the entity registered and never says which), Polish `PKD`, Romanian `CAEN` and Bulgarian `NKID`. Those keep their original key alone. The country pages and `/v2/catalog` list the exact keys each country returns, so you can see this per country rather than discover it from a response.
One related correction, for Croatia only: codes the court register stamps as NKD 1994 are no longer folded into `NACE`. NKD 2007 is Croatia's NACE Rev. 2 transposition and NKD 1994 is not, so treating a 1994 code as Rev. 2 produced a NACE class the register never declared.
## Shareholders reconstructed from filings: substantially more accurate
In Belgium, France, the United Kingdom and Iceland the register publishes no structured shareholder list, so `shareholders` is reconstructed by reading the company's filings — articles, notarial deeds, capital increases, confirmation statements — and folding them forward to today's cap table. That reconstruction has been rebuilt.
**What changes in your responses**
* **Holders we used to miss now appear.** The most common failure was reading a company's *controlling-interest* disclosure (a UK PSC entry, a beneficial-owner section) as if it were the share register, and reporting one holder at 100% when the share list named seven. Those sections are now used only to cross-check a cap table built from the share lists themselves.
* **Fewer invented figures.** Where filings established that several people hold shares but never stated the split, the previous behaviour could distribute the total evenly between them. A holder whose stake the filings do not state is now returned by name with the amount fields absent, rather than with a plausible-looking number.
* **Partial cap tables now say they are partial.** When part of the capital genuinely cannot be attributed from the filings — a transfer a jurisdiction never requires to be filed, a redacted deed, an undisclosed pool — you will more often see an explicit entry of `"type": "aggregate"` carrying that remainder, instead of a table that silently adds up to less than the company. Treat an `aggregate` entry as "these shares exist and the filings do not name their holder".
* **Reconstruction is roughly twice as fast**, so requests that include `shareholders` for these countries return sooner.
The response shape is unchanged; no integration needs updating.
**How we know it is better, and how it stays better**
Every change above is measured, not asserted. We built a frozen benchmark of real companies — the filing set captured exactly as it was, paired with a cap table verified by hand or against a register that publishes one independently — and the new reconstruction is scored against it on entity accuracy, on ownership percentages, and on whether it correctly declines to answer where the documents are silent. It beats the previous implementation on every one of those, on identical inputs.
That benchmark now runs as a regression gate: cases include the specific mistakes customers reported to us, so a change that reintroduces one is caught before it ships rather than after. When a customer tells us a cap table is wrong and we fix it, that company becomes a permanent case in the set.
## Italy: residence addresses, gender and nationality for individual legal representatives
Individual legal representatives of Italian companies now include the residence address the Registro Imprese files for them, along with their gender and, where the register publishes it, their nationality:
```json theme={null}
"legalRepresentatives": [
{
"type": "individual",
"role": { "localName": "Amministratore unico", "standardized": "Director" },
"individual": {
"name": { "fullName": "Marco Rossi" },
"gender": "Male",
"birthDate": { "year": 1980, "month": 5, "day": 15 },
"birthAddress": { "city": "Milano", "region": "MI", "countryCode": "IT" },
"residenceAddress": {
"addressLine1": "Via Giuseppe Verdi 8",
"city": "Milano",
"postalCode": "20121",
"region": "MI",
"countryCode": "IT"
}
}
}
]
```
This covers company officers and sole traders alike, in verification mode. Birth places also improved: a representative born outside Italy now carries their real birth country in `birthAddress.countryCode` instead of defaulting to Italy.
The fields are additive, so existing integrations parse responses unchanged. Responses are cached for 24 hours: a company you queried before the release keeps its cached response until the cache expires, then picks up the new fields on the next request.
## Activity codes now identify the company's main activity
Every activity code item in `company.activities` (and on establishments) can now carry `isMainActivity: true`, marking the code the register declares as the company's main — primary, prevailing — activity:
```json theme={null}
"activities": {
"NACE": [
{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false, "isMainActivity": true },
{ "code": "62.02", "description": "Computer consultancy activities", "isAIInferred": false }
]
}
```
Three things to know:
* **Absence means unknown, not secondary.** The flag appears only where the register distinguishes a main activity — either explicitly (Belgium's MAIN classification, Poland's *działalność przeważająca*, Croatia's *pretežita djelatnost*, Greece's Κύρια, Hungary's *főtevékenység*, Norway's first *næringskode*, Singapore's primary SSIC, and more) or because the register publishes exactly one code, which is its declared main activity (France's APE, Finland's main business line, Luxembourg, Spain, Ukraine, Serbia, and others). Registers that publish an undifferentiated list — the UK's SIC codes, for example — carry no flag on any code.
* **Derived codes inherit it.** When we derive NACE or ISIC from a register-native code, the derived code keeps the flag of the code it came from, so you can read `isMainActivity` on the standardized classifications without knowing each country's native system.
* **At most one code per classification carries it**, so `activities.NACE.find(a => a.isMainActivity)` is a safe way to pick one code per company.
Where activity codes are AI-inferred from an activity description, the single best-match code is flagged as the main activity and carries `isAIInferred: true` alongside, so you can always tell a register-declared main activity from an inferred one.
The field is optional and additive — existing integrations parse responses unchanged. Each country page documents whether its register declares a main activity.
## Singapore: the Business Profile document is available again
The ACRA Business Profile (`trade_register_extract`) is back in Singapore. It appears again in `GET /v2/company/{id}/documents` and can be ordered, and the `shareholders` and `legalRepresentatives` datapoints, which are read from it, resolve again with it.
It was briefly unavailable earlier this week while we fixed a problem delivering purchased documents from ACRA's portal. Orders complete reliably again.
Search, `company` in onboarding mode, and the onboarding profile were unaffected throughout, since they come from ACRA's open dataset (\~2.07 million entities) rather than the portal.
If you were billed for a Singapore Business Profile that did not arrive during that window, contact us and we will refund it.
## Ask questions about coverage and pricing in plain English
The pricing pages now carry an assistant. Ask it what a French company profile costs, which countries return UBOs, how fast a German profile comes back, which legal forms a country recognises, or whether to use onboarding or verification mode for a signup flow.
It answers from the live catalog and the documentation, not from a model's memory of them, so coverage, prices and response times are the current ones. Every answer names the sources it checked, so you can see what it read before quoting a figure internally.
It is the same catalog the [Topograph MCP](/guides/topograph-mcp) serves, so an answer here and an answer in your editor agree.
Conversations are saved to your account. Close the tab, come back next week or on another device, and pick up where you left off.
Sign in and open [/pricing](https://www.topograph.co/pricing) to try it.
## Any company request can now be downloaded as a PDF extract
Add `/pdf` to a request you have already made, and you get a single-file company extract — profile, legal representatives, shareholders, ultimate beneficial owners, other key persons, establishments and the ownership graph, whichever of those you asked for:
```bash theme={null}
curl --request GET \
--url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114/pdf \
--header 'x-api-key: ' \
--output company-extract.pdf
```
It is free, and never billed again. The extract renders data the request already paid for, so it triggers no new fetch and you can re-download it as often as you like.
### You do not have to wait for the request to finish
By default the extract renders whatever has arrived, matching `GET /v2/company/{requestId}`, which has always returned partial results while a request runs.
That is safe because a partial extract cannot be mistaken for a complete one. It carries its own disclosure:
* The seal reads **PARTIAL** rather than **VERIFIED**.
* A **Data completeness** section lists every requested datapoint and whether it was included, is still being retrieved, or failed — with the reason it failed.
* The `X-Topograph-Data-Status` response header carries `complete` or `partial`, so you can branch on it without opening the file.
If you would rather have an error than a partial file — for an archival export that must not be a snapshot of a half-finished request — pass `requireComplete=true` and get a `409` naming what it is still waiting on:
```json theme={null}
{
"code": "extract_data_incomplete",
"message": "The request is still running, so the extract would be partial.",
"pendingDataPoints": ["shareholders"]
}
```
Only datapoints decide completeness. Documents are delivered as separate files and never appear in the extract, so a document still downloading does not hold the PDF back.
The seal also stops overstating what it knows. It reads **UNVERIFIED** where a datapoint came from a non-authoritative source, rather than claiming verification for everything.
See [Company Data](/essentials/retrieve_company#pdf-extract).
## Poland now covers entities that are in neither KRS nor CEIDG
Polish company data came from two registers: **KRS** for legal entities and **CEIDG** for sole traders. An entity in neither was unreachable — most visibly a **spółka cywilna** (civil-law partnership), which holds a NIP and a REGON and trades normally, but is a contract between partners rather than a legal entity, so no entrepreneur register lists it.
We now also read the **REGON** register (`krajowy rejestr urzędowy podmiotów gospodarki narodowej`), the statistical register kept by Statistics Poland. Entry in it is compulsory for every entity in the national economy, so it reaches what the other two structurally cannot.
Two things change for a `spółka cywilna`, using its own NIP or REGON:
| | Before | Now |
| - | - | - |
| Search | Returned only the individual partners | Returns the partnership itself, alongside its partners |
| `GET /v2/company` | `notFound` | Returns the partnership's profile |
The same applies to housing communities, foreign representative offices, schools and public-sector bodies.
Data served this way is attributed with a new register code, wherever register codes already appear (`dataSources..register`, and `source.register` on documents):
```json theme={null}
"dataSources": {
"legalName": { "type": "live_from_registry", "register": "regon" },
"legalForm": { "type": "live_from_registry", "register": "regon" }
}
```
**REGON is a statistical register, so it returns identity only** — legal name, short name, legal form, registered seat, activity codes (PKD) and the registration and closure dates. It records no owners, representatives or beneficial owners, so a company served from REGON returns no management board and no shareholders. Beneficial ownership is unchanged and still comes from CRBR.
REGON is queried **only when neither KRS nor CEIDG holds the entity**. Every company already covered is served exactly as before, from the same register, with the same fields — for anything in the court register, KRS remains richer and authoritative.
One limit worth knowing: no register issues an extract for a `spółka cywilna`, so **documents are still requested per partner**, using that partner's own NIP. See [Poland](https://www.topograph.co/countries/pl).
## The published OpenAPI spec now matches what the API returns
Several of you told us the spec at [docs.topograph.co/openapi.json](https://docs.topograph.co/openapi.json) disagreed with the responses you were getting. Where a client is generated from that file, the disagreement is not cosmetic: it rejects calls, or discards values it was told could not exist. Every case we know of is fixed, and the spec is now regenerated and checked on every change, so it cannot silently fall behind again.
### `POST /v2/company` documents `201`
Creating a request has always answered `201 Created`. The spec listed only `200`, so a strictly generated client rejected every creation response. Both codes are now documented, and they mean different things:
| Code | When |
| - | - |
| `201` | A new request was created. Poll for the result with `requestId`. |
| `200` | You passed a `requestId` and got an existing result back. Nothing was created. |
`POST /v2/onboarding` answers `201` on both paths and now says so. No behaviour changed on either endpoint; only the documentation was wrong.
### Every datapoint error code is listed
`dataStatus` could return codes the spec never mentioned, including `account_configuration_required`, `source_unavailable`, `no_data_available` and `budget_exceeded`. The enum is now derived from our internal registry, so it cannot fall out of step again.
Please still treat it as an open vocabulary: keep the raw string when you meet a code your client does not recognise, rather than dropping it. A code you cannot classify is more useful than no code at all.
### A monetary amount can arrive without a currency
`currency` was marked required on `MonetaryAmountDTO`, and some sources do not state one. A German Gesellschafterliste, for example, publishes a bare Nennbetrag. A client following the schema to the letter discarded the amount without warning.
`currency` is now optional. When it is absent, the figure is still exactly what the register published, so keep it:
```json theme={null}
{ "amount": 7484400, "formatted": "7,484,400" }
```
`formatted` is now always present, falling back to the bare grouped number when there is no currency to format against. `amount` remains a JSON number in every case: where we cannot express a value as one, we omit the whole object rather than publish a string.
### Control nature uses `null`, not `"unknown"`
This changes a value in the response body. If you match on the string `"unknown"` for `control.details[].nature`, switch to a null check.
`nature` carries three distinct facts, and they matter in compliance:
| Value | Meaning |
| - | - |
| `"direct"` / `"indirect"` | The register stated it. |
| `null` | The register stated the control, but not its nature. |
| Absent | The register said nothing about nature at all. |
The middle case is common and real: the Belgian UBO register and the German Transparenzregister never disambiguate, and a UK PSC statement either carries an indirect marker or nothing. It used to be published as the string `"unknown"`, which was not in the documented enum, so strict clients deleted it and could no longer tell "the register does not know" from "no such information".
This applies to requests you made before the change too. Re-fetching an older `requestId` returns `null` where it previously returned `"unknown"`.
### Fields no longer promised
Six fields were marked required that we cannot always deliver. They are now optional, which is simply an accurate description of what you were already receiving:
`company.countryCode`, `control.description`, `ultimateBeneficialOwners[].control`, `companyRelationships[].company`, and, on requests, `id` and `countryCode` (both derived from the parent on a graph continuation).
Two moved the other way, because they are always present: `request.companyId` and `request.requestId`.
### What keeps it honest
The spec is generated from the same classes that build the response, and CI now fails if the published file drifts from them, if a route answers with a status code it does not document, or if a schema annotation contradicts the field it describes. Our daily suite additionally checks live responses across every country we cover against the published spec.
## Country pages and the catalog now publish indicative response times
Every country now carries indicative timings for search, for each datapoint in each mode, and for each document. They appear under **Speed** on the country pages, in the price list workbook, and on `/v2/catalog`:
```json theme={null}
"performance": {
"search": { "latencyMs": 2000 },
"datapoints": [
{ "datapoint": "company", "mode": "verification", "latencyMs": 3000 }
],
"documents": [
{
"documentType": "financial_statements",
"latencyMs": 1000,
"withProcessing": { "latencyMs": 30000 }
}
]
}
```
**These figures are strictly indicative and are not contractually binding.** Actual response times vary with load, register availability and rate limits, how much the register holds on a company, and the mode you request. They are not a service-level commitment.
What each figure covers:
| Figure | Covers |
| - | - |
| `search` | Time until the result you went on to fetch appeared. |
| `datapoints[*]` | The source that supplies the datapoint, per mode. |
| `documents[*].latencyMs` | The document file, which is released as soon as it is fetched. |
| `documents[*].withProcessing` | The same document including conversion and, where it yields structured data, that extraction. |
`withProcessing` is present only where processing costs real time. A French financial statement is about one second to the file and thirty to the parsed figures.
A datapoint or document with too little traffic to estimate from is left out rather than guessed at, and `lowConfidence` marks a figure resting on a thin sample. A country with nothing to publish carries no `performance` block at all.
## A succeeded datapoint now always carries its list, empty when the register published nothing
The list-shaped fields (`legalRepresentatives`, `otherKeyPersons`, `establishments`, `shareholders`, `subsidiaries`, `ultimateBeneficialOwners`) used to be omitted entirely when they had no entries. A datapoint could therefore report `"status": "succeeded"` with no corresponding key in the body, which was indistinguishable from a datapoint that never ran.
They now follow one rule, in the API response and the webhook payload alike:
```json theme={null}
{
"request": {
"dataStatus": {
"dataPoints": { "shareholders": { "status": "succeeded" } }
}
},
"shareholders": []
}
```
| Shape | Meaning |
| - | - |
| `[ … ]` | The records the register published. |
| `[]` | The datapoint succeeded and the register published no records. |
| Key absent | Not requested, still running, or `failed`. |
`succeeded` with a missing key can no longer happen. If you branch on presence (`if (response.shareholders)`), note that `[]` is truthy — switch to a length check. Nothing changes for a populated list, and no key that was previously present has been removed.
Worth knowing when reading an empty list: it means *the register holds no such record*, which is not always *the entity has none*. The Dutch KVK, for instance, registers a shareholder only when a company has a single 100% holder, so a BV with several shareholders returns `shareholders: []`. See [Netherlands](https://www.topograph.co/countries/nl#reading-an-empty-shareholders-list) and [Retrieve a company](/essentials/retrieve_company).
## Every supporting document now names the register it was collected from
When data is derived from documents (reconstructed shareholders, and any other `ai_analysis` source), `dataSources` already listed *which* documents were involved. Each entry now also says **where that document came from**, via a `register` code:
```json theme={null}
"documents": [
{ "name": "K-bis", "date": "2025-01-14", "register": "infogreffe" },
{ "name": "Capital increase notice", "date": "2024-03-02", "register": "inpi" }
]
```
The codes are the same vocabulary as `dataSources..register` and the `source.register` carried by every document in `availableDocuments`. The attribution is per-document rather than on the parent source, because a single reconstruction routinely draws on filings from more than one register. `register` is omitted when the register behind a document isn't known.
This is additive. No existing field changes shape. See [Shareholders Extraction](/essentials/shareholders-extraction#identifying-reconstructed-shareholders).
## Statutory filing dates now cover four more countries, read directly from the register's document
`company.statutoryFilings` now covers the Netherlands, Jersey, Singapore and Portugal, alongside the register-published countries it already covered.
For these four, the filing date comes from the register's own document text rather than a structured field, since the underlying registers don't expose one. See [Compliance Signals & Statutory Filings](/essentials/compliance-signals) for exactly what each country publishes, and how to tell these four apart from a register-stated date before building a compliance decision on top of them.
## Monitoring now surfaces credential-gated datapoints instead of failing silently
A handful of datapoints require your own account credentials for a third-party register -- most notably `ultimateBeneficialOwners` in Germany, sourced from the Transparenzregister, which by law only grants access to obliged entities making their own AML/KYC check. Previously, monitoring a company for one of these datapoints without the required credentials configured would fail that datapoint on every scheduled recheck with no visibility beyond the raw API error.
`POST /v2/monitors` now returns a `datapointNotices` array when a monitor is created for an account missing a required credential -- the monitor is still created, and every other datapoint is unaffected. Scheduled rechecks skip the affected datapoint rather than repeating a doomed fetch daily, and resume automatically once you configure the credential. You'll also receive a one-time `monitor.datapoint_blocked` webhook when a datapoint becomes unavailable this way, and `monitor.datapoint_unblocked` once it resumes -- these fire once per transition, not on every recheck.
See [Company Monitoring](/essentials/monitoring#credential-gated-datapoints) and [Germany](https://www.topograph.co/countries/de#quirks--gotchas).
## Statutory filing dates, and three new compliance signals
`company.statutoryFilings` is a new field carrying the periodic filing obligations a register holds a company to: the statutory annual accounts, and the confirmation filing that periodically confirms the company's particulars are current. Each obligation reports the period last filed and the one next due.
```json theme={null}
"statutoryFilings": {
"accounts": {
"financialYearEnd": "03-31",
"lastFiled": { "periodStart": "2024-04-01", "periodEnd": "2025-03-31" },
"next": { "periodStart": "2025-04-01", "periodEnd": "2026-03-31", "dueDate": "2026-12-31", "overdue": false }
},
"annualFiling": {
"cadence": "annual",
"lastFiled": { "periodEnd": "2025-10-25" },
"next": { "periodEnd": "2026-10-25", "dueDate": "2026-11-08", "overdue": false }
}
}
```
Both obligations exist in nearly every jurisdiction under different local names, so this is a cross-country field rather than one register's schema. It ships for the United Kingdom (the full calendar for both obligations), Ireland (the annual return, including the NARD), Guernsey (the annual validation), and 15 US states (the annual or biennial report).
`company.complianceFlags` gains three signals alongside the two overdue flags: `registeredCharges` (charges or mortgages over the company's assets), `insolvencyHistory` (insolvency proceedings in the company's history, so it stays set after a company recovers) and `liquidated`. All three ship for the United Kingdom.
**One behavioural change worth reading.** A compliance flag now appears whenever the register formally states the signal, carrying the register's answer in `active`, not only when the answer is "yes". So a UK company in good standing now returns `"registeredCharges": { "active": false }`, which is Companies House positively clearing it. An **absent** key means we hold no formal statement either way, and is not a clearance. This is additive: new keys appear with `active: false`, and no existing key changes shape. But if you treated the presence of a key as meaning "something is wrong", switch to reading `active`.
Every country's manifest now declares exactly which flags and filing dates it populates, and whether its register ever states the negative, so you can tell "the register says no" from "this country doesn't publish it" before you integrate.
See [Compliance Signals & Statutory Filings](/essentials/compliance-signals).
## Italy: a wrong identifier now answers immediately
`/v2/company` for Italy accepts the Codice Fiscale, and only the Codice Fiscale: 11 digits with a valid control digit, or the 16-character personal code for a sole proprietor. The `IT` prefix, surrounding whitespace, dots and hyphens, and lowercase input are all accepted and normalized to the bare uppercase form, so `IT01234567890` and `01234567890` are one company and one cache entry rather than two.
Anything else now returns `400 invalid_request` straight away, naming the expected format, and is not billed. The common case is a REA or CCIAA + REA code such as `RM-1734032`, which Italian register documents print next to the company name. Sending one used to take around 30 seconds and come back as "the register is temporarily unavailable". A wrong identifier now reads as a wrong identifier.
If you hold a REA code, a sole proprietor's Partita IVA, or a company name, pass it to [`/v2/search`](/essentials/search): it resolves all of them to the Codice Fiscale to use on `/v2/company`. See [Italy](https://www.topograph.co/countries/it#company-identifiers).
## Lithuania now available
Company data for Lithuania is available on `/v2/company` and `/v2/search`, covering the company profile: legal-entity code, registered name, registered office address, registration date, legal form and legal status, plus registered share capital for the forms that declare one. Entities removed from the register are covered too, and report their removal date.
Legal forms and statuses come from the register's own classifiers, so you get the Lithuanian name, the official English translation, and a standardized Topograph category for all 168 forms and 30 statuses.
Two things to know before you integrate:
* **Request Lithuania in `onboarding` mode.** Data comes from the register's daily open-data extracts, so a change filed with the register can take up to 24 hours to appear. There is no live register query, and the default verification path has no source to resolve.
* **Officers, shareholders and beneficial owners are not available.** The register publishes only counts in its open data, never names: how many governing bodies an entity has, and how many participants split by resident or foreign and natural or legal person. No amount of processing turns that into a person, so these datapoints are not offered for Lithuania rather than returned empty.
One coverage note: the register anonymises the names of individual enterprises (IĮ), general partnerships (TŪB) and limited partnerships (KŪB) in its open data, because those names contain personal names. Around 13,500 entities are affected. They return their legal-entity code, address, registration date, legal form and status as normal, but their registered name reads as the bare legal-form label. You can look them up by code, not find them by name.
See [Lithuania](https://www.topograph.co/countries/lt) for the full reference.
## Send a test notification for a monitor
You no longer have to wait for a real change to validate a monitoring integration. Open a monitor in the dashboard and click **Send Test Notification**, or call the new endpoint:
```bash theme={null}
curl -X POST https://api.topograph.co/v2/monitors/{monitorId}/test-notification \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "changeCategories": ["status"] }'
```
The event is built exactly as a genuine change notification is, with your own `monitorId` and `metadata` and the real company, so it exercises workflows that route on the metadata you set at monitor creation. The sample payload in the webhooks portal carries neither. You can pick the change category, or send the deactivation variant to exercise your cleanup branch. Your monitor is not modified.
Note that a test notification is deliberately indistinguishable from a real one, so what you test is what you get in production. If your pipeline opens a case for every notification, a test will open a real case. See [Company Monitoring](/essentials/monitoring#step-4-test-your-integration).
## One consistent rule for sole entrepreneurs and non-profits
Sole entrepreneurs (entrepreneur individuel, ЕТ, ditta individuale, ΑΤΟΜΙΚΗ, ФОП, …) and non-profits now behave the same way in every country:
* **`legalRepresentatives`** always returns the person behind a sole entrepreneur (with the identity fields the register publishes), and the officers/board for non-profits.
* **`ultimateBeneficialOwners`** returns the sole entrepreneur as the beneficial owner at 100% direct ownership where the country exposes a UBO datapoint. This is the AML-correct answer to "who owns this business", even when the register requires no separate UBO declaration for these forms.
* **`shareholders`** is never synthesized for entities that have no share capital. Instead of an empty array (or, in some countries, an invented 100% record), the datapoint now completes with a new machine-readable error code:
```json theme={null}
{
"status": "failed",
"error": {
"code": "datapoint_not_applicable",
"message": "Sole entrepreneurs have no share capital, so no shareholder record exists. The owner is returned under legalRepresentatives and, where available, ultimateBeneficialOwners.",
"retryable": false
}
}
```
`datapoint_not_applicable` is a definitive, benign answer: don't retry it, and don't treat it as an outage. When `shareholders` is the only datapoint of its billing block in the request, the block is automatically refunded.
If you previously relied on a fabricated 100% shareholder for Bulgarian ЕТ, Hungarian egyéni vállalkozó, Ukrainian ФОП, or Irish business names, read the owner from `legalRepresentatives` / `ultimateBeneficialOwners` instead. The rollout is per-country (Bulgaria, Greece, France, Italy, Hungary, Ukraine, and Ireland first); countries not yet converted may still return an empty array for these entity types.
Full behavior matrix: [Sole Entrepreneurs & Non-Profits](/essentials/entity-types).
## Metadata on monitors
`POST /v2/monitors` now accepts an optional `metadata` object: arbitrary key-value string pairs stored on the monitor and echoed back in monitor responses and in every `monitor.notification` webhook.
```json theme={null}
{
"companyId": "932884117",
"countryCode": "FR",
"metadata": { "caseId": "case-12345" }
}
```
Use it to map webhook notifications back to your internal records without keeping your own monitor-to-case mapping. Company requests already supported `metadata`; monitors now work the same way. See [Company Monitoring](/essentials/monitoring#step-1-create-a-monitor) for details.
Alongside this, the `monitorId` in `monitor.notification` webhooks now matches the `id` returned by `POST /v2/monitors`. Previously it carried an internal identifier that did not correspond to any monitor id visible in the API, so it could not be used for correlation. If you stored past webhook `monitorId` values, re-key on the ids from `GET /v2/monitors`.
## Documents now name their issuing register
Every document returned by `/v2/company` now carries a `source` object identifying the register it comes from, in the same format as the `dataSources` section:
```json theme={null}
"tradeRegisterExtract": {
"id": "1c932de4-4610-5506-b48d-4e62529d58e8",
"name": "Extrait K-bis (certifié)",
"source": {
"type": "live_from_registry",
"register": "infogreffe"
}
}
```
The field appears on every entry in `availableDocuments` and on every downloaded document, across all countries. Use `source.register` to show the issuing authority to your users, or to tell registers apart in countries where documents come from more than one source.
This is an additive change: no existing field moves. See [Document Retrieval](/essentials/document-guide#document-source) for details.
## Company history, filing by filing
Two registers now expose their full change history as a document, joining the Netherlands, Italy, and France under `documents.tradeRegisterHistory`.
* **Germany**: the Chronologischer Abdruck, the chronological register print listing every entry ever made against a company.
* **Ukraine**: a certified extract from the state register, orderable like any other document.
## Czech shareholders
Shareholders (společníci) are now returned for Czech companies. Add `shareholders` to your `dataPoints` on any `/v2/company` request, with ownership stakes as recorded in the Commercial Register.
Coverage follows what the register publishes: limited liability companies (s.r.o.) list their members, while joint-stock companies (a.s.) do not publish a shareholder list and return an empty array.
## Hungarian annual accounts
Annual financial statements for Hungarian companies are now available under `financialStatements`, sourced from the national filing portal.
## Beneficial ownership in three more jurisdictions
`ultimateBeneficialOwners` now resolves for **Cyprus**, **Slovenia**, and **Portugal**. Each request returns the parsed owners list plus the official certificate from the local register as a `ubo_extract` document.
These jurisdictions are fulfilled within one to three business days and carry a **Manual** badge on the pricing page.
## Every request now ends with a webhook
The terminal `company.updated` webhook is now always delivered when a request reaches its final state. If you saw requests that looked stuck as pending because the closing webhook never arrived, that is fixed. Use it together with `request.version` (see week 26) to keep your own copy in step.
## Ownership graphs cross borders
The `graph` datapoint now follows corporate shareholders into the country where they are incorporated, instead of stopping at the register boundary. A French company held by a German parent resolves that parent against the German register and keeps walking up the chain.
Where a country has no shareholder coverage, exploration stops cleanly at that node, so the graph tells you where the trail genuinely ends.
Ownership percentages are also reported only where the register states them. Holdings with no declared stake come back without a percentage rather than an even split across shareholders, so a number in the graph is always a number the register published.
## The ownership graph says why a node stopped
Nodes that cannot be expanded now explain themselves, with a badge and a short reason such as an unknown country of incorporation or an identifier that could not be resolved. A branch that ends is now distinguishable from one that failed.
## Italy: Fascicolo Storico
The Fascicolo Storico is now available on `/v2/company`. It records the history of share and quota transfers for an Italian company, filing by filing, which is what you need to reconstruct how ownership arrived at its current state.
Request it the same way as any other document: ask for `availableDocuments`, then pass the returned `id` back in `documents: [...]`.
## Luxembourg: publications and filings
Official publications and register filings for Luxembourg companies are now retrievable, covering the notices and deposited acts published for each entity.
## Portugal: publications
Portuguese company publications are now served through a dedicated index, with both a fast and an authoritative mode for company data.
## France: several INPI accounts on one integration
AML-obligated entities using their own INPI credentials for un-redacted UBO data can now register several accounts under a single configuration. Requests rotate across them, with automatic failover if one is unavailable, so a single account's rate limit no longer caps your throughput.
## Activity codes per establishment
Establishments now carry their own activity codes, not just the parent company's. A retailer whose head office is classified under management activities and whose branches are classified under retail now shows each correctly. Available for France and Belgium.
## Germany: flexible register search
`/v2/search` now accepts German register references the way people write them: abbreviated court codes, partial register numbers, and the court and number in either order. `HRB 12345 München` and `München HRB 12345` both find the same company.
## Webhooks: ordering guarantee
Webhook payloads now carry `request.version`, an incrementing counter you can use to order snapshots. When two webhooks for the same request arrive out of order, compare `version` and keep the higher one. This complements the existing guidance to merge rather than replace on `company.updated`.
## Cleaner response shapes
Three corrections to how optional data is represented, so strict consumers and generated clients behave predictably:
* Person identifiers are documented as a flat object rather than an array.
* Empty addresses are omitted entirely instead of returning an object of nulls.
* Optional response fields are no longer marked required in the OpenAPI spec.
## Faster US responses
Search and profile calls across a large set of US states are now several times quicker, with typical lookups landing in around two seconds.
## The United States, coast to coast
Company data is now available for **all 50 US states and Washington DC**, each sourced directly from that state's Secretary of State or equivalent business register. Texas, announced in week 18, was the first of the set. The rest are now live.
### What you get
Every state returns the company profile: legal name, status, formation date, registered address, registered agent, and entity type. Most states also return officers and directors as legal representatives, and a **Trade Register Extract** bundled with the company data at no extra charge.
Where a state issues official certificates (Certificates of Good Standing, Certificates of Existence, status reports, certified copies), they are available as orderable documents.
### Fast and authoritative modes
Most states offer both. Onboarding mode answers in seconds from state-published bulk data, which is what you want behind a signup form. Verification mode reads the live register for an authoritative answer. Pick per request with `mode`.
### Beta
US states ship as **beta** while coverage settles. Each state page carries the label, and the `developmentStatus` field on the country catalog exposes it programmatically so you can treat beta jurisdictions differently in your own flows.
Every state has its own page under [North America](https://www.topograph.co/countries/us-tx), listing accepted identifiers, available datapoints, and documents.
## New jurisdictions
**Antigua and Barbuda** and the **Marshall Islands** are now available on `/v2/company` and `/v2/search`.
## Filing-compliance signals
`company.complianceFlags` is a new field carrying signals the register reports about a company's filing standing. Two kinds ship first, both for the United Kingdom:
```json theme={null}
"complianceFlags": {
"accountsOverdue": { "active": true, "dueDate": "2024-09-30", "source": "companies_house" },
"annualFilingOverdue": { "active": false }
}
```
Each kind carries `active` plus `dueDate`, `since`, and `source` where the register reports them. The shape is country-agnostic, so the same keys will be reused as more registers publish these signals. A flag is present only when its register reports it.
## Belgium: coordinated articles of association
Belgian companies now return their coordinated statutes, the consolidated current text of the articles, under `documents.articlesOfAssociation`.
## Better ownership and profile data
* **Denmark**: beneficial owners are now also returned where the register records control by role rather than by shareholding, so more Danish companies resolve to a named owner.
* **Spain**: companies can be found by hoja registral, and it is returned in `company.identifiers`. `incorporationDate` is now the company's true constitution date, and a separate `registrationDate` carries the date it entered the register.
* **Belgium**: sole traders and natural-person businesses now carry a `legalForm`, standardized as a sole proprietorship, instead of leaving the field empty.
* **Malta**: `/v2/search` matches registration numbers written without a space, across every register prefix.
* **China**: company data and shareholders are now separate blocks, so you can buy either on its own, and beneficial ownership is available.
* **Cayman Islands**: a Director Details document is now orderable.
## Check your balance from the API
`GET /v2/billing/balance` returns your account's current remaining credit. Poll it to surface a balance in your own dashboard, or to alert before a batch run drains the wallet. This pairs with the low-balance notifications and auto top-up already available in the app.
## Trials no longer switch themselves off
Reaching the end of a trial no longer deactivates an account or blocks API calls. Your integration keeps working while commercial terms are settled.
## UBO certificates as orderable documents
For **Croatia** and **Serbia**, the official beneficial-ownership certificate is now surfaced in `availableDocuments` as a `ubo_extract` you can order on its own, without requesting the parsed `ultimateBeneficialOwners` datapoint.
## German WZ 2025 activity codes
German companies now return WZ 2025 codes alongside the existing WZ 2008 codes. WZ 2025 is the current edition of the German Klassifikation der Wirtschaftszweige (the national implementation of NACE Rev. 2.1).
Both appear under `company.activities`:
```json theme={null}
"activities": {
"WZ2008": [{ "code": "62.01.9", "description": "Sonstige Softwareentwicklung", "isAIInferred": true }],
"WZ2025": [{ "code": "62.10.3", "description": "Entwicklung und Programmierung von Anwendungssoftware", "isAIInferred": true }]
}
```
`WZ2008` is unchanged, so existing integrations keep working. `WZ2025` is up-converted from the WZ 2008 code using the official Destatis correspondence table. When a WZ 2008 code splits into several WZ 2025 codes, `WZ2025` contains all of them. As with NACE and ISIC, German activity codes are inferred from the company purpose and flagged `isAIInferred: true`.
See [Germany](https://www.topograph.co/countries/de) for the full reference.
## Poland: full board and shareholder names
Polish board members and shareholders now come back with their complete names, resolved from the register's official extract rather than the abbreviated public listing.
## Finland: companies awaiting registration
Finnish entities that exist with the tax authority but are not yet entered in the trade register are now returned, with a status that marks them as not yet registered. Useful when onboarding a business that has just been formed.
## Spanish foundations now available
Spanish foundations are now covered on `/v2/company` and `/v2/search`. Foundations carry a NIF beginning with **G**, resolved through the Registro de Fundaciones (Ministerio de Justicia). You get the company profile, the governing board (patronato) as legal representatives, and a Foundation Register Extract under `documents.tradeRegisterExtract`.
See [Spain](https://www.topograph.co/countries/es) for the full reference.
## Italian articles of association (Statuto) available
The Italian Statuto (articles of association) is now available on `/v2/company`, returned under the existing `documents.articlesOfAssociation` response key alongside France and the UK.
The document is the company's constitutional text as filed at the Chamber of Commerce, with every amending protocol indexed inside the PDF.
```http theme={null}
POST /v2/company
{
"countryCode": "IT",
"id": "04046761203",
"dataPoints": ["availableDocuments"]
}
```
The document appears as `documents.articlesOfAssociation` with `format: "pdf"` and an `id`. Pass that `id` back in `documents: [...]` to order the PDF. The response includes a signed `url` for download. Delivery time is in line with the other Italian documents.
## Bosnia and Herzegovina now available
Company data for Bosnia and Herzegovina is now available on `/v2/company` and `/v2/search`.
The integration covers the unified **Registar poslovnih subjekata BiH** — a single portal serving all three entities: Federation of BiH, Republika Srpska, and Brčko District.
### What's included
* **Company profile**: legal name, trade name (abbreviation), registration number (MBS), unique identification number (JIB/IDU), address, legal form, company status, share capital, registered activities (KD BiH 2010 / NACE Rev. 2), incorporation date, and branch offices as establishments.
* **Legal representatives**: directors, general directors, procurists, executive directors — with signatory mode (sole / joint) and authorisation details where registered.
* **Other key persons**: board members (`član Uprave`), supervisory board chairs (`Predsjednik nadzornog odbora`).
* **Shareholders**: founders of limited liability companies (d.o.o.), partnerships (k.d., d.n.o.), sole traders, associations, and foundations. Joint-stock companies (d.d.) list only a reference to the share register — no individual shareholders.
* **Trade Register Extract**: full printed PDF covering all 8 register sections (basic data, founders, management, capital, activities, branch offices, foreign trade, notes).
### Identifiers
Bosnia uses the **MBS** (Matični broj subjekta) as its primary identifier. The format varies by sub-register: `NN-01-XXXX-YY` for private companies in Federation BiH and Brčko, `NN-02-XXXX-YY` for joint-stock companies, and `N-XXXX` for Republika Srpska. Hyphens are part of the identifier. The JIB (13-digit tax ID) is returned in the response but cannot be used for lookups.
See [Bosnia and Herzegovina](https://www.topograph.co/countries/ba) for the full identifier and data availability reference.
## Consistent identifier keys in `company.identifiers`
Every company's registration numbers are now returned under consistent, local-language keys in `company.identifiers`, matching each country's own terminology. Most countries are unchanged. A few had a key renamed to follow the convention.
For the countries below, both the old and new keys are returned together until 1 September 2026. After that date, only the new key is returned. Update any code that reads the old key before then.
| Country | Old key | New key |
| - | - | - |
| Belgium | `Numéro BCE` | `ondernemingsnummer` |
| Spain | `NIF` | `nif` |
| Italy | `Codice Fiscale` | `codiceFiscale` |
| Italy | `CCIAA` | `cciaa` |
| Italy | `REA Code` | `rea` |
| Austria | `EUID` | `euid` |
The same canonical key now appears everywhere the number does: on the queried company, on related companies (officers, shareholders, subsidiaries), and in search match results. VAT is always returned under `VAT`.
If you parse `company.identifiers` by key for Belgium, Spain, Italy, or Austria, switch to the new key before 1 September 2026. Each country's accepted identifiers are listed on its page.
## Portugal: two more documents
Portuguese companies now offer an uncertified **Trade Register Extract** (a compilation of the company's register publications) alongside the existing certified extract, and **Annual Accounts** can be ordered on their own.
## Faster onboarding mode in more countries
Onboarding mode, which answers in seconds and is what you want behind a signup form, now covers **Cyprus, Greece, Latvia, Monaco, Poland, Portugal, France, and Sweden**. Verification mode is unchanged and remains the authoritative path. Pick per request with `mode`.
## Moldova now available
Company data for Moldova is available on `/v2/company` and `/v2/search`, covering the company profile, legal representatives, and shareholders, with activity codes mapped to NACE and ISIC.
See [Moldova](https://www.topograph.co/countries/md) for the full reference.
## Activity codes now standardized to NACE Rev. 2.1 and ISIC Rev. 5
Every company response now returns activity codes on the current international standards: **NACE Rev. 2.1** (the European classification in force since 2025) and **ISIC Rev. 5** (the global standard). Previously we returned the prior revisions (NACE Rev. 2 and ISIC Rev. 4).
### What changes
* The `activities.NACE` array uses NACE Rev. 2.1 codes, and `activities.ISIC` uses ISIC Rev. 5 codes, for every country.
* Where a register still publishes Rev. 2 codes, we upconvert them to Rev. 2.1 using the official Eurostat transition table.
* A handful of Rev. 2 codes were split into several Rev. 2.1 classes (for example, holding companies moved from a single code to separate financial and non-financial holding codes). When a code splits, we return all of its Rev. 2.1 successors, so the correct class is always present.
* The register's own local activity code (NAF, ATECO, ΚΑΔ, CAEN, SBI, and so on) is still returned under its own key, unchanged.
* `activities.ISIC` and `activities.NACE` are now always returned together for every country: when a register publishes only one of the two, we derive the other from the official correspondence. The pair is absent only when the register exposes no activity data at all.
### What to check
If you store or match on NACE or ISIC codes, review your mappings against NACE Rev. 2.1 and ISIC Rev. 5. Some four-digit codes were renumbered (for example, computer programming moved from `62.01` to `62.10`). See [Data Standardization](/guides/standardization) for how the mapping works.
## Italian Visura Camerale now ships in Italian, with the full register content
The `certifiedTradeRegisterExtract` document for Italy is now delivered in Italian, with every section the Registro Imprese publishes. No request change, no price change, no delivery-time change.
### New content in the PDF
* **Oggetto sociale** (corporate object): the full legal scope of the company, verbatim from the articles of association.
* **Poteri di firma** (board powers): the structured signing powers per officer, including joint vs. several authority and delegation rules.
* **ATECO classification**: the code is now explicitly labelled "ATECO" alongside the NACE mapping.
* **Per-branch activity matrix**: primary and secondary ATECO codes for every registered branch.
* **Statutory clauses**: withdrawal, exclusion, and pre-emption clauses flagged where present.
* **Employee distribution**: quarterly breakdown by contract type, working hours, qualification, and municipality, on top of the headcount.
* **Filing activity indicators**: filings in the last 12 months, share transfers, address transfers, holdings.
* **Available document inventory**: the list of fiscal years for which financial statements are available, plus indicators for the company file (fascicolo), articles of association (statuto), and other registered acts.
* **Quality and environmental certifications**: SOA qualification, ISO and other quality certificates, environmental rolls.
### How to request it
The request is unchanged.
```http theme={null}
POST /v2/company
{
"countryCode": "IT",
"id": "01234567890",
"dataPoints": ["availableDocuments"]
}
```
The document appears as `documents.certifiedTradeRegisterExtract` with `format: "pdf"` and an `id`. Pass that `id` back in `documents: [...]` to order the PDF. The response includes a signed `url` for download.
The new content applies to companies (società di capitale, società di persone) and sole proprietorships. Sole proprietorships do not have a corporate object or board powers, so those sections are absent for that entity type. The ATECO labelling fix applies to every entity type.
## France: Historique des modifications
France joins the Netherlands and Italy under `documents.tradeRegisterHistory`. The Historique des modifications lists every change filed against a French company since registration.
## Subsidiaries for France, Belgium, Germany, and the UK
The `subsidiaries` datapoint, introduced for Italy in week 18, now answers for **France, Belgium, Germany, and the United Kingdom**, and can be requested on its own without buying a full company block.
## Latin-script names for Bulgaria and Greece
`companyNameTransliterations` now also returns for **Bulgaria** and **Greece**, alongside Ukraine. Search matches Latin-script queries against Cyrillic and Greek company records, and the field lists the canonical Latin spellings.
## Pick documents by type, not by name
Document entries for France, the UK, and Austria now carry a `documentSubType` drawn from that country's own filing taxonomy. Select on it instead of matching the free-text `name` field, which varies per filing and is not a stable key.
## Latin search for Ukrainian companies
Ukrainian companies are registered in Cyrillic. You can now find them with a Latin-script query, and every Ukrainian company response carries a new `companyNameTransliterations` field with the canonical Latin spellings of its name.
### Search
A search like `Naftogaz`, `Kyivstar`, or `Pryvatbank` now matches the Cyrillic-only company record. Both common romanisations work: the modern Ukrainian spelling (`Naftohaz`) and the legacy spelling (`Naftogaz`). Diacritic forms pasted from academic or EU sources match too.
### New response field
`companyNameTransliterations` is a string array on both `/v2/search` results and `/v2/company` responses. It lists the deterministic Latin transliterations of the company's legal and commercial names, generated with three standards (modern Ukrainian, legacy, and the diacritic academic form), deduplicated. Use it to display alternative spellings or to match against your own records.
```http theme={null}
POST /v2/company
{
"countryCode": "UA",
"id": "00131305",
"dataPoints": ["company"]
}
```
The field is present for Ukrainian companies and absent for Latin-script countries. It complements the existing `transliterate=true` query flag, which romanises the whole response on demand. See [Transliteration](/essentials/transliteration) for how the two features differ.
## Historical trade register extracts
Two new historical documents are available on `/v2/company`, returned under a new response key `documents.tradeRegisterHistory`.
### Netherlands
`Uittreksel Handelsregister Historie` from the KVK. Lists every change ever filed against a Dutch company since registration: name changes, seat moves, board appointments and resignations, capital changes, status updates. Surfaced as `tradeRegisterHistory` in `availableDocuments` whenever KVK has a historical record for the company.
### Italy
`Visura Storica` from the Italian Chamber of Commerce. Lists every amendment to an Italian company since its registration, including ownership changes, officer changes, capital movements, and address history. Always available for active Italian companies.
### How to use it
```http theme={null}
POST /v2/company
{
"countryCode": "NL",
"id": "53781066",
"dataPoints": ["availableDocuments"]
}
```
The historical extract appears as `documents.tradeRegisterHistory` with `format: "pdf"` and an `id`. Pass that `id` back in `documents: [...]` to order the PDF. The response will include a signed `url` for download.
The historical extract sits alongside the existing `documents.tradeRegisterExtract` (current state only) and `documents.certifiedTradeRegisterExtract` keys, so you can request either or both depending on whether you need a point-in-time snapshot or the full change history.
## Test slow deliveries without waiting for one
The TEST country now accepts `DELAY_1M`, `DELAY_10M`, `DELAY_1H`, and `DELAY_10H` as company identifiers. Each returns a normal result after the delay in its name, so you can exercise your polling loop, your webhook handling, and your UI's pending state against a delivery that genuinely takes an hour.
They combine with the existing `GRAPH_*` fixtures. Build your integration against the slow path before a real register makes you.
## Ireland: shareholder provenance made explicit
Irish shareholders derived from annual return filings are now labelled `inferred` rather than read directly from the register, and the list states which fiscal year it covers. The data is unchanged; it is now honest about where it came from, so you can decide when to rely on it.
## Topograph MCP server and Claude Code plugin
Topograph now exposes an MCP server, so coding agents and AI assistants can read the country catalog, search the docs, pull the OpenAPI spec, and price a scenario without you pasting any of it in by hand. Sign in with your Topograph account to connect it.
There is also a Claude Code plugin that installs the server and a set of integration commands in one step. Point your agent at it when you are building against `/v2/search` and `/v2/company` and it will work from live coverage and pricing rather than from memory.
## Coverage and pricing, in the open
The public pricing page now documents, for every country: which registers each data block draws on, how requests route by entity type, the identifiers we accept, and the full legal-form, role, and status vocabularies with their standardised mappings.
Countries also carry a development status, so you can tell at a glance which jurisdictions are generally available and which are in beta. Capabilities we can deliver on request but have not shipped as self-serve are listed too, with a contact link.
## Errors name the register that failed
When an upstream register is unavailable, the error now names it. Instead of a generic "the data source is temporarily unavailable", you get the specific register, so your support team can tell at a glance whether the fault is upstream and your users can be told something meaningful.
The register name is available both in the error message and as a `source` field on the error, so you can branch on it in code.
Live register availability is published at [status.topograph.co](https://status.topograph.co), and you can subscribe there to be notified when a register we depend on is disrupted.
## Friendlier document downloads
Downloaded documents now arrive with a readable filename describing the document and the company, instead of an opaque identifier. No request change: the signed `url` simply serves a proper filename.
## Interactive ownership graph
Two new request fields on `/v2/company` give you click-by-click control over how deep the ownership graph goes.
### `graphInteractive`
Pass `graphInteractive: true` together with the `graph` datapoint to fetch only the entry company. Its direct shareholders are returned in the response: individuals as full nodes, companies as `budget_truncated` placeholders. Each placeholder carries a `nodeId`, a cost preview, and the depth at which it sits.
Use this when you want predictable per-step cost and a deterministic UI: one fetch, one billing event, the rest of the tree visible only as continuation handles.
When `graphInteractive` is set, `graphMaxBudget` is ignored.
### `graphContinueFromNodeIds`
Pass an array of `budget_truncated` nodeIds from a previous response to extend the graph from those leaves. The new request is linked to its parent via `mainRequestId`; `countryCode` and `id` are derived from the parent automatically. Cost deduplication applies across the full request tree, so already-paid companies are not re-billed.
If the parent request was made with `graphInteractive: true`, every continuation inherits the flag. Each chip click then expands a single level under the chosen node, with the new tier's company shareholders surfaced as fresh `budget_truncated` chips.
### Response field
`graph.metadata.interactive` is now returned alongside `stoppedReason`, `companiesFetched`, and `companiesSkipped` so you can tell whether a stored result was produced in interactive mode.
## Texas (US-TX)
Texas company data is now available, with full coverage of both formal entities and sole traders, and two official documents.
**Authoritative verification via the Secretary of State.** Verification-mode requests pull data directly from the Texas Secretary of State — the official corporate registry. This gives you authoritative entity status (In existence, Forfeited, Dissolved, Merged), the full untruncated officer record as filed, registered agent, assumed names, and formation details. Formal entities only (corporations, LLCs, limited partnerships, and other BOC-registered types).
**Fast onboarding via the Comptroller.** Onboarding-mode requests use the Texas Comptroller franchise tax and sales tax systems. Covers the same formal entities plus sole traders. Returns officers, registered agent, establishments, activity codes, and state of formation. Results in seconds.
**Two official documents.**
* **Information Letter** — Secretary of State document confirming entity status, filing date, and registered agent. Formal entities only.
* **Sales Tax Permit** — Comptroller record of permit status and outlet locations. Available for all permit holders, including sole traders.
Search accepts Taxpayer Number, Federal EIN, SOS File Number, or company name.
## Sweden: sole traders now supported
Swedish sole traders (enskild firma) can now be looked up by personnummer. Pass the 12-digit personal identity number (YYYYMMDDNNNN, with or without hyphen) as the identifier in any `/v2/company` request.
The profile returns `personalIdentityNumber` in `identifiers`, the correct VAT number derived from the personnummer, and all available company data from Bolagsverket. Available documents for sole traders are retrieved from the same document portal as other entity types.
## New datapoint: `subsidiaries`
Surface the companies a queried company holds equity in. Each entry carries the subsidiary's identifiers, ownership percentage, voting rights, number of shares, nominal capital held, and acquisition or end dates when reported.
Add `subsidiaries` to your `dataPoints` parameter to include them in any `/v2/company` request.
### Italy
First country to ship `subsidiaries`, sourced from InfoCamere. We return only current participations, picking the most recent filing per subsidiary and filtering out historical or dissolved holdings.
## Italy: `establishments` now available
Branch offices and secondary seats for Italian companies are now retrievable from InfoCamere. The response includes operational branches, secondary headquarters, and foreign branches, with full address and activity description. Closed locations are excluded.
## Beneficial ownership data for four new jurisdictions
The `ultimateBeneficialOwners` datapoint is now answered for **Ireland, Portugal, Serbia, and Croatia**. Each request returns the parsed beneficial owners list together with the official certificate from the local register, surfaced in `documents` as a `ubo_extract`.
### Ireland
Beneficial ownership data sourced from the Register of Beneficial Ownership (RBO).
### Portugal
Beneficial ownership data sourced from RCBE (Registo Central do Beneficiário Efetivo).
### Serbia
Beneficial ownership data sourced from APR's Centralna evidencija stvarnih vlasnika.
### Croatia
Beneficial ownership data sourced from the Registar stvarnih vlasnika (RSV).
### Delivery
These four sources are fulfilled within one to three business days. The pricing page surfaces them with a **Manual** badge so it's clear up front when to expect the result.
## Russia and Serbia now available
Two more jurisdictions are live on `/v2/company` and `/v2/search`.
* **Russia**: company and sole-entrepreneur data from the state register, with establishments, legal representatives, and shareholders.
* **Serbia**: company data from the Business Registers Agency, with establishments, legal representatives, other key persons, and shareholders.
See [Russia](https://www.topograph.co/countries/ru) and [Serbia](https://www.topograph.co/countries/rs) for the full reference.
## See how a reconstructed shareholding was derived
Where shareholders are reconstructed from filings rather than read from a shareholder register, `dataSources.shareholders` now explains the reasoning: an `overall` summary naming the documents used, a `limitations` list stating what the reconstruction cannot establish, and a per-shareholder narrative on each entry.
Use it to show your analysts why a percentage is what it is, and to decide when a figure needs a human check before it drives a compliance decision. The same detail is available for beneficial owners and for each node of the ownership graph.
## New document coverage across nine countries
Articles of association and annual accounts are now available on more jurisdictions, each retrieved from the country's official register.
### United Kingdom
Articles of association now include amendments filed after incorporation, not just the original filing. Special resolutions that change the articles land in `articlesOfAssociation`. Annual accounts unchanged.
### France
Articles of association (statuts) from INPI are now classified directly from the French register's official document dictionary. Statute filings, translations, cross-border merger statutes, and updated statute drafts all route into `articlesOfAssociation`. The same treatment applies to each component of the annual accounts.
### Slovakia
Annual financial statements (účtovné závierky) for every registered entity since 2009, from the Slovak financial statements register.
### Estonia
Annual reports (majandusaasta aruanne) for Estonian entities are now surfaced in `financialStatements`. Filings are available since 2010.
### Greece
First document integration for Greece: both `financialStatements` and articles of association (καταστατικό) from the GEMI publicity portal.
### Ukraine
Annual financial statements (Фінансова звітність підприємств) for Ukrainian legal entities, covering 2021 to 2025.
### Slovenia
Two new sources from AJPES:
* Articles of association (akt o ustanovitvi / statut) from the eObjave section.
* Annual reports (letno poročilo) from JOLP.
### Czech Republic
Annual reports and articles of association from the Sbírka listin (Collection of Deeds) of the Czech Commercial Register. Covers every filing type available on justice.cz, surfaced in `financialStatements` and `articlesOfAssociation`.
### Ireland
Company constitutions filed with the Irish Companies Registration Office (CRO), returned in `articlesOfAssociation`. Requesting a constitution triggers retrieval from CRO and returns the PDF like any other document.
## Germany: paid Hinterlegungen now retrievable
Voluntary §326 HGB financial-statement deposits filed by Kleinstkapitalgesellschaften are now part of the standard `availableDocuments` response. Requesting one returns the PDF like any other German document. See the live pricing page for current pricing.
## Retrieve a request with a GET
`GET /v2/company/{requestId}` returns a stored request result. Use it to poll a request to completion and to refresh expired signed document URLs, without rebuilding the original POST body.
The previous approach of POSTing `{"requestId": "..."}` still works, so nothing breaks. The GET is simply the natural shape for reading a result you already created.
## Onboarding mode has a firm deadline
Onboarding mode now enforces a 10 second budget per datapoint, end to end. A datapoint that cannot answer in time returns `onboarding_timeout` instead of holding your signup form open.
This makes onboarding latency predictable by design. When you need completeness over speed, use verification mode, which has no such cap.
## France: Avis de situation INSEE
Every active French company now carries an Avis de situation INSEE in `availableDocuments`, generated on demand from the national business directory. It confirms the company's registered identity, address, and activity, and is bundled with the French company data.
## Isle of Man now available
Company data for the Isle of Man is available on `/v2/company` and `/v2/search`, with a Trade Register Extract alongside the company profile.
## Germany: your own Transparenzregister credentials
AML-obligated entities can now connect their own Transparenzregister account to unlock German beneficial ownership data, the same way the French INPI credential flow works below. Add your register credentials in the app and UBO requests for Germany use them automatically.
## Latin-script responses for non-Latin countries
Getting company data from Bulgaria, Ukraine, Greece, China, or Hong Kong? You can now ask for the response in Latin characters.
Add `transliterate=true` to any `/v2/search` or `/v2/company` call and the company names, addresses, officer names, and activity descriptions come back romanized. Useful when your CRM, KYC system, or spreadsheet export only handles Latin text.
The flag does not change retrieval or billing. It is a presentation option applied to the response on the way out.
See the [Transliteration guide](/essentials/transliteration) to learn more.
## France: customer INPI credentials for AML-obligated entities
AML-obligated entities with their own INPI account carrying `ROLE_RBE_BENEFICIAL_OWNERS` and `ROLE_RBE_BENEFICIAL_OWNERS_PDF` can now provision those credentials on their Topograph account to unlock the un-redacted INPI dataset.
What it grants access to, under your credentials only:
* `ultimateBeneficialOwners` with full date of birth (day included), full residence address (street line), nationality, gender, and place of birth. The default Topograph service account returns these fields RGPD-redacted.
* `ubo_extract` synthesis PDF with the richer INPI content reserved for RBE-authorised accounts, typically around 20% larger than the default PDF.
Results fetched under your credentials are isolated to your account. No other account can read or observe them. Switching regimes or rotating credentials always produces a fresh INPI fetch, so stale data is never served across boundaries.
Other France data (company data, legal representatives, shareholders, actes, bilans, trade register extract) is unaffected. The INPI RBE role set only changes UBO-related responses.
To provision, contact **[support@topograph.co](mailto:support@topograph.co)**. See the [France country page](https://www.topograph.co/countries/fr) for details.
## Billing Notifications
Topograph now sends alerts for billing events through email and webhooks: low balance warnings, high-usage alerts, and auto top-up outcomes. Give your finance and operations teams cost visibility and governance over Topograph usage without polling the API for balance and spend.
Configure everything from the new Billing page in your dashboard or from the REST endpoints at `/v2/billing/notifications`.
### Two independent spend budgets
High-usage watches run as two parallel passes, both firing on every billable request:
* **Account-wide budget**: total spend across every workspace in your account. Fires once per account when the aggregate crosses your threshold. Use it as a top-line guardrail that catches runaway usage regardless of which team or integration is driving it.
* **Per-workspace budget**: each workspace is evaluated individually against a shared set of defaults. Each workspace gets alerts scoped to its own spend, so a single busy workspace doesn't drown out the rest.
A single spend spike can trip both passes at once. You get a distinct account-level event and a workspace-level event, with a `scope` field on the webhook payload so your alerting stack can route the two categories to different channels (for example, account-wide alerts to finance, per-workspace alerts to the team that owns the workspace).
### Per-workspace overrides
A workspace running heavy batch work can override its budget in isolation while every other workspace keeps the account defaults. Override the master toggle, the channel routing, the rolling period, or the tier values from the Billing page, or via `PATCH /v2/billing/notifications/workspaces/{id}/config`. Overridden workspaces show an explicit `overriding` badge in the UI so you can see at a glance which ones have drifted from the account policy.
### Off by default, admin-controlled
Every notification kind ships off on new accounts. Nothing fires until an admin opts in, so rolling billing notifications out to an established organisation does not surprise anyone with unexpected emails on day one. Enabling a kind seeds it with one starter warning tier at a sensible value; add `critical`, `depleted`, or extra high-usage bands from the tier editor as your policy matures.
### Webhook integration
Four new event types are delivered through the same webhook setup as your existing `company.updated` webhooks. Same signature verification, same retry logic, same signing secret, so adding billing alerts to your ops stack is a matter of subscribing to the new event types in your existing endpoint:
* `billing.low_balance.triggered`
* `billing.high_usage.triggered` (carries `scope: "global" | "workspace"` so you can route the two budgets independently)
* `billing.auto_topup.succeeded`
* `billing.auto_topup.failed`
### Full audit trail
Every fire records a row in the Recent Notifications card on the Billing page. Click a row to inspect the full webhook payload, workspace attribution, per-channel delivery status, and the exact threshold that was crossed. Programmatic access via `GET /v2/billing/notifications/recent` returns the same shape, so you can forward events to your observability pipeline alongside company-data webhooks.
### Getting started
1. Open the Billing page in your Topograph dashboard.
2. Expand **Notification preferences** and flip on the kinds you want.
3. Adjust tiers, period, and channels in place, or leave the starter defaults.
4. If you use webhooks, subscribe the four new event types in your existing endpoint.
Full threshold semantics, dedup key shapes, and rearm behaviour are documented in the [Billing notifications guide](/guides/billing-notifications).
## Data Product Model
### New Data Vocabulary
The API now supports granular datapoints instead of the bundled `companyProfile`:
* `company`: company information (name, address, status, legal form, activities)
* `legalRepresentatives`: directors, managers, board members
* `shareholders`: shareholder structure and ownership percentages
* `ultimateBeneficialOwners`: beneficial owners (unchanged)
Two additional datapoints are now available:
* `otherKeyPersons`: board members, auditors, compliance officers
* `establishments`: branch offices and secondary locations
The legacy `companyProfile` datapoint still works and maps to `company` + `legalRepresentatives`. No migration required.
### Monitoring expanded to 6 new countries
Monitoring is now automatically available for all countries with zero-cost, fixed-price, authoritative data sources. Countries with variable or dynamic pricing are excluded. Newly supported:
* **Bulgaria** (BG)
* **Greece** (GR)
* **Iceland** (IS)
* **Jersey** (JE)
* **Netherlands** (NL)
* **Slovenia** (SI)
Existing monitors also now fetch richer data: all eligible zero-cost datapoints (shareholders, UBOs, establishments, etc.) are automatically included in monitoring requests.
### Retrieval Modes
New `mode` parameter replaces `fast` and `authoritative`:
* `mode: "verification"` (default): picks the authoritative registry source
* `mode: "onboarding"`: picks the cheapest fast source for form prefill and screening
The `fast` and `authoritative` parameters are deprecated but still accepted.
### `/v2/onboarding` Deprecated
Use `POST /v2/company` with `mode: "onboarding"` instead. Same response format, same speed. See the [migration guide](/guides/migration-data-product-model).
### Authoritative Flag in Response
`dataStatus.dataPoints` now includes `authoritative: true/false` so you know whether data came from an official registry.
```json theme={null}
{
"dataStatus": {
"dataPoints": {
"company": { "status": "succeeded", "authoritative": true }
}
}
}
```
### Block-Based Pricing
Each data block has a fixed price per country with 24-hour deduplication. Requesting the same block for the same company within 24 hours is free. Some documents (trade register extract, UBO extract) are included free with their corresponding data block.
The `/v2/pricing` endpoint now returns a `blocks` array showing per-mode pricing and block grouping.
### Budget Cap
New `maxBudget` parameter (in credit cents) lets you cap the cost of a request. **Billable blocks** are applied in priority order: company, legal representatives, UBOs, then shareholders. Datapoints tied to blocks that do not fit the budget are dropped with a `budget_exceeded` status instead of failing the entire request.
## Countries
### 🇺🇦 Ukraine
**New Country — Ukraine Integration**
Ukraine is now fully supported, sourcing all data from the **Unified State Register (ЄДР — Єдиний державний реєстр)**, the official registry of legal entities, individual entrepreneurs, and foreign entity subdivisions operated by the Ministry of Justice of Ukraine.
* **Search** — By EDRPOU code (exact match, all entity types) or RECORD number (individual entrepreneurs), and by company name in Cyrillic or Latin script
* **Three datasets in one integration**:
* **Legal entities (UO)** — All registered companies: LLCs, joint-stock companies, cooperatives, nonprofits, state bodies, farm enterprises, and 50+ other legal forms
* **Individual entrepreneurs (FOP)** — Фізичні особи-підприємці, with full support for the unique FOP `RECORD` identifier scheme (prefixed as `FOP-{RECORD}` to avoid collision with EDRPOU codes)
* **Foreign entity subdivisions (FSU)** — Representative offices and branches of foreign companies, with parent company details including country code and foreign registry code
* **Company profile** — Legal name, legal form (50+ types, standardized), status (active, in dissolution, closed with reason and date), registration date, share capital (legal entities), and commercial names
* **Shareholders** — Founders for legal entities (individual and corporate, with nominal capital); self-ownership for individual entrepreneurs (100%); foreign parent company for FSU subdivisions
* **Legal representatives** — Directors and representatives from the EDR signatories section; individual entrepreneurs are self-represented (role: Owner)
* **5.8M+ individual entrepreneur records** — The FOP dataset is one of the largest in our platform, covering registrations going back to the 1990s
For detailed information, see our [Ukraine documentation](https://www.topograph.co/countries/ua).
## Who can sign, and alone or together
Legal representatives now carry `representationMode`, stating whether an officer can bind the company alone (`sole`) or only jointly with others (`joint`). Where the register publishes the detail, `minimumSignatories` and `namedCoSigners` are returned too.
This is the field you need to know whether one signature on a mandate is actually sufficient. Available for Germany, Switzerland, Finland, Greece, Hungary, Latvia, and Estonia, wherever the register states it.
## Hungary: sole traders
Hungarian sole traders from the individual-entrepreneur register are now covered. Look them up by registration number or tax ID.
## Malta: shareholders
Maltese companies now return `shareholders`, with ownership percentages.
## Countries
### 🇧🇪 Belgium
**Legal Representative Enrichment (Best Effort)**
When `agenticEnrichment: true` is passed, the system attempts to enrich legal representative details from eJustice publications (Moniteur Belge). This is **best effort**. Not all fields are guaranteed, as enrichment depends on which publications are available and what data they contain.
* **Enriched fields**: birth date, nationality, residence address (geocoded)
* **New `enriching` datapoint status**: indicates enrichment is in progress after base data has been retrieved
* **Pricing**: fixed 50 cents per request, charged only if at least one field was enriched
* Belgium only for now
### 🇧🇬 Bulgaria
**Full Integration: Bulgarian Trade Register**
Bulgaria is now fully supported with company data from the Trade Register (Търговски регистър), operated by the Registry Agency (Агенция по вписванията).
* **Search**: By UIC/EIK number (exact match) or by company name in Cyrillic (fuzzy match) via pre-indexed Open Data and live Trade Register API
* **Company Profile**: Full structured data including legal name, Latin transliteration, legal form (18 types with ISO 20275), status (deterministic mapping), address, share capital, activity description, legal representatives, shareholders, and board members
* **Shareholders**: Partners with nominal capital held and percentage for OOD companies; sole owner for EOOD companies; general and limited partners for KD companies. Both individual and corporate shareholders supported with country codes
* **Ultimate Beneficial Owners**: Live UBO data from beneficial ownership declarations in the Trade Register
* **Onboarding Profile**: Fast company lookups from pre-indexed Open Data with live API fallback
* **Documents**: Trade Register Extract (always available), Articles of Association, Financial Statements, and 25+ additional conditional document types
* **Activity Codes**: NKID/NACE/ISIC classification chain, all deterministic (no AI inference)
For detailed information, see our [Bulgaria documentation](https://www.topograph.co/countries/bg).
### 🇭🇺 Hungary
**Sole Trader (Egyéni Vállalkozó) Coverage**
Hungary now covers **sole traders** in addition to commercial companies, sourcing data from a second registry, the **NAV EVNY** (Egyéni Vállalkozók Nyilvántartása), operated by the Hungarian Tax Authority.
* **Search**: Sole traders are searchable by registration number (8 digits) or tax number (8 digits). An 8-digit query automatically searches both OCCSZ and EVNY in parallel, with deduplication.
* **Company profile**: Full sole trader profile including legal name, status, address, activity codes (6-digit TEÁOR → NACE → ISIC), branch offices, and registration date. The sole trader is automatically mapped as the legal representative (Owner) and 100% shareholder.
* **Documents**: EVNY extract available as a PDF (screenshot-based), included free with the profile.
* **Status mapping**: Supports all EVNY statuses: operating (Működő), dormant (Szünetelő), authority-suspended (Felfüggesztett), and terminated (Megszűnt), with proper `active` flag and closure reason mapping.
* **Pricing**: Sole trader profiles use fixed pricing only (no variable TRE cost). Budget precheck adapted accordingly.
## API
**Representation Mode for Legal Representatives**
Legal representatives now include a `representationMode` field indicating how a representative can bind the company. The field specifies whether signing authority is `sole` (can act alone) or `joint` (must act with others), with optional `minimumSignatories` for joint representation or `namedCoSigners` for joint representation with specific named individuals.
Available for: **Hungary (HU)**, **Latvia (LV)**, **Greece (GR)**, **Germany (DE)**, **Switzerland (CH)**, **Finland (FI)**, **Estonia (EE)**
* **Hungary**: Extracted from TRE §13 "együttes"/"önálló" markers (deterministic)
* **Latvia**: Mapped from UR API `rightsOfRepresentation.type` (deterministic)
* **Greece**: Enriched from GEMI boolean flags for ΑΕ companies
* **Germany**, **Switzerland**, **Finland**: AI-extracted from trade register documents (including named co-signers when specified)
* **Estonia**: Sourced from the RIK `esindus_v1` endpoint — `sole` when the person holds exclusive representation rights (`ainuesindusoigus_olemas: JAH`). Not set for `EI` or `EI TEA` (unknown/cannot determine)
## Countries
### 🇭🇺 Hungary
* **Fixed company status detection for deleted companies**. Companies with a deletion date ("Törlés hatálya") in Section 1 of the Trade Register Extract are now correctly identified as closed. Previously, these companies were incorrectly reported as active because only quoted status markers in the company name were checked. The fix parses the deletion date and reason ("Megjegyzés") from the TRE general data section, mapping deletion reasons to the appropriate closure reason (átalakulás → Merger, felszámolás → Bankruptcy, kényszertörlés → Administrative Dissolution, végelszámolás → Voluntary Dissolution).
### 🇸🇮 Slovenia
**New Country: Slovenia Integration**
We've added full support for Slovenia, sourcing all data from **AJPES** (Agency of the Republic of Slovenia for Public Legal Records and Related Services), the official operator of the Slovenian Business Register (ePRS).
* **Search**: Full-text search by company name, registration number, or tax number across 290,000+ entities
* **Company profile**: Legal name, status, legal form, registration date, address, share capital, and legal representatives
* **Shareholders**: Individual and corporate shareholders with equity interests and ownership percentages (d.o.o. companies)
* **Trade Register Extract**: Digitally signed PDF from AJPES, available for all court-registered entities
* **Onboarding profile**: Fast company lookup (\~1s) from synchronized PRS Open Data
Shareholder data is only available for d.o.o. (limited liability) companies.
Joint-stock companies (d.d.) do not disclose shareholders through the registry
as shares are publicly traded. The Slovenian UBO Register (RDL) is restricted
to authorized entities and is not currently accessible.
For detailed information, see our [Slovenia documentation](https://www.topograph.co/countries/si).
### 🇪🇪 Estonia
* **Partnership shareholders**: General partnerships (TÜ) and limited partnerships (UÜ) now return shareholders. Partners (TOSAN/UOSAN/EUSOS/EUSOS2) are extracted from `kaardile_kantud_isikud` and returned as shareholders alongside their legal representative entries. Limited partners include their capital contribution (`nominalCapitalHeld`). Partners holding multiple roles (e.g. EUSOS + UOSAN) are deduplicated by registry code, keeping the entry with capital contribution data.
* **Nominal capital precision fix**: Shareholder `nominalCapitalHeld` amounts for OÜ/AS companies now preserve full decimal precision (e.g. `10931254.40` instead of being truncated to `10931254`).
* **Consistent entity IDs**: All person mappers (legal representatives, shareholders, other key persons) now use `isikukood_registrikood` (registry code for companies, personal ID for individuals) instead of the internal RIK record ID (`kirje_id`). This ensures the same entity has a consistent ID across all sections of the response. Falls back to `kirje_id` for foreign companies that lack a local registry code.
* **Birth date extraction**: All individual persons (legal representatives, shareholders, other key persons) now include `birthDate`. For Estonian nationals, the date is derived from the 11-digit personal identification code (`isikukood`). For foreign nationals, it is read from the `synniaeg` field.
* **Country of residence**: Individual shareholders now include `residenceAddress.countryCode` when the registry provides the `aadress_riik` field (common for foreign shareholders).
* **Foreign company country codes**: Corporate shareholders and legal representatives registered abroad now show their actual country of registration (e.g. `GB`, `SE`, `CYM`) instead of defaulting to `EE`. Foreign registration numbers (`valis_kood`) are also used as the company ID.
## New Feature
### Workspaces: Per-Client Usage Tracking & Rebilling
We've introduced **Workspaces**, a new feature that lets you split API usage across sub-accounts, clients, or departments for easy cost tracking and rebilling.
* **Tag requests**: Send an `x-topograph-workspace-id` header with any `/v2/company` request (including `mode: "onboarding"`) to attribute usage to a specific workspace. The legacy `/v2/onboarding` route remains workspace-taggable for backward compatibility.
* **Manage workspaces**: Full CRUD API to create, update, list, and delete workspaces, each with an associated legal entity name
* **Usage reporting**: New `GET /v2/workspaces/usage` endpoint returns per-workspace credit consumption with catalog-item breakdown, filterable by date range
* **Default workspace**: Requests without an `x-topograph-workspace-id` header are automatically tagged to the default workspace (fully backward compatible)
* **Dashboard support**: The billing dashboard now shows a workspace column and supports "Split by Workspaces" in the usage graph
This is ideal for **resellers** rebilling clients, **multi-entity organizations** allocating costs, and **platforms** tracking per-tenant consumption.
See the full [Workspaces documentation](/essentials/workspaces) and [API reference](/api-reference/workspaces/list-all-workspaces).
## Countries
### 🇱🇻 Latvia
**Onboarding Profile & Fast Search: Open Data Batch Pipeline**
Latvia now has synchronized search and an onboarding profile powered by open data from data.gov.lv (\~480K entities), providing fast company lookups.
* **Fast search**: Fast search by company name or registration number, with register fallback for supplementary results
* **Onboarding profile**: Rich company data from synchronized source data (\~1s): legal form, status, capital, legal representatives, shareholders (SIA + AS), and ultimate beneficial owners
* **7 data sources**: Daily CSV sync: company register, officers, members, stockholders, beneficial owners, equity capitals, and areas of activity
* **Address geocoding**: Addresses are geocoded with skip-if-unchanged optimization for subsequent refreshes
* **Incremental updates**: Only companies with actual data changes are reprocessed on refresh runs
The onboarding profile does not include NACE/ISIC activity codes or AI
enrichment; use the full company profile for those. Shareholders of type
DEPOSITORY (Nasdaq CSD nominee holdings for listed companies) are excluded.
For detailed information, see our [Latvia documentation](https://www.topograph.co/countries/lv).
## Countries
### 🇪🇪 Estonia
* **Expanded UBO control type coverage**: Added support for 5 additional RIK control type codes (`K`, `C`, `S`, `Z`, `Y`), bringing the total from 4 to all 9 codes defined by the Estonian Money Laundering Prevention Act (RahaPTS §9). Notably, indirect ownership (`K`) is now correctly mapped with `nature: indirect`, and appointment rights (`Y`) have an explicit mapping instead of relying on the default fallback.
### 🇰🇾 Cayman Islands
**New Country: Cayman Islands Integration**
We've added full support for the Cayman Islands, sourcing all data from the **General Registry (CIREGISTRY)**, the official registrar of companies, partnerships, and trusts.
* **Search** - Name-based entity search across 45,000+ registered entities
* **Company profile** - AI-extracted from the Detailed Search document: legal name, status, legal form, incorporation date, registered office, directors, and shareholders (when disclosed)
* **Three document types** - Detailed Search, Company Details, and Director Details, all delivered as PDF.
* **Fast search** - Search sessions are prepared ahead of time to reduce latency.
* **Balance monitoring** - Internal balance monitoring protects document availability.
The Cayman Islands does not assign numeric registration numbers. Entity names
are used as identifiers (base64-encoded in API responses). Exempted companies
(the most common entity type) are not required to publicly disclose
shareholders.
For detailed information, see our [Cayman Islands documentation](https://www.topograph.co/countries/ky).
## Breaking Changes
### 🔖 `statusDetailsBeta` renamed to `statusDetails`
The `status.statusDetailsBeta` field has been **promoted to `status.statusDetails`** and is now considered stable. The `Beta` suffix has been removed.
**Action required:** Update any code reading `statusDetailsBeta` to `statusDetails`.
All existing values (`status`, `closureReason`, `closureDate`, `insolvencyStartDate`, `additionalInfo`) and their semantics are unchanged. A new `SPLIT` value has been added to `closureReason` to cover corporate splits.
See the [Company Status guide](/guides/company-status) for full documentation on the status model, all enum values, country coverage, and usage patterns.
## Countries
### 🇷🇴 Romania
**Onboarding Profile: ONRC Open Data Batch Pipeline**
Romania now has an onboarding profile powered by ONRC Open Data (\~4.1M entities), providing fast company lookups from synchronized data.
* **Search**: Full-text search by company name, CUI, or registration number
* **Onboarding Profile**: Fast company lookup (\~1s) with deterministic mappings for status (197 official codes), legal form (20+ types with ISO 20275), and activity codes (CAEN → NACE → ISIC)
* **Legal representatives**: Individual and corporate representatives with role mapping, birth date, nationality, and addresses
* **Activity codes**: CAEN Rev. 2 codes with Romanian descriptions, NACE Rev. 2 with English descriptions, and ISIC Rev. 4 derived via the official UN correspondence table. All deterministic (no AI inference)
* **Freshness check**: the integration detects new dataset publications on data.gov.ro and refreshes automatically
For detailed information, see our [Romania documentation](https://www.topograph.co/countries/ro).
### 🇧🇪 Belgium
**Full juridical situation mapping in `statusDetails`**
Belgium now surfaces the complete KBO/CBE **juridical situation** (A152 code list) in `statusDetails`, replacing the previous binary active/ceased classification.
* **`UNDER_INSOLVENCY_PROCEEDING`** for companies with an open bankruptcy (`050`) or judicial reorganisation (`091`) proceeding, with `insolvencyStartDate` when available
* **`closureReason`** now populated for closed companies: `BANKRUPTCY`, `VOLUNTARY_DISSOLUTION`, `ADMINISTRATIVE_DISSOLUTION`, `COURT_ORDER`, `LIQUIDATION`, `MERGER`, `SPLIT`
* **`localName`** now reflects the French juridical situation label (e.g. `Ouverture de faillite`) instead of the generic `Actif` / `Cessé`
All 36 KBO/CBE juridical situation codes are mapped. Both the BCE Open Data fast path and the CBE Public Search enrichment path converge on the same standardised output.
For the complete code table, see the [Belgium documentation](https://www.topograph.co/countries/be#juridical-situation-codes). For the full status model reference, see the [Company Status guide](/guides/company-status).
## Features
### 📍 GPS Coordinates on Addresses
Company addresses now include `latitude` and `longitude` fields, giving you precise geographic coordinates for every geocoded address. These coordinates are derived automatically from the address and are available across all countries.
* **Ready-to-use coordinates** - Latitude and longitude are returned directly in the address object, no extra API call needed
* **Map-friendly** - Easily plot company locations on a map or calculate distances between companies
## Features
### 🔍 Domain-Based Company Search
Search now supports web domain queries. When the search query looks like a domain (e.g., `doctrine.fr`, `stripe.com`, `kvk.nl`), the system resolves the company behind it and routes to the appropriate country's search.
* **Automatic detection** - Domains are detected transparently, including with `https://` or `www.` prefixes
* **Cross-country resolution** - The resolved company's country is used for the search, regardless of the country parameter
* **Fallback strategy** - If the resolved identifier returns no results, the system retries with the resolved legal name
## Countries
### 🇫🇮 Finland
**Ultimate Beneficial Owners (UBOs)**
Finland now supports Ultimate Beneficial Owner data, sourced from PRH's ESR (Beneficial Ownership Register), a separate service from the existing VIRRE Trade Register integration.
* **Ownership & voting rights** - Structured control details with percentage values and nature (direct/indirect)
* **Personal details** - Name, date of birth, nationality, and residence city (resolved from Finnish municipality codes)
* **Entity type awareness** - UBO data is available for private limited companies (Oy). Public companies (Oyj), state-owned entities, associations, foundations, and sole entrepreneurs typically have no UBO data due to Finnish law requirements (>25% ownership/voting threshold)
For detailed information, see our [Finland documentation](https://www.topograph.co/countries/fi).
### 🇩🇪 Germany
**WZ 2008 Activity Classification**
German company profiles now include WZ 2008 (Wirtschaftszweig) activity codes, the official German economic activity classification system. The WZ 2008 code is matched from the company's "Gegenstand des Unternehmens" using AI-based classification against all 839 official sub-classes from Destatis.
* **New `WZ2008` field** in company profile activities alongside ISIC and NACE
* Supports all 839 WZ 2008 sub-classes with German descriptions
* Available in both company profile and onboarding profile
### 🇭🇺 Hungary
**Major Rework: Official e-Cégjegyzék API Integration**
We've completely reworked the Hungary integration by switching to the official e-Cégjegyzék (OCCSZ) source for Trade Register Extract retrieval. Company profiles are parsed deterministically from the extract, with enrichment only for address parsing, legal form standardization, and role classification.
* **Variable pricing**: Unlike flat-rate countries, the Trade Register Extract price depends on the document size. Prices are shown before purchase.
* **Budget control**: New `profileMaxBudget` parameter lets you set a maximum spend. If the estimate exceeds your budget, the request fails with a `budget_exceeded` error so you can retry with a higher budget.
* **Expanded data coverage**: Company profiles now include shareholders (from TRE Part II), establishments (business premises and branch offices), other key persons (auditors, supervisory board members), and activity codes (TEÁOR, NACE, ISIC)
* **Field-level data source tracking**: Each field in the response includes provenance metadata (`live_from_registry` for TRE-derived data, `ai_analysis` for AI-enriched fields like address and legal form, `vies` for VAT validation)
* **Search by VAT number**: Search now supports Hungarian VAT numbers (with or without `HU` prefix)
For detailed information, see our [Hungary documentation](https://www.topograph.co/countries/hu).
### 🇫🇷 France
**Deterministic Legal Form & Role Mapping -- AI Removed**
We've replaced all AI-based legal form and role mapping in France with fully deterministic static lookups, eliminating runtime AI calls for these fields across both batch and live pipelines.
* **Legal forms** -- All 450 INSEE catégorie juridique codes are now mapped via a static lookup table providing the local French name, English translation, standardized category, and ISO 20275 (ELF) code. Previously, live requests used GPT-4.1-mini for translation and standardization. The static mapping was generated by running AI enrichment once on every code and freezing the results.
* **Roles** -- All 71 RNE role codes are now mapped via a static lookup with standardized role, English translation, and legal representative classification based on French corporate law. No AI involved.
* **SIRENE legal forms** -- SIRENE-only companies (not in RNE) now use the same static legal form mapping as RNE, providing full English translations, standardized categories, and ISO 20275 codes. Previously, SIRENE batch mode returned only the local name.
**Impact:**
* Faster response times (no AI calls for legal form or role enrichment)
* Consistent results (deterministic, no variance between requests)
* Lower cost (no LLM token usage for these fields)
* SIRENE-only companies now have the same legal form data quality as RNE companies
For the complete mapping tables, see our [France documentation](https://www.topograph.co/countries/fr#legal-forms).
### 🇮🇹 Italy
**Shareholders as a Standalone Datapoint**
Italy shareholders are now available as an independent `shareholders` datapoint, separate from the company profile. Previously, shareholder data was bundled into `companyProfile` and always fetched together. Now you can request shareholders independently or alongside the company profile.
* **Dedicated `shareholders` datapoint**: fetch shareholders without triggering a full company profile request
* **Birth data enrichment**: individual shareholders are cross-referenced with legal representatives to populate birth date and birth address when available (using the InfoCamere register, which is cached)
* **Sole proprietors**: correctly return an empty shareholders list, as sole proprietorships have no registered shareholders in the trade register
## Countries
### 🇸🇬 Singapore
**New Country: Full Company Data Platform**
Singapore is now available on Topograph, powered by ACRA Open Data (\~2.07M entities) and BizFile document purchases:
* **Search** - Full-text search by company name or UEN
* **Onboarding Profile** - Fast company lookup from ACRA batch data (\~3.5s) with formal mappings for status, legal form (ISO 20275), and activity codes (SSIC → ISIC)
* **Company Profile** - Detailed company data including shareholders and legal representatives, extracted from purchased Business Profile PDF
* **Documents** - Business Profile (Trade Register Extract) purchased via BizFile (\~60s delivery)
For detailed information, see our [Singapore documentation](https://www.topograph.co/countries/sg).
### 🇭🇷 Croatia
**Major Performance Improvements & Onboarding Profile**
We've significantly improved Croatia's performance by replacing the browser-based scraper with direct HTTP parsing and optimized API calls. All retrieval times are now dramatically faster:
* **Onboarding Profile** - New lightweight company data endpoint optimized for onboarding flows (\~5s)
* **Search** - \~3-10s
* **Company Profile** - \~15s (now includes legal representative start dates when available)
* **Certified Trade Register Extract** - \~5s (previously \~1m30s)
* **Shareholders** - New standalone shareholders datapoint
* **Shared documents information retrieval time** - \~7s (previously \~1m30s)
For detailed information, see our [Croatia documentation](https://www.topograph.co/countries/hr).
## API
### 🧾 Expanded VAT Validation to 20 EU Countries
We've dramatically expanded VAT validation support from 2 to 20 EU countries. All supported countries now include:
* **VAT search** - Search for companies using their VAT number (with or without country prefix)
* **VIES verification** - Automatic validation with legally admissible proof (`consultationNumber`)
* **Frontend display** - New Tax ID component in company profiles showing verification status with expandable VIES details
![Tax ID verification details showing registered name, address, verification date and consultation number]()
**Full taxId support (VAT in profile + VIES verification):**
🇫🇷 France, 🇪🇸 Spain, 🇸🇪 Sweden, 🇮🇹 Italy, 🇵🇹 Portugal, 🇵🇱 Poland, 🇪🇪 Estonia, 🇦🇹 Austria, 🇧🇪 Belgium, 🇱🇺 Luxembourg, 🇩🇰 Denmark, 🇨🇿 Czechia, 🇷🇴 Romania, 🇭🇺 Hungary, 🇫🇮 Finland, 🇭🇷 Croatia
**VAT search only (VIES reverse lookup, no taxId in profile):**
🇱🇻 Latvia, 🇨🇾 Cyprus, 🇮🇪 Ireland, 🇲🇹 Malta
For countries with "VAT search only", the VAT number is neither
algorithmically derivable from the registration number nor available in the
registry API. You can still search by VAT number via VIES reverse lookup, but
the `taxId` field won't appear in company profiles.
For detailed documentation, see our [VAT Validation guide](/essentials/vat-validation).
### 🧾 Tax ID Support (taxId) - France & Spain
Added a new `taxId` field to company profiles that provides structured tax identification information.
**Key features:**
* **Structured tax ID data** - Includes type, value, country, and verification status
* **Verification with legal proof** - Optional VIES validation provides a `consultationNumber` (official EU receipt) for audit purposes
* **No external calls for basic data** - VAT numbers are calculated mathematically (France) or derived from NIF (Spain) without API calls
* **Search by VAT** - Both countries now support searching by VAT number
**Response structure:**
```json theme={null}
{
"taxId": {
"type": "eu_vat",
"value": "27443061841", // WITHOUT country prefix
"country": "FR",
"verification": {
"status": "unverified",
"consultationNumber": "WAPIAAAAW..." // Only with VIES validation
}
}
}
```
**Country-specific notes:**
* 🇫🇷 **France**: VAT calculated from SIREN using the official formula. Search now supports TVA Intracommunautaire format.
* 🇪🇸 **Spain**: VAT value equals NIF (Número de Identificación Fiscal). Note: Having a NIF doesn't guarantee EU VAT registration (requires ROI enrollment).
The `taxId.value` field stores the VAT number WITHOUT the country prefix. The
country is stored separately in `taxId.country`. The `identifiers.VAT` field
also stores the VAT value without prefix for consistency.
## Countries
### 🇬🇷 Greece
We're excited to announce support for **Greece** company data from the **GEMI** (Γενικό Εμπορικό Μητρώο - General Commercial Registry):
* **Search** - Find companies by GEMI number, VAT number (ΑΦΜ), or company name
* **Onboarding Profile** - Fast, lightweight company data optimized for onboarding flows (\~7 seconds)
* **Company Profile** - Comprehensive company data including legal representatives, shareholders, activities (NACE codes), and share capital (\~10 seconds)
* **Available Documents** - List all available documents including financial statements, articles of association, and official GEMI announcements (\~6 seconds)
* **Document Download** - Retrieve financial statements, articles of association, and official publications (\~6 seconds) or Trade Register Extract (\~10 seconds) as PDFs
OKOIP (Charities register) integration for additional company data is planned
for a future release.
For detailed information about Greece's registration system and available features, see our [Greece documentation](https://www.topograph.co/countries/gr).
### 🇱🇺 Luxembourg
* **Improved speed & reliability** - We've made significant improvements to Luxembourg data retrieval. Company searches, profile lookups, and Trade Register Extract orders are now faster and more reliable.
* **Onboarding Profile** - Added a new fast onboarding profile endpoint that returns basic company data (name, address, legal form, activities) in \~250-500ms.
### 🇨🇾 Cyprus
* **Shareholders support** - Added shareholders extraction from the Trade Register Extract (Study File) PDF. Shareholders are extracted using AI parsing from the official DRCOR document, supporting both individual and corporate shareholders with ownership percentages when available. Billing occurs via the Trade Register Extract document purchase.
## Countries
### 🇮🇪 Ireland
**Legal Representatives & Shareholders Now Available**
We've significantly expanded Ireland data coverage with two major additions:
* **Legal Representatives** - Directors and other key persons (secretaries, filing agents) are now extracted from the Company Printout (Trade Register Extract) document using AI parsing. Available in the `companyProfile` response.
* **Shareholders** - A new `shareholders` datapoint extracts ownership information from B1C Annual Return documents. The AI parses member details, share counts, and calculates ownership percentages from the issued share capital.
Both extractions use AI parsing from PDF documents. Role standardization and
shareholder type determination are AI-inferred. Shareholders are only
extracted for active companies.
For details, see our [Ireland documentation](https://www.topograph.co/countries/ie).
### 🇧🇪 Belgium
Fixed `representedBy` field for corporate legal representatives. When a company is a legal representative (e.g., Director), the natural person who acts on its behalf (permanent representative) is now correctly populated in the `representedBy` field.
## Features
### Designee Role in Relationships Table
Added a new **Designee** role type to the relationships table. When a company is a legal representative, the natural person designated to act on its behalf now appears as a separate entity with the "Designee" role badge. This provides clearer visibility into who actually represents corporate officers.
* Designees are shown as distinct entities in the relationships table
* Expanding a company legal rep now shows the designee in the details section
* Added info tooltips to all role badges explaining their meaning
### 💰 Financial Data Analysis
Improved financial data extraction and analysis is now accessible in the frontend app. Financial data can be viewed directly from the documents table with detailed AI analysis, ratios, and structured financial statements. See the [Financial Data Extraction documentation](/essentials/financial-data-extraction) for details.
## Platform
### 📄 Improved PDF Export
Enhanced PDF export with improved visual design, correct logo rendering, and better alignment with the frontend color palette.
## API
### 🔍 Enhanced Search Results with Match Reason
Search results now include a `matchReason` field that provides detailed information about why a result was returned:
* **`matchType`** - Indicates the type of match:
* `id` - Guaranteed 1:1 match from an ID-based search (e.g., VAT number, CCIAA+REA)
* `exactLegalName` - The legal name exactly matches the search query
* `partialId` - Matched by a partial identifier not guaranteed unique (e.g., REA without CCIAA)
* `default` - Used when the exact matching criteria is unknown
* **`identifier`** - Shows which identifier matched (when applicable), with typed definitions per country
**Example response:**
```json theme={null}
{
"legalName": "ACME SRL",
"matchReason": {
"matchType": "id",
"identifier": { "VAT": "02580590541" }
}
}
```
### 🇮🇹🇫🇷 Typed Country Identifiers
Introduced typed identifier definitions with full OpenAPI documentation:
* **Italy**: VAT, Codice Fiscale, CCIAA, REA Code
* **France**: SIREN, SIRET, TVA Intracommunautaire, RNA, RNA Alsace-Moselle
Each identifier includes detailed descriptions, format specifications, and issuing authority information in the API documentation.
## Countries
### 🇻🇬 British Virgin Islands
We're excited to announce support for **British Virgin Islands (BVI)** company data from the BVI Financial Services Commission (FSC) Public Search:
* **Search** - Find companies by name or company number (numeric or alphanumeric format like `L658`)
* **Onboarding Profile** - Fast, lightweight company data optimized for onboarding flows including legal form, status, and company type classification
* **Company Profile** - Comprehensive company data including legal representatives and shareholders when disclosed, extracted from the Trade Register Extract using AI parsing
* **Trade Register Extract (Certificate of Good Standing)** - Official PDF document from the BVI FSC containing company registration information
As of now, document retrieval for BVI relies on a manual concierge process due
to instability in direct API access. This may result in some delay (typically
1-2 business days) when retrieving the Trade Register Extract. We are actively
working on improving this process.
For detailed information about BVI's company number system and available features, see our [British Virgin Islands documentation](https://www.topograph.co/countries/vg).
### 🇱🇮 Liechtenstein
We're excited to announce support for **Liechtenstein** company data from the official Handelsregister (Trade Register):
* **Search** - Find companies by name or FL registration number (e.g., `FL-0002.658.754-1`)
* **Onboarding Profile** - Fast, lightweight company data optimized for onboarding flows including legal form, status, and registration details
* **Company Profile** - Comprehensive company data including legal representatives, shareholders, and share capital, extracted from the Trade Register Extract using AI parsing
* **Trade Register Extract** - Official PDF document from the Liechtenstein Handelsregister containing complete company registration information
For detailed information about Liechtenstein's registration number system and available features, see our [Liechtenstein documentation](https://www.topograph.co/countries/li).
### 🇱🇻 Latvia
We're excited to announce full support for **Latvia** company data from the Enterprise Register (Uzņēmumu reģistrs):
* **Search** - Find companies by name or registration number (11-digit identifier, e.g., `40103217882`)
* **Company Profile** - Comprehensive company data including legal form, status, capital, activities (NACE codes), legal representatives, shareholders, and other key persons (\~15 seconds retrieval time)
* **Ultimate Beneficial Owners** - UBO data with ownership percentages and control details
* **Certified Trade Register Extract** - Official PDF extract from the Enterprise Register (\~25 seconds retrieval time)
* **Articles of Association** - Company statutes and amendments (\~25 seconds retrieval time)
* **Financial Statements** - Annual reports in PDF format (\~25 seconds retrieval time)
* **Other Registry Documents** - Registration certificates, shareholder registers, board protocols, and more (\~ 25 seconds retrieval time)
For detailed information about Latvia's registration system and available features, see our [Latvia documentation](https://www.topograph.co/countries/lv).
### 🇸🇰 Slovakia
We're excited to announce full support for **Slovakia** company data from the RPO (Register of Legal Entities, Entrepreneurs and Public Authorities) and ORSR (Commercial Register):
* **Search** - Find companies by name (partial match supported) or IČO (8-digit Organization Identification Number)
* **Company Profile** - Comprehensive company data including legal representatives, shareholders, share capital, business activities, and more. (\~20 seconds retrieval time)
* **Trade Register Extract** - Official PDF extract from the Commercial Register in mixed English and Slovakian (\~15 seconds retrieval time)
Slovakia uses **IČO** (Identifikačné číslo organizácie) as the primary company identifier, an 8-digit number assigned to all registered legal entities.
For detailed information about Slovakia's identifier system and available features, see our [Slovakia documentation](https://www.topograph.co/countries/sk).
### 🇬🇬 Guernsey
We're excited to announce full support for **Guernsey** company data from the Guernsey Registry (GFSC):
* **Search** - Find entities by name or registration number with prefix (e.g., `CMP10001`, `FND167`, `LLP149`)
* **Company Profile** - Comprehensive company data including legal representatives, other key persons, activities, and addresses (\~15 seconds retrieval time)
* **Trade Register Extract** - Official Statement of Register PDF for companies, foundations, partnerships, charities, and non-profits (\~1-3 minutes retrieval time)
* **Certificate of Good Standing** - Official certificate confirming current good standing (\~1-3 minutes retrieval time)
* **Certificate of Incorporation** - Historical incorporation certificate (\~1-3 minutes retrieval time)
* **Articles of Association** - Constitutional documents and amendments (\~1-3 minutes retrieval time)
* **Other Filed Documents** - Annual validations, resolutions, and other registry filings (\~1-3 minutes retrieval time)
Guernsey uses **registration number prefixes** to identify entity types: `CMP` (Companies), `FND` (Foundations), `LLP` (Limited Liability Partnerships), `LP` (Limited Partnerships), `CH` (Charities), and `NP` (Non-Profit Organisations).
For detailed information about Guernsey's identifier system and available features, see our [Guernsey documentation](https://www.topograph.co/countries/gg).
### 🇨🇿 Czechia
* **UBO support disabled** - Due to Czechia restricting access to its UBO registry, we are disabling Ultimate Beneficial Owners support for Czech companies. Other features remain available including company search, company profile, and trade register extracts.
## Features
### Shareholders Extraction (Alpha)
We're introducing a new `shareholders` datapoint for countries where shareholder data is not available directly from official registries. This feature reconstructs the most probable current shareholder structure by analyzing available company documents.
Currently available for **France (FR)**, **United Kingdom (GB)**, and **Belgium (BE)**.
This is an alpha feature providing best-effort reconstruction. Results should
be verified manually for compliance use cases.
For more details, see our [Shareholders Extraction documentation](/essentials/shareholders-extraction).
## Countries
### 🇨🇭 Switzerland
* **Trade Register Extract now available for all 26 cantons** - You can now download official trade register extracts (PDF) for Swiss companies across all cantons, including Zürich, Geneva, Vaud, Bern, and all other Swiss jurisdictions.
### 🇯🇪 Jersey
We're excited to announce full support for **Jersey** company data from the Jersey Financial Services Commission (JFSC) Registry:
* **Search** - Find companies by name or registration number (4-7 digit numeric identifier)
* **Onboarding Profile** - Fast, lightweight company data optimized for onboarding flows including legal form, status, and registration date
* **Company Profile** - Comprehensive company data including legal representatives (directors, secretary) and shareholders when disclosed (\~1 minute processing time)
* **Entity Profile Report** - Official PDF document from the JFSC containing complete company registration information (\~1 minute retrieval time)
For detailed information about Jersey's registration number system and available features, see our [Jersey documentation](https://www.topograph.co/countries/je).
### 🇲🇺 Mauritius
We're excited to announce full support for **Mauritius** company data:
* **Search** - Find companies by name, File Number, Business Name, or BRN
* **Onboarding Profile** - Fast, lightweight company data optimized for onboarding flows (typically \~3 seconds)
* **Company Profile** - Comprehensive company data including legal representatives, shareholders, capital, and activities (typically \~15-20 seconds)
* **Trade Register Extract** - Official PDF document from the Corporate and Business Registration Department (CBRD)
Mauritius companies use **File Number** (e.g., `C227332`) as the primary identifier, with support for both domestic companies and Global Business Companies (GBC).
### 🇲🇨 Monaco
* **Initial support for Monaco** - We're excited to announce support for Monégasque companies with our integration of the RCI (Répertoire du Commerce et de l'Industrie) register! Currently available features:
* **Company search by name** - Find Monégasque companies using their registered business names
* **Company search by RCI number** - Direct lookup using Monaco RCI registration numbers (format: `YY[A-Z]{1,2}\\d{4,5}`; legacy civil alias like `YYSC#####` is normalized to `YYC#####`)
* **Fast onboarding-style company data** - Lightweight company data optimized for onboarding flows including legal form, activities, and address
* **`companyProfile`** - Comprehensive company information extracted from the trade register extract, including legal representatives, capital, registration dates, and enriched data (\~1 minute processing time)
* **Trade Register Extract** - Official PDF extract from RCI containing complete company registration information including legal representatives, activities, capital, and status (\~1 minute retrieval time)
For detailed information about Monaco's RCI number system and available features, see our [Monaco documentation](https://www.topograph.co/countries/mc).
### 🇧🇪 Belgium
* **Improved performance and robustness** - Enhanced speed and reliability for Belgian company data retrieval operations.
### 🇭🇰 Hong Kong
* **Restored `companyProfile` and `registerExtract` functionality** and significantly improved system robustness for Hong Kong data retrieval.
### 🇭🇷 Croatia
* **Initial support for Croatia** - We're excited to announce support for Croatian companies with our integration of Sudreg (Court Registry) and RGFI/FINA (Annual Financial Statements Registry)! Currently available features:
* **Company search by name** - Find Croatian companies using their registered business names
* **Company search by MBS** - Direct lookup using the 9-digit company registration number (e.g., `080000376`)
* **Company search by OIB** - Direct lookup using the 11-digit tax identification number (e.g., `81793146560`)
* **`companyProfile`** - Comprehensive company information including status, legal form, legal representatives, shareholders, supervisory board members, share capital, and business activities (\~15s retrieval time)
* **Certified Trade Register Extract** - Official PDF extract from Sudreg containing current company information (\~1m30s retrieval time)
* **Financial Statements** - Balance sheets, profit & loss statements, notes, and profit distribution decisions from RGFI/FINA (\~1m30s retrieval time)
* **Constitutional Documents** - Articles of association and minutes of establishment
* **Registry Documents** - Registration decisions, announcements, OIB certificates, and other court filings
For detailed information about Croatia's identifier system and available features, see our [Croatia documentation](https://www.topograph.co/countries/hr).
## Platform
### Ownership Graph Enhancements
We've significantly improved our ownership graph feature with better control and visualization:
* **Budget control** - Set a maximum credit budget when requesting the ownership graph to control traversal costs
* **Interactive visualization** - The ownership graph now displays as an interactive diagram with nodes representing companies and individuals, and edges showing ownership percentages
* **Traversal transparency** - See exactly why the graph stopped (completed, budget exhausted, depth limit) and how many companies were fetched or skipped
### Application Redesign
We've made numerous improvements to make the experience smoother and the interface has been globally enhanced.
**Key improvements:**
* **Automatic document listing** - Since document listing is free, it is now always requested automatically when you open a company
* **New relationships view** - People appearing in multiple roles (shareholder + UBO for example) are now automatically grouped together, with advanced filters and customizable columns
* **Interactive map for establishments** - The establishments section now displays an interactive map with Street View
* **Real-time updates** - Requested data and documents now appear in real-time, without reloading the page
* **Request history improvements** - Access all your previous requests through infinite scroll, and switch between "All requests" (organization scope) and "My requests" views
## Platform
### 📋 Legal Representative Data Model Enhancement
* **Added `representedBy` field for corporate legal representatives** - When a company (personne morale) serves as a legal representative, you can now see the physical person who represents that company. This captures the "représentant permanent" (permanent representative) commonly found in French documents or "vertreten durch" in German documents.
Example: When "SAS MANAGEMENT" is a legal representative, the API now shows both the company details and the individual (e.g., "Jean DUPONT") who acts on its behalf.
### ⚠️ Deprecations
* **Removed `source` field from shareholders** - The `source` field has been temporarily removed from shareholder data. We're working on a more comprehensive solution for tracking data provenance that will be introduced in a future release.
## Countries
### 🇪🇸 Spain
* **Improved speed and reliability** - Spanish company data operations are now significantly faster with parallel request handling and automatic retry on slow connections
* **IRUS as primary identifier** - Spain now uses IRUS (Identificador Único del Registro de Sociedades) as the primary company identifier for document operations. Search by NIF/CIF still supported and returns the corresponding IRUS
* **Available documents with pricing** - Trade register extracts and financial statements show pricing before download
### 🇮🇪 Ireland
* **Full access to CRO documents** - You can now purchase and download documents from Ireland's Companies Registration Office:
* **Company Printout** - Official trade register extract with current company details
* **Letter of Status** - Official letter confirming company standing
* **Annual Returns** - Yearly company filings including financial statements (B1C, B1)
* **Constitutional Documents** - Company constitution and incorporation documents
* **Director/Secretary Filings** - Appointment and resignation records (B10)
* **Charge Documents** - Mortgage and charge registrations (C1, C6)
* **Share Capital Documents** - Allotment and capital structure filings (B5, B7)
* **Resolutions** - Special and ordinary shareholder resolutions (G1, G2)
The average document download time is \~2 minutes.
## Platform
### 🚀 Onboarding Profiles
We've expanded fast **onboarding-style** company retrieval (today: `POST /v2/company` with `mode: "onboarding"`; previously documented as the Onboarding Profile flow) to support more countries:
* 🇧🇪 **Belgium (BE)**
* 🇩🇰 **Denmark (DK)**
* 🇫🇷 **France (FR)**
* 🇳🇱 **Netherlands (NL)**
* 🇸🇪 **Sweden (SE)**
* 🇬🇧 **United Kingdom (GB)**
## Countries
### 🇸🇪 Sweden
* **Offering access to more Bolagsverket documents** - You now have access to the following documents from the register :
* **Certified Trade Register Extract** - Official & certified PDF extract from Bolagsverket containing information about the company (\~3 minutes retrieval time)
* **Articles of association** - Official PDF from Bolagsverket indicating business activities, registered office of the company, and so on (\~ 3 minutes retrieval time)
* **Statutes** - Official PDF from Bolagsverket containing information about the company (\~3 minutes retrieval time)
* **Ultimate Beneficial Owners extract** - Official PDF from Bolagsverket containing information about the ultimate beneficial owners of the company (\~3 minutes retrieval time)
* **Annual reports (all years compilation)** - Official PDF from Bolagsverket containing financial informations of the company (\~3 minutes retrieval time)
* **Minutes (all years compilation)** - Official PDF from Bolagsverket containing notes from board and general meetings (\~3 minutes retrieval time)
* **Current assignments** - Official PDF from Bolagsverket containing information about a person's or company's current assignements in other entities (\~3 minutes retrieval time)
* **Ultimate Beneficial Owners** - Extracted from the **Ultimate Beneficial Owners extract**: Bolagsverket (the Swedish Companies Registration Office) reports control extent ("Omfattning"), not ownership percentage. Key difference: Multiple beneficial owners can each show 100% control because the percentage represents how much influence a person can exercise over the company, not their economic stake.
## Platform
### 🔄 Streaming Search
* **Progressive search results** - Search endpoints now support streaming mode via the `stream=true` query parameter, enabling progressive result delivery as each search source completes. This provides faster time-to-first-result and better user experience, especially for countries with multiple search sources.
* **Server-Sent Events (SSE)** - Streaming search uses SSE format with named events (`progress`, `complete`, `error`) for real-time result updates
* **CLI support** - The `topo` CLI tool now supports `--stream` flag for streaming search results
Streaming search is particularly beneficial for countries like Germany that
query multiple sources (cached, live APIs). Use streaming to get cached
results immediately (\~200ms) while live sources continue to fetch additional
results in the background.
For detailed documentation and code examples, see our [Search guide](/essentials/search).
### Application performance
Minor improvements of the backoffice interface performance.
## Countries
### 🇩🇪 Germany
* **Hybrid search architecture** - Germany now uses three complementary search sources:
* **Fast search** - Fast results from weekly-refreshed active company data
* **Live Unternehmensregister search** - Direct API queries for active companies in HRB, HRA, Genossenschaftsregister, Partnerschaftsregister, and Gesellschaftsregister registers
* **Live Handelsregister VR search** - Direct queries for non-profit organizations in the VR register
* **Enhanced search recall and robustness** - By combining cached and live sources, search now provides higher recall and better fault tolerance. If one source fails, others continue to provide results.
## Platform
### 💳 Auto Top-Up
* **Automatic credit replenishment** - Your account credits are automatically topped up when your balance falls below a configurable threshold. Supports both instant payment methods (cards) and asynchronous methods (SEPA, ACH).
## Countries
### 🇩🇪 Germany
* **Improved speed** - Enhanced performance across all German company data operations, resulting in faster response times for company profile retrieval, document listing, and document downloads.
* **Vereinsregister (Non-Profit Register) support** - Introduced support for the Vereinsregister (VR register), enabling access to non-profit organization data in Germany. Currently available features:
* **Trade Register Extract (Aktueller Abdruck)** - Official PDF extract from the Vereinsregister containing current company information
### 🇷🇴 Romania
* **Initial support for Romania** - We're excited to announce support for Romanian companies with our integration of the ONRC (Romanian trade register). Currently available features:
* **Company search by name** - Find Romanian companies using their registered business names
* **Company search by tax identification number (CUI)** - Find Romanian companies using their Romanian tax numbers
* **Company search by Ordine Rc Number (Romanian company registration number)** - Find Romanian companies using their national Romanian registration numbers
* **Certified Trade Register Extract** - Official & certified PDF extract from ONRC containing information about the company (\~2 minutes retrieval time)
* **`companyProfile`** - Access comprehensive company information including status, legal form, address, legal representatives, shareholders, company establishments and much more
## Countries
### 🇩🇪 Germany
* **Improved speed and robustness** - Enhanced performance and reliability across all German company data operations, including company profile retrieval, document listing, and document downloads.
### 🇭🇺 Hungary
* **Initial support for Hungary** - We're excited to announce support for Hungarian companies with our integration of the Cégszolgálat (Hungarian company information register). Currently available features:
* **Company search by name** - Find Hungarian companies using their registered business names
* **Company search by registration number** - Find Hungarian companies using Hungarian registration numbers
* **Company search by tax number** - Find Hungarian companies using their national Hungarian tax numbers
* **`companyProfile`** - Access comprehensive company information including status, legal form, address, legal representatives and share capital
* **Trade Register Extract** - Official PDF extract from Cégszolgálat containing information about the company (\~2 minutes retrieval time)
## Countries
### 🇸🇪 Sweden
* **Initial support for Sweden** - We're excited to announce support for Swedish companies with our integration of the Bolagsverket (Swedish Companies Registration Office) register! Currently available features:
* **Company search by name** - Find Swedish companies using their registered business names
* **Company search by registration number** - Direct lookup using Swedish registration numbers
* **`companyProfile`** - Access comprehensive company information including status, legal form, address, legal representatives and other key persons
* **`availableDocuments`** - Access annual reports from Swedish companies when available (ZIP format)
## Platform
* Improved stability in Documents section.
* When a document is available both in a PDF and non-PDF format, when clicking on the PDF download icon then the PDF version of the file opens correctly.
* Removed last year financial statement shortcut support as part of the document ID cleanup.
## Countries
### 🇨🇾 Cyprus
* **Initial support for Cyprus** - We're excited to announce support for Cypriot companies with our integration of the DRCOR (Department of Registrar of Companies and Official Receiver) register! Currently available features:
* **Company search by name** - Find Cypriot companies using their registered business names
* **Company search by registration number** - Direct lookup using Cyprus registration numbers with Greek prefixes (ΗΕ, ΕΕ, ΑΕ, Σ)
* **`companyProfile`** - Access comprehensive company information including status, legal form, address, and legal representatives
* **Trade Register Extract (Study File)** - Official PDF extract from DRCOR containing complete company registration history, officers, shareholders, filings, and status since incorporation (\~2 minutes retrieval time)
* **Multiple company types** - Support for Private Limited Companies, Overseas Companies, Sole Traders, and Partnerships
For detailed information about Cyprus's unique identifier system with Greek prefixes, see our [Cyprus documentation](https://www.topograph.co/countries/cy).
### Estonia 🇪🇪
* You can now **search for available documents** !
* **Trade Register Extract** - Official PDF extract from RIK containing complete and extensive company information
* **Articles of Association** (PDF)
* **Annual reports** (PDF or XBRL)
## Countries
### 🇨🇭 Switzerland
**Enhanced Integration for Speed and Reliability**
We've completely reworked our integration with the Swiss business register to deliver significantly improved performance and reliability. The new implementation ensures faster data retrieval and more robust handling of edge cases.
Additionally, the **certificate of incorporation** is now available for Swiss companies, providing access to the official founding document.
## Platform
* Improved data management in web interface (request status indicator and data refresh)
* Fixed display of the map when a
company has registered headquarters
* Fixed data points selection when
changing countries, i.e : if "available documents" is available in France but
not in Estonia, then when switching to Estonia the datapoint should not be
checked and disappear from the credit count.
## Platform
### 🔄 Request Metadata Field
We've introduced a new `metadata` field on the `/company` endpoint that enables stateless request tracking without requiring local state management.
**Key Features:**
* **Pass custom metadata** - Include any JSON-serializable data (object, string, number) with your company data requests
* **Automatic passthrough** - Your metadata is returned with polling responses and webhook notifications
* **Stateless tracking** - Associate requests with your internal systems without maintaining a local state database
* **Perfect for webhooks** - Correlate asynchronous webhook callbacks with the original request context
## Countries
### 🇩🇪 Germany
**Improved Document Download Robustness**
We've enhanced the reliability of document downloads for German companies. Documents are now automatically preloaded in the background when you list available documents, ensuring they're ready when you need them.
While we've significantly improved reliability, the Unternehmensregister and
Handelsregister can be quite unstable at times, so we cannot guarantee 100%
success rates for document downloads. Our system now handles these
instabilities gracefully with automatic retries.
### 🇪🇸 Spain
**Enhanced Document Operations**
We've significantly improved the speed and reliability of document operations for Spanish companies.
## Platform
### 🔔 Company Monitoring (Beta)
**New Feature: Real-time Company Monitoring with AI-powered Change Detection**
We're excited to introduce Company Monitoring, a powerful new system that tracks changes in company data and sends real-time webhook notifications when important updates occur.
**Key Features:**
* **Automated daily checks** - Monitors run every 24 hours to detect changes in company profiles, ownership, and legal status
* **AI-powered change detection** - Intelligently identifies meaningful changes while filtering out noise
* **Smart categorization** - Changes are classified into 7 categories: `status`, `address`, `ownership`, `financial`, `legalRepresentatives`, `other`, and `disappeared`
* **Real-time webhooks** - Instant notifications via webhook when changes are detected
* **Automatic deactivation** - Monitors automatically stop when companies cease to exist, with a final notification
**Supported Countries:**
Currently available in 16+ countries: 🇦🇹 AT, 🇧🇪 BE, 🇨🇭 CH, 🇨🇿 CZ, 🇩🇪 DE, 🇩🇰 DK, 🇪🇸 ES, 🇫🇮 FI, 🇫🇷 FR, 🇬🇧 GB, 🇮🇪 IE, 🇲🇹 MT, 🇳🇱 NL, 🇳🇴 NO, 🇵🇱 PL, 🇵🇹 PT
This feature is currently in beta. We're actively collecting feedback to
refine change detection accuracy and expand country coverage. Contact
[support@topograph.co](mailto:support@topograph.co) to participate in the beta program.
For detailed API documentation and integration guide, see our [Company Monitoring documentation](/essentials/monitoring).
### 📄 Document Metadata Simplification
We've simplified document metadata fields for better consistency and clarity:
* **Removed `nameInEnglish` and `descriptionInEnglish` fields** - These redundant fields have been removed from the API response
* **Standardized `name` field** - Now always contains the original document name in the local language of the country where it was issued
* **Standardized `description` field** - Now always contains the document description in English
This change provides a more predictable API structure and eliminates confusion about which field to use for document identification and description.
## Countries
### 🇩🇪 Germany
**Intelligent ID-Based Search Enhancements**
We've significantly improved the German company search with intelligent ID parsing and prioritization:
* **ID Extraction**: We parse queries to extract and validate German company ID components (bureau/court, register type like HRB/HRA, registration number) from natural language queries. Includes full validation against all 154 known bureaus and 6 register types, with fuzzy matching for variations (e.g., "Munchen" matches "München").
* **Full ID Precision**: When all three ID components are detected and yield an exact match, returns a single precise result without name search fallback.
* **Partial ID Prioritization**: For queries with 1-2 ID components, partial ID matches are ranked first, followed by name search results (deduplicated by ID).
* **Robust Fallback**: If full ID search fails or query lacks ID components, seamlessly falls back to comprehensive name search.
This enhancement provides precision for ID-based lookups while maintaining broad discoverability for general searches. Supports queries like "München HRB 228960" (exact single result) or "HRB 12345" (prioritized partial matches).
### 🇵🇱 Poland
**Ultimate Beneficial Owners Support**
We've added comprehensive UBO (Ultimate Beneficial Owner) support for Polish companies through integration with CRBR (Centralny Rejestr Beneficjentów Rzeczywistych):
* **`ultimateBeneficialOwners`** - Access beneficial ownership information from Poland's official UBO register for both KRS and NIP companies
* **`ubo_extract` document** - Official PDF extract from CRBR, conditionally available only when UBO data exists
**Financial Documents Support**
Added support for retrieving financial statements for Polish companies with automatic XML-to-PDF conversion:
* **Automatic XML conversion** - Financial documents in XML format (Ministry of Finance schema) are automatically converted to human-readable PDF format using the official Polish government visualization tool at [e-sprawozdania.mf.gov.pl](https://e-sprawozdania.mf.gov.pl/ap/)
* **Dual format availability** - Both the original XML and converted PDF are stored and accessible
* **Seamless handling** - Conversion happens transparently during document retrieval with graceful fallback to XML if conversion fails
Note: Due to technical limitations of the Polish register portal, document format information is not available during listing and is only determined when documents are downloaded.
## Platform
### 📊 AI-Powered Financial Data Extraction (Beta)
**Beta Feature: Structured Financial Data Extraction**
We're excited to introduce automatic extraction of structured financial data from financial statements using AI. This beta feature analyzes financial statement documents and extracts key financial metrics into a structured, machine-readable format.
**Key Features:**
* **Automatic extraction** - No additional configuration needed; extraction happens automatically during document post-processing
* **Comprehensive data capture** - Extracts income statement items, balance sheet components, fiscal periods, and accounting metadata
* **Multi-language support** - Works with financial statements in various languages and formats
* **Structured output** - Financial data is returned in the `extractedData.financialData` field within financial statement documents
**Extracted Data Includes:**
* Income statement: revenue, operating income, depreciation, net income
* Balance sheet: assets (fixed/current), equity, liabilities (current/non-current)
* Metadata: fiscal year dates, approval date, currency, accounting standard, statement type
This feature is currently in beta. The data model may evolve as we refine
extraction accuracy and expand coverage. We welcome your feedback to help
improve this feature.
For detailed information about the data model and structure, see our [Financial Data Extraction documentation](/essentials/financial-data-extraction).
### 📄 Automatic PDF Document Conversion
We've introduced automatic conversion of non-PDF documents to PDF format for easier handling and viewing. Supported input formats include:
**Images:** JPG, JPEG, PNG, TIFF/TIF **Tabular:** CSV, XLS, XLSX **Documents:** DOC, DOCX, RTF, TXT, XPS, PPT, PPTX
**How it works:** When a raw document is retrieved, our system automatically converts it to PDF in the background. The converted PDF typically becomes available approximately 20 seconds after the original raw document is obtained. Both the original format and the converted PDF are available for download in the frontend interface.
### 🎨 Improved Document Download Interface
The frontend document download experience has been completely redesigned with significant UX improvements:
* **Enhanced metadata display** - Richer, more organized presentation of document details including descriptions, dates, and periods
* **Seamless raw + PDF handling** - Clear visual distinction between original documents and their PDF conversions with dedicated download actions for each
* **Improved row interactions** - Intuitive click-to-request functionality for pending documents with visual feedback
* **Better visual hierarchy** - Cleaner layout with icon-only type column and expanded space for document names and metadata
![Improved documents table with enhanced metadata and PDF conversion support]()
### ⚠️ Deprecations
* **Removed `jobs_in_progress` field** - This legacy internal field has been removed from API responses for security and clarity
* **Deprecated `main_article_of_association` smart document mapping** - We've removed the automatic mapping of document IDs to `main_article_of_association`. We're revisiting this feature with an improved approach and welcome feedback on your document mapping needs
* **Removed `isConsolidated` field** - This field has been removed from the API response as we were unable to provide consistently accurate information across different jurisdictions and document types. We plan to revisit this feature in future updates with improved data validation and source-specific accuracy indicators.
### 🔒 API Response Improvements
* **Cleaner error handling** - The `errors` field is now optional and only appears when errors actually occur, reducing response clutter
## Countries
### 🇩🇪 Germany
* **Major rewrite for speed and robustness** - We rebuilt the Germany integration to significantly improve performance and reliability across all flows: company data retrieval, document listing, and document downloads.
### 🇫🇮 Finland
* **Initial support for Finland** - We're excited to announce support for Finnish companies with our integration of the Finnish business registers! Currently available features:
* **Company search by name** - Find Finnish companies using their registered business names
* **Company search by registration number** - Direct lookup using Finnish company registration numbers
* **`companyProfile`** - Access comprehensive company information from Finnish business registers
* **Trade register extract support** - Full document retrieval functionality for Finnish companies
* **Article of Association support** - Access to company articles of association documents
## Platform
### 📄 Automatic PDF Document Conversion
We've introduced automatic conversion of non-PDF documents to PDF format for easier handling and viewing. Supported input formats include:
**Images:** JPG, JPEG, PNG, TIFF/TIF **Tabular:** CSV, XLS, XLSX **Documents:** DOC, DOCX, RTF, TXT, XPS, PPT, PPTX
**How it works:** When a raw document is retrieved, our system automatically converts it to PDF in the background. The converted PDF typically becomes available approximately 20 seconds after the original raw document is obtained. Both the original format and the converted PDF are available for download in the frontend interface.
### 🎨 Massively Improved Document Download Interface
The frontend document download experience has been completely redesigned with significant UX improvements:
* **Enhanced metadata display** - Richer, more organized presentation of document details including descriptions, dates, and periods
* **Seamless raw + PDF handling** - Clear visual distinction between original documents and their PDF conversions with dedicated download actions for each
* **Improved row interactions** - Intuitive click-to-request functionality for pending documents with visual feedback
* **Better visual hierarchy** - Cleaner layout with icon-only type column and expanded space for document names and metadata
![Improved documents table with enhanced metadata and PDF conversion support]()
### ⚠️ Field Updates
* **Removed `isConsolidated` field** - This field has been removed from the API response as we were unable to provide consistently accurate information across different jurisdictions and document types. We plan to revisit this feature in future updates with improved data validation and source-specific accuracy indicators.
## Countries
### 🇮🇹 Italy
* **Added support for closed/inactive companies** - Implemented fallback mechanism to retrieve data for closed/inactive companies not available in InfoCamere blocchi
* **Enhanced shareholder data structure** - Fixed missing `id` and `countryCode` fields for company shareholders to ensure consistent data structure
## Countries
### 🇫🇷 France
* **Improved KBis retrieval** - We've made K-Bis acquisition both faster and more resilient
### 🇮🇪 Ireland
* **Enhanced search robustness** - Improved error handling for company searches, ensuring more reliable search results when companies are not found
* **Better not found company handling** - Search operations now return empty results instead of errors when companies don't exist in the CRO register, while company profile requests properly throw not found exceptions
* **Improved address parsing** - Enhanced address geocoding accuracy by including Eircode (Irish postal codes) in the address parsing process
### 🇮🇹 Italy
* **Fixed financials retrieval bug**. We fixed the bug that prevented the retrieval of financial statements for Italian companies.
### 🇨🇿 Czechia
* **Initial support for Czechia** - We're excited to announce support for Czech companies with our integration of the Czech business registers (ARES & RZP)! Currently available features:
* **Company search by name** - Find Czech companies using their registered business names
* **Company search by registration number** - Direct lookup using Czech company registration numbers
* **`companyProfile`** - Access comprehensive company information from both ARES (Administrative Register of Economic Subjects) and RZP (Trade Register) registers
* **Trade register extract support** - Full document retrieval functionality for Czech companies from the RZP register
### 🇦🇹 Austria
* **Added trade register extract support** - Full document retrieval functionality for Austrian companies from the Firmenbuch register
### 🇵🇱 Poland
* **Restored and enhanced Poland support** - Complete rewrite of Poland integration with improved data mapping and document retrieval
* **Dual register support** - Full integration with both KRS (National Court Register) and CEIDG (Central Registration of Business Activity) registers
* **Enhanced document retrieval** - Now supports multiple document types:
* Trade register extracts (current) for both KRS and CEIDG companies
* Historical trade register extracts (full) for KRS companies
* Representatives/proxy documents for CEIDG sole proprietorships
* **Improved data mapping** - Better handling of company statuses, legal forms, and registration numbers with proper prefix support (krs- and nip-)
* **Fixed PDF document downloads** - Resolved issues with document retrieval returning JSON instead of PDF files
## Platform
### 🔍 Enhanced Search Error Management
* **Improved error handling and user guidance** - Search operations now provide clearer, more actionable error messages when queries fail due to user input issues
* **Better API documentation** - OpenAPI specifications now include comprehensive error response examples for both 400 (user errors) and 500 (server errors) status codes
* **Consistent error format** - Streamlined error response structure with unified guidance messages
### 📊 Shareholder Capital Fields Restructuring
* **Replaced `shareNominalPrice` with two distinct fields:**
* `nominalCapitalHeld` - Total face value or par value of all shares owned by the shareholder
* `paidInAmount` - Actual amount paid by the shareholder, including any share premium
* **Key improvements:**
* Better support for complex shareholding structures with multiple share classes
* Clear distinction between legal capital (nominal) and actual investment (paid-in)
* More accurate representation of shareholder contributions
* Alignment with international accounting standards
### 📅 Enhanced Company Date Tracking
* **Introduced `incorporationDate` field** - Now clearly distinguishes between when a company was legally incorporated/founded versus when it was registered with trade authorities
## Countries
### 🇲🇹 Malta
* **Much improved robustness** - Significantly enhanced system stability and reliability for Malta company data retrieval with better error handling and recovery mechanisms.
* **Restored document retrieval** - Fixed document access functionality that was experiencing issues, ensuring reliable document retrieval for Maltese companies.
## Platform
* **Fixed webhook delivery issues** - Resolved an issue affecting webhook delivery for asynchronous job completions and failed jobs. Webhooks are now reliably sent for all job status updates, ensuring dependable real-time notifications.
## Countries
### 🇨🇳 China
* **Enhanced robustness and improved identifier standardization** - Strengthened China implementation with better error handling and system stability. Standardized company identification around the **Unified Social Credit Code** as the single, authoritative 18-character alphanumeric identifier for all Chinese companies and organizations, replacing previous inconsistent identifier formats.
### 🇲🇹 Malta
* **Improved data accuracy and performance** - Enhanced Malta company data retrieval with more reliable parsing and faster processing times.
### 🇩🇰 Denmark
* **Financial statements and trade register extract support** - Enhanced Denmark implementation with full document retrieval capabilities. Added support for financial statements (annual reports) and official CVR trade register extracts, completing our comprehensive Danish business register integration.
### 🇪🇸 Spain
* **Enhanced robustness** - Improved stability and reliability of Spanish company data retrieval with better error handling and system resilience.
## Platform
* Improved document download experience in the customer portal, ensuring faster and more reliable access to retrieved files.
## Countries
### 🇫🇷 France
* Significantly improved the speed and reliability of Ultimate Beneficial Owner (UBO) data parsing for French companies.
## Countries
### 🇩🇰 Denmark
**Complete Danish Business register Support**
We're excited to announce support for Danish companies through our integration with the Danish Central Business Register (CVR)! This implementation features a sophisticated hybrid approach combining formal data mapping with AI-powered enrichment.
**Available Data Points:**
* **`companyProfile`** - Complete company information with legal representatives, shareholders, establishments, and other key personnel from the CVR register
* **`ultimateBeneficialOwners`** - Dedicated extraction of beneficial owners (UBOs) separate from legal shareholders, providing enhanced ownership transparency
**Technical Implementation:**
* **Direct CVR Integration** - Real-time access to Denmark's authoritative business database
**Coming soon**
* ***Documents support***
## Platform
### 💳 New Billing Dashboard & Analytics (Admin-only)
Your organisation admins now have access to a brand-new billing section that makes it easier than ever to understand how credits are being used.
* **Flexible global filters** – Pick any date range (or quick presets) and choose exactly which users – plus the API – you want to analyse.
* **Usage analytics** – Interactive bar chart that flips between daily, weekly, or monthly views and can be split by individual user or total.
* **Per-request cost tracking** – A detailed table shows the exact credit cost for every request, including ones that incurred no charge.
* **CSV export** – Download the full, filtered history (not just the current page) for deeper analysis in your favourite BI tool.
Head over to *Billing → Dashboard* (admins only) to explore the new insights.
![Billing dashboard – usage analytics]()
![Billing dashboard – request history]()
### 🔧 Field Naming Standardization
* **Renamed `englishName` to `englishTranslation`** - Updated field naming to align with our API naming strategy, maintaining consistency with other translated fields like `legalForm`. This change ensures a more coherent and predictable API structure across all data points.
## Countries
### 🇮🇹 Italy
* **Enhanced search validation** - Search queries must now be at least 2 characters long and cannot be overly broad. Clear error messages guide users when queries are too short or return too many results
* **Improved legal form parsing** - Enhanced accuracy and standardization of 70+ Italian legal forms for better company classification. See complete list in our [Italy documentation](https://www.topograph.co/countries/it#legal-forms)
* **Added establishments support** - Integrated establishment data with comprehensive location and activity information, including active status indicators
* **Enhanced shareholder parsing** - Significant improvements to shareholder data extraction, now enabling full support for `graph` ownership tree analysis
* **Added search by VAT and tax code** - New search functionality allowing company lookup using Italian VAT numbers (Partita IVA) or tax codes (Codice Fiscale)
### 🇬🇧 United Kingdom
* **Improved legal form and role mapping** - Enhanced accuracy and standardization of 40+ legal forms and 60+ officer roles with direct mapping to Topograph standards. See complete lists in our [UK documentation](https://www.topograph.co/countries/gb#legal-forms)
* **Standardized company identifiers** - Cleaned up identifier structure with consistent naming (`companiesHouseNumber` and `jurisdiction`)
* **Guaranteed SIC codes** - Direct SIC codes from Companies House with AI mapping to NACE and ISIC international standards
## ✨ Week 26 Highlights
* **🇮🇪 Ireland Launch** - New support for Irish entities with CRO register integration for company search and profiles
* **🚀 New Topograph Portal** - Deployed a heavily improved version of our customer portal with enhanced performance, better async handling, and modern design
* **🔧 Enhanced Activity Code Mapping** - Improved standardization and accuracy of business activity codes across France, Belgium, and Switzerland
## Platform
### 🚀 Portal Redesign (app.topograph.co)
We've completely redesigned and rebuilt our customer portal from the ground up, delivering a significantly improved user experience with modern architecture and enhanced capabilities.
![Redesigned Topograph customer portal]()
**Key Improvements:**
* **Enhanced Performance** - Faster navigation and reduced loading times across all portal features
* **Granular Data Point Control** - Precise selection and management of requested data points for optimized queries
* **First-Class Async Support** - Built-in asynchronous request handling with real-time progress tracking and status updates
* **Modern Design** - Refreshed interface with improved usability and visual hierarchy
* **New Data Points Integration** - Native support for Establishments and Other Key People with dedicated UI components
**Coming Soon:**
* **Usage Tracking** - Comprehensive analytics and monitoring of API consumption
* **Request History** - Detailed audit trail of all API requests and responses
* **Interactive Ownership Graph** - Visual representation of company ownership structures powered by our enhanced graph engine
## Countries
### 🇮🇪 Ireland
* **Initial support for Ireland** - We're excited to announce support for Irish companies with our integration of the Companies Registration Office (CRO)! Currently available features:
* **Company search by name** - Find Irish companies using their registered business names
* **Company search by registration number** - Direct lookup using CRO registration numbers
* **`companyProfile`** - Access comprehensive company information from the Companies Registration Office
* **Document support coming soon** - Full document retrieval functionality will be available in upcoming releases
### 🇫🇷 France
* **Fixed activity code mapping** - Resolved issues with business activity code standardization and improved accuracy of sector classification for French companies
### 🇧🇪 Belgium
* **Fixed activity code mapping** - Enhanced processing and standardization of Belgian NACE codes, ensuring better alignment with international classification standards
### 🇨🇭 Switzerland
* **Fixed activity code mapping** - Improved mapping of Swiss business activity codes (NOGA) to standardized formats, providing more accurate industry classification
## ✨ Week 25 Highlights
* **🎯 Enhanced Ownership Graph Analysis** - Improved UBO identification with dual calculation methods and better data visualization
* **🇩🇪 Intelligent German Shareholder Computation** - Multi-source extraction strategy with automatic fallbacks
* **🇵🇱 Poland Launch** - Full support for Polish entities with CEIDG and KRS register integration
* **🇦🇹 Austria Launch** - We're excited to announce support for Austrian companies, financial statements and company informations are available.
* **🇱🇺 Luxembourg Trade register Extract** - New comprehensive document access (up to 1 hour retrieval time)
## Platform
### 🎯 Enhanced Ownership Graph Analysis
We've launched improved ownership graph analysis with better UBO identification and cleaner data presentation, tested with German companies and providing cross-checking capabilities against Transparenzregister data.
**Key Improvements:**
* **Dual calculation methods** - Accumulation and domination approaches with 25% ownership threshold
* **Corporate UBO flagging** when ownership chains end at companies rather than individuals
* **Nodes and edges structure** for clearer ownership visualization with cross-border support
* **Better error handling** with partial results, circular ownership detection, and entity deduplication
## Countries
### 🇩🇪 Germany
**Enhanced Multi-Source Shareholder Data Extraction**
* **Three-source strategy** - Gesellschafterliste extraction, trade register analysis, and financial statement analysis *(NEW)*
* **Multi-source validation** combines results from different document types for better accuracy
* **Transparenzregister cross-checking** and automatic fallbacks when primary data sources are unavailable
* **Improved Handelsregister fallback** for document listing and retrieval with exponential backoff retry logic
### 🇵🇱 Poland
**Comprehensive Polish Business register Support**
* **Dual register coverage** - CEIDG (individual businesses) and KRS (companies) with smart ID prefixes
* **Complete data points** - `companyProfile` and `availableDocuments` tailored to entity type
* **Document support** - Trade register extract for both registers, historical extracts for KRS entities
### 🇪🇸 Spain
* **Fixed document retrieval and listing** - Resolved deployment issue affecting Spanish document access
* **Improved parsing of activities** - Enhanced extraction and processing for better accuracy
### 🇮🇹 Italy
* **Improved parsing of activities** - Enhanced extraction and processing for better accuracy
### 🇫🇷 France
* **Fixed Ultimate Beneficial Owner retrieval** - Resolved UBO data extraction issues for reliable beneficial ownership information
### 🇲🇹 Malta
* **Switched companyProfile to async process** - Automatic retry mechanism to overcome register instability
### 🇵🇹 Portugal
* **Improved shareholder parsing** - Enhanced extraction and processing of shareholder data
### 🇱🇺 Luxembourg
* **Added trade register extract support** - Comprehensive functionality for Luxembourg companies *(Note: May take up to one hour due to register processing time)*
### 🇦🇹 Austria
* **`companyProfile`** - Access comprehensive company information and legal representatives from the Austrian Firmenbuch
* **`availableDocuments`** - Document categorization for financial statements and other documents
## Platform
* **Renamed mostCompleteStatus**: The mostCompleteStatus document category has been renamed to mostCompleteArticleOfAssociation to better align with our naming conventions.
## Countries
### 🇳🇱 Netherlands
* **Improved system reliability** for Dutch company data retrieval, enhancing stability and reducing error rates.
* **Fixed trade register extract ID consistency** - Resolved an issue where document IDs would change when only the document was required, ensuring stable document references.
### 🇬🇧 United Kingdom
* **Added establishments support** - Integrated with the UK Companies House establishments endpoint to retrieve branch offices, subsidiaries, and other affiliated locations for UK companies.
* **Many improvements** - Enhanced documents metadata accuracy, fixed trade register extract listing issues, and improved overall system reliability for UK company data retrieval.
### 🇫🇷 France
* **Fixed establishments data** - Resolved establishment identification by adding SIRET as ID and corrected establishment names for improved accuracy and consistency.
### 🇳🇴 Norway
* **Added establishment IDs** - Enhanced establishments data by adding proper unique identifiers, improving data structure and referencing capabilities.
### 🇩🇪 Germany
* **Fixed company status for cached requests** - Resolved an issue where company status might be returned as unknown when retrieving stored company data, ensuring accurate status information.
### 🇵🇹 Portugal
* **Restored document retrieval** - Fixed document access functionality after adapting to changes in the Portuguese register's retrieval workflow, ensuring reliable document retrieval for Portuguese companies.
## Platform
**Major Data Model Enhancements**
We are progressively rolling out these data model enhancements to our supported countries, depending on the availability of data in the currently connected registers. This means that not all enhancements may be available for every country immediately, but coverage will expand as register data allows.
* **Establishments** - Now you can retrieve all establishments associated with a company, including branch offices, subsidiaries, and other affiliated locations that operate under the parent company's legal identity. This helps you understand a company's physical presence and operational footprint.
* **Other Key People** - Introducing a new data point to capture important company personnel beyond legal representatives. This includes board members, auditors, commissioners, and other significant roles. Unlike legal representatives who have binding authority, Other Key People provides visibility into the broader governance and oversight structure of a company.
* **Phone Numbers** - Companies can now include multiple phone numbers in E.164 format (e.g., +33123456789), making it easier to establish contact through official channels.
* **Website** - Retrieve the official company website URL directly from the API response, providing quick access to the company's online presence.
* **Status Details (Beta)** - We're introducing `statusDetails`, which provides enriched information about company status changes, including closure reasons, liquidation details, and important dates. The data model for status details is highly likely to evolve as we gather feedback and adapt to the diversity of register data. As this feature is in beta, we're actively collecting feedback to refine the data structure and ensure it meets your needs.
* **Topograph Standard Roles Revision** - The roles in Topograph Standard for legal representatives have been revised to cover a broader range of situations and to ensure there is no overlap with Other Key People. This provides clearer, more accurate role classification across jurisdictions.
## Countries
### 🇳🇴 Norway
* **Initial support for Norway** - We're excited to announce support for Norwegian companies, with our integration of the Norwegian Business register (Brønnøysundregistrene)! Currently available data points:
* `companyProfile` - Access comprehensive company information, legal representatives, other key people and establishments from the Norwegian Business register (Brønnøysundregistrene)
* Official trade register extract - Access an official PDF extract providing comprehensive company information including all registered data, roles, and establishments. Available in English.
## Platform
* **Extended data model to include establishment logic**, enhancing our ability to capture and process subsidiary and branch office information across all supported countries.
* **New values in Topograph Standard for roles**
## Countries
### 🇫🇷 France
* **Added establishments support**, enabling retrieval of subsidiary and branch office information for French companies.
* **Fixed UBO parsing**, improving accuracy and reliability of Ultimate Beneficial Owner data extraction.
## Countries
### 🇫🇷 France
* **Fixed access to UBO extract**, ensuring reliable retrieval of Ultimate Beneficial Owner information.
## Platform
* **Enhanced financial statement metadata quality** for availableDocuments, improving accuracy and consistency of document classification and information retrieval.
## Countries
### 🇪🇸 Spain
* **Improved document retrieval system** with enhanced robustness and significantly faster processing times, ensuring more reliable access to Spanish company documents.
## Countries
### 🇳🇱 Netherlands
* **Fixed document retrieval and companyProfile** to adapt to recent changes on the KVK website, restoring full functionality for Dutch company data access.
### 🇭🇰 Hong Kong
* **Restored `companyProfile` and `registerExtract` functionality** and significantly improved system robustness for Hong Kong data retrieval.
## Platform
**Key Feature Release**
* **Company Detention Tree (Beta)** - Introducing `graph`, a new datapoint that allows you to retrieve the complete detention tree of a company. This feature helps visualize company ownership structures and can assist in identifying potential Ultimate Beneficial Owners (UBOs). To use this feature, simply include the "graph" datapoint in your API calls.
This feature is currently in early beta. As it requires retrieving
companyProfile data for each entity in the ownership tree, usage may incur
significant costs. We recommend reaching out to become a design partner to
help shape this feature's development and discuss optimal usage patterns.
## Countries
### 🇩🇪 Germany
* **Enhanced detention tree reconstruction** by incorporating control statements from Register Extract documents, enabling more accurate ownership structure analysis.
## Countries
### 🇪🇸 Spain
* **Improved robustness and scalability** of data processing systems, enhancing overall performance and reliability of Spanish company data retrieval.
### 🇨🇳 China
* **Enhanced error handling** for cases where company is not found but register is accessible, providing clearer feedback and improved user experience.
### 🇬🇧 United Kingdom
* **Enhanced error handling** for cases where companies are not found in the register, providing more informative and user-friendly error messages.
### 🇩🇪 Germany
* **Improved shareholder data extraction** from documents, adding support for rotated document processing.
## Countries
### 🇩🇪 Germany
* **Enhanced robustness** of shareholders computation system, improving reliability and accuracy of ownership data processing.
### 🇪🇸 Spain
* **Improved system resilience** for document access and retrieval, implementing additional error handling and recovery mechanisms.
## Platform
* **Implemented embedding reuse system** for standardized activity codes, legal forms, and roles processing, saving up to 1.5 second of processing time per query.
* **Fixed error handling** for cases when companies are not found, eliminating 500 errors. Users now see a generic "An Error has occurred in the job status" message. We're working on improving generic error messages.
## Countries
### 🇩🇪 Germany
* **Major Update: Shareholders now derived from Gesellschafterliste**. This is preliminary work to enable detention tree reconstruction and UBO identification in Germany. Coming soon!
* Improved robustness of company data retrieval by implementing additional error handling and fallback mechanisms.
* Improved parsing of shareholders data, enhancing accuracy and completeness of ownership information.
* Improved handling of german id including parenthesis.
### 🇬🇧 United Kingdom
* Fixed Register Extract functionality to adapt to the new Companies House website flow, ensuring reliable document retrieval.
## Platform
* **Fixed error handling** for cases when companies are not found, eliminating 500 errors. Users now see a generic "An Error has occurred in the job status" message. We're working on improving generic error messages.
## Countries
### 🇪🇸 Spain
* Fixed financial document listing functionality to correctly retrieve and display available financial documents.
## Platform
* **Optimized request processing pipeline**, resulting in an average **2 seconds reduction** in response time across all endpoints.
* **Fixed performance bottlenecks** when processing companies with large document collections by implementing a **faster inference endpoint** for document metadata processing.
* **Enhanced performance logging** across the application to better identify and address bottlenecks.
We are actively working on improving overall performance, with a focus on
inference speed optimization. A **faster inference solution** is currently in
development.
## Countries
### 🇮🇹 Italy
* Added support for asynchronous data retrieval from the Italian Chamber of Commerce (Camerale). As a result, **companyProfile for Italy is now an asynchronous data point**.
### 🇩🇪 Germany
* Implemented fallback to Handelsregister when Unternehmensregister is unavailable for search and companyProfile.
### 🇪🇸 Spain
* Improved overall speed and reliability of Spanish company data retrieval through infrastructure optimizations.
* Added support for asynchronous data retrieval for legalRepresentatives in Spain. Note that base companyProfile data still remains synchronous. This change prevents blocking access to base company data when fetching many legal representatives, which could be time-consuming for companies with extensive representative lists.
* As a result, **companyProfile for Spain is now a partially asynchronous data point**.
### 🇨🇳 China
* Improved overall speed and reliability of Chinese company data retrieval through infrastructure optimizations.
### 🇳🇱 Netherlands
* Updated document listing functionality to match KVK's new API specifications, restoring the ability to list available documents for Dutch companies.
# Activity Codes
Source: https://docs.topograph.co/essentials/activity-codes
How a register’s own activity codes become ISIC Rev. 5 and NACE Rev. 2.1
Every business register classifies what a company does, and almost every one of them uses its own
scheme: PKD in Poland, ATECO in Italy, NAF in France, EMTAK in Estonia, OKVED in Russia, NAICS in
the United States. Topograph publishes the register's own code exactly as it was declared, and
alongside it two international standards you can build one integration against:
* **ISIC Rev. 5**, the global standard maintained by the United Nations Statistics Division
* **NACE Rev. 2.1**, the European standard maintained by Eurostat, in force for EU statistics
from 2025
## Three layers, always
```mermaid theme={null}
flowchart LR
A["Register's own code
PKD 62.01.Z"] --> B["NACE Rev. 2.1
62.10"]
B --> C["ISIC Rev. 5
621"]
A -.->|"published as declared"| A2["activities.PKD"]
B --> B2["activities.NACE"]
C --> C2["activities.ISIC"]
```
Wherever a declared activity can be placed in the international standards, the response carries
**both** `ISIC` and `NACE`. If a register publishes only one of the two, we derive the other. The
register's own code keeps its own key, in the register's own format, untouched, and is always
published.
`ISIC` and `NACE` can be missing when the source register exposes no activity data for the company,
when a declared code has no NACE Rev. 2.1 successor or its candidates span unrelated divisions, or
when no confident match exists.
## Why the revision matters
This is the single most common source of confusion, so it is worth being precise.
NACE Rev. 2.1 replaced NACE Rev. 2 for EU statistics from 2025. It is **not** a renaming: a
substantial number of four-digit codes were reused for a different activity.
| Code | Meaning in NACE Rev. 2 | Meaning in NACE Rev. 2.1 |
| - | - | - |
| `46.71` | Wholesale of solid, liquid and gaseous fuels | Wholesale of motor vehicles |
| `35.12` | Transmission of electricity | Production of electricity from renewable sources |
| `58.13` | Publishing of newspapers | Publishing of journals and periodicals |
A register that has not yet migrated still reports Rev. 2. We transition those codes to Rev. 2.1
using the official Eurostat correspondence before publishing them under `activities.NACE`, so
everything on that key is Rev. 2.1 regardless of where it came from.
If you hold historical Topograph responses, or you compare our output against a register's raw
export, expect Rev. 2 and Rev. 2.1 codes to disagree on the same company. Compare the
**descriptions**, not the digits.
## ISIC and NACE do not share their four-digit codes
NACE Rev. 2.1 is built on ISIC Rev. 5, but the two are only identical down to the **two-digit
division**. Below that they diverge: NACE subdivides more finely (651 classes against ISIC's 463)
and numbers its classes independently.
```mermaid theme={null}
flowchart TB
subgraph D["Division 46 · Wholesale trade (identical in both standards)"]
direction LR
N["NACE Rev. 2.1
46.71 Wholesale of motor vehicles"]
I["ISIC Rev. 5
4661 Wholesale of motor vehicles"]
N <-->|"correspondence"| I
end
X["ISIC Rev. 5 4671
Wholesale of fuels"]
N -.->|"NOT the same activity"| X
```
The practical consequence: **never assume an ISIC code and a NACE code with the same four digits
mean the same thing.** ISIC `4671` is wholesale of fuels; NACE `46.71` is wholesale of motor
vehicles. If you segment your portfolio on the two-digit division, the two standards agree exactly,
and that is the safest cross-standard key.
No official NACE Rev. 2.1 to ISIC Rev. 5 correspondence table is published by either Eurostat or
the UNSD. Ours is derived from the two official structures, matching classes on their official
headings and falling back to the guaranteed division containment. Every published pair sits
inside the division both standards share.
## One code in, one code out
**We never publish an activity the register did not declare.** You get one standardized class per
declared code, never a list of candidates we could not choose between.
Classification systems do not line up one-to-one. When a declared class corresponds to several
classes in the target standard, the true one is unknowable from the code alone. Rather than return
all of them, we return the most precise code the correspondence actually supports:
```mermaid theme={null}
flowchart TB
S["Declared code"] --> Q1{"Corresponds to exactly
one class?"}
Q1 -->|Yes| R1["Publish that class
69.20 → 6920"]
Q1 -->|No| Q2{"Do all candidates
share a group?"}
Q2 -->|Yes| R2["Publish the group
62.10 → 621"]
Q2 -->|No| Q3{"Do they share
a division?"}
Q3 -->|Yes| R3["Publish the division
49.12 → 49"]
Q3 -->|No| R4["Publish nothing standardized
register's own code only"]
```
| The declared code corresponds to | What you get |
| - | - |
| Exactly one class in the target standard | That class |
| Several classes in one group | Their shared group (`64.2` rather than guessing `64.21` or `64.22`) |
| Several classes across groups of one division | Their shared division (`47`) |
| Classes scattered across unrelated divisions | No standardized code, the register's own code only |
A shorter code is not missing data. `64.2` means the register told us the company is a holding
company but not which kind, and that is the most specific statement the source supports. The
register's own code is always published in full alongside it.
Of the 651 NACE Rev. 2.1 classes, 554 correspond to a single four-digit ISIC class. The remaining
97 are finer than any ISIC class, so they resolve to an ISIC group or division by design.
## Deterministic first, AI only as a fallback
Most of the work is a table lookup, not a model.
```mermaid theme={null}
flowchart TB
A["Register response"] --> B{"Did the register give
a NACE-family code?"}
B -->|Yes| S{"Does it split across several
NACE Rev. 2.1 classes?"}
S -->|No| C["Transition to NACE Rev. 2.1
(official Eurostat table)"]
C --> D["Derive ISIC Rev. 5
(correspondence table)"]
S -->|Yes| T{"Is a description of
the business available?"}
T -->|Yes| F
T -->|No| U["Publish the shared
group or division"]
U --> Z
B -->|No| E{"A local code or a
free-text description?"}
E -->|Yes| F["Match to an ISIC class
with a language model"]
F --> G["Derive NACE Rev. 2.1
(correspondence table)"]
E -->|No| H["No activity data"]
D --> Z["Response"]
G --> Z
style F fill:#fef3c7,stroke:#b45309,color:#111
```
The AI step runs only when a register publishes a classification we hold no formal correspondence
for (a national scheme such as ATECO or SIC), or only a free-text description of the business. It
also runs when a declared NACE Rev. 2 code splits across several Rev. 2.1 classes and the register
gives a description of the business: the model picks the class from that description. Without a
description, we publish the group or division the candidates share, when they share one. The model
chooses from the 463 ISIC Rev. 5 classes and nothing else: it cannot invent a code, and it cannot
return a coarse section or division. When it is not confident, it returns nothing rather than
guessing.
### `isAIInferred`
Every activity code carries this flag, so you can always tell how it was produced.
| Value | Meaning |
| - | - |
| `false` | The register declared this code, or we derived it through an official correspondence table. Deterministic and reproducible. |
| `true` | A language model chose this code from the company's description, from a national code we hold no formal correspondence for, or to settle a NACE Rev. 2 code that splits in Rev. 2.1. |
A derived code inherits the flag of the code it came from: an ISIC class matched by AI produces a
NACE code that is also marked `true`.
If your compliance process requires register-sourced classification only, filter on
`isAIInferred: false`.
## National classifications
Where a register publishes its own national scheme, you get its code in its declared format alongside the standardized codes. Each classification and revision has one canonical response key.
`ISIC` is Rev. 5 and `NACE` is Rev. 2.1 in current responses. These revisions apply to both deterministic and AI-inferred codes; historical responses can predate the transition.
### Revisions of unversioned keys
When the register stamps each record with an edition, we publish that record under its revision key. A bare key such as `TOL` or `NACE_BEL` contains only records whose edition could not be resolved; it does not repeat codes already returned under revision keys.
| Classification | Response keys | Revision |
| - | - | - |
| NACE-BEL | `NACE_BEL_2003`, `NACE_BEL_2008`, `NACE_BEL_2025` | Per the register's record |
| SBI | `SBI` | 2025 for current active registrations; historical and deregistered records can retain 2008 |
| ATECO | `ATECO_2007`, `ATECO_2025` | ATECO 2007 family including the 2022 update, or ATECO 2025 |
| CNAE | `CNAE_2009` | CNAE-2009 |
| TOL | `TOL_1995`, `TOL_2002`, `TOL_2008`, `TOL_2025` | Per company |
| TEÁOR | `TEAOR_2008`, `TEAOR_2025` | Per record; one company can have both |
| RNA | `RNA` | Association purposes, with no published revision identifier |
`SBI` does not guarantee a year. Earlier responses also used `SBI_2025` for these same codes without independently verifying their edition. Current responses use only `SBI`; check historical and deregistered records before assigning a revision.
The [standardization guide](/guides/standardization#revision-explicit-keys) lists the other classifications. Declared country-specific classification keys are listed in `/v2/catalog` under `activityCodes.responseKeys`. That field does not enumerate every possible response key, including unstamped and association-purpose classifications.
### Alternate spellings
Current responses use only the canonical spelling. When source records or cached data contain aliases, their distinct codes are merged into that key and repeated codes are deduplicated.
| Earlier or source spellings | Current response key | Display label |
| - | - | - |
| `NAFREV2`, `NAFRev2`, `NAF_REV2` | `NAF_REV2` | NAF rév. 2 |
| `WZ2008`, `WZ_2008` | `WZ_2008` | WZ 2008 |
| `WZ2025`, `WZ_2025` | `WZ_2025` | WZ 2025 |
| `ATECO2025`, `ATECO_2025` | `ATECO_2025` | ATECO 2025 |
| `ISIC_REV5`, `ISIC` | `ISIC` | ISIC Rev. 5 |
| `NACE_REV21`, `NACE` | `NACE` | NACE Rev. 2.1 |
If your integration reads an earlier spelling, switch to the current response key. Aliases are accepted from sources, but are no longer repeated in API responses. Different editions, such as `WZ_2008` and `WZ_2025`, remain separate.
The bare `NAF` key does not fix a revision and is not an alias of `NAF_REV2`.
### RNA association purposes
`RNA` refers to the French Répertoire National des Associations' *nomenclature des objets sociaux*. These codes describe an association's purpose, such as sport or culture. They are a separate classification from NAF and NACE, and are not association registration numbers.
We publish the declared purpose code and its label without a revision identifier. Display it as “RNA, association purpose” without adding a year.
### Authorized response keys
The complete list below matches the allowed keys in our published OpenAPI schema. Each key holds an array of activity objects. Additional keys and source-alias spellings are excluded from that response schema.
A revision is fixed only where stated. “Not stated by the key” means the key alone cannot establish the edition; “Unresolved per record” applies only to records without a resolved revision. Distinct editions retain separate keys.
| Response key | Classification | Revision |
| - | - | - |
| `ISIC` | International Standard Industrial Classification | Rev. 5 |
| `NACE` | Statistical Classification of Economic Activities in the European Community | Rev. 2.1 |
| `NACE_REV1` | Statistical Classification of Economic Activities in the European Community | Rev. 1 |
| `NACE_REV11` | Statistical Classification of Economic Activities in the European Community | Rev. 1.1 |
| `NACE_REV2` | Statistical Classification of Economic Activities in the European Community | Rev. 2 |
| `NACE_BEL` | Nomenclature générale des activités économiques (Belgian NACE) | Unresolved per record |
| `NACE_BEL_2003` | Nomenclature générale des activités économiques (Belgian NACE) | 2003 |
| `NACE_BEL_2008` | Nomenclature générale des activités économiques (Belgian NACE) | 2008 |
| `NACE_BEL_2025` | Nomenclature générale des activités économiques (Belgian NACE) | 2025 |
| `WZ_2008` | Klassifikation der Wirtschaftszweige | 2008 |
| `WZ_2025` | Klassifikation der Wirtschaftszweige | 2025 |
| `DB25` | Dansk Branchekode | 2025 |
| `CNAE_2009` | Clasificación Nacional de Actividades Económicas | 2009 |
| `CNAE_BR` | Classificação Nacional de Atividades Econômicas (Brazil) | Not stated by the key |
| `TOL` | Toimialaluokitus | Unresolved per record |
| `TOL_1995` | Toimialaluokitus | 1995 |
| `TOL_2002` | Toimialaluokitus | 2002 |
| `TOL_2008` | Toimialaluokitus | 2008 |
| `TOL_2025` | Toimialaluokitus | 2025 |
| `NAF` | Nomenclature d'activités française | Not stated by the key |
| `NAF_1993` | Nomenclature d'activités française | 1993 |
| `NAF_REV1` | Nomenclature d'activités française | Rév. 1 |
| `NAF_REV2` | Nomenclature d'activités française (code APE) | rév. 2 |
| `NAF_2025` | Nomenclature d'activités française (code APE) | 2025 |
| `NAP` | Nomenclature d'activités et de produits | Not stated by the key |
| `RNA` | RNA association-purpose classification | Not stated by the key |
| `ALSACE_MOSELLE` | Alsace-Moselle association purposes | Not stated by the key |
| `SIC` | Standard Industrial Classification | Not stated by the key |
| `SIC_2007` | UK Standard Industrial Classification | 2007 |
| `KAD_2025` | Κωδικός Αριθμός Δραστηριότητας | 2025 |
| `NKD` | Nacionalna klasifikacija djelatnosti | Unresolved per record |
| `NKD_1994` | Nacionalna klasifikacija djelatnosti | 1994 |
| `NKD_2007` | Nacionalna klasifikacija djelatnosti | 2007 |
| `NKD_2025` | Nacionalna klasifikacija djelatnosti | 2025 |
| `TEAOR` | Tevékenységek Egységes Ágazati Osztályozási Rendszere | Unresolved per record |
| `TEAOR_2008` | Tevékenységek Egységes Ágazati Osztályozási Rendszere | 2008 |
| `TEAOR_2025` | Tevékenységek Egységes Ágazati Osztályozási Rendszere | 2025 |
| `ATECO_2007` | Classificazione delle attività economiche | 2007 (aggiornamento 2022) |
| `ATECO_2025` | Classificazione delle attività economiche | 2025 |
| `CAEM_REV11` | Clasificatorul Activităților din Economia Moldovei | Rev. 1.1 |
| `CAEM_REV2` | Clasificatorul Activităților din Economia Moldovei | Rev. 2 |
| `SBI` | Standaard Bedrijfsindeling | Not stated by the key |
| `CAE_REV3` | Classificação Portuguesa das Atividades Económicas | Rev. 3 |
| `CAE_QC` | Code d’activité économique du Québec | Edition not stated on the register record |
| `OKVED_REV2` | Общероссийский классификатор видов экономической деятельности | Rev. 2 (ОК 029-2014) |
| `SNI_2025` | Svensk näringsgrensindelning | 2025 |
| `KVED_2010` | Класифікація видів економічної діяльності | 2010 |
| `NAICS` | North American Industry Classification System | Not stated by the key |
| `PKD` | Polska Klasyfikacja Działalności | Not stated by the key |
| `CAEN` | Clasificarea Activităților din Economia Națională | Unresolved per record |
| `CAEN_REV2` | Clasificarea Activităților din Economia Națională | Rev. 2 |
| `CAEN_REV3` | Clasificarea Activităților din Economia Națională | Rev. 3 |
| `NKID` | Национална класификация на икономическите дейности | Not stated by the key |
| `EMTAK` | Eesti majanduse tegevusalade klassifikaator | Unresolved per record |
| `EMTAK_2008` | Eesti majanduse tegevusalade klassifikaator | 2008 |
| `EMTAK_2025` | Eesti majanduse tegevusalade klassifikaator | 2025 |
| `NACE_EE` | Estonian register activity classification | Not stated by the key |
| `NACE_SK` | Slovak register activity classification | Not stated by the key |
| `SKD` | Standardna klasifikacija dejavnosti | Not stated by the key |
| `ISAT_2008` | Íslensk atvinnugreinaflokkun | 2008 |
| `KD_BIH_2010` | Klasifikacija djelatnosti | 2010 |
| `NOGA` | Nomenclature générale des activités économiques | Not stated by the key |
| `SSIC` | Singapore Standard Industrial Classification | Not stated by the key |
| `GG_ACTIVITY` | Guernsey economic-activity classification | Not stated by the key |
National codes can belong to a different revision from standardized `NACE`. Their descriptions belong to their own classification and revision. Do not compare a national code to a NACE code digit by digit.
## Example response
A Polish company whose register entry declares one PKD activity:
```json theme={null}
{
"activities": {
"PKD": [
{
"code": "62.01.Z",
"description": "Działalność związana z oprogramowaniem",
"isAIInferred": false
}
],
"NACE": [
{
"code": "62.10",
"description": "Computer programming activities",
"isAIInferred": false
}
],
"ISIC": [
{
"code": "621",
"description": "Computer programming activities",
"isAIInferred": false
}
]
}
}
```
The PKD code is the register's, in the register's format. NACE `62.10` is the Rev. 2.1 class the
Rev. 2 code `62.01` transitions to. ISIC `621` is a group rather than a class because NACE `62.10`
covers the whole of ISIC group `621`, and naming one of its children would claim a precision the
register never gave.
## Working with the data
Use the two-digit division. It is identical in ISIC Rev. 5 and NACE Rev. 2.1, present on every
standardized code we publish, and stable across the Rev. 2 to Rev. 2.1 transition for most
divisions. Take the first two characters of either `activities.NACE[].code` or
`activities.ISIC[].code`.
Match on the full code, and handle codes shorter than four digits. Treat a three-digit ISIC
group or two-digit division as "within this family, precision not available", not as a
non-match. Never pad or truncate a code to force a comparison.
Compare descriptions rather than digits, and check which revision your extract uses. A register
export that predates the 2025 transition is NACE Rev. 2, and its four-digit codes will disagree
with ours for a substantial number of activities.
Filter on `isAIInferred`. `false` means register-declared or derived through an official
correspondence, and is reproducible. The register's own code under its national key is always
`false`.
# Antigua and Barbuda
Source: https://docs.topograph.co/essentials/antigua-and-barbuda
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Antigua and Barbuda reference is on the [Antigua and Barbuda country page](https://www.topograph.co/countries/ag).
## Start here
This guide contains public integration notes for Antigua and Barbuda. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Antigua and Barbuda uses a single official register. All data comes from the **Intellectual Property and Commerce Office (IPCO)**, which keeps the companies register of Antigua and Barbuda ([abipco.gov.ag](https://abipco.gov.ag/)). There is no cross-register merging.
* **IPCO companies register**: the **sole source** for company search and for the `company` datapoint. It provides the legal name, entity number, company type, status, incorporation date, and registered office address.
**Same answer in both modes.** The IPCO register is the only source, so prefill (`mode: "prefill"`) and verification (`mode: "verification"`) requests return the same data from the same source.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Examples | Notes |
| - | - | - | - |
| **Entity Number** | Uppercase `C`, sometimes followed by a space, then 1 to 4 digits, optionally with a year suffix (`/YY`, or `/YYYY` with the number zero-padded to 4 digits) | `C8093`, `C84/09`, `C 963`, `C0728/2025` | Issued by IPCO. The only public identifier for a company. |
**Pass the entity number exactly as the register writes it, including any space.** Some numbers contain a space after the `C` (for example `C 963`). The register treats `C 963` and `C963` as different values, so the version without the space does not find the company, in search or in `/v2/company`. If you are unsure of the exact spelling, search by company name and use the `id` it returns.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | Same as the query identifier | `C8093` | All companies |
The company `id` is the entity number, as written by the register.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Entity Number | `C`, optional space, 1 to 4 digits, optional year suffix | `C8093` | `id` | Companies whose entity number matches the query |
| By Name | 2 to 100 characters | `"Example Trading"` | `default`, or `exactLegalName` when the query equals the legal name | Multiple results |
**Search is live.** Both name and entity-number searches query the IPCO register in real time. Name search matches the query anywhere in the legal name, so short queries return many results. Use a fuller name to narrow them down.
An entity-number search can return more than one company when other numbers contain the same characters. Pick the result whose `id` equals your entity number, then pass that `id` to `/v2/company`.
Search results carry the company `id`, `legalName`, `countryCode`, and `matchReason`. Status, company type, and address come with the `company` datapoint.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Entity number spacing matters** | Some entity numbers include a space after the `C`. Keep it. Removing the space means the register does not find the company. |
| **Varied entity number shapes** | Numbers appear with or without a year suffix (`C4521`, `C52/08`, `C0310/2024`). Treat the whole string, suffix included, as the identifier. |
| **Company data only** | The register publishes a company-level record. Officers, directors, shareholders, and beneficial owners are not published, so `legalRepresentatives`, `otherKeyPersons`, `shareholders`, and `ultimateBeneficialOwners` are not available. |
| **Legal form is not standardized** | The company type is returned as the register writes it (for example `Private Ordinary Company`) in `legalForm.localName`, without an English translation or standardized value. |
| **Status is the register's own label** | `status.localName` is the register's status text. `status.active` is `true` only when that text is `Active`. |
| **Single-line address** | The registered office address is published as one free-text line. It is returned in `legalAddress.addressLine1` with `countryCode: "AG"`, and is not split into city or postal code. |
| **No activity codes** | The register does not collect industry classification codes, so no national, NACE, or ISIC codes are returned. |
| **No documents** | The register does not offer downloadable certificates or extracts. |
## Mappings
### Company Status
The register's status label is returned unchanged in `status.localName`. No English translation or standardized status is added.
| Register Status | `status.active` |
| - | - |
| `Active` | `true` |
| Any other label | `false` |
### Legal Forms
The register's company type is returned unchanged in `legalForm.localName` (for example `Private Ordinary Company`). No standardized legal form or ISO 20275 code is returned for Antigua and Barbuda.
### Legal Representatives, Shareholders, and Activity Codes
Not applicable. The register does not publish officers, shareholders, beneficial owners, or activity codes.
## Data Availability
### Data Availability Matrix
| Data Point | Available | Notes |
| - | - | - |
| Company name | ✅ | Current legal name |
| Entity number | ✅ | `identifiers.entityNumber` |
| Company status | ✅ | Register label, with `active: true` only for `Active` |
| Legal form | ✅ | Register company type, local name only |
| Incorporation date | ✅ | When published by the register |
| Registered office address | ✅ | Single free-text line, when published by the register |
| Legal representatives | ❌ | Not published by the register |
| Other key persons | ❌ | Not published by the register |
| Shareholders | ❌ | Not published by the register |
| Ultimate beneficial owners | ❌ | No public beneficial-ownership register |
| Activity codes | ❌ | Not collected by the register |
| Establishments | ❌ | Not available |
| Documents | ❌ | The register does not offer downloadable certificates or extracts |
For the full datapoint catalog, check the [Antigua and Barbuda pricing page](https://topograph.co/pricing/ag).
### Documents by Company Type
No documents are available for Antigua and Barbuda. The register does not offer downloadable certificates or extracts, so `availableDocuments` and document orders are not supported.
## Example API Responses
All examples use **placeholder data**.
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=AG&query=Example%20Trading" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "C4521",
"legalName": "EXAMPLE TRADING (ANTIGUA) LIMITED",
"countryCode": "AG",
"matchReason": { "matchType": "default" }
},
{
"id": "C0310/2024",
"legalName": "EXAMPLE TRADING SERVICES LIMITED",
"countryCode": "AG",
"matchReason": { "matchType": "default" }
}
]
```
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=AG&query=C4521" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "C4521",
"legalName": "EXAMPLE TRADING (ANTIGUA) LIMITED",
"countryCode": "AG",
"matchReason": { "matchType": "id", "identifier": { "entityNumber": "C4521" } }
}
]
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "AG", "id": "C4521", "dataPoints": ["company"]}'
```
```json theme={null}
{
"company": {
"id": "C4521",
"countryCode": "AG",
"identifiers": { "entityNumber": "C4521" },
"legalName": "EXAMPLE TRADING (ANTIGUA) LIMITED",
"incorporationDate": "2004-06-18",
"status": { "localName": "Active", "active": true },
"legalForm": { "localName": "Private Ordinary Company" },
"legalAddress": { "addressLine1": "12 Example Street, St. John's, Antigua", "countryCode": "AG" }
}
}
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "AG", "id": "C 917", "dataPoints": ["company"]}'
```
```json theme={null}
{
"company": {
"id": "C 917",
"countryCode": "AG",
"identifiers": { "entityNumber": "C 917" },
"legalName": "EXAMPLE ASSEMBLIES ANTIGUA",
"incorporationDate": "1987-02-09",
"status": { "localName": "Active", "active": true },
"legalForm": { "localName": "Private Ordinary Company" },
"legalAddress": { "addressLine1": "PO Box 000, Example Road, St. John's", "countryCode": "AG" }
}
}
```
# Austria
Source: https://docs.topograph.co/essentials/austria
Country-specific identifiers, data sources, and field mappings for Austria
This guide is outdated and will be removed on 1 November 2026. The up-to-date Austria reference is on the [Austria country page](https://www.topograph.co/countries/at).
## Start here
This guide contains public integration notes for Austria. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
Austria uses **three registers**, each covering a distinct entity type. Company profile data for an entity comes from the register that holds it.
### Commercial companies
* **Firmenbuch (Austrian Companies Register).** Operated by the Federal Ministry of Justice via the Justiz Online platform. The Firmenbuch has been the central business register since 1991, replacing the former Handelsregister. It is the **primary source** for all entities registered with the commercial courts: GmbH, AG, KG, OG, cooperatives, foundations, and registered sole proprietors (e.U.). The Firmenbuch contains registration details, legal form, address, share capital, business purpose, key persons (officers, prokuristen, supervisory board), and filed documents (financial statements, articles of association, annual reports).
The Firmenbuch is accessed via official interfaces operated by the Austrian judiciary, providing company profile data, available documents, document content, and company name searches.
### Sole proprietorships
* **GISA (Gewerbeinformationssystem Austria).** Austria's trade information system, operated by the Federal Ministry of Labour and Economy (BMAW). GISA is the **primary source** for sole proprietorships (Einzelunternehmen), covering trade rights (Gewerbe), business locations, and trade managers. Each trade licence has a unique GISA-Zahl identifier.
GISA provides sole proprietorship data including the owner, trade rights with classification codes, business locations, and appointed trade managers. It does not provide financial statements or historical documents - only a digitally signed trade licence excerpt.
### Associations (non-profits)
* **Vereinsregister (ZVR - Zentrales Vereinsregister).** The Central Association Register, operated by the Federal Ministry of the Interior (BMI). The Vereinsregister is the **primary source** for registered associations (Vereine), which are a common legal form in Austria for non-profits, clubs, and civic organizations. It provides the association name, officers with their roles, mailing address, and supervising authority.
The Vereinsregister provides association profiles and a digitally signed register extract (Vereinsregisterauszug). It does not provide financial statements or other documents.
### Supplementary sources
* **VIES (VAT Information Exchange System).** The EU-wide VAT validation service resolves a VAT number to a company name during **VAT number searches**. When a company is requested by its VAT number, VIES also verifies that number, and the result appears in `taxId.verification` on the company (status, verified name and address, consultation number).
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **Commercial companies** | Firmenbuch | Digits + lowercase check letter (FNR), up to 6 digits seen | `184018s` | Firmenbuchnummer (FN), spaces are stripped |
| **Sole proprietorships** | GISA | Digits, 8 in every record seen | `10118573` | GISA-Zahl (trade licence number) |
| **Associations** | Vereinsregister | 1–10 digits | `432857691` | ZVR number (Vereinsregisternummer) |
**Firmenbuchnummer Format:** The FNR consists of digits followed by a lowercase check letter (e.g., `184018s`, `41375x`). Numbers are assigned in sequence nationwide, so older companies have fewer digits. The registry format may include a space (e.g., `184018 s`) but all whitespace is automatically stripped.
### Identifiers in API Response
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `firmenbuchnummer` | Digits + lowercase check letter | `184018s` | Firmenbuch companies |
| `gisaZahl` | Digits, 8 in every record seen | `10118573` | GISA trade licences |
| `zvrNumber` | 1–10 digits | `432857691` | Vereinsregister associations |
| `VAT` | U + 8 digits (AT prefix removed) | `U63496924` | VAT-registered companies (when available) |
| `euid` | `ATBRA.` + FN padded to 6 digits without the check letter + `-000` | `ATBRA.184018-000` | Firmenbuch companies (when the register provides one) |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Firmenbuch number (`firmenbuchnummer`) or association number (`zvrNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Source | Match Type | Expected Results |
| - | - | - | - | - | - |
| By Firmenbuchnummer | Digits + check letter | `184018s` | Firmenbuch | Exact | Exact match returned first (matchType: id); other results may follow |
| By GISA-Zahl | 5–10 digits | `10118573` | GISA | Exact | Exact match returned first (matchType: id); other results may follow |
| By ZVR Number | 1–10 digits | `432857691` | Vereinsregister | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | ATU + 8 digits | `ATU63496924` | VIES → Firmenbuch | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT (no prefix) | U + 8 digits | `U63496924` | VIES → Firmenbuch | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Staatsoper GmbH"` | All three | Fuzzy | Up to 10 Firmenbuch companies, plus matching GISA sole traders and at most one association |
**Name searches fan out to all three sources** in parallel, returning aggregated results from the Firmenbuch, GISA, and Vereinsregister.
**Search Performance:** Use identifier-based searches (FNR, GISA-Zahl, ZVR, VAT) for best performance and exact matching. Name searches query all three sources: up to 10 Firmenbuch companies, every GISA sole trader whose name matches, and a Vereinsregister association only when the name matches exactly one association.
**VAT Search Flow:** VAT searches first validate the number via VIES to retrieve the official company name, then search the Firmenbuch by that name. This two-step process means VAT search results depend on the company name registered with VIES matching the Firmenbuch entry.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Company-register results are filtered when the register marks them deleted, and trade-licence number lookups are filtered on the licence status. Association results and trade-licence name searches carry no status and are returned whatever their status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Three distinct sources** | Identifier format determines which source is queried. A Firmenbuchnummer (digits + check letter) goes to the Firmenbuch. An all-digit id is looked up in both GISA and the Vereinsregister, and resolves in whichever register holds it. |
| **GISA indexes by person** | GISA data is organised around the trade holder (natural person). A search returns trade licences associated with a person. The "company name" for a sole proprietor is the person's full name. |
| **Vereinsregister name search limitation** | Name searches against the Vereinsregister only return a result when there is exactly one matching association. Ambiguous queries return no results. Use the ZVR number for reliable lookups. |
| **AI-enriched company data** | For Firmenbuch companies, legal form standardization and activity codes are **AI-enriched** from register data. Status and legal representatives come directly from the register. The `isAIInferred` flag is set on activity codes. |
| **FNR formatting** | Firmenbuchnummer may contain spaces in the registry format (e.g., `184018 s`). These are always stripped to `184018s` in API responses. |
| **AI-extracted shareholders** | Shareholders of Firmenbuch companies are extracted with AI from the official register extract (Firmenbuchauszug), in verification mode only, where the extract discloses them. They are not part of the base company profile. Check them against the source before relying on them for compliance. For sole traders (GISA) and associations (ZVR) the datapoint is not applicable and returns `datapoint_not_applicable` at no charge. |
| **No UBO data** | Ultimate beneficial owner information is not available through any of the three sources. Austria maintains a separate UBO register (Wirtschaftliche Eigentumer Register) not currently integrated. |
| **No official activity codes** | The Firmenbuch does not store NACE or national activity codes. Activity information is AI-inferred from the business purpose text. GISA provides trade classification codes (Gewerbe-Schluessel) but these are not NACE codes. |
| **Document format variety** | Firmenbuch documents can be in various formats: PDF, DOC, DOCX, XLS, XLSX, TXT, XML, HTML. XML financial statements (XBRL) are common for recent filings. |
| **No share capital** | Share capital is not returned for any Austrian entity, including Firmenbuch companies. |
| **Financial statements** | Only available from the Firmenbuch. GISA and Vereinsregister do not provide financial documents. Period dates use the reporting date as the end date. |
| **Register extract** | The Firmenbuchauszug is retrieved from the official register and may take longer (up to 10 minutes). The GISA-Auszug and Vereinsregisterauszug are generally faster. |
| **FlexKapG (new since 2024)** | Austria introduced the Flexible Kapitalgesellschaft (FlexKapG/FlexCo) as a new legal form on January 1, 2024. It may appear in the Firmenbuch. Its ISO 20275 ELF code is `BCSV`. |
| **Deleted companies in search** | The Firmenbuch search filters out deleted companies. Only active/current companies appear in search results. |
## Mappings
### Company Status
#### Firmenbuch
Company status is set by a fixed rule on the Firmenbuch record.
| Local Status | English | `active` | Notes |
| - | - | - | - |
| Aktiv | Active | `true` | No liquidator is registered |
| In Liquidation | In Liquidation | `false` | A liquidator is registered on the company |
#### GISA
Status is determined from the trade licence data (trade right dates and dormancy flag).
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| Aktiv | Active | Active | Trade licence is active |
| Ruhend | Dormant | Inactive | Trade licence is temporarily dormant |
| Beendet | Ended | Closed | Trade licence has been terminated |
#### Vereinsregister
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| Aktiv | Active | Active | Only active associations appear in the register |
### Legal Forms
Austria uses a variety of legal forms. Legal form mapping for Firmenbuch entities is **AI-enriched** - the legal form is AI-inferred from registry data and mapped to standardized categories and ISO 20275 codes. GISA entities are mapped deterministically based on the owner type. Vereinsregister entities are always mapped to "Verein".
Because legal form standardization and ISO 20275 assignment are AI-enriched for Firmenbuch entities, exact mappings may evolve. The local Austrian legal form name is always preserved verbatim.
#### Key Business Forms
| Local Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Gesellschaft mit beschrankter Haftung | GmbH | Limited Liability Company | Limited Liability Company | `AXSB` |
| Aktiengesellschaft | AG | Joint-Stock Company | Corporation | `EQOV` |
| Kommanditgesellschaft | KG | Limited Partnership | Partnership | `ONF1` |
| Offene Gesellschaft | OG | General Partnership | Partnership | `JTAV` |
#### Sole Proprietorships
| Local Name | Abbr. | English Translation | Standardized | ISO 20275 | Source |
| - | - | - | - | - | - |
| Einzelunternehmer | e.U. | Sole Proprietor | Sole Proprietorship | `ECWU` | Firmenbuch |
| Einzelkaufmann | - | Sole Trader | Sole Proprietorship | `G3R6` | Firmenbuch |
| Einzelunternehmen | - | Sole Proprietorship | Sole Proprietorship | - | GISA |
GISA licences held by a natural person are mapped to "Einzelunternehmen" (Sole Proprietorship), with the holder's personal name as the legal name. Licences held by a legal entity return that entity's name, legal form and register number (`firmenbuchnummer` or `zvrNumber`).
#### Cooperatives
| Local Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Erwerbs- und Wirtschaftsgenossenschaft | - | Trade and Commercial Cooperative | Cooperative | `NIJH` |
| Genossenschaft | Gen | Cooperative | Cooperative | `8XDW` |
#### Foundations & Non-Profits
| Local Name | Abbr. | English Translation | Standardized | ISO 20275 | Source |
| - | - | - | - | - | - |
| Privatstiftung | PSt | Private Foundation | Other | `5WWO` | Firmenbuch |
| Gemeinnutzige Stiftung | - | Charitable Foundation | Nonprofit Organization | `E9OX` | Firmenbuch |
| Verein | - | Registered Association | Nonprofit Organization | `DX6Z` | Vereinsregister |
#### Public Law & Financial Institutions
| Local Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Korperschaft offentlichen Rechts | - | Public Law Corporation | Government-Owned Entity | `JJYT` |
| Sparkasse | - | Savings Bank | Other | `JQOI` |
| Versicherungsverein auf Gegenseitigkeit | - | Mutual Insurance Association | Other | `CAQ1` |
#### European Forms
| Local Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Europaische Gesellschaft (SE) | SE | European Company (SE) | Corporation | `O65B` |
| Europaische Genossenschaft (SCE) | SCE | European Cooperative Society | Cooperative | `69H1` |
| Europaische wirtschaftliche Interessenvereinigung | EWIV | European Economic Interest Grouping | Other | `DM88` |
#### Historical & Special Forms
| Local Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Offene Handelsgesellschaft | OHG | General Commercial Partnership | Partnership | `GVPD` |
| Offene Erwerbsgesellschaft | OEG | General Trade Partnership | Partnership | `JUHG` |
| Kommandit-Erwerbsgesellschaft | KEG | Limited Trade Partnership | Partnership | `AAL7` |
| Gesellschaft des burgerlichen Rechts | GesbR | Civil Law Partnership | Partnership | `UI81` |
| stille Gesellschaft | stG | Silent Partnership | Partnership | `NNLI` |
| Sonstiger Rechtstrager | - | Other Legal Entity | Other | `1NOX` |
The OHG (Offene Handelsgesellschaft) and OEG (Offene Erwerbsgesellschaft) are **historical legal forms** that were replaced by the OG (Offene Gesellschaft) under the 2007 Austrian company law reform (UGB). Existing OHG/OEG entities may still appear in the Firmenbuch. The **GmbH & Co KG** is not a separate legal form in the ELF code list - it is a Kommanditgesellschaft (KG) where the general partner is a GmbH.
The FlexKapG (Flexible Kapitalgesellschaft), introduced on January 1, 2024, has the ISO 20275 ELF code `BCSV`. It may appear in the Firmenbuch as "Flexible Kapitalgesellschaft" or "FlexCo".
### Legal Representatives
Legal representatives are extracted from three sources, each with its own role vocabulary.
#### Firmenbuch Roles
Legal representatives are extracted from the Firmenbuch register data. Known representing offices appear under `legalRepresentatives`; known supervisory, auditor and ownership-only offices appear under `otherKeyPersons`. Recorded titles keep their original spelling and known meanings have fixed translations and standardized values. Unlisted function labels may have no standardized meaning. An officer title does not establish a sole or joint signing mode.
| German Role | English Translation |
| - | - |
| Geschaftsfuhrer/in | Managing Director |
| Geschaftsfuhrer/in (handelsrechtlich) | Managing Director (commercial law) |
| Vorstandsmitglied | Board Member |
| Vorstandsvorsitzender | Chairman of the Board |
| Einzelvertretungsbefugtes Vorstandsmitglied | Board Member with Sole Representation |
| Selbstandiger Vertreter | Independent Representative |
| German Role | English Translation |
| - | - |
| Prokurist/in | Authorized Signatory (Prokura) |
| Einzelprokurist | Sole Authorized Signatory |
| Gesamtprokurist | Joint Authorized Signatory |
| German Role | English Translation |
| - | - |
| Personlich haftender Gesellschafter | Personally Liable Partner (General Partner) |
| Komplementar | General Partner |
| Kommanditist | Limited Partner |
| Gesellschafter | Partner / Shareholder |
| German Role | English Translation |
| - | - |
| Liquidator | Liquidator |
| Masseverwalter | Insolvency Administrator |
| Stiftungsvorstand | Foundation Board Member |
| Obmann / Obfrau | Chairman / Chairwoman (Association) |
| Stellvertretender Obmann | Deputy Chairman (Association) |
The local German role name is always preserved from the Firmenbuch. Managing directors, authorized signatories (Prokura), general partners, board members, owners and liquidators also get a standardized role. Both individuals and corporate entities can hold roles.
#### GISA Roles
| German Role | English Translation | Standardized |
| - | - | - |
| Inhaber | Owner | Owner |
| Gewerberechtlicher Geschäftsführer | Trade Law Manager | Other |
When a natural person holds the licence, the holder (Inhaber) is returned first as a legal representative, with a birth date when the register publishes one. Appointed trade managers (Gewerberechtlicher Geschäftsführer) appear under `otherKeyPersons`. Their trade-law compliance appointment alone does not establish civil-law signing powers.
#### Vereinsregister Roles
| German Role | English Translation | Standardized |
| - | - | - |
| Präsident | President | President |
| Vizepräsident | Vice President | Vice President |
| Obmann | Chairman | Chairman |
| Obfrau | Chairwoman | Chairman |
| Obmann-Stellvertreter | Deputy Chairman | Vice President |
| Obfrau-Stellvertreterin | Deputy Chairwoman | Vice President |
| Schriftführer | Secretary | Secretary |
| Kassier | Treasurer | Treasurer |
| Generalsekretär | Secretary General | Secretary |
| Generalsekretär-Stv. | Deputy Secretary General | Secretary |
Both individuals and corporate entities (juridical persons) can serve as association officers in the Vereinsregister.
#### Supervisory & Control Roles (Firmenbuch)
When present in the Firmenbuch, known supervisory and auditor offices appear under `otherKeyPersons`; those titles do not by themselves grant ordinary company representation.
| German Role | English Translation |
| - | - |
| Aufsichtsratsvorsitzender | Chairman of Supervisory Board |
| Stellvertreter des Vorsitzenden | Deputy Chairman of Supervisory Board |
| Aufsichtsratsmitglied | Supervisory Board Member |
| Abschlussprufer | Auditor |
### Shareholders
Shareholders are available for Firmenbuch companies. They are extracted with AI from the official register extract (Firmenbuchauszug), in verification mode only, so check them against the source before relying on them for compliance.
Shareholder coverage depends on what the Firmenbuch extract discloses. For sole traders (GISA) and associations (ZVR), the `shareholders` datapoint is not applicable and returns `datapoint_not_applicable` at no charge. The owner of a sole trader and the officers of an association appear under `legalRepresentatives`. When a trade licence is held by a company rather than a person, request shareholders with that company's Firmenbuch identifier. Shareholders are distinct from ultimate beneficial owners: Austria maintains a separate Economic Owners Register (Wirtschaftliche Eigentumer Register / WiEReG) that is not currently integrated.
### Activity Code Mapping
Austria does not use a formal national industry classification code in the Firmenbuch. Instead, activity information is derived from the business purpose text stored in the registry.
```
Business Purpose Text (German) --> ISIC Rev. 5 (AI-inferred) --> NACE Rev. 2.1 (derived from ISIC)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **ISIC** | Matched to the business purpose by AI | `9000` | Yes |
| **NACE** | Derived from ISIC through the official correspondence table | `9004` | Yes (inherited from ISIC) |
**AI Enrichment:** Both NACE and ISIC codes are AI-inferred from the business purpose text in the Firmenbuch. Every activity item includes an `isAIInferred` flag set to `true`. There is no official Austrian activity code in the Firmenbuch data. GISA provides trade classification codes (Gewerbe-Schluessel) but these are used as trade descriptions, not mapped to NACE.
**Main activity:** The best-match code in each classification is flagged with `isMainActivity: true`. Because it always carries `isAIInferred: true`, it cannot be mistaken for a main activity declared by the register. When the flag is absent, the source did not designate a main activity.
## Data Availability
### Data Availability Matrix
| Data Type | Firmenbuch | GISA | Vereinsregister |
| - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async |
| Legal Representatives | ✅ | ✅ | ✅ |
| Other Key Persons | ✅ Known supervisory / auditor offices, Sync | ✅ Trade-law managers, Sync | ❌ |
| Shareholders | ⚠️ AI-extracted, Async, when disclosed in the extract | Not applicable for sole traders (for a company holding the licence, use its Firmenbuch identifier) | Not applicable |
| Ultimate Beneficial Owners | ❌ | ❌ | ❌ |
| Establishments | ❌ | ❌ | ❌ |
| Activity Codes | ⚠️ AI-inferred | ❌ | ❌ |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Documents by Source
#### Firmenbuch
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Firmenbuchauszug** | `tradeRegisterExtract` | PDF | ✅ Always available | Official trade register extract |
| **Jahresabschluss** | `financialStatements[]` | PDF/XML | ✅ When filed | Annual financial statements |
| **Konzernabschluss** | `financialStatements[]` | PDF/XML | ✅ When filed | Consolidated financial statements |
| **Bestatigungsvermerk** | `financialStatements[]` | PDF/XML | ✅ When filed | Auditor's confirmation report |
| **Lagebericht** | `otherDocuments[]` | PDF/XML | ✅ When filed | Management report |
| **Sonstiges Dokument** | `otherDocuments[]` | PDF/various | ✅ When filed | Articles of association, decisions, etc. |
#### GISA
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **GISA-Auszug** | `tradeRegisterExtract` | PDF | ✅ Always available | Digitally signed trade licence excerpt |
#### Vereinsregister
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Vereinsregisterauszug** | `tradeRegisterExtract` | PDF | ✅ Always available | Official register extract with digital signature (Amtssignatur) |
**Document Formats:** Most Firmenbuch documents are available in PDF format. Recent financial filings (from approximately 2023 onward) are often available in both PDF and XML (XBRL) format. GISA and Vereinsregister documents are always PDF.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "AT", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "123456a",
"countryCode": "AT",
"identifiers": { "firmenbuchnummer": "123456a" },
"taxId": { "type": "eu_vat", "value": "", "country": "AT", "verification": { "status": "unavailable" } },
"legalName": "Beispiel Technologie GmbH",
"registrationDate": "2005-03-15",
"activityDescription": "Entwicklung und Vertrieb von Softwareloesungen.",
"status": { "localName": "Aktiv", "active": true },
"legalForm": { "localName": "Gesellschaft mit beschraenkter Haftung", "standardized": "Limited Liability Company", "iso20275Code": "AXSB", "englishTranslation": "Limited Liability Company" },
"legalAddress": { "addressLine1": "Mariahilfer Strasse 45", "city": "Wien", "postalCode": "1060", "countryCode": "AT" }
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": { "localName": "Geschaeftsfuehrer/in (handelsrechtlich)", "standardized": "Managing Director", "englishTranslation": "Managing Director" },
"startDate": "2020-09-01",
"individual": { "name": { "fullName": "Hans Mueller", "firstName": "Hans", "lastName": "Mueller" }, "birthDate": { "day": 15, "month": 3, "year": 1975 } }
},
{
"type": "individual",
"entityId": "person_002",
"role": { "localName": "Prokurist/in", "standardized": "Authorized Signatory", "englishTranslation": "Authorized Signatory (Procurist)" },
"startDate": "2020-07-01",
"individual": { "name": { "fullName": "Anna Schmidt", "firstName": "Anna", "lastName": "Schmidt" }, "birthDate": { "day": 22, "month": 8, "year": 1982 } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "654321b",
"countryCode": "AT",
"identifiers": { "firmenbuchnummer": "654321b" },
"taxId": { "type": "eu_vat", "value": "", "country": "AT", "verification": { "status": "unavailable" } },
"legalName": "Oesterreichische Industrie AG",
"registrationDate": "1995-01-10",
"activityDescription": "Herstellung und Vertrieb von industriellen Anlagen und Maschinen.",
"status": { "localName": "Aktiv", "active": true },
"legalForm": { "localName": "Aktiengesellschaft", "standardized": "Corporation", "iso20275Code": "EQOV", "englishTranslation": "Joint-Stock Company" },
"legalAddress": { "addressLine1": "Ringstrasse 1", "city": "Wien", "postalCode": "1010", "countryCode": "AT" }
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": { "localName": "Vorstandsvorsitzender", "standardized": "Chairman of the Board", "englishTranslation": "Chairman of the Board" },
"startDate": "2018-01-01",
"individual": { "name": { "fullName": "Friedrich Weber", "firstName": "Friedrich", "lastName": "Weber" }, "birthDate": { "day": 10, "month": 5, "year": 1968 } }
},
{
"type": "individual",
"entityId": "person_002",
"role": { "localName": "Vorstandsmitglied", "standardized": "Board Member", "englishTranslation": "Board Member" },
"startDate": "2020-06-01",
"individual": { "name": { "fullName": "Elisabeth Gruber", "firstName": "Elisabeth", "lastName": "Gruber" }, "birthDate": { "day": 3, "month": 11, "year": 1975 } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "10118573",
"countryCode": "AT",
"identifiers": { "gisaZahl": "10118573" },
"legalName": "Maria Huber",
"registrationDate": "2018-06-01",
"activityDescription": "Gastgewerbe",
"status": { "localName": "Aktiv", "active": true },
"legalForm": { "localName": "Einzelunternehmen", "standardized": "Sole Proprietorship", "englishTranslation": "Sole Proprietorship" },
"legalAddress": { "addressLine1": "Hauptstrasse 12", "city": "Salzburg", "postalCode": "5020", "countryCode": "AT" }
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": { "localName": "Inhaber", "standardized": "Owner", "englishTranslation": "Owner" },
"startDate": "2018-06-01",
"individual": { "name": { "fullName": "Maria Huber", "firstName": "Maria", "lastName": "Huber" }, "birthDate": { "day": 12, "month": 3, "year": 1985 } }
}
],
"otherKeyPersons": [
{
"type": "individual",
"entityId": "person_002",
"role": { "localName": "Gewerberechtlicher Geschäftsführer", "standardized": "Other", "englishTranslation": "Trade Law Manager" },
"startDate": "2018-06-01",
"individual": { "name": { "fullName": "Josef Berger", "firstName": "Josef", "lastName": "Berger" } }
}
]
}
```
**Note:** For GISA sole proprietorships, the `legalName` is the trade holder's personal name, and the holder is also returned as a legal representative with the role `Inhaber`. The `activityDescription` contains the trade right description (Wortlaut). No capital information is provided.
```json theme={null}
{
"company": {
"id": "432857691",
"countryCode": "AT",
"identifiers": { "zvrNumber": "432857691" },
"legalName": "Wiener Kulturverein Harmonie",
"registrationDate": "2010-04-15",
"status": { "localName": "Aktiv", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Verein", "standardized": "Nonprofit Organization", "englishTranslation": "Registered Association" },
"legalAddress": { "addressLine1": "Neubaugasse 8", "city": "Wien", "postalCode": "1070", "countryCode": "AT" }
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": { "localName": "Obmann", "standardized": "Chairman", "englishTranslation": "Chairman" },
"individual": { "name": { "fullName": "Thomas Steiner", "firstName": "Thomas", "lastName": "Steiner" } }
},
{
"type": "individual",
"entityId": "person_002",
"role": { "localName": "Schriftführer", "standardized": "Secretary", "englishTranslation": "Secretary" },
"individual": { "name": { "fullName": "Katharina Moser", "firstName": "Katharina", "lastName": "Moser" } }
},
{
"type": "individual",
"entityId": "person_003",
"role": { "localName": "Kassier", "standardized": "Treasurer", "englishTranslation": "Treasurer" },
"individual": { "name": { "fullName": "Peter Wimmer", "firstName": "Peter", "lastName": "Wimmer" } }
}
]
}
```
**Note:** Vereinsregister associations have no capital, no activity description, and no birth dates. Officers are always returned with their association-specific roles (Obmann, Schriftführer, Kassier, etc.).
```json theme={null}
{
"company": {
"id": "789012c",
"countryCode": "AT",
"identifiers": { "firmenbuchnummer": "789012c" },
"taxId": { "type": "eu_vat", "value": "", "country": "AT", "verification": { "status": "unavailable" } },
"legalName": "Alte Handels GmbH",
"registrationDate": "2010-06-01",
"activityDescription": "Handel mit Waren aller Art.",
"status": { "localName": "In Liquidation", "active": false },
"legalForm": { "localName": "Gesellschaft mit beschraenkter Haftung", "standardized": "Limited Liability Company", "iso20275Code": "AXSB", "englishTranslation": "Limited Liability Company" },
"legalAddress": { "addressLine1": "Landstrasse 12", "city": "Graz", "postalCode": "8010", "countryCode": "AT" }
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": { "localName": "Liquidator", "standardized": "Liquidator", "englishTranslation": "Liquidator" },
"startDate": "2023-01-15",
"individual": { "name": { "fullName": "Karl Berger", "firstName": "Karl", "lastName": "Berger" }, "birthDate": { "day": 7, "month": 2, "year": 1970 } }
}
]
}
```
**Note:** A Firmenbuch company with a registered liquidator has `active: false` and the local status `In Liquidation`.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Format | Source | Notes |
| - | - | - | - | - |
| `tradeRegisterExtract` | Firmenbuchauszug | PDF | Firmenbuch | Always available (FNR entities) |
| `tradeRegisterExtract` | GISA-Auszug | PDF | GISA | Always available (GISA-Zahl entities) |
| `tradeRegisterExtract` | Vereinsregisterauszug | PDF | Vereinsregister | Always available (ZVR entities) |
| `financialStatements[]` | Jahresabschluss | PDF/XML | Firmenbuch | When filed, with `period.endDate` |
| `financialStatements[]` | Konzernabschluss | PDF/XML | Firmenbuch | When filed, consolidated accounts |
| `financialStatements[]` | Bestatigungsvermerk | PDF/XML | Firmenbuch | When filed |
| `otherDocuments[]` | Lagebericht | PDF/XML | Firmenbuch | When filed |
| `otherDocuments[]` | Sonstiges Dokument | PDF/various | Firmenbuch | Articles, decisions, etc. |
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc-extract-001",
"name": "Register Extract (Firmenbuchauszug)",
"subType": "firmenbuchauszug",
"format": "pdf",
"description": "Official trade register extract"
},
"financialStatements": [
{
"id": "doc-fs-001",
"name": "Jahresabschluss",
"subType": "jahresabschluss",
"format": "pdf",
"date": "2024-08-31",
"period": { "endDate": { "day": 31, "month": 8, "year": 2024 } }
},
{
"id": "doc-fs-002",
"name": "Bestatigungsvermerk zum Jahresabschluss",
"subType": "bestaetigungsvermerk",
"format": "pdf",
"date": "2024-08-31",
"period": { "endDate": { "day": 31, "month": 8, "year": 2024 } }
}
],
"otherDocuments": [
{
"id": "doc-other-001",
"name": "Lagebericht",
"format": "pdf",
"date": "2024-08-31"
}
]
}
}
```
# Belgium
Source: https://docs.topograph.co/essentials/belgium
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Belgium reference is on the [Belgium country page](https://www.topograph.co/countries/be).
## Start here
This guide contains public integration notes for Belgium. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Compliance Flags](#compliance-flags)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Juridical Situation Codes](#juridical-situation-codes)
* [Registration & Incorporation Dates](#registration--incorporation-dates)
* [VAT Verification](#vat-verification)
* [Establishments](#establishments)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Belgium combines open data with the official register service. For a given entity, **base data comes from BCE Open Data** and **CBE Public Search adds the fields the open data does not carry** (legal representatives, other key persons, share capital). Each datapoint is delivered as soon as it is ready.
### All entity types
* **BCE Open Data** (Banque-Carrefour des Entreprises / Kruispuntbank van Ondernemingen): The Belgian open data portal operated by the FPS Economy. Updated regularly, this dataset covers \~2.5 million enterprises and provides **base company data**: legal name (multilingual), status, legal form, registration date, NACE activity codes, registered address, contact information (phone, website), and establishments. This is the **primary source for fast company profiles**.
* **CBE Public Search** (kbopub.economie.fgov.be): The official public search service of the Crossroads Bank for Enterprises. It provides the data not available in the open dataset: legal representatives, other key persons (auditors, supervisory board) and share capital. For companies not found in BCE Open Data (e.g., closed companies), CBE provides the **complete profile** in verification mode.
### Documents
* **NBB CBSO** (National Bank of Belgium, Central Balance Sheet Office). Official API (`consult.cbso.nbb.be`) operated by the National Bank of Belgium. Provides **financial statements** (annual accounts, consolidated accounts, holding company accounts) filed by Belgian companies. Documents are available in PDF, XBRL, and CSV formats depending on how they were submitted.
* **eJustice / Moniteur Belge** (Belgian Official Gazette): The official publication portal (`ejustice.just.fgov.be`) operated by the FPS Justice. Provides **legal publications** including articles of association, appointments/resignations, capital changes, registered office changes, and other official company modifications. All publications are in PDF format.
* **Belgian UBO Register**: The official UBO register operated by the FPS Finance (Treasury). Provides **ultimate beneficial owner data** and **UBO extract PDFs**.
**BCE Open Data only lists active entities.** Companies missing from it (typically closed companies, or companies legally created but not yet active) are served from CBE Public Search in verification mode. In prefill mode, `company` and `establishments` are served from BCE Open Data only, so these companies return not found. Retry in verification mode to get the full profile.
1. **BCE Open Data**: base company data (name, status, legal form, activities, address, contact info, establishments)
2. **CBE Public Search**: legal representatives and other key persons (both modes), and share capital (verification mode only)
If a company is **not found in BCE Open Data** (e.g., closed or only legally created), CBE Public Search returns the full company profile in verification mode. In prefill mode, `company` and `establishments` return not found for these companies.
Each datapoint (`company`, `legalRepresentatives`, `establishments`, ...) is delivered as soon as it is ready. For current response times, see the Speed section of the [pricing page](https://topograph.co/pricing/be).
### Source labels in `dataSources`
In verification mode, fields from BCE Open Data are labelled `live_from_registry` (register `bce_opendata`) when our copy holds the register's latest daily publication. That is checked on every request.
If the copy cannot be confirmed current, verification does not use it. Company details and establishments are fetched live from CBE Public Search instead (register `bce`). If that live lookup fails, the datapoint fails with a retryable `source_unavailable` error rather than returning older data. The registration date is the one field only BCE Open Data carries, and it keeps `cached_from_registry` in that case.
Prefill results always carry `cached_from_registry` for BCE Open Data fields. Share capital, legal representatives and other key persons come from CBE Public Search and are labelled `live_from_registry` (register `bce`).
## Compliance Flags
Belgium covers two independent UBO compliance signals under `company.complianceFlags`. They describe register-reported obligations and notices; they do not change retrieval status in `request.dataStatus` or the company's legal status.
| Flag | Request in verification mode | Evidence and meaning |
| - | - | - |
| `uboConfirmationOverdue` | `ultimateBeneficialOwners` | The Belgian UBO Register explicitly reports whether annual confirmation is overdue. `active: true` means overdue; `active: false` means the register reports a valid confirmation. `lastConfirmedOn` is the last confirmation date when available. |
| `uboAdministrativeStrikingOff` | `company` | BCE Public Search explicitly publishes an administrative striking-off notice for non-compliance with UBO obligations. `active: true` means the notice is present; `since` is its effective date when available. Absence does not establish `active: false`. |
Request both datapoints to obtain both signals. A UBO-only request can contain a `company` object limited to the confirmation flag; it does not include an unrequested company profile. A document-only request does not provide these flags.
The [SPF Finances guidance](https://finances.belgium.be/fr/E-services/ubo-register) requires annual confirmation even when ownership has not changed.
A modification date, an owner's control-start date, or a document's creation date cannot establish overdue confirmation. Topograph returns the register's explicit statement; an absent flag means unknown, including when access or confirmation evidence is unavailable.
An administrative striking-off notice can coexist with an active company and a normal legal situation. It does not dissolve the entity. A valid annual UBO confirmation does not clear the BCE notice: the notice remains independent until BCE reports its removal.
Each flag carries its own `source` (`ubo_register` or `bce`) and an `observedAt` timestamp. This is when the statement was observed, not a confirmation or modification date.
Reused results retain that observation time. Per-flag provenance is available under `dataSources.company`.
The dates and identifiers in this example are placeholders. Both statements can be present together.
```json theme={null}
{
"company": {
"complianceFlags": {
"uboConfirmationOverdue": {
"active": false,
"source": "ubo_register",
"lastConfirmedOn": "2026-09-15",
"observedAt": "2026-10-06T10:00:00.000Z"
},
"uboAdministrativeStrikingOff": {
"active": true,
"source": "bce",
"since": "2024-10-02",
"observedAt": "2026-10-06T10:00:01.000Z"
}
}
},
"dataSources": {
"company": {
"complianceFlags.uboConfirmationOverdue": { "type": "live_from_registry", "register": "ubo_register" },
"complianceFlags.uboAdministrativeStrikingOff": { "type": "live_from_registry", "register": "bce" }
}
}
}
```
See [Compliance signals](/essentials/compliance-signals) for the shared response contract and the [Belgium pricing details](https://topograph.co/pricing/be) for current country coverage. The same country descriptions are available through the [Topograph Wizard](/guides/topograph-mcp).
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Supported for domestic company forms registered in BRIS: SA/NV, SRL/BV (and former SPRL/BVBA), SCA/Comm.VA, Societas Europaea and new-statute cooperatives (SC/CV), including their public-law and social-purpose variants. Example: `BEKBOBCE.0403.170.701`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
Belgium uses a single identifier system through the **BCE/KBO (Crossroads Bank for Enterprises)**:
| Identifier | Format | Example | Notes |
| - | - | - | - |
| **Enterprise Number** | 10 digits: `0XXX.XXX.XXX` or `1XXX.XXX.XXX` | `0403.227.515` | Primary identifier for all entity types. Numbers issued since September 2023 start with `1`. The last two digits are check digits (97 minus the first eight digits modulo 97) |
| **Enterprise Number (no dots)** | 10 digits: `0XXXXXXXXX` or `1XXXXXXXXX` | `0403227515` | Also accepted, auto-normalized |
| **Enterprise Number (9 digits)** | 9 digits: `XXXXXXXXX` | `403227515` | A number starting with `0` sent without that zero, auto-padded |
| **VAT Number** | `BE` + 10 digits | `BE0403227515` | Accepted by search only |
**Automatic Normalization:** `/v2/company` accepts the enterprise number in any of the three enterprise-number formats above and normalizes it to the canonical dotted format (`0XXX.XXX.XXX` or `1XXX.XXX.XXX`). The number must pass the register's check digit. A `BE`-prefixed VAT number is rejected with a `400`: use search to resolve it to the enterprise number first.
### Identifiers in API Response
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| `ondernemingsnummer` | `0XXX.XXX.XXX` or `1XXX.XXX.XXX` | `0403.227.515` | Always present, canonical format with dots |
| `VAT` | 10 digits, no dots, no `BE` prefix | `0403227515` | The enterprise number without dots. Derived from it, so it is returned whether or not the entity is registered for VAT |
**Identifier naming:** The identifier key in the API response is `ondernemingsnummer` (Dutch: enterprise number, issued by the Crossroads Bank for Enterprises). This is the single, universal identifier for all Belgian entities (commercial companies, sole proprietors, non-profits, and public entities alike). The legacy `Numéro BCE` key was retired on 1 September 2026. In verification mode, the VAT number is also returned in `taxId` with its VIES check (see [VAT Verification](#vat-verification)).
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the enterprise number (`ondernemingsnummer`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Enterprise Number (dots) | `0XXX.XXX.XXX` or `1XXX.XXX.XXX` | `0403.227.515` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Enterprise Number (no dots) | `0XXXXXXXXX` or `1XXXXXXXXX` | `0403227515` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | `BE` + 10 digits | `BE0403227515` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Company Name | Text string | `"KBC Group"` | Fuzzy | Multiple results |
**Search uses both a pre-built index and live registry lookups.** Name searches query an index built from BCE Open Data for fast results. Identifier searches also perform live CBE Public Search lookups as a fallback to ensure the most up-to-date data.
**Multilingual names:** Belgian companies have names in up to four languages (French, Dutch, German, English). Search matches across all language variants. The API returns the English name when available, falling back to French, then Dutch, then German.
### Active companies only
With [`activeOnly=true`](/essentials/search#active-companies-only), every result is checked against the status the register reports, and entities it reports stopped are removed, also from streamed results. An entity that is legally created but not yet active is still returned.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Two sources** | Company profiles are assembled from BCE Open Data and CBE Public Search. Each datapoint is delivered as soon as it is ready. In verification mode, `company` includes share capital from CBE Public Search. |
| **Multilingual company names** | Belgium has four official languages. Legal names follow priority: English > French > Dutch > German. Other language variants appear as `commercialNames`. |
| **BCE Open Data has no legal reps** | The open dataset does not include legal representatives, other key persons, or capital. These come exclusively from CBE Public Search. |
| **Companies missing from BCE Open Data** | BCE Open Data only lists active entities. In verification mode, closed or only legally created companies are served from CBE Public Search. In prefill mode, `company` and `establishments` return not found for them. |
| **Shareholders are AI-extracted** | Belgium has no structured shareholder register. Shareholders are reconstructed by AI from annual accounts and Official Gazette publications (constitution, capital increases). Quality depends on document availability. Sole traders and non-profit forms get a not-applicable response. |
| **UBO data** | UBO data is read from the official Belgian UBO Register. Responses take longer than company data and the register may occasionally be unavailable. |
| **Company status uses juridical situation codes** | BCE distinguishes `AC` (Active) and `ST` (Stopped/Ceased) at the top level. The `juridicalSituation` code provides a richer standardised status in `statusDetails`, including `UNDER_INSOLVENCY_PROCEEDING` for ongoing bankruptcy or reorganisation proceedings and specific `closureReason` values (e.g. `BANKRUPTCY`, `VOLUNTARY_DISSOLUTION`, `MERGER`, `SPLIT`). See [Juridical Situation Codes](#juridical-situation-codes) for the full mapping. |
| **Registration date = Incorporation date** | Both `registrationDate` and `incorporationDate` return the same value, the BCE/KBO enterprise start date. In Belgium, registration and incorporation happen simultaneously upon filing with the BCE. The registry does not distinguish between the two concepts. |
| **VAT is verified via VIES** | In verification mode, the VAT number (which equals the enterprise number with a `BE` prefix) is verified against the EU VIES registry using a qualified check. The response includes a `consultationNumber` that serves as legal proof of verification. See [VAT Verification](#vat-verification) for details. |
| **Establishments are branch locations** | Establishments represent physical branch/office locations where the company operates, separate from the registered office. A company can have multiple establishments, each with its own ID, name, creation date, and address. Only active establishments are returned, except for companies missing from BCE Open Data (see [Establishments](#establishments)). |
| **NACE-BEL national codes** | Belgian registers use NACE-BEL (5-digit national extension). The API returns national codes under `NACE_BEL_2025`, `NACE_BEL_2008` or `NACE_BEL_2003`, per the edition stamped on each record, alongside standardized `NACE` and `ISIC`. Bare `NACE_BEL` contains only records whose edition could not be resolved. Where a NACE-BEL code has no single equivalent in NACE Rev.2.1, the shared parent class is returned rather than every candidate: see [One code in, one code out](/guides/standardization#one-code-in-one-code-out). |
| **Financial statements in 3 formats** | NBB CBSO financial statements filed electronically (XBRL/ZIP) are available in PDF, XBRL, and CSV. Paper-filed statements are not downloadable. |
| **eJustice publications** | Moniteur Belge publications cover the full publication history of a company. |
| **Establishment addresses as fallback** | For sole proprietors with no registered seat address, the system uses the sole establishment address as the legal address. |
## Mappings
### Company Status
Company status is determined **deterministically** from BCE Open Data and CBE Public Search. No AI inference is involved.
The BCE `status` field provides a binary `active` flag (`AC` / `ST`). The **`juridicalSituation` code** adds a richer layer, surfaced in the `status.statusDetails` object:
| Field | Description |
| - | - |
| `status.active` | `true` (BCE code `AC`) or `false` (BCE code `ST`) |
| `status.localName` | French label from the juridical situation code (e.g. `Ouverture de faillite`) |
| `status.statusDetails.status` | Standardised enum: `ACTIVE`, `UNDER_INSOLVENCY_PROCEEDING`, `CLOSED`, `UNKNOWN` |
| `status.statusDetails.closureReason` | Closure reason enum when applicable (see table below) |
Insolvency start dates and closure dates are not provided for Belgium.
### Juridical Situation Codes
The KBO/CBE assigns each enterprise a **juridical situation code** from the official A152 code list. The mapping to standardised values is:
| Code | French label | Standardised status |
| - | - | - |
| 000 | Situation normale | `ACTIVE` |
| 001 | Création juridique | `ACTIVE` |
| 002 | Prorogation | `ACTIVE` |
| 003 | Remplacement du numéro | `ACTIVE` |
| 090 | Nouveaux statuts | `ACTIVE` |
| 100 | Identification de l'entreprise | `ACTIVE` |
| Code | French label | Standardised status | Closure reason |
| - | - | - | - |
| 048 | Ouverture faillite (excusable) | `UNDER_INSOLVENCY_PROCEEDING` | `BANKRUPTCY` |
| 049 | Ouverture faillite (inexcusable) | `UNDER_INSOLVENCY_PROCEEDING` | `BANKRUPTCY` |
| 050 | Ouverture de faillite | `UNDER_INSOLVENCY_PROCEEDING` | `BANKRUPTCY` |
| 091 | Sursis (réorganisation) | `UNDER_INSOLVENCY_PROCEEDING` | - |
| 040 | Sursis provisoire | `UNDER_INSOLVENCY_PROCEEDING` | - |
| 041 | Sursis définitif | `UNDER_INSOLVENCY_PROCEEDING` | - |
| 030 | Concordat avant faillite | `UNDER_INSOLVENCY_PROCEEDING` | `BANKRUPTCY` |
| Code | French label | Standardised status | Closure reason |
| - | - | - | - |
| 010 | Dissolution de plein droit | `CLOSED` | `ADMINISTRATIVE_DISSOLUTION` |
| 012 | Dissolution anticipée | `CLOSED` | `VOLUNTARY_DISSOLUTION` |
| 013 | Dissolution judiciaire | `CLOSED` | `COURT_ORDER` |
| 014 | Clôture de liquidation | `CLOSED` | `LIQUIDATION` |
| 011 | Arrêt des activités en Belgique | `CLOSED` | `OTHER` |
| 015 | Arrêt d'une entreprise | `CLOSED` | `OTHER` |
| 016 | Cessation d'activité | `CLOSED` | `OTHER` |
| 017 | Transfert d'une entreprise | `CLOSED` | `OTHER` |
| 018 | Cessation de l'identification | `CLOSED` | `OTHER` |
| 019 | Cessation EDRL ou Non UE | `CLOSED` | `OTHER` |
| Code | French label | Standardised status | Closure reason |
| - | - | - | - |
| 020 | Réunion des parts | `CLOSED` | `MERGER` |
| 021 | Fusion par absorption | `CLOSED` | `MERGER` |
| 022 | Fusion par constitution | `CLOSED` | `MERGER` |
| 023 | Scission | `CLOSED` | `SPLIT` |
| 024 | Scission par absorption | `CLOSED` | `SPLIT` |
| 025 | Scission par constitution | `CLOSED` | `SPLIT` |
| 026 | Scission mixte | `CLOSED` | `SPLIT` |
| Code | French label | Standardised status | Closure reason |
| - | - | - | - |
| 051 | Clôture faillite (excusable) | `CLOSED` | `BANKRUPTCY` |
| 052 | Clôture faillite (inexcusable) | `CLOSED` | `BANKRUPTCY` |
| 053 | Clôture de faillite | `CLOSED` | `BANKRUPTCY` |
| 031 | Concordat après faillite | `CLOSED` | `BANKRUPTCY` |
| 042 | Révocation du sursis | `CLOSED` | `OTHER` |
| 043 | Fin du sursis | `CLOSED` | `OTHER` |
| 006 | Arrêtée pour remplacement | `CLOSED` | `OTHER` |
| Code | French label | Standardised status |
| - | - | - |
| 999 | Dossier annulé | `UNKNOWN` |
BCE Open Data and CBE Public Search both provide the juridical situation code, which is mapped to the same standardised values. Both paths converge on `status.statusDetails`.
### Registration & Incorporation Dates
Both `registrationDate` and `incorporationDate` return the **same value**, the BCE/KBO enterprise start date. In Belgium's BCE/KBO system, registration and legal creation happen simultaneously upon filing. The register maintains a single date per enterprise.
| Field | Value | Source |
| - | - | - |
| `registrationDate` | Enterprise start date | BCE/KBO enterprise start date |
| `incorporationDate` | Enterprise start date (same) | BCE/KBO enterprise start date |
Both dates come from BCE Open Data. Companies missing from BCE Open Data and served from CBE Public Search are returned without `registrationDate` and `incorporationDate`.
This is distinct from **establishment creation dates** (`establishments[].creationDate`), which represent when individual branch locations were opened, and these can differ from the enterprise start date.
### VAT Verification
**Verification mode only.** The Belgian VAT number equals the enterprise number prefixed with `BE` (e.g. `BE0403227515`). VAT verification is performed against the **EU VIES registry** (VAT Information Exchange System) using a qualified check that includes a requester VAT number.
| Field | Description |
| - | - |
| `taxId.type` | `EU_VAT` |
| `taxId.value` | Enterprise number without `BE` prefix (e.g. `0403227515`) |
| `taxId.country` | `BE` |
| `taxId.verification.status` | `VERIFIED`, `UNVERIFIED`, or `UNAVAILABLE` |
| `taxId.verification.verifiedAt` | ISO 8601 timestamp of the verification |
| `taxId.verification.verifiedName` | Company name as registered with VIES |
| `taxId.verification.verifiedAddress` | Address as registered with VIES |
| `taxId.verification.consultationNumber` | Legal proof of the VIES verification |
**Legal proof:** The `consultationNumber` returned by VIES serves as official proof that the VAT number was verified at the given time. This is the same identifier you would get from the EU VIES web portal.
### Establishments
Establishments represent **physical branch locations** where a company operates (offices, warehouses, retail locations), separate from the company's registered office. A company can have multiple establishments.
| Field | Company Registration | Establishment |
| - | - | - |
| **Identifier** | Enterprise number (`0XXX.XXX.XXX` or `1XXX.XXX.XXX`) | Establishment number (separate ID) |
| **Date** | `registrationDate` / `incorporationDate` | `creationDate` (when the branch was opened) |
| **Address** | `legalAddress` (registered office) | `address` (branch physical location) |
| **Count** | One per company | Multiple per company |
Each establishment includes:
| Field | Description |
| - | - |
| `id` | Unique establishment number |
| `name` | Branch name (from denominations, or fallback to company name + city) |
| `creationDate` | Date the branch was established |
| `active` | Whether the branch is currently active |
| `address` | Physical address of the branch |
| `activities` | Branch-level activity codes (`NACE_BEL` + `NACE` + `ISIC`), when the register records them. An establishment's activity can differ from the company-level activity. |
**Only active establishments are returned** for companies listed in BCE Open Data. For companies missing from BCE Open Data, in verification mode, the establishment list comes from CBE Public Search and may include closed establishments. If a sole proprietor has no registered office address but has exactly one establishment, that establishment's address is used as the `legalAddress`.
### Legal Forms
Belgium uses the **KBO/BCE juridical form codelist** maintained by the FPS Economy. The mapping to standardized forms and **ISO 20275 (ELF)** codes is **deterministic**: a formal lookup table maps each code to its French name, English translation, standardized category, and ISO 20275 code.
**Old codes resolve to their current form.** Codes for forms abolished by the 2019 Code of Companies and Associations (for example `015`, the former SPRL/BVBA) are returned under their current equivalent (`Société à responsabilité limitée`, `3W7E`). The tables below show the values the API returns for each code.
Natural-person enterprises have no juridical form code in the register. They are returned with this legal form:
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| - | Personne physique | Natural Person (Sole Proprietor) | Sole Proprietorship | 3N94 |
These are the modern legal forms introduced by the 2019 Code of Companies and Associations (CSA/WVV), which replaced most older forms:
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 610 | Société à responsabilité limitée | Private Limited Company (BV/SRL) | Limited Liability Company | 3W7E |
| 014 | Société anonyme | Public Limited Company | Corporation | R85P |
| 612 | Société en commandite | Limited Partnership (CommV/SComm) | Partnership | MQH3 |
| 706 | Société coopérative | Cooperative Company | Cooperative | 28FE |
| 027 | Société européenne (Societas Europaea) | European Company (Societas Europaea) | Corporation | 36KV |
Companies incorporated before the 2019 reform may still carry these codes. Each is returned under its current equivalent form:
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 015 | Société à responsabilité limitée | Private Limited Company (BV/SRL) | Limited Liability Company | 3W7E |
| 010 | Société à responsabilité limitée | Private Limited Company (BV/SRL) | Limited Liability Company | 3W7E |
| 011 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 012 | Société en commandite | Limited Partnership (CommV/SComm) | Partnership | MQH3 |
| 013 | Société anonyme | Public Limited Company | Corporation | R85P |
| 016 | Société coopérative | Cooperative Company | Cooperative | 28FE |
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 001 | Société coopérative européenne | European Cooperative Society | Cooperative | YBHM |
| 006 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 007 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 008 | Société coopérative | Cooperative Company | Cooperative | 28FE |
| 009 | Société coopérative | Cooperative Company | Cooperative | 28FE |
| 106 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 107 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 108 | Société coopérative de droit public | Public Law Cooperative Company | Cooperative | JAM3 |
| 109 | Société coopérative de droit public | Public Law Cooperative Company | Cooperative | JAM3 |
| 116 | Société coopérative de droit public | Public Law Cooperative Company | Cooperative | JAM3 |
| 716 | Société coopérative de droit public | Public Law Cooperative Company | Cooperative | JAM3 |
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 017 | Association sans but lucratif | Non-Profit Association | Nonprofit Organization | W3WH |
| 018 | Établissement d'utilité publique | Public Utility Institution | Nonprofit Organization | QZIS |
| 019 | Mutualité / Société Mutualiste | Mutual Society / Mutual Insurance Company | Nonprofit Organization | - |
| 020 | Association sans but lucratif | Non-Profit Association | Nonprofit Organization | W3WH |
| 021 | Association d'assurances mutuelles | Mutual Insurance Association | Nonprofit Organization | - |
| 022 | Organisation scientifique internationale de droit belge | International Scientific Organization under Belgian Law | Nonprofit Organization | - |
| 026 | Fondation privée | Private Foundation | Nonprofit Organization | Y1Q4 |
| 028 | Institution sans but lucratif | Non-Profit Institution | Nonprofit Organization | 8YLB |
| 029 | Fondation d'utilité publique | Public Utility Foundation | Nonprofit Organization | ZUHK |
| 070 | Association des copropriétaires | Co-Owners' Association | Nonprofit Organization | - |
| 117 | Association sans but lucratif de droit public | Public Law Non-Profit Association | Nonprofit Organization | EDMK |
| 123 | Corporation professionnelle / Ordre | Professional Corporation / Order | Nonprofit Organization | - |
| 125 | Association internationale sans but lucratif | International Non-Profit Association | Nonprofit Organization | V03J |
| 128 | Temporel des cultes / Établissement cultuel public | Religious Temporal / Public Religious Institution | Nonprofit Organization | - |
| 217 | Parti politique européen | European Political Party | Nonprofit Organization | - |
| 218 | Fondation politique européenne | European Political Foundation | Nonprofit Organization | - |
| 325 | Association internationale sans but lucratif de droit public | Public Law International Non-Profit Association | Nonprofit Organization | V03J |
| 724 | Syndicat | Trade Union | Nonprofit Organization | - |
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 206 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 208 | Société coopérative | Cooperative Company | Cooperative | 28FE |
| 211 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 212 | Société en commandite | Limited Partnership (CommV/SComm) | Partnership | MQH3 |
| 213 | Société anonyme | Public Limited Company | Corporation | R85P |
| 214 | Société anonyme | Public Limited Company | Corporation | R85P |
| 215 | Société à responsabilité limitée | Private Limited Company (BV/SRL) | Limited Liability Company | 3W7E |
| 225 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 506 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 508 | Société coopérative | Cooperative Company | Cooperative | 28FE |
| 510 | Société à responsabilité limitée | Private Limited Company (BV/SRL) | Limited Liability Company | 3W7E |
| 511 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 512 | Société en commandite | Limited Partnership (CommV/SComm) | Partnership | MQH3 |
| 513 | Société anonyme | Public Limited Company | Corporation | R85P |
| 514 | Société anonyme | Public Limited Company | Corporation | R85P |
| 515 | Société à responsabilité limitée | Private Limited Company (BV/SRL) | Limited Liability Company | 3W7E |
| 560 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 606 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 608 | Société coopérative | Cooperative Company | Cooperative | 28FE |
| 614 | Société anonyme | Public Limited Company | Corporation | R85P |
| 651 | Autre forme légale | Other Legal Form | Other | - |
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 110 | État, Province, Région, Communauté | State, Province, Region, Community | Government-Owned Entity | - |
| 114 | Société anonyme de droit public | Public Law Public Limited Company | Government-Owned Entity | TPTU |
| 124 | Établissement public | Public Institution | Government-Owned Entity | QZIS |
| 126 | Centre public d'action sociale | Public Social Welfare Centre | Government-Owned Entity | - |
| 127 | Monts-de-Piété | Pawnshop | Government-Owned Entity | - |
| 129 | Polder / wateringue | Polder / Wateringue | Government-Owned Entity | - |
| 155 | Zone de police locale | Local Police Zone | Government-Owned Entity | - |
| 160 | Organisme public étranger ou international | Foreign or International Public Body | Government-Owned Entity | - |
| 301 | Service public fédéral | Federal Public Service | Government-Owned Entity | - |
| 302 | Service public fédéral de programmation | Federal Public Programming Service | Government-Owned Entity | - |
| 303 | Autre service fédéral | Other Federal Service | Government-Owned Entity | - |
| 310 | Autorité de la Région flamande et de la Communauté flamande | Flemish Region and Community Authority | Government-Owned Entity | - |
| 320 | Autorité de la Région wallonne | Walloon Region Authority | Government-Owned Entity | - |
| 330 | Autorité de la Région de Bruxelles-Capitale | Brussels-Capital Region Authority | Government-Owned Entity | - |
| 340 | Autorité de la Communauté française | French Community Authority | Government-Owned Entity | - |
| 350 | Autorité de la Communauté germanophone | German-speaking Community Authority | Government-Owned Entity | - |
| 370 | Ministère des Affaires économiques | Ministry of Economic Affairs | Government-Owned Entity | - |
| 371 | Ministère des Affaires étrangères | Ministry of Foreign Affairs | Government-Owned Entity | - |
| 372 | Ministère de l'Agriculture | Ministry of Agriculture | Government-Owned Entity | - |
| 373 | Ministère des Classes moyennes | Ministry of Small and Medium Enterprises | Government-Owned Entity | - |
| 374 | Ministère des Communications | Ministry of Communications | Government-Owned Entity | - |
| 375 | Ministère de la Défense | Ministry of Defence | Government-Owned Entity | - |
| 376 | Ministère de l'Éducation nationale et de la Culture | Ministry of National Education and Culture | Government-Owned Entity | - |
| 377 | Ministère de l'Emploi et du Travail | Ministry of Employment and Labour | Government-Owned Entity | - |
| 378 | Ministère des Finances | Ministry of Finance | Government-Owned Entity | - |
| 379 | Ministère de l'Intérieur | Ministry of the Interior | Government-Owned Entity | - |
| 380 | Ministère de la Justice | Ministry of Justice | Government-Owned Entity | - |
| 381 | Ministère de la Prévoyance sociale | Ministry of Social Welfare | Government-Owned Entity | - |
| 382 | Ministère de la Santé publique et de la Famille | Ministry of Public Health and Family | Government-Owned Entity | - |
| 383 | Services du Premier Ministre | Prime Minister's Services | Government-Owned Entity | - |
| 384 | Ministère des Communications et de l'Infrastructure | Ministry of Communications and Infrastructure | Government-Owned Entity | - |
| 385 | Ministère de la Communauté flamande | Flemish Community Ministry | Government-Owned Entity | - |
| 386 | Ministère de la Communauté française | French Community Ministry | Government-Owned Entity | - |
| 387 | Ministère de la Région de Bruxelles-Capitale | Brussels-Capital Region Ministry | Government-Owned Entity | - |
| 388 | Ministère de la Région wallonne | Walloon Region Ministry | Government-Owned Entity | - |
| 389 | Ministère de la Communauté germanophone | German-speaking Community Ministry | Government-Owned Entity | - |
| 390 | Ministère de la Fonction publique | Ministry of Public Service | Government-Owned Entity | - |
| 391 | Ministère des Classes moyennes et de l'Agriculture | Ministry of SMEs and Agriculture | Government-Owned Entity | - |
| 392 | Ministère des Affaires sociales, de la Santé publique et de l'Environnement | Ministry of Social Affairs, Public Health and Environment | Government-Owned Entity | - |
| 400 | Autorité provinciale | Provincial Authority | Government-Owned Entity | - |
| 401 | Organisme immatriculé par l'ONSS-APL | Organization Registered with NSSO-LPA | Government-Owned Entity | - |
| 411 | Ville / commune | Town / Municipality | Government-Owned Entity | - |
| 412 | Centre public d'action sociale | Public Social Welfare Centre | Government-Owned Entity | - |
| 413 | Zone de police locale | Local Police Zone | Government-Owned Entity | - |
| 414 | Intercommunale | Intermunicipal Company | Government-Owned Entity | - |
| 415 | Association de projet | Project Association | Government-Owned Entity | - |
| 416 | Association prestataire de services (Région flamande) | Service Provider Association (Flemish Region) | Government-Owned Entity | 6DGX |
| 417 | Association chargée de mission (Région flamande) | Mission-Assigned Association (Flemish Region) | Government-Owned Entity | MGCM |
| 418 | Régie communale autonome | Autonomous Municipal Enterprise | Government-Owned Entity | - |
| 419 | Régie provinciale autonome | Autonomous Provincial Enterprise | Government-Owned Entity | - |
| 420 | Association de CPAS | PCSW Association | Government-Owned Entity | - |
| 421 | Prézone | Pre-Zone | Government-Owned Entity | - |
| 422 | Zone de secours | Emergency Zone | Government-Owned Entity | - |
| 616 | Société à responsabilité limitée de droit public | Public Law Private Limited Company | Government-Owned Entity | L05H |
| 617 | Société en commandite de droit public | Public Law Limited Partnership | Government-Owned Entity | - |
Codes 370 to 392 are historical ministry forms, replaced by Federal Public Services (301 to 303) following the 2002 Copernicus reform. They remain in the KBO to preserve historical records.
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 023 | Association étrangère privée avec établissement en Belgique | Foreign Private Association with Establishment in Belgium | Branch or Representative Office | 3LMA |
| 030 | Entité étrangère | Foreign Entity | Branch or Representative Office | 3LMA |
| 230 | Entité étrangère avec un bien immobilier en Belgique | Foreign Entity with Real Estate in Belgium | Branch or Representative Office | 3LMA |
| 235 | Entité étrangère sans établissement belge avec représentant responsable TVA | Foreign Entity without Belgian Establishment with VAT Representative | Branch or Representative Office | 3LMA |
| 453 | Société étrangère sans établissement belge cotée en bourse | Foreign Listed Company without Belgian Establishment | Branch or Representative Office | 3LMA |
| 454 | Entité étrangère avec un bien immobilier en Belgique (sans personnalité juridique) | Foreign Entity with Real Estate in Belgium (without Legal Personality) | Branch or Representative Office | 3LMA |
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 025 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 060 | Société en nom collectif | General Partnership | Partnership | UW1Y |
| 065 | Groupement européen d'intérêt économique | European Economic Interest Grouping | Partnership | 7SJP |
| 260 | Groupement d'intérêt économique sans siège avec établissement en Belgique | Economic Interest Grouping without Headquarters with Establishment in Belgium | Partnership | J5OU |
| 265 | Groupement européen d'intérêt économique sans siège avec établissement en Belgique | European Economic Interest Grouping without Headquarters with Establishment in Belgium | Partnership | 7SJP |
| 701 | Société commerciale irrégulière | Irregular Commercial Company | Other | CFH5 |
| 702 | Société de droit commun | Civil Law Partnership | Partnership | KM6O |
| 703 | Société momentanée | Temporary Partnership | Partnership | CFH5 |
| 704 | Société interne | Internal Partnership | Partnership | CFH5 |
| 721 | Société ou association sans personnalité juridique | Company or Association without Legal Personality | Other | CFH5 |
| 722 | Association momentanée | Temporary Association | Other | CFH5 |
| 723 | Association de frais | Cost-Sharing Association | Other | CFH5 |
| Code | French Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 002 | Organisme de financement de pensions | Pension Financing Institution | Other | - |
| 003 | Unité TVA | VAT Unit | Other | - |
| 040 | Société congolaise (loi de 1927) | Congolese Company (1927 Law) | Other | - |
| 051 | Autre forme de droit privé avec personnalité juridique | Other Private Law Form with Legal Personality | Other | - |
| 121 | Association d'assurances mutuelles de droit public | Public Law Mutual Insurance Association | Government-Owned Entity | - |
| 151 | Autre forme légale | Other Legal Form | Other | - |
| 200 | Société en formation | Company in Formation | Other | - |
| 393 | Divers | Miscellaneous | Other | - |
| 451 | Organismes immatriculés pour l'O.N.P. | Organizations Registered with NPO | Government-Owned Entity | - |
| 452 | Organisme immatriculé pour l'Administration des Pensions | Organization Registered with Pension Administration | Government-Owned Entity | - |
| 790 | Divers sans personnalité juridique | Miscellaneous without Legal Personality | Other | CFH5 |
| 999 | Forme légale inconnue (ONSS) | Unknown Legal Form (NSSO) | Other | - |
### Legal Representatives
The same `entityId` can appear in several entries when a person holds multiple roles. For example, `Administrateur` (Director) and `Membre du comité de direction` (Member of the management committee) are separate roles, but both have `role.standardized: "Director"`. Group by `entityId` to identify the person while preserving each role and its appointment dates. See [Person identities and role entries](/essentials/retrieve_company#person-identities-and-role-entries).
Legal representatives come from **CBE Public Search**. Role classification is **deterministic**: a formal lookup table maps each official CBE function code to its French name, English translation, and whether it constitutes a legal representative role.
Both **individuals and companies** can hold legal representative roles. When a company is a legal representative, it is returned with its enterprise number and legal name. Its **permanent representative** (the natural person acting on behalf of the company) appears as a separate legal representative entry with the role `Représentant permanent`.
| Code | French Role | English Translation | Standardized |
| - | - | - | - |
| 00001 | Fondateur d'une entité enregistrée personne physique | Founder registered entity natural person | Owner |
| 00002 | Mandataire général | General agent | Authorized Signatory |
| 00005 | Représentant permanent suppléant | Deputy permanent representative | Director |
| 10002 | Administrateur | Director | Director |
| 10003 | Représentant permanent | Permanent representative | Director |
| 10004 | Personne déléguée à la gestion journalière | Person in charge of daily management | Manager |
| 10005 | Membre du comité de direction | Member of the management committee | Director |
| 10006 | Gérant | Manager | Manager |
| 10007 | Administrateur délégué | Managing Director | Managing Director |
| 10008 | Syndic | Property manager | Manager |
| 10010 | Président | Chairman | President |
| 10013 | Directeur général | Managing Director | Managing Director |
| 10014 | Directeur général adjoint | Deputy Managing Director | Other |
| 10015 | Vice-président | Vice President | Vice President |
| 10017 | Membre du conseil de direction | Member of the management committee | Director |
| 10018 | Représentant personne morale | Legal person representative | Director |
| 10022 | Représentant (non administrateur) | Representative (non-administrator) | Authorized Signatory |
| 10023 | Administrateur général | General administrator | Other |
| 10030 | Liquidateur | Liquidator | Liquidator |
| 10031 | Représentant légal | Legal representative | Authorized Signatory |
| 10032 | Représentant (succursale) | Representative (branch) | Authorized Signatory |
| 10033 | Secrétaire (Région flamande) | Secretary (Flemish Region) | Secretary |
| 10041 | Bourgmestre | Mayor | Other |
| 10042 | Secrétaire / Directeur général | Secretary / Managing director | Other |
| 90000 | Séquestre (désignation par tribunaux) | Receiver (designated by court) | Other |
| 90001 | Curateur (désignation par tribunaux) | Curator (designated by court) | Other |
| 90002 | Administrateur provisoire (désignation par tribunaux) | Provisional administrator (designated by court) | Other |
| 90005 | Mandataire de justice | Judicial trustee | Other |
The complete function catalogue includes 42 codes, including historical functions whose code-table end dates are marked as discontinued. Office categories identify the appointment; they do not establish unrestricted individual signing authority.
#### Person Enrichment
Base person data (names, roles, start dates) comes from the register. When `agenticEnrichment: true` is passed in the request, the system attempts to enrich the details of individuals in `legalRepresentatives`, `otherKeyPersons`, `shareholders` and `ultimateBeneficialOwners` from **eJustice publications** (Moniteur Belge).
**This is best effort.** Enrichment depends on publication availability and content. Not all fields are guaranteed for every person. Older founding acts typically contain birth date, birth place and nationality; appointment notices typically contain residence addresses. Recent founding acts print the birth details as "(…)", so a newly incorporated company rarely gets a birth date from its publications. Recently appointed representatives or companies with sparse publication history may have partial or no enrichment. Sole traders and co-ownership associations publish nothing in the Moniteur Belge and get no enrichment from it.
**What can be enriched:**
* Birth date
* Birth place (`birthAddress.city`)
* Nationality
* Residence address (geocoded)
* Signing powers of legal representatives (`signingPowers`, `signingAuthority`), for individuals and companies alike
**How it works:** founding acts and appointment notices are OCR'd and parsed with AI to extract person details, then matched to the corresponding people.
**Identity from the UBO register:** when a person is also a beneficial owner, the birth date, nationality and residence address the UBO register holds for them are copied onto their legal representative, other key person and shareholder entries. These register values come first; publications only fill what they leave empty. They come from the `ultimateBeneficialOwners` of the same request, or, when the request asks for no UBOs, from the latest UBO register read your account made for the company (birth date and nationality only, since an address may have changed). Enrichment never runs a UBO lookup of its own, uses no other customer's data, and copies nothing when UBO access is turned off for the workspace.
**Signing powers:** the articles of association say how the company is represented towards third parties: every director alone, two directors jointly, the managing director alone within daily management, and so on. The notarial extracts published in the Moniteur Belge restate that clause. Enrichment reads the most recent publication that restates it, not the founding act, since companies change the rule over time. It then keeps, for each legal representative, the sentences that apply to their role:
* `signingPowers.localText` is the publication's own wording, verbatim, and `signingPowers.englishTranslation` its translation.
* `signingAuthority` is an AI reading of that text: a `verdict` (`sole`, `sole_within_limits`, `joint` or `unclear`), one rule per scope with its mode and any required co-signers, and the verbatim excerpt each rule was read from.
* `representationMode` is also set when that reading is confident and one mode covers the representative's general representation of the company: `sole` when they can bind the company alone for all acts, `joint` (with `minimumSignatories`) when every way they can bind it needs a co-signer. It is absent when the authority is conditional, for example a managing director who may sign alone only within daily management. Read `signingAuthority` for those. For Belgium this mode is read from the published articles, not stated by the register as a field.
A representative whose role the clause does not address gets no signing powers rather than a guess. A signing rule is never derived from the role alone. Signing powers are left out when the recent publications do not restate the clause, which is common for companies with a long filing history.
**Billing:** enrichment is billed separately, only when at least one field was enriched from the publications. Values copied from the UBO register alone are not billed. See the [pricing page](https://topograph.co/pricing/be).
While enrichment is running, affected datapoints show the `enriching` status. Enriched fields are attributed to `ejustice` in `dataSources`. Values copied from the UBO register are attributed field by field, under keys such as `individual.birthDate` and `individual.nationality`, to `ubo_register`: `live_from_registry` when they come from the same request, `cached_from_registry` when they come from an earlier read.
### Other Key Persons
Other key persons include supervisory, audit, advisory and membership offices whose title does not establish general authority to bind the company. A non-administrator representative can hold a delegated representation mandate and appears among legal representatives; its scope still depends on the appointment and applicable law.
| Code | French Role | English Translation | Standardized |
| - | - | - | - |
| 00003 | Associé ou membre | Associate or member | Other |
| 00004 | Représentant de l'unité TVA | VAT-grouping representative | Other |
| 10001 | Fondateur d'une entité sans personnalité juridique | Founder of a body without legal personality | Other |
| 10011 | Secrétaire | Secretary | Secretary |
| 10012 | Trésorier | Treasurer | Other |
| 10016 | Membre du conseil de surveillance | Member of the supervisory board | Supervisory Board Member |
| 10020 | Commissaire | Statutory Auditor | Auditor |
| 10021 | Représentant permanent du commissaire | Permanent representative of the auditor | Auditor |
| 10045 | Membre du collège de zone | Member of area association | Board Member |
| 10500 | Personne de contact EDRL | EDRL contact person | Other |
| 11000 | Notaire suppléant | Supply solicitor | Other |
| 12000 | Huissier de justice faisant fonction | Acting bailiff | Other |
| 90003 | Commissaire au sursis (désignation par tribunaux) | Deferment auditor (designated by court) | Auditor |
| 90004 | Conseil judiciaire (prodigues) | Judicial board (prodigals) | Other |
### Shareholders
Belgium has **no structured shareholder register**. Shareholder data is **reconstructed by AI from company documents**: annual accounts filed with NBB CBSO and Moniteur Belge publications (constitution, capital increases).
Sole traders and non-profit forms (ASBL/VZW, foundations and similar) have no share capital. For these, `shareholders` returns a not-applicable response.
**AI-extracted data:** Shareholders are inferred by AI from PDF documents. The quality and completeness depends on document availability and readability. This is not structured registry data.
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | AI-extracted from company documents |
| `type` | Individual or Company | AI-inferred from document context |
### Activity Code Mapping
Belgium uses the **NACE-BEL** classification, the Belgian extension of the European NACE standard. BCE Open Data provides three versions of NACE codes (2003, 2008, 2025); the system automatically selects the most recent version available.
```
NACE-BEL (Belgian) --> NACE Rev. 2.1 (European) --> ISIC Rev. 5 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NACE\_BEL** | BCE Open Data / CBE | `69.201` | No (official) |
| **NACE** | Derived from NACE-BEL (truncated to class level) | `69.20` | No (formal mapping) |
| **ISIC** | Derived from NACE (formal mapping) | `6920` | No (formal mapping) |
NACE-BEL codes are 5-digit national extensions (e.g., `69.201`). Standard NACE codes are class-level codes (e.g., `69.20`), derived by truncating the 5th digit. Multiple NACE-BEL codes can map to the same NACE class and are de-duplicated. If a code is already at class level, it appears in `NACE` only, not in `NACE_BEL`.
**You get one `NACE` and one `ISIC` code per declared NACE-BEL code.** A company with three declared
activities returns three of each. Where a Belgian code has no single equivalent in NACE Rev.2.1, the
shared parent class is returned rather than every candidate — see
[One code in, one code out](/guides/standardization#one-code-in-one-code-out).
NACE-BEL 2025 codes use their NACE Rev. 2.1 class directly; 2008 codes use the formal Rev. 2 transition. Legacy 2003 and unstamped codes retain their national wording without a fabricated standard conversion. Deterministic mappings are never AI-inferred. National descriptions use the source revision; standard descriptions use NACE Rev. 2.1. The response uses canonical `NACE_BEL_2025`, `NACE_BEL_2008` or `NACE_BEL_2003` keys for stamped national records and `NACE` and `ISIC` for standardized codes. Bare `NACE_BEL` contains only unstamped records. See the [standardization guide](/guides/standardization).
### Activity Code Versions
| NACE Version | Priority | Notes |
| - | - | - |
| **NACE 2025** | Highest | Newest version, preferred when available |
| **NACE 2008** | Medium | Most common in existing data |
| **NACE 2003** | Lowest | Legacy national code retained; no formal standard conversion available |
Within each version, activities are ordered by classification: **MAIN** (primary activity) first, then **SECO** (secondary), then **ANCI** (ancillary). The MAIN-classified activity (the register's "activité principale" / "hoofdactiviteit") carries `isMainActivity: true` on the `NACE_BEL` code, and the derived `NACE` and `ISIC` codes inherit the flag. At most one code per classification is flagged; activities without the flag are not necessarily secondary, the register may simply not classify them.
## Data Availability
### Data Availability Matrix
| Data Type | BCE Open Data | CBE Public Search | Notes |
| - | - | - | - |
| Company name (multilingual) | Yes | Yes | BCE: EN > FR > NL > DE priority. CBE: French legal name |
| Company status | Yes | Yes | Binary: Active / Ceased |
| Legal form | Yes | Yes | Formal mapper with ISO 20275 codes |
| Registration date | Yes | No | Start date of the enterprise |
| NACE-BEL / NACE activity codes | Yes | Yes | NACE-BEL (5-digit national) + standard NACE + ISIC with descriptions, one standardized code per declared activity |
| Registered address | Yes | Yes | Available from both sources |
| Contact info (phone, website) | Yes | No | Only from BCE Open Data |
| Establishments | Yes | Yes | BCE: active only. CBE: only for companies missing from BCE Open Data (verification mode), may include closed establishments |
| Legal representatives | No | Yes | Mapped from the register's official function codes |
| Other key persons | No | Yes | Auditors, supervisory board, etc. |
| Share capital | No | Yes | Amount and currency (verification mode) |
| Shareholders | No | No | AI-reconstructed from annual accounts and Official Gazette publications |
| Subsidiaries | No | No | AI-extracted from the participating-interests section of the annual accounts (separate source) |
| Ultimate Beneficial Owners | No | No | From Belgian UBO Registry (separate source) |
### Subsidiaries
`subsidiaries` is available for Belgium. It returns the equity participations the queried company holds in other entities, AI-extracted from section 6.5.1 "Participating interests and other rights in other companies" of the latest annual accounts filed at the National Bank of Belgium Central Balance Sheet Office. Verify the values against the filing before relying on them for compliance.
Availability follows the filing: a company that has filed no annual accounts returns no subsidiaries, and small or micro-schema filers frequently omit the participating-interests section entirely. `subsidiaries` is a separate data block from `company`, and it is available in verification mode only. See the [Subsidiaries](/essentials/subsidiaries-extraction) guide for the response shape.
### Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | All companies | From the BCE/KBO register |
| **UBO Extract** | `ultimateBeneficialOwnersCertificate` | PDF | All companies | From Belgian UBO Registry |
| **Financial Statements** | `financialStatements[]` | PDF, XBRL, CSV | When filed | From NBB CBSO |
| **Official Publications** | `officialPublications[]` / `otherDocuments[]` | PDF | When published | From eJustice / Moniteur Belge |
| **Articles of Association** | `articlesOfAssociation[]` | PDF | Notarial BV/CV/NV incorporated or amended since 1 May 2019 | Full coordinated statutes from the Belgian notaries' database |
**Articles of Association vs Official Publications.** `articlesOfAssociation[]` is the full **coordinated** text of a company's statutes, held in the Belgian notaries' database and covering legal persons incorporated or amended before a Belgian notary since 1 May 2019 (BV/SRL, CV/SC, NV/SA). `officialPublications[]` holds the Moniteur Belge publications, which are short deed *extracts* — including statute-change extracts — and never the complete statutes. Entities whose statutes were never amended after 1 May 2019, and forms with no notarial deed (CommV/SComm, VOF/SNC, maatschap), have no coordinated version and must be ordered from the enterprise court registry.
**Financial statement formats:** Statements filed electronically (XBRL/ZIP submission) are available in PDF, XBRL, and CSV formats. Statements originally filed on paper or microfilm are **not downloadable**.
**Publication types from eJustice include:** Articles of Association, Appointments, Resignations, Capital changes, Shares, Company Name changes, Registered Office changes, Corporate Purpose changes, General Assembly decisions, Legal Form changes, Restructuring, Formation, Dissolution, Annual Accounts, and more. Each publication is categorized by type and available as a PDF download.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "BE", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "0403.227.515",
"countryCode": "BE",
"identifiers": { "ondernemingsnummer": "0403.227.515" },
"legalName": "Banque Exemple",
"commercialNames": ["Voorbeeld Bank", "Beispielbank"],
"registrationDate": "1935-12-19",
"incorporationDate": "1935-12-19",
"status": { "localName": "Situation normale", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Société anonyme", "englishTranslation": "Public Limited Company", "standardized": "Corporation", "iso20275Code": "R85P" },
"capital": { "amount": 24500000, "currency": "EUR", "formatted": "24.500.000 EUR" },
"activities": {
"NACE_BEL": [{ "code": "64.192", "description": "Other monetary intermediation", "isAIInferred": false }],
"NACE": [{ "code": "64.19", "description": "Other monetary intermediation", "isAIInferred": false }],
"ISIC": [{ "code": "6419", "description": "Other monetary intermediation", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Avenue du Port 2", "postalCode": "1080", "city": "Molenbeek-Saint-Jean", "countryCode": "BE" },
"phones": ["+32 2 555 01 01"],
"website": "https://www.exemple-banque.be"
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Administrateur délégué", "englishTranslation": "Managing Director", "standardized": "Chief Executive Officer" },
"individual": { "name": { "fullName": "Jan De Smedt", "firstName": "Jan", "lastName": "De Smedt" } },
"startDate": "2020-06-15"
},
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Administrateur", "englishTranslation": "Director", "standardized": "Director" },
"company": { "id": "0874.162.515", "legalName": "Conseil SA", "countryCode": "BE" },
"startDate": "2021-01-10"
}
],
"otherKeyPersons": [
{
"entityId": "company_002",
"type": "company",
"role": { "localName": "Commissaire", "englishTranslation": "Statutory Auditor", "standardized": "Auditor" },
"company": { "id": "0446.334.711", "legalName": "Audit Partners SCRL", "countryCode": "BE" }
}
],
"establishments": [
{ "id": "2012345678", "name": "Banque Exemple - Bruxelles", "active": true, "creationDate": "1935-12-19", "address": { "addressLine1": "Avenue du Port 2", "postalCode": "1080", "city": "Molenbeek-Saint-Jean", "countryCode": "BE" } },
{ "id": "2087654321", "name": "Banque Exemple - Antwerpen", "active": true, "creationDate": "1990-03-01", "address": { "addressLine1": "Meir 48", "postalCode": "2000", "city": "Antwerpen", "countryCode": "BE" } }
]
}
```
```json theme={null}
{
"company": {
"id": "0414.138.629",
"countryCode": "BE",
"identifiers": { "ondernemingsnummer": "0414.138.629" },
"legalName": "Ancien Restaurant SPRL",
"status": { "localName": "Clôture de liquidation", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "LIQUIDATION" } },
"legalForm": { "localName": "Société à responsabilité limitée", "englishTranslation": "Private Limited Company (BV/SRL)", "standardized": "Limited Liability Company", "iso20275Code": "3W7E" },
"activities": {
"NACE_BEL": [{ "code": "56.101", "description": "Restaurants and mobile food service activities", "isAIInferred": false }],
"NACE": [{ "code": "56.10", "description": "Restaurants and mobile food service activities", "isAIInferred": false }],
"ISIC": [{ "code": "5610", "description": "Restaurants and mobile food service activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Rue de la Montagne 12", "postalCode": "1000", "city": "Bruxelles", "countryCode": "BE" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Gérant", "englishTranslation": "Manager", "standardized": "Manager" },
"individual": { "name": { "fullName": "Pierre Vandenberghe", "firstName": "Pierre", "lastName": "Vandenberghe" } }
}
]
}
```
**Note:** Closed companies have `active: false`, and `status.localName` carries the juridical situation label. Closed companies are not in BCE Open Data, so in verification mode all data comes from CBE Public Search, without `registrationDate` and `incorporationDate`. The pre-2019 legal form code (`015`, SPRL) is returned as its current equivalent. In prefill mode, `company` returns not found for these companies.
```json theme={null}
{
"company": {
"id": "0715.648.281",
"countryCode": "BE",
"identifiers": { "ondernemingsnummer": "0715.648.281" },
"legalName": "Dupont, Marc",
"registrationDate": "2018-04-01",
"incorporationDate": "2018-04-01",
"status": { "localName": "Situation normale", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Personne physique", "englishTranslation": "Natural Person (Sole Proprietor)", "standardized": "Sole Proprietorship", "iso20275Code": "3N94" },
"activities": {
"NACE_BEL": [{ "code": "90.021", "isAIInferred": false }],
"NACE": [{ "code": "90.02", "description": "Support activities to performing arts", "isAIInferred": false }],
"ISIC": [{ "code": "9002", "description": "Support activities to performing arts", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Steenweg 45", "postalCode": "3000", "city": "Leuven", "countryCode": "BE" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Fondateur d'une entité enregistrée personne physique", "englishTranslation": "Founder registered entity natural person", "standardized": "Owner" },
"individual": { "name": { "fullName": "Dupont, Marc", "firstName": "Marc", "lastName": "Dupont" } }
}
],
"establishments": [
{ "id": "2282534813", "name": "Dupont, Marc", "active": true, "creationDate": "2018-04-01", "address": { "addressLine1": "Steenweg 45", "postalCode": "3000", "city": "Leuven", "countryCode": "BE" } }
]
}
```
**Note:** Sole proprietors have no legal form code in the register, so the natural-person legal form (`3N94`) is returned instead. The `legalName` is the individual's name. The founder role (`00001`) is mapped as the legal representative.
```json theme={null}
{
"company": {
"id": "0456.123.789",
"countryCode": "BE",
"identifiers": { "ondernemingsnummer": "0456.123.789" },
"legalName": "Association Sportive de Bruxelles",
"commercialNames": ["Brusselse Sportvereniging"],
"registrationDate": "2010-09-15",
"incorporationDate": "2010-09-15",
"status": { "localName": "Situation normale", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Association sans but lucratif", "englishTranslation": "Non-Profit Association", "standardized": "Nonprofit Organization", "iso20275Code": "W3WH" },
"activities": {
"NACE_BEL": [{ "code": "93.129", "isAIInferred": false }],
"NACE": [{ "code": "93.12", "description": "Activities of sports clubs", "isAIInferred": false }],
"ISIC": [{ "code": "9312", "description": "Activities of sports clubs", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Rue du Sport 8", "postalCode": "1050", "city": "Ixelles", "countryCode": "BE" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Président", "englishTranslation": "Chairman", "standardized": "President" },
"individual": { "name": { "fullName": "Sophie Peeters", "firstName": "Sophie", "lastName": "Peeters" } }
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Administrateur", "englishTranslation": "Director", "standardized": "Director" },
"individual": { "name": { "fullName": "Luc Van Damme", "firstName": "Luc", "lastName": "Van Damme" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Secrétaire", "englishTranslation": "Secretary", "standardized": "Secretary" },
"individual": { "name": { "fullName": "Emma Claes", "firstName": "Emma", "lastName": "Claes" } }
},
{
"entityId": "person_004",
"type": "individual",
"role": { "localName": "Trésorier", "englishTranslation": "Treasurer", "standardized": "Other" },
"individual": { "name": { "fullName": "Thomas Willems", "firstName": "Thomas", "lastName": "Willems" } }
}
]
}
```
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "be-ubo-12345",
"name": { "fullName": "Jan De Smedt", "firstName": "Jan", "lastName": "De Smedt" },
"birthDate": { "day": 15, "month": 3, "year": 1975 },
"nationality": "BE",
"residenceAddress": { "addressLine1": "Koningsstraat 100", "postalCode": "1000", "city": "Brussel", "countryCode": "BE" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"details": [
{ "type": "shares", "percentageValue": 60, "nature": null },
{ "type": "voting-rights", "percentageValue": 60, "nature": null }
]
}
},
{
"entityId": "be-ubo-67890",
"name": { "fullName": "Marie Janssens", "firstName": "Marie", "lastName": "Janssens" },
"birthDate": { "day": 22, "month": 8, "year": 1982 },
"nationality": "BE",
"residenceAddress": { "addressLine1": "Avenue Louise 200", "postalCode": "1050", "city": "Ixelles", "countryCode": "BE" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"details": [
{ "type": "shares", "percentageValue": 40, "nature": null },
{ "type": "voting-rights", "percentageValue": 40, "nature": null }
]
}
}
]
}
```
**Note:** UBO data comes from the Belgian UBO Registry. The `nature` field is always `null` because the Belgian registry does not specify whether ownership is direct or indirect. `null` means the register stated the control but not its nature; an absent `nature` means the source said nothing about nature at all. Birth dates are in DD/MM/YYYY format from the API, parsed into structured components.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Source | Notes |
| - | - | - | - |
| `tradeRegisterExtract` | Register extract as PDF | CBE Public Search | Always available |
| `ultimateBeneficialOwnersCertificate` | UBO extract PDF | Belgian UBO Registry | Always listed |
| `financialStatements[]` | Annual accounts | NBB CBSO | Multiple years, up to 3 formats per filing |
| `articlesOfAssociation[]` | Coordinated statutes (statuts coordonnés) | Fednot STAPOR | Notarial BV/CV/NV amended since 1 May 2019 |
| `officialPublications[]` | Moniteur Belge deed extracts | eJustice | When published — 2-page extracts, not the full statutes |
| `otherDocuments[]` | Other publications | eJustice | Appointments, capital changes, etc. |
# Bosnia and Herzegovina
Source: https://docs.topograph.co/essentials/bosnia-herzegovina
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Bosnia and Herzegovina reference is on the [Bosnia and Herzegovina country page](https://www.topograph.co/countries/ba).
## Start here
This guide contains public integration notes for Bosnia and Herzegovina. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction is in beta. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Company data comes from three official registers, one per jurisdiction. Bosnia and Herzegovina has no single national company register: registration is devolved to the two entities and the Brčko District, and each runs its own.
* **Registar poslovnih subjekata BiH (BiH Business Entity Register)**: operated by the Federal Ministry of Justice and the Judiciary Commission of District Brčko BiH, accessible at [bizreg.pravosudje.ba](https://bizreg.pravosudje.ba). It serves Federation BiH companies.
* **Brčko District Business Register (e-Registar)**: operated by the Judiciary Commission of the Brčko District, accessible at [bizreg.osbd.ba](https://bizreg.osbd.ba). It serves Brčko District companies, including every registration made since 2021, and backs company search for the district.
* **Republika Srpska Business Register**: operated under the Government of Republika Srpska, accessible at [bizreg.esrpska.com](http://bizreg.esrpska.com). It serves Republika Srpska companies.
A company lookup with a register-qualified id (`RS 3-35-00 4402503100008`, `FBiH 3-70`) goes to that register only. A lookup with a bare number asks the Brčko District register first and uses the BiH Business Entity Register when Brčko District has no record of it.
**Republika Srpska covers companies only, for now.** Sole traders (samostalni preduzetnici) and associations are held in separate parts of the Republika Srpska register that are not yet integrated, so search does not return them.
A bare number is never resolved to a Republika Srpska company by `/v2/company`. Search first and pass back the qualified `id` (`RS 3-35-00 4402503100008`).
### What the register provides per entity
| Register page | Content |
| - | - |
| Basic data | MBS, legal name, abbreviation, address, legal form, status, JIB (tax number), customs number |
| Founders (page 21) | Individual and corporate founders with capital contributions and share count |
| Board and management (page 22) | Federation management and governance persons appear on one register page. The position and authorisation fields are free text. The published role catalogue covers known and observed titles rather than a complete official codelist. |
Representation follows the actual register and entity context. Federation company management represents the company under Companies Act articles 23–24, within registered powers. Brčko's authorised-person roster and Republika Srpska's authorised-person and procura rosters establish representation independently of title. Supervisory, audit, assembly and ownership appointments do not themselves establish a separate representation mandate.
| Local position | Classification | Standardized role |
| - | - | - |
| Direktor / Direktorica | Legal representative | Director |
| Generalni direktor / generalni direktor-član uprave | Legal representative | Managing Director |
| Izvršni direktor / V.D. Izvršni direktor | Legal representative | Executive Director |
| Prokurist / Prokurista | Legal representative | Authorized Signatory |
| Predsjednik Uprave | Legal representative in registered management or authorised roster; otherwise other key person | Chairman of the Board |
| Član uprave | Legal representative in registered management or authorised roster; otherwise other key person | Board Member |
| Predsjednik / Član nadzornog odbora | Other key person unless a distinct representation grant is recorded | Supervisory Board Member |
| Osnivač — actual sole trader | Legal representative | Owner |
| Osnivač — ownership alone in a company | Other key person | Other |
| Likvidator | Legal representative | Liquidator |
| Stečajni upravnik | Legal representative | Receiver |
| Revizor | Other key person unless a distinct representation grant is recorded | Auditor |
| Sekretar | Other key person unless a distinct representation grant is recorded | Secretary |
| Knjigovođa / Računovođa / assembly office | Other key person unless a distinct representation grant is recorded | Other |
| Unknown title — authorised roster or positive representation grant | Legal representative | Authorized Signatory |
| Unknown title — no recorded representation evidence | Other key person | Other |
A separate representation grant on an oversight holder is returned as Authorized Signatory, preserving the filed title and powers. A sole trader's owner remains available under `legalRepresentatives`; the shareholders datapoint is not applicable to that entity type.
#### Signatory Modes
The register's actual authorisation text is preserved in `signingPowers.localText`. Sole or joint mode is returned only when that text states how signatures operate.
| Authorisation text | Published mode |
| - | - |
| `samostalno` / `pojedinačno` | Sole |
| `zajedno sa` / additional or co-signature wording | Joint, with the source condition preserved |
| `bez ograničenja` without explicit signing wording | Unspecified; source scope preserved |
| Monetary limit or statute reference | Unspecified; source restriction preserved |
| Missing authorisation text | Unspecified |
### Shareholders
Founders of **d.o.o. companies** are returned as shareholders, with individual and corporate founders both supported. Capital contribution amounts in BAM (Bosnian Convertible Mark) are included when the register provides them.
For **d.d. companies**, individual shareholders are not listed in the public register. Only a reference to the separately maintained share register is available. The `shareholders` datapoint is therefore not populated for d.d. entities.
### Activity Code Mapping
Bosnia and Herzegovina uses **KD BiH 2010** (Klasifikacija djelatnosti BiH 2010), the official BiH harmonisation of NACE Rev. 2, established by the Official Gazette of BiH no. 47/10 and in force since January 1, 2011. Codes use the same `XX.YY` four-digit format as NACE Rev. 2.
```
KD BiH 2010 (register code, NACE Rev. 2) → NACE Rev. 2.1 → ISIC Rev. 5
```
| Key | Classification | Example | AI Inferred? |
| - | - | - | - |
| `KD_BIH_2010` | KD BiH 2010, as declared in the register | `62.01` | No (official code from register) |
| `NACE` | NACE Rev. 2.1, converted from the register's Rev. 2 code | `62.10` | No (formal correspondence) |
| `ISIC` | ISIC Rev. 5, derived from NACE Rev. 2.1 | `621` | No (formal correspondence) |
The register's own code is returned under `KD_BIH_2010`. Because it is a NACE Rev. 2 code, it is converted to NACE Rev. 2.1 before it is published under `NACE`, so the digits under `KD_BIH_2010` and `NACE` can differ. See [Activity Codes](/essentials/activity-codes) for how the conversion works. Not all companies have registered activities; banks and some large joint-stock companies have none.
## Data Availability
### Data Availability Matrix
| Data Type | BiH Business Register | Notes |
| - | - | - |
| Company Profile | ✅ | Legal name, MBS, JIB, address, legal form, status, capital |
| Legal Representatives | ✅ | Directors, executive directors, procurists |
| Other Key Persons | ✅ | Governance-only, supervisory, audit and administrative appointments |
| Shareholders | ⚠️ Conditional | d.o.o. founders only, not available for d.d. (see Quirks) |
| Ultimate Beneficial Owners | ❌ | No public UBO register in BiH |
| Establishments / Branches | ✅ | Branch offices when registered (page 31) |
| Activity Codes | ⚠️ Conditional | KD BiH 2010 / NACE + ISIC, absent for banks and some large d.d. |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available
### Documents
| Document | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | ⚠️ Listed for every company | Printed PDF of the company detail page, all 8 sections in one document |
The Trade Register Extract is a printed PDF of the BiH Business Entity Register company detail page, covering basic data, founders, board and management, capital, activities, branch offices, foreign trade authorisation, and notes. It is bundled with the company data.
The extract comes from the BiH Business Entity Register only. That register holds no Brčko District registration made after 2021, so ordering the extract for one of those companies returns a not-found error, even though their company data is available.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": " ", "countryCode": "BA", "dataPoints": ["company", "legalRepresentatives"] }`, e.g. `"Brčko 1-369"`, or `"RS 3-35-00 4402503100008"` for Republika Srpska. A bare `` is accepted too, but see [the note above](#the-company-id-names-its-register) on what it does when a number exists in two registers.
```json theme={null}
{
"company": {
"id": "FBiH 65-01-0001-10",
"countryCode": "BA",
"identifiers": {
"mbs": "65-01-0001-10",
"jib": "4200000000001"
},
"legalName": "PRIMJER d.o.o. Sarajevo",
"status": {
"localName": "Nije u stečaju/likvidaciji (Active)",
"active": true
},
"legalForm": {
"localName": "DRUŠTVO SA OGRANIČENOM ODGOVORNOŠĆU",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"capital": { "amount": 50000, "currency": "BAM" },
"activities": {
"KD_BIH_2010": [
{ "code": "62.01", "description": "Računarsko programiranje", "isAIInferred": false }
],
"NACE": [
{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false }
],
"ISIC": [
{ "code": "621", "description": "Computer programming activities", "isAIInferred": false }
]
},
"legalAddress": {
"addressLine1": "ul. Džemala Bijedića br. 1",
"city": "Sarajevo",
"countryCode": "BA"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Direktor",
"englishTranslation": "Director",
"standardized": "Director"
},
"representationMode": { "mode": "sole" },
"individual": {
"name": {
"fullName": "PRIMJER, EMIR",
"lastName": "PRIMJER",
"firstName": "EMIR"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Prokurista",
"englishTranslation": "Procurist (Authorized Signatory)",
"standardized": "Authorized Signatory"
},
"representationMode": {
"mode": "joint",
"particularity": "zajedno sa bilo kojim članom Uprave"
},
"individual": {
"name": {
"fullName": "PRIMJER, AMRA",
"lastName": "PRIMJER",
"firstName": "AMRA"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "FBiH 65-02-0001-10",
"countryCode": "BA",
"identifiers": {
"mbs": "65-02-0001-10",
"jib": "4200000000002"
},
"legalName": "PRIMJER BANKA d.d. Sarajevo",
"status": {
"localName": "Nije u stečaju/likvidaciji (Active)",
"active": true
},
"legalForm": {
"localName": "DIONIČKO DRUŠTVO",
"englishTranslation": "Joint-Stock Company",
"standardized": "Corporation"
},
"capital": { "amount": 10000000, "currency": "BAM" },
"legalAddress": {
"addressLine1": "Trg Bosne i Hercegovine br. 1",
"city": "Sarajevo",
"countryCode": "BA"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Generalni direktor",
"englishTranslation": "Director",
"standardized": "Director"
},
"representationMode": { "mode": "sole" },
"individual": {
"name": {
"fullName": "PRIMJER, EMIR",
"lastName": "PRIMJER",
"firstName": "EMIR"
}
}
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Predsjednik nadzornog odbora",
"englishTranslation": "Supervisory Board Chair",
"standardized": "Supervisory Board Member"
},
"individual": {
"name": {
"fullName": "PRIMJER, AMRA",
"lastName": "PRIMJER",
"firstName": "AMRA"
}
}
}
]
}
```
**Note:** d.d. companies do not return `shareholders`. Individual shareholders are not listed in the public register. The `otherKeyPersons` array carries supervisory board members when registered.
```json theme={null}
{
"company": {
"id": "Brčko 1-0001",
"countryCode": "BA",
"identifiers": {
"mbs": "1-0001",
"jib": "4000000000001"
},
"legalName": "PRIMJER d.o.o. Brčko",
"status": {
"localName": "Nije u stečaju/likvidaciji (Active)",
"active": true
},
"legalForm": {
"localName": "DRUŠTVO SA OGRANIČENOM ODGOVORNOŠĆU",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"capital": { "amount": 2000, "currency": "BAM" },
"legalAddress": {
"addressLine1": "ul. Bulevar mira br. 1",
"city": "Brčko",
"countryCode": "BA"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Direktor",
"englishTranslation": "Director",
"standardized": "Director"
},
"representationMode": { "mode": "sole" },
"individual": {
"name": {
"fullName": "PRIMJER, ALEKSANDAR",
"lastName": "PRIMJER",
"firstName": "ALEKSANDAR"
}
}
}
]
}
```
**Note:** the short MBS format `N-XXXX` / `NN-XXXX` carries no canton code and no year suffix. It reflects an older registration rather than a particular jurisdiction, and appears in the Federation and Brčko registers alike.
Query: `{ "id": "RS 1-1234-00 4400000000001", "countryCode": "BA", "dataPoints": ["company", "legalRepresentatives", "shareholders", "ultimateBeneficialOwners"] }`
```json theme={null}
{
"company": {
"id": "RS 1-1234-00 4400000000001",
"countryCode": "BA",
"identifiers": {
"mbs": "1-1234-00",
"jib": "4400000000001"
},
"legalName": "\"PRIMJER\" d.o.o. Banja Luka",
"status": { "localName": "Registrovan (Registered)", "active": true },
"legalForm": {
"localName": "d.o.o.",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"capital": { "amount": 2000, "currency": "BAM", "formatted": "BAM 2,000" },
"legalAddress": {
"addressLine1": "Ulica Kralja Petra I broj 1",
"city": "Banja Luka",
"countryCode": "BA"
},
"activities": {
"NACE": [{ "code": "62.10", "description": "Computer programming activities" }],
"ISIC": [{ "code": "6211", "description": "Computer programming activities", "isAIInferred": false }]
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Direktor", "englishTranslation": "Director", "standardized": "Director" },
"representationMode": { "mode": "sole" },
"individual": { "name": { "fullName": "Marko Primjer", "firstName": "Marko", "lastName": "Primjer" } }
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 60,
"individual": { "name": { "fullName": "Marko Primjer" } },
"nominalCapitalHeld": { "amount": 1200, "currency": "BAM", "formatted": "BAM 1,200" }
},
{
"entityId": "company_001",
"type": "company",
"sharePercentage": 40,
"company": { "legalName": "\"PRIMJER HOLDING\" d.o.o." },
"nominalCapitalHeld": { "amount": 800, "currency": "BAM", "formatted": "BAM 800" }
}
],
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "Marko Primjer" },
"control": {
"types": ["ownership-of-shares"],
"details": [{ "type": "shares", "percentageValue": 84, "nature": null }]
}
}
]
}
```
**Note:** the id carries the JIB because the Republika Srpska register can give one MBS to two companies. Shareholders come from the register's current data overview, with their subscribed amount and share. Beneficial owners come from the register's beneficial ownership register: natural persons only, each with an overall share that includes holdings through other companies (here 60 % directly, plus 24 % through the holding company he owns 60 % of).
```json theme={null}
{
"company": {
"id": "FBiH 65-01-0002-05",
"countryCode": "BA",
"identifiers": {
"mbs": "65-01-0002-05",
"jib": "4200000000003"
},
"legalName": "PRIMJER STARI d.o.o. Sarajevo U STEČAJU",
"status": {
"localName": "U stečaju (In Bankruptcy)",
"active": false
},
"legalForm": {
"localName": "DRUŠTVO SA OGRANIČENOM ODGOVORNOŠĆU",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "ul. Ferhadija br. 2",
"city": "Sarajevo",
"countryCode": "BA"
}
}
}
```
**Note:** Status is inferred from the company name suffix. Companies in bankruptcy include `U STEČAJU` in the registered legal name; companies in liquidation include `U LIKVIDACIJI`.
```json theme={null}
{
"company": {
"id": "Brčko 96-05-0001-15",
"countryCode": "BA",
"identifiers": {
"mbs": "96-05-0001-15",
"jib": "4600000000001"
},
"legalName": "FONDACIJA PRIMJER",
"status": {
"localName": "Nije u stečaju/likvidaciji (Active)",
"active": true
},
"legalForm": {
"localName": "FONDACIJA",
"englishTranslation": "Foundation",
"standardized": "Nonprofit Organization"
},
"legalAddress": {
"addressLine1": "ul. Bosanska br. 1",
"city": "Brčko",
"countryCode": "BA"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Direktor",
"englishTranslation": "Director",
"standardized": "Director"
},
"representationMode": { "mode": "sole" },
"individual": {
"name": {
"fullName": "PRIMJER, EMIR",
"lastName": "PRIMJER",
"firstName": "EMIR"
}
}
}
],
"shareholders": [
{
"entityId": "person_002",
"type": "individual",
"individual": {
"name": {
"fullName": "PRIMJER, AMRA",
"lastName": "PRIMJER",
"firstName": "AMRA"
}
},
"nominalCapitalHeld": { "amount": 10000, "currency": "BAM" }
}
]
}
```
**Note:** Foundations, associations, cooperatives, and institutions use the `-05-` MBS sub-code. Their founding members are returned as shareholders (the register records their capital contributions to the founding endowment). The legal form field contains the specific form type (`FONDACIJA`, `UDRUŽENJE`, etc.) rather than the umbrella category `DRUGO`.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Availability |
| - | - | - |
| `tradeRegisterExtract` | Trade Register Extract (Izvod iz registra poslovnih subjekata) | Listed for every company; not yet deliverable for Brčko District registrations made after 2021 |
The Trade Register Extract is a PDF covering all register sections for the company: basic data, founders, board and management, capital, activities, branch offices, foreign trade authorisation, and notes. All sections are assembled into a single document and printed in one pass.
# Bulgaria
Source: https://docs.topograph.co/essentials/bulgaria
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Bulgaria reference is on the [Bulgaria country page](https://www.topograph.co/countries/bg).
## Start here
This guide contains public integration notes for Bulgaria. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Bulgaria has two official registers, operated by the same Registry Agency and sharing one UIC numbering space. Each entity is served from the register that holds its full record, so a single lookup resolves automatically. Older traders may also have a legacy BULSTAT record, but their Commercial Register record is always the one used.
* **Trade Register (Търговски регистър).** Operated by the Registry Agency (Агенция по вписванията) under the Ministry of Justice, the Trade Register is the official commercial register for traders and non-profit legal entities. It is our primary source for those entities, providing structured data for company identification, status, legal form, address, share capital, shareholders, legal representatives, supervisory board members, and UBOs.
* **BULSTAT register (Регистър БУЛСТАТ).** Also operated by the Registry Agency, BULSTAT holds the entities that are **not** in the Commercial Register: civil-law partnerships (ДЗЗД / Дружество по ЗЗД), freelancers and self-employed professionals, foreign entities and branches, associations, foundations, community centres (читалища), cooperatives, and state/municipal institutions. When a UIC is not a Commercial-Register trader, we resolve it automatically from BULSTAT, returning the same structured company data (identity, registered seat, activity, status, management, and ownership participation) plus a Trade Register Extract. For a natural-person subject only the register-public correspondence address is returned; the register's own masked fields are never surfaced.
* **Open Data (data.egov.bg).** Bulk datasets published periodically by the Registry Agency on Bulgaria's government Open Data portal. Contains historical deed filings with company data including status, legal form, address, capital, activity codes (NKID/NACE), legal representatives, and shareholders. Used for **search** and **prefill profile** (fast, pre-indexed lookups).
**Open Data for fast lookups:** The search and prefill profile use
pre-indexed Open Data for sub-second response times. The company profile and
UBO endpoints query the live Trade Register for the most current data.
### Data Source Priority & Routing
A lookup first resolves **which register holds the entity**, then queries the right sources for it. The Commercial Register and BULSTAT share one UIC space, and the Commercial Register is asked first, so a trader that also has a legacy BULSTAT record still resolves from the Commercial Register.
**Commercial-Register entity** (traders and non-profit legal entities). The source depends on the mode:
1. **Prefill mode.** Served from the pre-indexed Open Data export for fast lookups. A company missing from the export falls back to a live Trade Register lookup.
2. **Verification mode.** Queried live from the Trade Register for the most current data, plus a VIES check of VAT registration. Open Data is not used.
The two sources are not merged: each mode returns the data of its own source.
**BULSTAT entity** (civil-law partnerships, self-employed persons, foreign entities, associations, foundations, cooperatives, institutions) — resolved from a **single live BULSTAT query**. There is no Open Data layer for these entities, so the prefill profile and the company profile both come from the same live source.
### Attribute-Level Source Mapping
| Attribute | Prefill | Verification | Notes |
| - | - | - | - |
| Company name, legal form, status | **Open Data** | **Trade Register** | Registered deed data |
| Latin transliteration (`legalNameInEnglish`) | **Open Data** | **Trade Register** | From official transliteration field |
| Registered address | **Open Data** | **Trade Register** | Structured parsing of Bulgarian address format |
| Share capital | **Open Data** | **Trade Register** | Amount + currency (BGN, EUR, USD) |
| Activity description | **Open Data** | **Trade Register** | Bulgarian text description of business purpose |
| Activity codes (NKID/NACE/ISIC) | **Open Data** | **Trade Register** | Prefill: declared NKID with deterministic NACE/ISIC. Verification: NACE/ISIC inferred from the activity description, no NKID |
| Legal representatives | **Open Data** | **Trade Register** | |
| Shareholders | **Open Data** | **Trade Register** | Partners (OOD) or sole owner (EOOD) with capital amounts |
| VAT validation (`taxId`) | - | **VIES** | Verification only |
| UBOs | **Trade Register** | **Trade Register** | Live-only (always fetched fresh); not available for BULSTAT entities |
In prefill mode, a company missing from the Open Data export is served from a live Trade Register lookup instead.
The mapping above applies to Commercial-Register entities. A **BULSTAT entity**
gets its identity, registered seat, activity, status, management, and ownership
participation from the single live BULSTAT query — there is no Open Data layer
and no UBO datapoint for these entities.
## Company Identifiers
### Query Identifiers
| Company Type | Register | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | Trade Register | 9 digits (UIC/EIK) | `831094393` | Unified Identification Code, accepted for all endpoints |
| **Branches** | Trade Register | 13 digits (UIC/EIK) | `0006940370018` | The parent's 9-digit UIC followed by 4 more digits |
| **Non-trader entities** | BULSTAT | 9 or 13 digits (UIC) | `103861777` | Civil-law partnerships, self-employed persons, foreign entities, associations, foundations, cooperatives, institutions |
The **UIC (Unified Identification Code)**, also known as **EIK (Единен
идентификационен код)**, is the primary identifier used across all endpoints.
The Commercial Register and BULSTAT share this one numbering space, so you pass
the same UIC regardless of which register holds the entity — routing to the
right register is automatic. `/v2/company` accepts 9 or 13 digits only. To use a
legacy 10-digit BULSTAT code, look it up with `/v2/search`, which returns the
current UIC to pass to `/v2/company`. You can also search by **VAT number** using the `BG`
prefix (e.g., `BG831094393`).
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `uic` | 9 or 13 digits | `831094393` | All companies |
| `VAT` | 9 digits | `831094393` | VAT-registered companies (via VIES check) |
### European Unique Identifier (EUID)
Eligible ООД, ЕООД, АД and ЕАД companies can return `company.identifiers.euid` in the format `BGCOMREG.` followed by their 9-digit UIC. Sole traders and BULSTAT-only entities are excluded. EUID is a response identifier, not a search key.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the EIK/UIC (`uic`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By UIC/EIK (9 digits) | `^\d{9}$` | `831094393` | Exact | Exact match returned first (matchType: id); other results may follow |
| By UIC/EIK (13 digits) | `^\d{13}$` | `0006940370018` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | `^BG\d{9}$` | `BG831094393` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name (Cyrillic) | Cyrillic text | `ВИВАКОМ` | Fuzzy | Multiple results (up to 25) |
**Cyrillic gives the best name search results.** Bulgarian company names are
registered in Cyrillic script. Latin transliterations of company names also
match companies in the pre-built index, but the live register fallbacks only
match Cyrillic.
**Search is free.** Search queries do not incur any cost. Only prefill
profile, company profile, UBO, and document retrieval are charged.
**Address may be missing in name search results.** Name searches return data
from pre-indexed Open Data (change feeds since January 2021). Companies that
have not filed an address change in that period will not have an address. The
live Trade Register fallback for name search does not return addresses either.
Use the **company profile** endpoint to get the current address.
### Search Source Priority
Search queries use pre-built indexes, live registry lookups, and the BULSTAT register:
1. **Pre-built index by ID.** Fast lookup in pre-indexed Open Data for identifier-based searches
2. **Pre-built index by name.** Full-text search in pre-indexed Open Data for name-based searches
3. **VAT number lookup.** Validates VAT via EU VIES service, then searches by VIES-returned company name
4. **Live Trade Register by name.** Fallback to live API for name searches not found in index
5. **Live Trade Register by ID.** Fallback to live API for ID searches not found in index
6. **BULSTAT by ID / name.** Makes non-trader entities (civil-law partnerships, self-employed persons, foreign entities, associations, foundations) findable by UIC or Cyrillic name. Lower priority, so Commercial-Register results stream first and BULSTAT results follow.
Search streams results as each source resolves. Commercial-Register hits (fast,
pre-indexed) return first; a BULSTAT-only entity surfaces a moment later. Once an
entity has been retrieved via `/v2/company`, it is indexed and returns quickly on
subsequent searches.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Trading companies are filtered, including those in liquidation or insolvency. Other registered entities (associations, foundations, civil partnerships, sole traders, foreign entities) are returned whatever their status.
## Supported Entity Families
| Entity Family | Supported | Notes |
| - | - | - |
| Companies | ✅ | ООД, ЕООД, АД, ЕАД, СД, КД, КДА, ЕДПК (all commercial legal forms) |
| Sole traders / entrepreneurs | ✅ | ЕТ (Едноличен търговец), 9-digit UIC |
| Associations / organisations | ✅ | Сдружение, Фондация, Народно читалище — from the Commercial Register or BULSTAT depending on registration |
| Non-trader entities (BULSTAT) | ✅ | Civil-law partnerships (ДЗЗД), freelancers / self-employed, foreign entities & branches, cooperatives, and state/municipal institutions — resolved from the BULSTAT register |
| Closed / dissolved entities | ✅ | Companies in liquidation, insolvency, or ceased. Status detected from deed codes and name text |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Cyrillic name search** | Company names are registered in Cyrillic, and Cyrillic queries give the best results. Latin transliterations match companies in the pre-built index only; the live register fallbacks need Cyrillic. |
| **Status from company name** | Company status can be inferred from the company name itself (e.g., names containing "в ликвидация" or "в несъстоятелност"), which takes priority over the deed status code. |
| **Capital in EUR** | Since Bulgaria's euro adoption (1 January 2026), share capital is reported in **EUR**. Partner holdings (`nominalCapitalHeld`) remain filed in **BGN**, so ownership percentages are derived from the sum of the BGN holdings — see Shareholders. Some legacy or foreign-invested filings may still show BGN or USD. |
| **Latin transliteration** | Many companies have an official Latin transliteration of their name registered in the Trade Register, returned as `legalNameInEnglish`. This is a transliteration, not a translation. |
| **Shareholder availability** | OOD (LLC) companies have multiple partners with share amounts. EOOD (Single-Member LLC) and single-member EAD (joint-stock) companies have a sole owner at 100% holding the full registered capital. KD (Limited Partnership) companies have general and limited partners. Multi-shareholder AD (joint-stock) companies do not disclose individual shareholders in the Trade Register. Entities with **no share capital** — ET (Sole Trader) and BULSTAT natural persons and non-profits — have no shareholder record: `shareholders` returns a `datapoint_not_applicable` error and the person/officers are returned under `legalRepresentatives`. |
| **Former partners after conversion** | A company that converted from a multi-partner OOD to a single-member EOOD keeps its former partner list on the register as a struck-through (ceased) record. Only the current sole owner is returned in `shareholders`. The prior partners are historical and are not included. |
| **Activity codes by mode** | The register-declared NKID code (with deterministic NACE and ISIC) comes from Open Data, so it is returned in prefill mode. The live Trade Register returns only a free-text activity description, so verification mode returns NACE and ISIC codes inferred from it (AI) and no NKID code. |
| **Address in name search** | Name search results use pre-indexed Open Data (change feeds since Jan 2021) or the live Summary endpoint as fallback, neither of which guarantees an address. \~77% of indexed companies have no address because they haven't filed an address change in that period. The **company profile** endpoint always fetches the current address from the live Trade Register. |
| **UBO data varies** | UBO declarations are only available for companies that have filed beneficial ownership declarations. Not all companies have UBO filings. |
## Mappings
### Company Status
Company status is determined **deterministically** from deed status codes and company name patterns. No AI inference is involved.
#### Deed Status Codes
| Code | Bulgarian Status | English | Standardized Status | Closure Reason |
| - | - | - | - | - |
| A | Вписан | Registered | Active | - |
| N | Новорегистриран | Newly Registered | Active | - |
| E | Вписана промяна | Amended | Active | - |
| L | В ликвидация | In Liquidation | Closed | Liquidation |
| C | Прекратено | Ceased | Closed | Voluntary Dissolution |
#### Status Detection from Company Name
When the company name contains specific keywords, the status is overridden regardless of the deed status code:
| Name Pattern | English | Standardized Status | Closure Reason |
| - | - | - | - |
| в ликвидация | In Liquidation | Closed | Liquidation |
| в несъстоятелност | In Insolvency | Under Insolvency Proceeding | Bankruptcy |
| прекратено / заличен | Ceased / Struck Off | Closed | Administrative Dissolution |
Company name patterns take **priority** over deed status codes. A company with
deed status `E` (Amended) but "в ликвидация" in its name is correctly mapped
as Closed with Liquidation as the closure reason.
#### BULSTAT Statuses
BULSTAT entities use the register's own status labels instead of deed status codes:
| Bulgarian Status | English | Standardized Status | Active |
| - | - | - | - |
| развиващ дейност | Carrying on activity | Active | `true` |
| неактивен | Inactive | Inactive (`INACTIVE_NOT_CLOSED`) | `false` |
| архивиран | Archived record | Inactive (`INACTIVE_NOT_CLOSED`) | `false` |
Any other label is returned verbatim in `localName` with an `UNKNOWN` standardized status.
### Legal Forms
Bulgaria uses numeric codes from the Trade Register, string codes from Open Data, and legal-form names from the BULSTAT register. The **deterministic mapping covers every common Commercial-Register and BULSTAT legal form** — including civil-law partnerships, cooperatives, associations, foundations, foreign entities, and state/municipal institutions — with the ISO 20275 (ELF) code taken from the official Bulgarian GLEIF list. For a rarer form outside the static map, the standardized type and ISO 20275 code are filled in by AI enrichment **in verification mode only**; in prefill mode the local Bulgarian name is returned verbatim without a standardized mapping. The local Bulgarian legal form name is always preserved verbatim in every mode.
#### Common Legal Forms
| Bulgarian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Дружество с ограничена отговорност | ООД | Limited Liability Company | Limited Liability Company | VJ3G |
| Еднолично дружество с ограничена отговорност | ЕООД | Single-Member Limited Liability Company | Limited Liability Company | WVIN |
| Акционерно дружество | АД | Joint Stock Company | Corporation | WTK4 |
| Еднолично акционерно дружество | ЕАД | Single-Member Joint Stock Company | Corporation | EJ06 |
| Инвестиционно акционерно дружество | ИАД | Investment Joint Stock Company | Corporation | WTK4 |
#### Sole Traders
| Bulgarian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Едноличен търговец | ЕТ | Sole Trader | Sole Proprietorship | 946C |
**Sole trader (ЕТ) vs. self-employed natural person.** Both are one-person
operators standardized as `Sole Proprietorship`, but they come from two
different registers and are distinguished by their local name:
* **Sole trader (Едноличен търговец, ЕТ)** is a natural person registered **as a
trader in the Commercial Register** — a registered one-person business
(`localName: "Едноличен търговец"`, ISO 20275 `946C`). The trader is returned
under `legalRepresentatives` and, for a beneficial-ownership request, as the
sole 100% beneficial owner.
* **Self-employed natural person** (freelancer / free-profession practitioner —
lawyer, notary, farmer, etc.) is **not** a trader and is held **only in the
BULSTAT register** (`localName: "Физическо лице"`, no ISO 20275 code, since the
register states no legal form). It has no shareholders and no ultimate
beneficial owners (both return a benign not-applicable response).
A given UIC is always served from exactly one register, so the two are never mixed. Our
standardized enum has no dedicated "self-employed" value — `Sole Proprietorship`
is the fleet-standard bucket for one-person operators (as with Estonia's FIE) —
so the register of origin and the local name carry the distinction.
#### Partnerships
| Bulgarian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Събирателно дружество | СД | General Partnership | Partnership | FPP2 |
| Командитно дружество | КД | Limited Partnership | Partnership | S94S |
| Командитно дружество с акции | КДА | Limited Partnership with Shares | Partnership | HN63 |
#### Cooperatives
| Bulgarian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Кооперация | К | Cooperative | Cooperative | CTCH |
#### Non-Profits & Public Entities
| Bulgarian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Сдружение | Сдр | Association | Nonprofit Organization | - |
| Фондация | Ф | Foundation | Nonprofit Organization | UFG8 |
| Народно читалище | НЧ | Community Center | Nonprofit Organization | - |
| Търговско предприятие на публичноправен субект | ТППД | Trading Enterprise of Public Law Entity | Government-Owned Entity | - |
#### Branch Offices
| Bulgarian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Клон на чуждестранен търговец | Клон / КЧТ | Branch of Foreign Trader | Branch or Representative Office | - |
| Клон на чуждестранно юридическо лице | КЧЮЛ | Branch of Foreign Legal Entity | Branch or Representative Office | - |
#### Variable Capital Companies
| Bulgarian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Еднолично дружество с променлив капитал | ЕДПК | Single-Member Variable Capital Company | Limited Liability Company | - |
#### BULSTAT-only Forms
These forms are not held in the Commercial Register — they are resolved from the BULSTAT register:
| Bulgarian Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Дружество по ЗЗД (ДЗЗД) | Civil-Law Partnership (Consortium) | Partnership | TCGV |
| Жилищностроителна кооперация | Housing Construction Cooperative | Cooperative | CTCH |
| Физическо лице | Natural person (self-employed) | Sole Proprietorship | - |
| Чуждестранно нефизическо лице с място на стопанска дейност | Foreign legal entity with a place of business | Branch or Representative Office | - |
| Чуждестранно лице | Foreign entity | Other | - |
| Детска градина / училище / община | Kindergarten / school / municipality | Government-Owned Entity | - |
The deterministic mapping covers every common Commercial-Register and BULSTAT
legal form, with the ISO 20275 (ELF) code taken from the official Bulgarian
GLEIF list (only currently-active ELF codes are used). For a rarer form outside
the static map, the standardized type and ISO 20275 code are filled in by AI
enrichment **in verification mode only**; in prefill mode the local Bulgarian
name is returned verbatim. The local Bulgarian legal form name is always
preserved verbatim in every mode.
The most common Bulgarian legal forms are **ООД** (LLC, \~45% of active
companies), **ЕООД** (Single-Member LLC, \~35%), **ЕТ** (Sole Trader, \~10%),
and **АД/ЕАД** (Joint Stock, \~5%).
### Legal Representatives
Appointments use the published role references for the Commercial Register and BULSTAT. The register's representative fields establish an individual appointment; separate governance fields identify board and oversight memberships. Exact known labels have the same standardized value in live and cached results. An unspecified office on an established representative row is an `Authorized Signatory`; unknown generic management titles remain other key persons until a mandate is evidenced.
| Bulgarian Role | English Translation | Standardized Role |
| - | - | - |
| Управител | Manager | Managing Director |
| Управител на клон | Branch Manager | Managing Director |
| Изпълнителен директор | Executive Director | Executive Director |
| Главен изпълнителен директор | Chief Executive Director | Chief Executive Officer |
| Председател на управителния съвет | Chairman of the Management Board | Chairman of the Board |
| Член на управителния съвет | Member of the Management Board | Board Member |
| Представител | Representative | Authorized Signatory |
| Прокурист | Procurator | Authorized Signatory |
| Ликвидатор | Liquidator | Liquidator |
| Синдик | Receiver / Trustee in Bankruptcy | Receiver |
| Председател | Chairman | Chairman |
| Президент | President | President |
| Зам. председател | Deputy Chairman | Vice Chairman of the Board |
| Едноличен търговец | Sole Trader | Owner |
These representative values apply to a source-established capacity, rather than to every occurrence of the title. Corporate and individual holders retain their identity. Recorded manner-of-representation text is preserved in `signingPowers.localText`; an unambiguous individual or joint condition can also populate `representationMode`. Missing or alternative conditions do not imply a sole signature.
Commercial Act Article 235 provides collective director/management-board representation by default unless the articles provide otherwise, and also permits registered delegated representatives. Board membership alone does not establish the applicable current articles, full-board signature rule or an individual mandate. Unmandated board appointments remain in `otherKeyPersons`; their classification does not deny exceptional or collective capacity. Liquidator and procuration powers also have statutory and recorded conditions.
### Other Key Persons
Separate board, supervisory, audit and control appointments use the other-key-person vocabulary. The same title may have a different value when the record establishes an individual representation grant. A name appearing in the representative roster is excluded from the live board-only list. Public XML records also distinguish representatives of entities in the ownership chain from direct representatives of the subject company.
| Bulgarian Role | English Translation | Standardized Role |
| - | - | - |
| Член на Съвета на директорите | Board of Directors Member | Board Member |
| Член на управителния съвет | Management Board Member | Board Member |
| Член на надзорния съвет | Supervisory Board Member | Supervisory Board Member |
| Председател на надзорния съвет | Chairman of the Supervisory Board | Supervisor |
| Председател на управителния съвет | Chairman of the Management Board | Chairman of the Board |
| Зам. председател | Deputy Chairman | Vice Chairman of the Board |
| Контрольор | Controller / Auditor | Auditor |
| Член на проверителната комисия | Verification Commission Member | Auditor |
| Член на настоятелството | Board of Trustees Member | Board Member |
| Председател | Chairman | Chairman of the Board |
| Член | Member | Board Member |
| Изпълнителен директор | Executive Director, unmandated body context | C-Level Executive |
| Главен изпълнителен директор | Chief Executive Director, unmandated body context | C-Level Executive |
| Друга длъжност | Other Position | Other |
| Представител на дружество в собствеността | Representative of an ownership entity | Other |
The reference list covers the known source vocabulary and observed labels; the registers return free text and do not publish a complete closed title classifier. Older cached XML appointments may lack the original field context, and a change-feed record can omit an unchanged current representative. Current live representative fields remain the stronger source for those cases.
### Shareholders
Shareholders are extracted from the Trade Register for **OOD, EOOD, KD, and single-member EAD entities**. Multi-shareholder **AD** (joint-stock) companies do not disclose their individual shareholders in the Bulgarian Trade Register. Entities with **no share capital** — **ET** (sole traders) and BULSTAT natural persons (freelancers / self-employed) and non-profits (associations, foundations) — have no shareholders: the `shareholders` datapoint returns an explicit not-applicable response (at no charge) and the person or officers are returned under `legalRepresentatives` instead.
#### Extraction Logic
| Legal Form | Source | Data Available |
| - | - | - |
| **ООД** (LLC) | Partners list | Multiple shareholders with nominal capital held and share percentage |
| **ЕООД** (Single-Member LLC) | Sole owner | Single shareholder at 100%, holding the full registered capital (`nominalCapitalHeld`) |
| **ЕАД** (Single-Member Joint Stock) | Sole owner | Single shareholder at 100%, holding the full registered capital (`nominalCapitalHeld`) |
| **ЕТ** (Sole Trader) | — (no share capital) | Not applicable — no shareholders; the trader is returned under `legalRepresentatives` |
| **КД** (Limited Partnership) | General + limited partners | General partners (unlimited liability) and limited partners |
| **АД** (multi-shareholder Joint Stock) | - | Not available (individual shareholders not disclosed in Trade Register) |
| **ДЗЗД** (Civil-Law Partnership, BULSTAT) | Participants list | Partners with participation percentage where the register states it |
| **BULSTAT natural persons** (freelancers / self-employed) | — (no share capital) | Not applicable — no shareholders; the person is returned under `legalRepresentatives` |
| **Non-profits** (Сдружение, Фондация, читалище) | — (no share capital) | Not applicable — no shareholders; officers are returned under `legalRepresentatives` |
#### Ownership Fields
| Field | Description | Notes |
| - | - | - |
| `sharePercentage` | Ownership percentage | Each partner's share of the total holdings (see note below) |
| `nominalCapitalHeld` | Absolute capital held | Amount as filed in the register — partner holdings are in **BGN** |
Since Bulgaria's euro adoption (1 January 2026), the register reports the
company's **share capital in EUR** while partner holdings remain filed in
**BGN**. Ownership percentages are therefore derived from the **sum of the
partners' BGN holdings** (no currency conversion), so they always total 100%.
The held amounts (`nominalCapitalHeld`) are returned in their filed currency
(BGN); the company-level `capital` is the register's EUR figure. For a
single-member company (ЕООД), the sole owner holds the entire registered
capital, so their `nominalCapitalHeld` equals the company's registered capital
(the EUR figure). A sole trader (ЕТ) has no registered capital, so the field is
omitted.
Both individual and corporate shareholders are supported. Corporate
shareholders include the company's legal name, registration number (when
available), and country code. Foreign corporate shareholders are identified by
markers in the registry text.
### Activity Code Mapping
Bulgaria uses the **NKID (Национална класификация на икономическите дейности)** classification, which is Bulgaria's national transposition of the European NACE Rev. 2 standard.
```
NKID (Bulgarian) -> NACE Rev. 2.1 (European) -> ISIC Rev. 5 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NKID** | Open Data (official) | `6201` | No |
| **NACE** | Derived from NKID (identical structure) | `62.10` | No (formal mapping) |
| **ISIC** | Derived from NACE via UN correspondence table | `621` | No (formal mapping) |
| **NACE** | AI-inferred from activity description | `62.01` | Yes (verification mode) |
| **ISIC** | AI-inferred from activity description | `6201` | Yes (verification mode) |
**One code in, one code out.** You get one `NACE` and one `ISIC` code per declared NKID code. Where a NKID code has no single equivalent in the target revision, the shared parent class is returned rather than every candidate — see [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
**Main activity.** The Open Data NKID code is the register's declared main activity (основна дейност), so it carries `isMainActivity: true`, and the NACE and ISIC codes derived from it inherit the flag. AI-inferred codes from the free-text activity description do not carry the flag.
In **prefill mode**, the NKID code comes from Open Data and the full
NKID → NACE → ISIC chain is **deterministic** (no AI). In **verification
mode**, the live Trade Register returns only the free-text activity
description, so NACE and ISIC codes are **AI-inferred** from it and no NKID
code is returned. An prefill lookup for a company missing from Open Data
falls back to the live register and returns no activity codes. Check the
`isAIInferred` flag on each activity code to distinguish.
## Establishments
`establishments` returns branches recorded in the Commercial Register in both prefill and verification mode. Names, branch codes, addresses, closure status, and closure dates are returned where published. Branch codes are local to the parent company.
Closed branches may be included with `active: false`. An empty list means no branches are listed, rather than proving the company has no other operating sites.
For entities registered only in BULSTAT, this datapoint returns `datapoint_not_applicable`: the public subject report does not provide an establishments list.
## Data Availability
### Data Availability Matrix
| Data Type | Open Data (Pre-indexed) | Trade Register (Live) | Notes |
| - | - | - | - |
| Prefill Profile | ✅ Fast | ✅ Fallback | Pre-indexed for sub-second response |
| Company Profile | ❌ | ✅ | Verification mode queries the live register only |
| Legal Representatives | ✅ | ✅ | Open Data in prefill, live in verification |
| Other Key Persons | ✅ | ✅ | Supervisory board, auditors, controllers |
| Establishments | ❌ | ✅ | Registered branches, queried live in both modes; not applicable for BULSTAT-only entities |
| Shareholders | ✅ | ✅ | OOD/EOOD + single-member EAD; multi-shareholder AD not disclosed; not applicable for no-capital entities (ET, BULSTAT natural persons/non-profits) |
| Ultimate Beneficial Owners | ❌ | ✅ | Live-only (always fetched fresh); not applicable for BULSTAT-only entities |
| Activity Codes | ✅ | ✅ AI-inferred | NKID with deterministic NACE/ISIC from Open Data; live data gives AI-inferred NACE/ISIC only |
| Activity Description | ✅ | ✅ | Free-text description of business purpose |
| VAT Validation (taxId) | - | ✅ (via VIES) | EU VAT verification with consultation number |
| Documents | - | ✅ | Trade Register Extract + conditional documents |
**Legend:** ✅ Available | ❌ Not Available
The matrix above describes Commercial-Register entities. **BULSTAT-only
entities** (civil-law partnerships, self-employed persons, foreign entities,
associations, foundations, cooperatives, institutions) are resolved from a
single live BULSTAT query — Open Data does not cover them. They return identity,
registered seat, activity, status, management, and (where applicable) ownership
participation, plus a Trade Register Extract. Ultimate beneficial owners are not
applicable for BULSTAT-only entities, and personal data is anonymised by the
register, so legal-representative and key-person street addresses are not
returned.
### Documents by Company Type
| Document Type | API Category | Format | Availability |
| - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | ✅ All companies |
| **Articles of Association** | `articlesOfAssociation` | PDF | Conditional |
| **Financial Statements** | `financialStatements` | PDF | Conditional |
The **Trade Register Extract** is always available for any registered company —
for a Commercial-Register entity it is an extract of the trade-register record,
and for a BULSTAT-only entity it is a printable extract of the BULSTAT detail
page. **Articles of Association** and **Financial Statements** are available only
when a Commercial-Register company has filed them with the registry (they are not
offered for BULSTAT-only entities). Additional document types (shareholder
meeting notices, transformation plans, insolvency documents) may be available
depending on the company's filing history. They are listed under
`officialPublications` or `otherDocuments`. See the
[pricing page](https://topograph.co/pricing/bg) for document pricing.
The following additional documents may be available depending on the company's filing history:
| Category | Documents |
| - | - |
| **Financial** | Annual Financial Statement, Annual Activity Report, Management Board Report |
| **Corporate Actions** | New Share Subscription Invitation, Capital Increase Resolution, Shareholder Privileges Resolution, Share Buyback Proposal |
| **Official Publications** | Shareholders Meeting Notice, Bondholders Meeting Notice, Bond Loan Notice, Minority Shareholders Proposal |
| **Transformation** | Transformation Plan, Transformation Board Report |
| **Insolvency** | Accepted Claims List, Distribution Account Notice, Foreign Creditor Summons, Court Order on Accepted Claims |
| **Non-Profit** | NFPO Members Meeting Notice, NFPO Registration Changes |
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "123456789", "countryCode": "BG", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "123456789",
"countryCode": "BG",
"identifiers": { "uic": "123456789", "VAT": "123456789" },
"legalName": "ПРИМЕРНА КОМПАНИЯ ООД",
"legalNameInEnglish": "PRIMERNA KOMPANIYA",
"status": { "localName": "Вписана промяна", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Дружество с ограничена отговорност (ООД)", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "VJ3G" },
"capital": { "amount": 51129.19, "currency": "EUR" },
"activityDescription": "Търговия на дребно с хранителни стоки, консултантска дейност",
"legalAddress": { "addressLine1": "бул. Витоша № 100", "city": "София", "postalCode": "1000", "countryCode": "BG" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Управител", "englishTranslation": "Manager", "standardized": "Managing Director" }, "individual": { "name": { "fullName": "ИВАНОВ ПЕТЪР ГЕОРГИЕВ" } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 60, "nominalCapitalHeld": { "amount": 60000, "currency": "BGN" }, "individual": { "name": { "fullName": "ИВАНОВ ПЕТЪР ГЕОРГИЕВ" } } },
{ "entityId": "company_001", "type": "company", "sharePercentage": 40, "nominalCapitalHeld": { "amount": 40000, "currency": "BGN" }, "company": { "legalName": "ПАРТНЬОР ХОЛДИНГ ГмбХ", "id": "FN524697", "countryCode": "AT" } }
]
}
```
```json theme={null}
{
"company": {
"id": "987654321",
"countryCode": "BG",
"identifiers": { "uic": "987654321", "VAT": "987654321" },
"legalName": "ТЕХНОЛОГИИ БЪЛГАРИЯ ЕООД",
"legalNameInEnglish": "TEHNOLOGII BULGARIA",
"status": { "localName": "Вписана промяна", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Еднолично дружество с ограничена отговорност (ЕООД)", "englishTranslation": "Single-Member Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "WVIN" },
"capital": { "amount": 25564.59, "currency": "EUR" },
"legalAddress": { "addressLine1": "ул. Раковски № 50", "city": "Пловдив", "postalCode": "4000", "countryCode": "BG" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Управител", "englishTranslation": "Manager", "standardized": "Managing Director" }, "individual": { "name": { "fullName": "ДИМИТРОВА МАРИЯ СТЕФАНОВА" } } }
],
"shareholders": [
{ "entityId": "company_001", "type": "company", "sharePercentage": 100, "nominalCapitalHeld": { "amount": 25564.59, "currency": "EUR" }, "company": { "legalName": "ПАРЕНТ КОРП С.А.Р.Л.", "id": "B145882", "countryCode": "LU" } }
]
}
```
```json theme={null}
{
"company": {
"id": "201234567",
"countryCode": "BG",
"identifiers": { "uic": "201234567" },
"legalName": "СЧЕТОВОДНА КЪЩА - ПЕТЪР ИВАНОВ ЕТ",
"legalNameInEnglish": "SCHETOVODNA KASHTA - PETAR IVANOV",
"status": { "localName": "Вписан", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Едноличен търговец (ЕТ)", "englishTranslation": "Sole Trader", "standardized": "Sole Proprietorship", "iso20275Code": "946C" },
"activityDescription": "Счетоводни услуги, търговска и транспортна дейност",
"legalAddress": { "addressLine1": "ул. Хан Аспарух № 12", "city": "Пловдив", "postalCode": "4000", "countryCode": "BG" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Едноличен търговец", "englishTranslation": "Sole Trader", "standardized": "Owner" }, "individual": { "name": { "fullName": "ПЕТЪР ГЕОРГИЕВ ИВАНОВ" } } }
]
}
```
**Note:** A sole trader (ЕТ) is a natural person trading under a business name, with no share capital. The `shareholders` datapoint is therefore **not applicable** — it returns a benign not-applicable response (at no charge) rather than a fabricated record. The trader is returned under `legalRepresentatives`, and, where a beneficial-ownership datapoint is requested, as the sole 100% beneficial owner.
```json theme={null}
{
"company": {
"id": "202345678",
"countryCode": "BG",
"identifiers": { "uic": "202345678" },
"legalName": "КАПИТАЛ ПАРТНЪРС - ИВАНОВ И СИЕ КД",
"status": { "localName": "Вписан", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Командитно дружество (КД)", "englishTranslation": "Limited Partnership", "standardized": "Partnership", "iso20275Code": "S94S" },
"legalAddress": { "addressLine1": "бул. Христо Ботев № 79", "city": "София", "postalCode": "1303", "countryCode": "BG" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Управител", "englishTranslation": "Manager", "standardized": "Managing Director" }, "individual": { "name": { "fullName": "ИВАНОВ ГЕОРГИ ПЕТРОВ" } } }
],
"shareholders": [
{ "entityId": "company_001", "type": "company", "company": { "legalName": "КАПИТАЛ ХОЛДИНГ ЕООД", "id": "175000001", "countryCode": "BG" } },
{ "entityId": "person_002", "type": "individual", "individual": { "name": { "fullName": "ФРАНЦ МЮЛЕР" } } }
]
}
```
**Note:** A limited partnership (КД) has at least one general partner (unlimited liability, listed first) and one or more limited partners (liability capped at their contribution). Partners can be individuals or companies, and either type can be foreign. КД partners are returned without a `sharePercentage`, because the register records partner roles rather than share amounts.
```json theme={null}
{
"company": {
"id": "111222333",
"countryCode": "BG",
"identifiers": { "uic": "111222333", "VAT": "111222333" },
"legalName": "ТЕЛЕКОМ БЪЛГАРИЯ ЕАД",
"status": { "localName": "Вписана промяна", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Еднолично акционерно дружество (ЕАД)", "englishTranslation": "Single-Member Joint Stock Company", "standardized": "Corporation", "iso20275Code": "EJ06" },
"capital": { "amount": 766937.61, "currency": "EUR" },
"legalAddress": { "addressLine1": "бул. Цариградско шосе № 111", "city": "София", "postalCode": "1784", "countryCode": "BG" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Изпълнителен директор", "englishTranslation": "Executive Director", "standardized": "Executive Director" }, "individual": { "name": { "fullName": "ГЕОРГИЕВ АЛЕКСАНДЪР НИКОЛАЕВ" } } }
],
"otherKeyPersons": [
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Член на Съвета на директорите", "englishTranslation": "Board of Directors Member", "standardized": "Board Member" }, "individual": { "name": { "fullName": "СТОЯНОВА ЕЛЕНА ПЕТРОВА" } } },
{ "entityId": "person_003", "type": "individual", "role": { "localName": "Член на Съвета на директорите", "englishTranslation": "Board of Directors Member", "standardized": "Board Member" }, "individual": { "name": { "fullName": "ПЕТКОВ МАРТИН АНГЕЛОВ" } } }
],
"shareholders": [
{ "entityId": "company_001", "type": "company", "sharePercentage": 100, "nominalCapitalHeld": { "amount": 766937.61, "currency": "EUR" }, "company": { "legalName": "ХОЛДИНГ ГРУП АД", "id": "831000001", "countryCode": "BG" } }
]
}
```
**Note:** A single-member joint-stock company (ЕАД) discloses its sole owner, returned in `shareholders` at 100% with the full registered capital. Multi-shareholder AD companies do not disclose individual shareholders. Board members are returned in `otherKeyPersons`. This example shows a one-tier **Board of Directors** (Съвет на директорите); two-tier companies instead have a **Management Board** (Управителен съвет) plus a **Supervisory Board** (Надзорен съвет). A board member who also represents the company (the Executive Director above) is returned once, under `legalRepresentatives`.
```json theme={null}
{
"company": {
"id": "444555666",
"countryCode": "BG",
"identifiers": { "uic": "444555666", "VAT": "444555666" },
"legalName": "СТАРА ФИРМА ООД - в ликвидация",
"status": { "localName": "В ликвидация", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "LIQUIDATION" } },
"legalForm": { "localName": "Дружество с ограничена отговорност (ООД)", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "VJ3G" },
"legalAddress": { "addressLine1": "ул. Шипка № 25", "city": "Варна", "postalCode": "9000", "countryCode": "BG" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Ликвидатор", "englishTranslation": "Liquidator", "standardized": "Liquidator" }, "individual": { "name": { "fullName": "НИКОЛОВ ДИМИТЪР ИВАНОВ" } } }
]
}
```
**Note:** Companies in liquidation have a Ликвидатор (Liquidator) as legal representative instead of the regular Управител (Manager). The company name itself contains "в ликвидация" (in liquidation).
Query: `POST /v2/company` with `{ "id": "123456789", "countryCode": "BG", "dataPoints": ["ultimateBeneficialOwners"] }`
```json theme={null}
{
"ultimateBeneficialOwners": [
{ "entityId": "person_001", "name": { "fullName": "ИВАНОВ ПЕТЪР ГЕОРГИЕВ" } },
{ "entityId": "person_002", "name": { "fullName": "ДИМИТРОВА МАРИЯ СТЕФАНОВА" } }
]
}
```
**Note:** UBO data is fetched live from the Commercial Register beneficial-ownership declarations. Not all companies have UBO filings, so the field may be absent if no declaration has been filed. Beneficial ownership is a Commercial-Register concept: for entities held only in the BULSTAT register (civil-law partnerships, self-employed persons, foreign entities, associations, and foundations) the `ultimateBeneficialOwners` datapoint returns a benign not-applicable response (at no charge) — a self-employed person is never synthesised as their own beneficial owner. A sole trader (ЕТ), by contrast, is a Commercial-Register entity whose trader is legitimately returned as the sole 100% beneficial owner.
Query: `POST /v2/company` with `{ "id": "123456789", "countryCode": "BG", "dataPoints": ["availableDocuments"] }`
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "",
"name": "Trade Register Extract",
"format": "pdf"
},
"articlesOfAssociation": [
{
"id": "",
"name": "Articles of Association",
"format": "pdf"
}
],
"financialStatements": [
{
"id": "",
"name": "Annual Financial Statement 2024",
"format": "pdf",
"period": { "startDate": { "year": 2024, "month": 1, "day": 1 }, "endDate": { "year": 2024, "month": 12, "day": 31 } }
},
{
"id": "",
"name": "Annual Financial Statement 2023",
"format": "pdf",
"period": { "startDate": { "year": 2023, "month": 1, "day": 1 }, "endDate": { "year": 2023, "month": 12, "day": 31 } }
}
]
}
}
```
**Note:** The Trade Register Extract is always available. Articles of Association and Financial Statements are conditional, only listed when the company has filed them with the registry.
Query: `POST /v2/company` with `{ "id": "175883961", "countryCode": "BG", "dataPoints": ["company", "legalRepresentatives", "shareholders"] }`
```json theme={null}
{
"company": {
"id": "175883961",
"countryCode": "BG",
"identifiers": { "uic": "175883961" },
"legalName": "ДЗЗД ОБЕДИНЕНИЕ ПЪТИЩА",
"legalForm": { "localName": "Дружество по ЗЗД (ДЗЗД)", "englishTranslation": "Civil-Law Partnership (Consortium)", "standardized": "Partnership", "iso20275Code": "TCGV" },
"status": { "localName": "развиващ дейност", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalAddress": { "addressLine1": "гр. София, ул. Оборище № 5", "city": "София", "countryCode": "BG" },
"activityDescription": "Строителство на пътища и магистрали"
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Представляващ", "englishTranslation": "Representative", "standardized": "Authorized Signatory" }, "individual": { "name": { "fullName": "ГЕОРГИЕВ ИВАН ПЕТРОВ" } } }
],
"shareholders": [
{ "entityId": "company_001", "type": "company", "sharePercentage": 50, "company": { "legalName": "ПЪТСТРОЙ ЕООД", "id": "131234567" } },
{ "entityId": "company_002", "type": "company", "sharePercentage": 50, "company": { "legalName": "МАГИСТРАЛИ АД", "id": "121987654" } }
]
}
```
**Note:** A civil-law partnership (ДЗЗД) is held only in the BULSTAT register — it is resolved automatically when the UIC is not a Commercial-Register trader. Unlike sole traders and self-employed persons, a ДЗЗД has participating members, so `shareholders` returns them (with participation percentage where the register states it). Note there is no `VAT` identifier: it is only added when a VIES check confirms the entity is VAT-registered. Identifiers, values, and names above are illustrative.
Query: `POST /v2/company` with `{ "id": "112233445", "countryCode": "BG", "dataPoints": ["company", "legalRepresentatives", "shareholders", "ultimateBeneficialOwners"] }`
```json theme={null}
{
"company": {
"id": "112233445",
"countryCode": "BG",
"identifiers": { "uic": "112233445" },
"legalName": "МАРИЯ ИВАНОВА ДИМИТРОВА",
"legalForm": { "localName": "Физическо лице", "englishTranslation": "Natural person (self-employed)", "standardized": "Sole Proprietorship" },
"status": { "localName": "развиващ дейност", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalAddress": { "addressLine1": "гр. Пловдив", "city": "Пловдив", "countryCode": "BG" },
"activityDescription": "Адвокатска дейност"
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "individual": { "name": { "fullName": "МАРИЯ ИВАНОВА ДИМИТРОВА" } } }
],
"request": {
"dataStatus": {
"dataPoints": {
"shareholders": {
"status": "failed",
"error": { "code": "datapoint_not_applicable", "retryable": false }
},
"ultimateBeneficialOwners": {
"status": "failed",
"error": { "code": "datapoint_not_applicable", "retryable": false }
}
}
}
}
}
```
**Note:** A self-employed natural person (freelancer / free-profession practitioner) is held only in BULSTAT and is **not** a sole trader (ЕТ) — sole traders live in the Commercial Register. Both standardize as `Sole Proprietorship`; they are distinguished by the local name (`Физическо лице` vs `Едноличен търговец`) and the register of origin. The person has no share capital, so both `shareholders` and `ultimateBeneficialOwners` complete as `failed` with the `datapoint_not_applicable` error code in `request.dataStatus.dataPoints` rather than a fabricated record. See [Sole Entrepreneurs & Non-Profits](/essentials/entity-types). There is no `VAT` identifier or `taxId` unless a VIES check confirms VAT registration. BULSTAT anonymises personal data, so only the register-public correspondence locality is returned, not a full street address. Identifiers, values, and names above are illustrative.
# British Virgin Islands
Source: https://docs.topograph.co/essentials/bvi
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date British Virgin Islands reference is on the [British Virgin Islands country page](https://www.topograph.co/countries/vg).
## Start here
This guide contains public integration notes for British Virgin Islands. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
**Current coverage limitation**
Document-based verification is temporarily unavailable for the British Virgin Islands. Only the FSC public search is currently supported.
Only the public search is available today. In prefill mode the `company` datapoint returns the current legal name and company number. Company status and legal form are no longer published in the public search (the FSC moved them to its paid profile report, which is currently unavailable), and directors, shareholders, registered address and capital are not available either. Full verification depends on access to FSC profile documents.
Concretely: pass `"mode": "prefill"` on every request. `/v2/company` uses `verification` when you omit `mode`, and with no authoritative lane available the datapoint comes back failed with the error code `authoritative_source_unavailable`. See [Modes](/essentials/modes).
## Data Sources
BVI company data comes from the **British Virgin Islands Financial Services Commission (FSC)**, the autonomous regulatory authority that operates the Registry of Corporate Affairs.
* **BVI FSC Public Search** (`publicsearch.bvifsc.vg`). Provides the legal name, company number and any previous names in search results. This is currently the only active source for BVI data. The prefill profile returns the current legal name and number; it does not include previous names.
## Company Identifiers
### Query Identifiers
We have found no check digit and no internal structure in BVI company numbers. The FSC has assigned identifiers across several historical registers, which is why two different formats coexist today.
| Format | Regex | Example | Applies To |
| - | - | - | - |
| Pure numeric | `^\d+$` | `17195`, `587145`, `1567724` | BVI Business Companies (type 1), International Business Companies (type 5) |
| Letter-prefixed | `^[A-Z]\d+$` | `L658`, `L732`, `L7805` | Local Companies (type 7), pre-existing under the old Companies Act |
Both formats are validated before we hit the register. In the records we have seen there is no check digit, no leading zero and no embedded year, and no structural meaning beyond the optional letter prefix indicating a legacy Local Company. In the records we have seen, numeric company numbers have 5 to 7 digits.
### Identifiers in API Response
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| `companyNumber` | Numeric or letter-prefixed | `587145` or `L658` | Official registration number assigned by the BVI FSC |
The BVI register does not publish VAT numbers, tax IDs, or other secondary identifiers. An optional LEI may be returned from GLEIF as described below.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the BVI company number matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
## Search Capabilities
| Search Type | Pattern | Example | Match Type |
| - | - | - | - |
| By company number (numeric) | Digits only | `587145` | Exact |
| By company number (prefixed) | Letter + digits | `L658` | Exact |
| By name | Text string (min 2 chars) | `"BANKIM"` | Fuzzy |
Both name and ID searches query the BVI FSC public search API in real time. There is no deduplicated index for BVI.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. The current prefill profile normally has no `company.status` either.
## Company Status
The BVI FSC public search no longer returns company status, so the prefill profile normally has no `status`. The mapping below applies only when the register includes a status for an entity.
The BVI FSC status is a free-text string. We map known values deterministically and fall back to keyword inference for unrecognized values.
| Local Status | Standardized | Active |
| - | - | - |
| Active | Active | Yes |
| In Good Standing | Active | Yes |
| In Penalty - Non filing of Beneficial Ownership | Inactive | No |
| In Liquidation (insolvent) | Under Insolvency Proceeding | No |
| In Liquidation (solvent) | In Liquidation | No |
| Dissolved | Closed | No |
| Dissolved (10 year non-pmt) | Closed | No |
| Dissolved (7 year non-pmt) | Closed | No |
| Struck off - Dissolved | Closed | No |
| Struck off - Non Pmt A/Fee | Closed | No |
## Legal Forms
The BVI FSC public search no longer returns the entity type, so the prefill profile normally has no `legalForm`. The mapping below applies only when the register includes a type for an entity.
The entity type is a coarse numeric `type` code indicating one of 5 broad categories. Detailed BVI Business Companies Act 2004 subtypes (Company Limited by Shares, Company Limited by Guarantee, Unlimited Company, Restricted Purpose Company, Segregated Portfolio Company) only appear in the trade register extract document, which is not reachable today.
| Type Code | Local Name | Standardized | Notes |
| - | - | - | - |
| `1` | BVI Business Company | `Limited Liability Company` | Most common, incorporated under BCA 2004 |
| `3` | Limited Partnership | `Partnership` | Limited and general partners |
| `4` | Foreign Company | `Other` | Foreign entity registered in BVI |
| `5` | International Business Company | `Limited Liability Company` | Legacy type, pre-BCA 2004, grandfathered |
| `7` | Local Company | `Limited Liability Company` | Incorporated under the old Companies Act, uses letter-prefixed numbers |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Document retrieve deactivated** | The BVI FSC register document service is broken on their side. We deactivated the document-based verification flow in March 2026 and will reactivate it once the FSC restores retrieval. |
| **High document fees** | Even when the gateway works, BVI document fees are among the highest of any jurisdiction we cover. |
| **Privacy jurisdiction** | BVI is a well-known privacy jurisdiction. Even when documents are accessible, directors and shareholders visible on them are frequently nominees rather than beneficial owners. |
| **No UBO register** | BVI does not have a public UBO register. Beneficial ownership data sits in the BOSS (Beneficial Ownership Secure Search) system, which is restricted to competent authorities. |
| **No registration date in search** | The public search API does not expose incorporation or registration dates. These only appear in the trade register extract document (currently unreachable). |
| **No address in search** | Registered addresses are not available in the public search API. |
| **No status or legal form in search** | Company status and entity type are published only in the FSC's paid profile report, which is currently unavailable. When the register does include a `type`, it gives only a broad category; detailed BCA 2004 subtypes are not exposed. |
| **No activity codes** | BVI has no national industry classification system in its registry. Many holding companies and SPVs have no stated business description. |
## Data Availability
| Data Type | Prefill Profile | Verification Mode | Notes |
| - | - | - | - |
| Company Name | Available | Not available | |
| Company Number | Available | Not available | |
| Company Status | Not available | Not available | Published only in the FSC's paid profile report, currently unavailable |
| Legal Form | Not available | Not available | Published only in the FSC's paid profile report, currently unavailable |
| Previous Company Names | Not available | Not available | Not returned in the `company` datapoint |
| Registration Date | Not available | Not available | Would come from document |
| Legal Address | Not available | Not available | Would come from document |
| Share Capital | Not available | Not available | Would come from document |
| Legal Representatives | Not available | Not available | Would come from document |
| Shareholders | Not available | Not available | Would come from document |
| Ultimate Beneficial Owners | Not available | Not available | BVI has no public UBO register |
| Activity Codes | Not available | Not available | BVI has no classification system |
Verification mode is listed as unavailable because document retrieve is deactivated. We will update this table as soon as the FSC register document service is fixed.
## Example API Response
Query: `POST /v2/company` with `{ "id": "1987245", "countryCode": "VG", "mode": "prefill", "dataPoints": ["company"] }`
```json theme={null}
{
"company": {
"id": "1987245",
"countryCode": "VG",
"identifiers": {
"companyNumber": "1987245"
},
"legalName": "PACIFIC VENTURES INC."
}
}
```
This is the complete shape of the prefill response. No status, no legal form, no address, no directors, no shareholders, no registration date, no capital.
# Canada (Alberta)
Source: https://docs.topograph.co/essentials/canada-alberta
Identifiers, data sources, and integration details for companies registered in Alberta
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Alberta) reference is on the [Canada (Alberta) country page](https://www.topograph.co/countries/ca-ab).
## Start here
This guide contains public integration notes for `CA-AB`, the Alberta register. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Alberta) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-AB` covers entities registered in Alberta.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A federal corporation that registers in Alberta to do business there keeps its own record in [Canada (Federal)](/essentials/canada-federal): its Alberta registration is returned here flagged as such, with the federal corporation number and Business Number to use with `countryCode: "CA-FED"`. `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Canada's Business Registries | **Primary source** for search and company data (business corporations and limited partnerships) | Name, entity type, status, incorporation or registration date, registered office city, Business Number when published, and the link between a company's registrations across provinces. Updated daily by the Alberta register. |
| Alberta Registrar's Periodical | Search and company data for the other Alberta entities | Every incorporation, registration, continuance, amalgamation, name change and revival the Alberta Corporate Registry has published since 2006, with the entity type and registered address |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches the corporate access number |
**Directors and shareholders are not offered yet.** The Alberta record does not list them; they are only on the corporate search Alberta sells through registry agents. A federal corporation registered in Alberta has its directors and beneficial owners in [Canada (Federal)](/essentials/canada-federal).
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Corporate access number** | 9 or 10 digits; partnerships: `LP`, `AL` or `EL` followed by 7 or 8 digits | `2028462931`, `LP4270245` | Assigned by the Alberta Corporate Registry. Spaces and hyphens are ignored. |
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `corporateAccessNumber` | 9 or 10 digits, or a 2-letter partnership prefix and 7 or 8 digits | `2028462931` | All entities. Same value as `company.id` |
| `businessNumber` | 9 digits (the BN root) | `139829337` | When the register publishes it; for the Alberta registration of a federal corporation, the federal corporation's BN |
| `lei` | 20 letters and digits | | When GLEIF has a unique match |
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `ATCO` | Name | Business corporations and limited partnerships live; other Alberta entities from the Registrar's Periodical |
| By corporate access number | `2028462931`, `LP4270245` | `id` | Exact match |
| By Business Number | `139829337` or `139829337RC0001` | `id` | Returns the Alberta records carrying that BN |
Search is free. Only company data retrieval is charged.
### Active companies only
Search returns inactive companies too. Business corporations and limited partnerships carry the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Entities found only in the Registrar's Periodical carry no status and are kept.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Alberta business corporations (named, numbered, professional) | Yes | Company data with status |
| Limited partnerships | Yes | Company data with status |
| Societies, non-profit companies, cooperatives, limited liability partnerships | Partial | Company data from the Registrar's Periodical, without status |
| Alberta registrations of federal or other-province corporations | Flagged | Returned with their home jurisdiction and, for a federal corporation, the number to use with `CA-FED` |
| Sole proprietorships and trade names | No | Not covered |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Extra-provincial registrations** | A corporation incorporated federally or in another province also has an Alberta number. Its company record says so in `status.statusDetails.additionalInfo` (home jurisdiction and number there), its legal form is `Extra-Provincial Corporation`, and its `businessNumber` links it to the home record. |
| **Registered office city only** | Canada's Business Registries publishes the city and province of the registered office, not the street address. Entities read from the Registrar's Periodical carry the full address published with their latest registration notice, which may have changed since. |
| **Periodical entities have no status** | The Registrar's Periodical lists dissolutions and strike-offs by name only, without the corporate access number, so no status is returned for an entity found only there. |
| **No beneficial owners** | Alberta has no public register of beneficial owners. |
| **No activity codes** | The register publishes no industry classification. |
## Mappings
### Company Status
| Local Status | `active` | Standardized Status |
| - | - | - |
| Active | `true` | `ACTIVE` |
| Inactive | `false` | `CLOSED` |
| Struck | `false` | `CLOSED` (administrative dissolution) |
| Dissolved | `false` | `CLOSED` |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes | Live for business corporations and limited partnerships; Registrar's Periodical for other entities |
| `legalRepresentatives` | Not yet | Not on the Alberta record; only on the corporate search |
| `shareholders` | Not yet | Not on the Alberta record; only on the corporate search |
| `ultimateBeneficialOwners` | No | No public beneficial-ownership register in Alberta |
| Documents | No | No document is offered yet |
# Canada (British Columbia)
Source: https://docs.topograph.co/essentials/canada-british-columbia
Identifiers, data sources, and integration details for companies and other entities registered in British Columbia
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (British Columbia) reference is on the [Canada (British Columbia) country page](https://www.topograph.co/countries/ca-bc).
## Start here
This guide contains public integration notes for `CA-BC`, the British Columbia register. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (British Columbia) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-BC` covers entities registered with BC Registries.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A federal corporation that registers in British Columbia to do business there keeps a BC registration (prefix `A`), which `CA-BC` returns flagged as such, but the company itself is a [Canada (Federal)](/essentials/canada-federal) company: use `countryCode: "CA-FED"` and its corporation number for its directors and beneficial owners. `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Federal and other extraprovincial companies](#federal-and-other-extraprovincial-companies)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| BC Registries and Online Services, as published on OrgBook BC | **Primary source** for search and company data | Every BC registration, active and historical: name and former names, entity type, status and the filing or event behind it, registration date, Business Number, home jurisdiction of an extraprovincial registration, names the entity does business as |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches |
Search and company data are read live from the register's public directory, which BC Registries updates within about 30 minutes of a filing. The directory carries **no address and no people**: BC law keeps them off this publication. Directors and officers are not offered yet: the register lists them only on a report.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **BC incorporation or registration number** | A letter prefix of 1 to 3 letters followed by 7 digits, no space | `BC0922942` | Assigned by BC Registries. Keep the prefix: it is part of the number. `/v2/company` accepts lower case and spaces and returns the canonical form |
Prefixes observed on the register, with the entity type it records for them:
| Prefix | Entity types |
| - | - |
| `BC` | BC company, BC unlimited liability company, community contribution company, benefit company |
| `C` | Company continued into British Columbia (also as an unlimited liability company) |
| `FM` | Sole proprietorship, general partnership |
| `S`, `CS` | Society, society continued into British Columbia |
| `CP` | Cooperative association |
| `LP`, `LL` | Limited partnership, limited liability partnership |
| `A` | Extraprovincial company (formed outside British Columbia, federal corporations included) |
| `XP`, `XL`, `XS`, `XCP`, `LLC` | Extraprovincial limited partnership, limited liability partnership, society, cooperative, limited liability company |
| `QA` to `QE`, `PA`, `FI`, `LIB`, `B`, `EPR`, `FOR`, `REG`, `LIC` | Older registers and special entities (companies under the acts before 1897, private acts, financial institutions, library associations, former extraprovincial registers) |
The Business Number (BN) is **not** accepted by `/v2/company`: several registrations can share one (an amalgamated company keeps it, and a company shares it with the sole proprietorships it registers as trade names). Search by BN first and use the registration number it returns.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `incorporationNumber` | Letter prefix + 7 digits | `BC0922942` | Every registration. Same value as `company.id` |
| `businessNumber` | 9 digits (the BN root) | `844222687` | Most registrations. Issued by the Canada Revenue Agency; it links a federal corporation's BC registration to its `CA-FED` record |
| `lei` | 20 letters and digits | | When GLEIF has a unique match |
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `TELUS CORPORATION` | Name | Ranked by the register's relevance. Active and historical registrations |
| By registration number | `BC0922942`, `bc 0922942` | `id` | Exact match |
| By Business Number | `844222687` or `844222687BC0001` | `partialId` | Returns every registration carrying the BN |
Search is free. Only company data retrieval is charged.
### Active companies only
Search returns historical registrations too (dissolved, amalgamated, cancelled). [`activeOnly=true`](/essentials/search#active-companies-only) is passed to the register, which leaves them out.
## Supported Entity Types
| Entity type | Company data |
| - | - |
| BC companies (limited, unlimited liability, community contribution, benefit) | Yes |
| Cooperatives and societies | Yes |
| Sole proprietorships and partnerships | Yes, under the name the firm is registered with |
| Extraprovincial registrations | Yes, flagged with the home jurisdiction; for a federal corporation, use `CA-FED` |
| Historical registrations | Yes, reported as closed with the filing or event that ended them |
## Federal and other extraprovincial companies
A company formed outside British Columbia registers here as an **extraprovincial** entity (prefix `A`, `XP`, `XL`, `XS`, `XCP` or `LLC`). `CA-BC` returns that registration as it is, never as a BC incorporation:
* `legalForm.localName` is the register's extraprovincial type (for example `Extraprovincial Company`);
* `status.statusDetails.additionalInfo` names the home jurisdiction. For a corporation formed under federal law it reads *"Extraprovincial registration in British Columbia of a corporation formed under federal law (home jurisdiction: Canada, federal). Its own record is Canada (Federal), CA-FED, with Business Number …"*;
* `identifiers.businessNumber` is the link to the `CA-FED` record, where the corporation's directors and beneficial owners are.
When an extraprovincial registration is historical, the **BC registration** has ended (cancelled or withdrawn). The entity may still exist in its home jurisdiction, so the closure reason is never stronger than what the register recorded.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No address** | The register's public directory carries no address. `legalAddress` is absent. |
| **No people** | Directors and officers, and the proprietor or partners of a firm, are not offered yet: the register lists them only on a report. |
| **Firms are registered under their trade name** | A sole proprietorship or partnership (`FM` numbers) is registered under the name it trades under; that is its `legalName`. |
| **Trade names of a company** | Firms a company registered and does business as are returned in `commercialNames`. |
| **Former names** | Earlier registered names are returned in `legacyLegalNames`. |
| **Registration date** | `registrationDate` is when the entity was registered in British Columbia: incorporation, continuation in, amalgamation, or extraprovincial registration. `incorporationDate` is not returned. |
| **Dissolution process** | An active company the register has moved into the administrative dissolution process stays `active: true`, with the standardized status `PENDING_DISSOLUTION` and the event in `additionalInfo`. |
| **No shareholders** | BC Registries does not publish shareholders. |
| **No beneficial owners** | BC companies keep their transparency register of individuals with significant control privately; the public register the province has legislated is not open yet. |
| **No activity codes** | The register records no industry classification. |
## Mappings
### Company Status
| Local Status | `active` | Standardized Status |
| - | - | - |
| Active | `true` | `ACTIVE`, or `PENDING_DISSOLUTION` while the register is dissolving it |
| Historical | `false` | `CLOSED`, with the closure reason read from the filing or event that ended the registration (voluntary or administrative dissolution, amalgamation, liquidation, court order, continuation out) and its label in `additionalInfo` |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company data | Yes | Legal name, former names, entity type, status, registration date and Business Number, live from the register |
| Legal representatives | Not yet | Not offered yet: the register lists directors and officers only on a report. |
| Shareholders | No | Not published by the register |
| Ultimate beneficial owners | No | Not public in British Columbia; for a federal corporation, see `CA-FED` |
| Documents | No | No document is offered yet |
# Canada (Federal)
Source: https://docs.topograph.co/essentials/canada-federal
Identifiers, data sources, and integration details for federally incorporated Canadian corporations
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Federal) reference is on the [Canada (Federal) country page](https://www.topograph.co/countries/ca-fed).
## Start here
This guide contains public integration notes for `CA-FED`, the federal register of Canada. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Federal) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-FED` covers corporations incorporated under a federal act only.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A company incorporated in Ontario, Quebec, British Columbia or any other province or territory is not in this register, even if it operates nationwide. Provinces and territories are separate jurisdictions (`CA-ON`, `CA-QC`, and so on), the same way US states are. Use `countryCode: "CA-FED"` on `/v2/company`; `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
All `CA-FED` data comes from **Corporations Canada**, the federal corporate register run by Innovation, Science and Economic Development Canada (ISED). It holds every corporation incorporated, continued or amalgamated under a federal act: the Canada Business Corporations Act (CBCA, 1975), the Canada Not-for-profit Corporations Act (2009), the Canada Cooperatives Act (1998), and a few older or special acts.
| Source | Role | What it provides |
| - | - | - |
| Corporations Canada, federal corporation record | **Primary source** for company data, directors and beneficial owners | Names and name history, status, governing act, registered office, Business Number, annual filings, directors, individuals with significant control |
| Corporations Canada open data | **Search** | Every federal corporation, active and inactive, published by the register daily under the Open Government Licence - Canada |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches the corporation number |
Company data, directors and beneficial owners are read live from the corporation's public record at Corporations Canada, so every request reflects the register as it stands. One read serves all three datapoints.
**Beneficial owners are filed by business corporations only.** Since 22 January 2024, corporations governed by the CBCA must file their individuals with significant control with Corporations Canada, which publishes part of that information. Not-for-profit corporations, cooperatives and the other federal forms have no such obligation.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Corporation number** | Digits only, no leading zero. 4 to 8 digits in the records we have seen | `8660115` | Assigned by Corporations Canada. The register displays it with a hyphen before the last digit (`866011-5`) and sometimes zero-padded (`059585-3`); `/v2/company` accepts both and returns the canonical form (`8660115`, `595853`). |
The Business Number (BN) is **not** accepted by `/v2/company`, because several corporations can share one (an amalgamated corporation keeps one of its predecessors' BNs). Search by BN first and use the corporation number it returns.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `corporationNumber` | Digits only, no leading zero (4 to 8 digits seen) | `8660115` | All corporations. Same value as `company.id` |
| `businessNumber` | 9 digits (the BN root) | `835752437` | Almost every active corporation. Issued by the Canada Revenue Agency; program account suffixes (`RC0001`) are dropped |
| `lei` | 20 letters and digits | | When GLEIF has a unique match (see below) |
A federal corporation that registers to do business in a province also gets a provincial registration number there. That number is not the corporation number and is not returned under `CA-FED`.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when the corporation number has a unique match against a GLEIF record registered with Corporations Canada.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `MINDANGLER CAPITAL` | Name | Full-text match on the name in either official language |
| By corporation number | `8660115`, `866011-5`, or the zero-padded `059585-3` | `id` | Exact match |
| By Business Number | `835752437` | `id` | Returns every corporation that shares the BN |
| By BN program account | `835752437RC0001` | `id` | Resolved to the 9-digit BN |
**Search runs on the register's daily open data.** A corporation incorporated since the latest daily publication is found by search the next day. Its corporation number can usually be passed to `/v2/company` before then, since company data is read live from the register, but the register itself can take a short while to publish a brand new record.
Search is free. Only company data retrieval is charged.
### Active companies only
Search returns inactive and dissolved corporations too. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Business corporations (CBCA) | Yes | The large majority of the register. Directors and beneficial owners |
| Not-for-profit corporations | Yes | Directors. No beneficial owners (not filed under this act) |
| Cooperatives | Yes | Directors. No beneficial owners |
| Boards of trade, special act corporations, pension fund societies | Yes | Directors. No beneficial owners |
| Inactive, amalgamated and dissolved corporations | Yes | Reported as closed, with the date and, for an amalgamation, the successor |
| Provincially incorporated companies | No | Not on the federal register. Covered by the provincial jurisdictions as they ship |
| Sole proprietorships and partnerships | No | Registered with the provinces, not with Corporations Canada |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Federal only** | A company incorporated in a province is not in this register. Ontario and Quebec companies are not found under `CA-FED` unless they were incorporated federally. |
| **Two official-language names** | A corporation can have an English and a French form of its name. The first is `legalName`; the other form is returned in `commercialNames`. Name search matches either. |
| **Name history** | Former names are returned in `legacyLegalNames`. |
| **Two dates** | `incorporationDate` is the date of the certificate of incorporation or amalgamation. `registrationDate` is the date the corporation came under its current act, which differs for a corporation that was continued from another jurisdiction or amalgamated. |
| **Business Number is shared after amalgamations** | An amalgamated corporation keeps one of its predecessors' BNs, so a BN search can return the inactive predecessor and the active successor. Pick by status. |
| **Directors only, no officers** | Corporations Canada records directors (name and address). Officers such as the president or secretary are not filed with the register. |
| **Director addresses** | The register publishes the address a director filed. Many directors file the corporation's own address ("c/o"), so the address is not always residential. |
| **No shareholders** | Corporations keep their securities register at their own records office; the federal register does not publish shareholders. Beneficial owners are the ownership answer. |
| **Beneficial owners: current only** | Individuals who have ceased to have significant control are not returned. |
| **Beneficial owners: ranges, not exact percentages** | The register publishes a band (for example "more than 75% of the shares"), returned as `percentageRange`. |
| **Beneficial owners: empty lists are answers** | `ultimateBeneficialOwners` succeeds with `[]` when the corporation has not filed yet, when it is a public corporation listed on a designated stock exchange or its wholly-owned subsidiary (excluded by law), or when its act has no beneficial-ownership filing (not-for-profits, cooperatives, other federal forms). Individuals under 18 are not made public by the register. |
| **Annual filings** | The register states whether each of the last annual returns was filed, overdue or not yet due. That is returned in `statutoryFilings.annualFiling` as years, without a due date, because the register gives the filing window as a month and day only. |
| **Dissolution pending is still active** | A corporation the register intends to dissolve for non-compliance stays `active: true`, with the standardized status `PENDING_DISSOLUTION`. |
| **No activity codes** | The federal register records no industry classification. |
| **No documents yet** | Certificates and filed documents are ordered from Corporations Canada and delivered by email. They are not offered yet. |
## Mappings
### Company Status
The register publishes a status and, for most cases, a status detail. `status.localName` is the detail when there is one, else the status. Extra wording the register prints (such as the section of the act) and the successor of an amalgamation go to `status.statusDetails.additionalInfo`; the date of a closure goes to `closureDate`.
| Local Status | Meaning | `active` | Standardized Status |
| - | - | - | - |
| Active | Active | `true` | `ACTIVE` |
| Active - Dissolution Pending (non-compliance) | The register has started dissolving it for failing to file | `true` | `PENDING_DISSOLUTION` |
| Active - Intent to Dissolve Filed | The corporation has filed to dissolve itself | `true` | `PENDING_DISSOLUTION` |
| Active - Discontinuance Pending | Moving to another jurisdiction | `true` | `ACTIVE` |
| Inactive | Inactive | `false` | `CLOSED` |
| Inactive - Amalgamated | Merged into another corporation | `false` | `CLOSED` (merger) |
| Inactive - Discontinued | Continued under the law of another jurisdiction | `false` | `CLOSED` |
| Dissolved | Dissolved | `false` | `CLOSED` |
| Dissolved for non-compliance | Dissolved by the register for failing to file | `false` | `CLOSED` (administrative dissolution) |
| Dissolved by the corporation | Voluntary dissolution | `false` | `CLOSED` (voluntary dissolution) |
| Dissolved by court order | Court-ordered dissolution | `false` | `CLOSED` (court order) |
| Dissolved by Corporations Canada | Dissolved by the register | `false` | `CLOSED` (administrative dissolution) |
| Dissolved – Part II of CCA | Dissolved under the former Canada Corporations Act; the value alone does not say how | `false` | `CLOSED` (voluntary dissolution when the corporation filed its own dissolution, otherwise no reason) |
### Legal Forms
The federal register records no legal form as such: a corporation's form is the act it is governed by. `legalForm.localName` is that act.
| Local Name (governing act) | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Canada Business Corporations Act | Business corporation (CBCA) | Corporation | `UDLA` |
| Canada Not-for-profit Corporations Act | Not-for-profit corporation | Nonprofit Organization | `D90J` |
| Canada Cooperatives Act | Cooperative | Cooperative | `MGE0` |
| Boards of Trade Act - Part I | Board of trade | Nonprofit Organization | `59T2` |
| Boards of Trade Act - Part II | Board of trade | Nonprofit Organization | `59T2` |
| Special Act of Parliament | Corporation created by a special Act of Parliament | Other | `6TRA` |
| Pension Fund Societies Act | Pension fund society | Other | `M4IF` |
| Other | Other federal act | Other | - |
| Canada Corporations Act - Part II (discontinued) | Corporation without share capital (former act) | Nonprofit Organization | `D90J` |
| Canada Corporations Act Part I - Private (discontinued) | Private company (former act) | Corporation | - |
| Canada Corporations Act Part I - Public (discontinued) | Public company (former act) | Corporation | - |
| Canada Cooperative Associations Act (discontinued) | Cooperative association (former act) | Cooperative | `MGE0` |
| More than 1 Act Applicable (discontinued) | Governed by more than one act | Other | - |
### Legal Representatives
| Local Role Name | English Translation | Standardized |
| - | - | - |
| Director | Director | `Director` |
Directors are always individuals under federal law. Each is returned with `type: "individual"`, `corporateBody: "board"`, and the address the director filed in `individual.residenceAddress`. The register publishes no appointment dates for directors.
### Ultimate Beneficial Owners
Corporations Canada calls beneficial owners **individuals with significant control** (ISC). An ISC owns, controls or directs 25% or more of the shares (by votes or by value), alone or jointly, or has control in fact over the corporation.
| What the register states | How it is returned |
| - | - |
| Owns, controls or directs 25% or more of the shares | `control.types: ["ownership-of-shares"]`, with the band in `control.details[].percentageRange` |
| Has control in fact without owning shares | `control.types: ["significant-influence-or-control"]`, no band |
| Held directly / indirectly | `control.details[].nature`: `direct` / `indirect` (`null` when the register says both) |
| Band, such as "More than 75% of the shares" | `percentageRange: { "lower": 75, "upper": 100 }` |
| Address for service, else residential address | `residenceAddress` |
The register's own wording (type of interest, how the shares are held, individually or jointly, the band, the start date) is kept in `control.description`.
### Addresses
`legalAddress` is the registered office. The province or territory code is in `state` (on search results too), Newfoundland and Labrador is returned as `NL`, postal codes read `A1A 1A1`, and `countryCode` is `CA`. When the registered office is in someone's care, that party is in `careOf`, not in the street lines. Directors and beneficial owners living abroad are returned with their own country and no province.
### Activity Code Mapping
Not applicable. The federal register records no industry classification, so `activities` is not returned.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company profile (`company`) | Yes | Legal name, other-language name, former names, status, governing act, incorporation date, registered office, Business Number, annual filings |
| Legal representatives (`legalRepresentatives`) | Yes | Directors, with the address they filed. Every federal act |
| Ultimate beneficial owners (`ultimateBeneficialOwners`) | Business corporations (CBCA) | Current individuals with significant control. In a random sample of 120 federal corporations checked in August 2026, 90% had them on record. Empty for listed corporations and for forms that do not file them |
| Other key persons | No | Officers are not filed with the register |
| Shareholders | No | Not published by the register |
| Establishments | No | Not recorded by the federal register |
| Activity codes | No | Not recorded by the federal register |
| Statutory filings | Yes | `statutoryFilings.annualFiling`: last filed year, next year and whether it is overdue |
| Documents | No | Not offered yet |
## Example API Responses
All examples use placeholder data.
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=CA-FED&query=700000001" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "7654321",
"legalName": "EXAMPLE HOLDINGS INC.",
"countryCode": "CA-FED",
"matchReason": { "matchType": "id" },
"address": { "city": "Toronto", "state": "ON", "countryCode": "CA" }
}
]
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "CA-FED", "id": "765432-1", "dataPoints": ["company", "legalRepresentatives"]}'
```
```json theme={null}
{
"company": {
"id": "7654321",
"countryCode": "CA-FED",
"identifiers": { "corporationNumber": "7654321", "businessNumber": "700000001" },
"legalName": "EXAMPLE HOLDINGS INC.",
"commercialNames": ["PLACEMENTS EXEMPLE INC."],
"legacyLegalNames": ["7654321 CANADA INC."],
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": {
"localName": "Canada Business Corporations Act",
"englishTranslation": "Business corporation (CBCA)",
"standardized": "Corporation",
"iso20275Code": "UDLA"
},
"incorporationDate": "2010-05-12",
"registrationDate": "2010-05-12",
"legalAddress": { "addressLine1": "100 Example Street", "addressLine2": "Suite 200", "city": "Toronto", "state": "ON", "postalCode": "M5V 0A1", "countryCode": "CA" },
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"lastFiled": { "year": 2025 },
"next": { "year": 2026, "overdue": false },
"source": "corporations_canada"
}
}
},
"legalRepresentatives": [
{
"type": "individual",
"role": { "localName": "Director", "standardized": "Director" },
"corporateBody": "board",
"individual": {
"name": { "fullName": "Jane Example" },
"residenceAddress": { "addressLine1": "1 Sample Avenue", "city": "Toronto", "state": "ON", "postalCode": "M4W 1A1", "countryCode": "CA" }
}
}
]
}
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "CA-FED", "id": "7654321", "dataPoints": ["ultimateBeneficialOwners"]}'
```
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"name": { "fullName": "Jane Example" },
"residenceAddress": { "addressLine1": "1 Sample Avenue", "city": "Toronto", "state": "ON", "postalCode": "M4W 1A1", "countryCode": "CA" },
"control": {
"types": ["ownership-of-shares"],
"details": [{ "type": "shares", "percentageRange": { "lower": 75, "upper": 100 }, "nature": "direct" }],
"description": "Individual with significant control (Type of interest or control: Owns, controls or directs 25% or more of shares; Holds the shares: Directly; Significant control held: Individually; Holds: More than 75% of the shares; Since 2010-05-12)."
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "7000002",
"countryCode": "CA-FED",
"identifiers": { "corporationNumber": "7000002", "businessNumber": "700000001" },
"legalName": "EXAMPLE OPERATIONS LTD.",
"status": {
"localName": "Inactive - Amalgamated",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "MERGER",
"closureDate": "2024-06-05",
"additionalInfo": "Amalgamated into EXAMPLE HOLDINGS INC. (corporation number 7654321)"
}
}
}
}
```
# Canada (Manitoba)
Source: https://docs.topograph.co/essentials/canada-manitoba
Identifiers, data sources, and integration details for companies registered in Manitoba
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Manitoba) reference is on the [Canada (Manitoba) country page](https://www.topograph.co/countries/ca-mb).
## Start here
This guide contains public integration notes for `CA-MB`, the Manitoba register. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Manitoba) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-MB` covers entities registered in Manitoba.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A federal corporation that registers in Manitoba keeps its own record in [Canada (Federal)](/essentials/canada-federal): its Manitoba registration is returned here flagged as such, with the federal corporation number and Business Number to use with `countryCode: "CA-FED"`. `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Quirks & Gotchas](#quirks--gotchas)
* [Data Availability](#data-availability)
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Canada's Business Registries | **Primary source** for search and company data | Name, entity type, status, incorporation or registration date, registered office city, Business Number when published, and the link between a company's registrations across provinces. Updated daily by the Manitoba Companies Office |
| Manitoba Companies Office, weekly filing listings | Search (supplementary) | Every incorporation, registration, amendment, amalgamation, revival and dissolution the Companies Office publishes each week, with the registered office |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches the registry number |
**Directors and officers are not offered yet.** The Companies Office lists them only on a report sold through an account-only service.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Registry number** | 5 to 8 digits | `10084092` | Assigned by the Manitoba Companies Office ("File No."). |
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `registryNumber` | 5 to 8 digits | `10084092` | All entities. Same value as `company.id` |
| `businessNumber` | 9 digits (the BN root) | `120721048` | When published; for the Manitoba registration of a federal corporation, the federal corporation's BN |
| `lei` | 20 letters and digits | | When GLEIF has a unique match |
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `Bison Transport` | Name | Share corporations and limited partnerships live; other entities once a weekly filing listing has named them |
| By registry number | `10084092` | `id` | Exact match |
| By Business Number | `120721048` or `120721048MC0005` | `id` | Returns the Manitoba records carrying that BN |
Search is free. Only company data retrieval is charged.
### Active companies only
Search returns inactive companies too. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Manitoba share corporations | Yes | Company data |
| Limited partnerships | Yes | Company data |
| Manitoba registrations of federal or other-province corporations | Flagged | Returned with their home jurisdiction and number there; directors are on the home record |
| Non-share corporations and co-operatives | Partial | Found by search once a weekly filing listing names them |
| Business names | No | Not covered |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Extra-provincial registrations** | A corporation incorporated federally or in another province also has a Manitoba registry number. Its legal form is extra-provincial (standardized by its own form, for example `Corporation`), it carries no incorporation date, `status.statusDetails.additionalInfo` names its home jurisdiction and number, and `businessNumber` links it to the home record. |
| **Registered office city only** | Company data publishes the city of the registered office, not the street address. |
| **No people** | Directors and officers are not offered yet: the register lists them only on a report. |
| **No shareholders, no beneficial owners** | The Companies Office publishes neither. |
| **No activity codes** | The register publishes no industry classification. |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes | Live |
| `legalRepresentatives` | Not yet | Not offered yet: the register lists directors and officers only on a report. |
| `shareholders` | No | Not published |
| `ultimateBeneficialOwners` | No | Not public |
| Documents | No | No document is offered yet |
# Canada (Newfoundland and Labrador)
Source: https://docs.topograph.co/essentials/canada-newfoundland-and-labrador
Identifiers, data sources, and integration details for companies incorporated in Newfoundland and Labrador
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Newfoundland and Labrador) reference is on the [Canada (Newfoundland and Labrador) country page](https://www.topograph.co/countries/ca-nl).
## Start here
This guide contains public integration notes for `CA-NL`, the Newfoundland and Labrador register. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Newfoundland and Labrador) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-NL` covers companies incorporated in Newfoundland and Labrador.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A federal corporation that registers in Newfoundland and Labrador to do business there is a [Canada (Federal)](/essentials/canada-federal) company: use `countryCode: "CA-FED"` and its corporation number. `CA` on its own is not a jurisdiction.
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Registry of Companies (Newfoundland and Labrador) | **Primary register**, read live | Search, company record, current directors |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches the company number |
Company data and directors come from one live read of the company's public record on the Registry of Companies.
## Company Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Company number** (`companyNumber`) | Up to 6 digits (e.g. 21782, 100547); some older registrations end with a letter (e.g. 4239F, 394I) | `21782` | Assigned by the Registry of Companies to every company it incorporates or registers, extra-provincial companies included. Same value as `company.id`. |
## Search Capabilities
| Search Type | Example | Notes |
| - | - | - |
| By company number | `21782`, `4239F` | Exact match |
| By name | `Fortis` | The words of the query are matched anywhere in a current or former company name |
Search reads the register live, returns inactive companies too (each with its status, so `activeOnly=true` filters them), and lists extra-provincial registrations alongside local companies. A single very common word can be refused by the register: add a word.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Extra-provincial companies** | A company incorporated elsewhere and registered in the province is returned as a registration, never as a Newfoundland and Labrador incorporation: `status.statusDetails.additionalInfo` states where it was incorporated, and a federal corporation is pointed to `CA-FED`. The register publishes neither its federal corporation number nor its Business Number. |
| **Directors only, names only** | The register lists the current directors of a company incorporated in the province, by name. Officers and addresses are not published, and no director is listed for an extra-provincial company. |
| **Good standing** | An active company "Not in Good Standing" (late annual returns) stays `active: true`; the mention is in `status.statusDetails.additionalInfo`. |
| **Former names** | Returned in `legacyLegalNames`. |
| **No shareholders, no beneficial owners** | The register keeps no shareholder list, and individuals with significant control are recorded by each company itself, not filed with the register. |
| **No documents** | Copies of filings are viewable only under a licence the Registrar grants to approved organizations. |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes | Name and former names, status, business type, incorporation and registration dates, registered office |
| `legalRepresentatives` | Yes | Current directors (names) of companies incorporated in the province |
| `shareholders` | No | Not kept by the register |
| `ultimateBeneficialOwners` | No | Not filed with the register |
| Documents | No | Licence required |
# Canada (Northwest Territories)
Source: https://docs.topograph.co/essentials/canada-northwest-territories
Identifiers, data sources, and integration details for entities formed in the Northwest Territories
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Northwest Territories) reference is on the [Canada (Northwest Territories) country page](https://www.topograph.co/countries/ca-nt).
## Start here
This guide contains public integration notes for `CA-NT`, the Northwest Territories register. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Northwest Territories) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-NT` covers entities formed in the Northwest Territories.** A federal corporation registered there to do business is a [Canada (Federal)](/essentials/canada-federal) company: use `countryCode: "CA-FED"` and its corporation number. `CA` on its own is not a jurisdiction.
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Corporate Registries (Northwest Territories), public search | **Primary register**, read live | Search, entity name, type, status and jurisdiction |
| GLEIF | Supplementary | Legal Entity Identifier (LEI) |
## Company Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **File number** (`fileNumber`) | 6 digits in the records we have seen (e.g. 502328, 605523); older GLEIF records also show a letter prefix (e.g. C4459) | `502328` | Assigned to every registered entity, extra-territorial corporations and business names included. |
## Search Capabilities
| Search Type | Example | Notes |
| - | - | - |
| By file number | `502328` | Exact match |
| By name | `Nahanni` | The text is matched anywhere in a current, former or trade name |
The register lists at most 100 entities: a broader name is refused and must be made more specific. Inactive entities are returned with their status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Company data is a summary** | The public search publishes the name, former and trade names, entity type, status and jurisdiction only: no address, no date, no people. |
| **No directors yet** | The public search shows no people. Directors are only on the Entity Profile, which is not offered yet: `legalRepresentatives` is answered as not supported. |
| **Extra-territorial corporations** | Returned as registrations, with their home jurisdiction in `status.statusDetails.additionalInfo`; a federal corporation is pointed to `CA-FED`, where its directors are. |
| **In Default** | An entity that missed an annual filing stays `active: true`, standardized as `INACTIVE_NOT_CLOSED`. |
| **Nunavut Entity** | A Northwest Territories corporation that became a Nunavut corporation in 1999 is closed here. |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes, live | Summary from the public search |
| `legalRepresentatives` | Not yet | Directors are only on the Entity Profile, not offered yet |
| `shareholders` | No | Not published |
| `ultimateBeneficialOwners` | No | No public register |
# Canada (Nova Scotia)
Source: https://docs.topograph.co/essentials/canada-nova-scotia
Identifiers, data sources, and integration details for companies registered in Nova Scotia
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Nova Scotia) reference is on the [Canada (Nova Scotia) country page](https://www.topograph.co/countries/ca-ns).
## Start here
This guide contains public integration notes for `CA-NS`, the Nova Scotia register. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Nova Scotia) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-NS` covers entities registered in Nova Scotia.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A federal corporation that registers in Nova Scotia to do business there keeps its own record in [Canada (Federal)](/essentials/canada-federal): its Nova Scotia registration is returned here flagged as such (a branch registration, with its home jurisdiction), never as a Nova Scotia incorporation. `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Quirks & Gotchas](#quirks--gotchas)
* [Data Availability](#data-availability)
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Registry of Joint Stock Companies (RJSC Connect) | **Primary source** for search, company data and legal representatives | Registered name, former and trade names, entity type, status and its date, registration date, registered office, directors, officers with the office held, partners |
| Canada's Business Registries | Supplementary | Business Number of Nova Scotia records |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches the registry ID |
Search, company data and legal representatives are read live from the public record of the Registry of Joint Stock Companies, so every request reflects the register as it stands. One read serves both datapoints. A read takes up to a minute, so company data is available in `verification` mode only, not in `onboarding` mode.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Registry ID** | 7 digits | `3023784` | Assigned by the Registry of Joint Stock Companies ("Reg. Number"). Spaces are ignored. |
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `registryId` | 7 digits | `3023784` | All entities. Same value as `company.id` |
| `businessNumber` | 9 digits (the BN root) | `104902135` | When the register publishes it on Canada's Business Registries |
| `lei` | 20 letters and digits | | When GLEIF has a unique match |
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `Sobeys` | Name | Every entity whose name contains the words, at most 50 results, exact matches and active entities first |
| By registry ID | `3023784` | `id` | Exact match |
Search is free. Only company data retrieval is charged.
### Active companies only
Search returns inactive entities too (struck off, revoked, amalgamated, dissolved). Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the closed ones. A registration revoked less than a year ago can still be reinstated and is kept.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Limited companies, unlimited companies (ULC), private investment holding companies | Yes | Company data, directors and officers |
| Co-operatives, societies | Yes | Company data, directors and officers |
| Partnerships, limited partnerships, sole proprietorships | Yes | Company data; partners (people or corporations) |
| Nova Scotia registrations of federal, other-province or foreign corporations | Flagged | Returned as an extra-provincial registration with its home jurisdiction; directors and officers as filed in Nova Scotia |
| Business names and name reservations | No | Trade names and reservations are not entities; a company's active business names are returned as its trade names |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Extra-provincial registrations** | A corporation incorporated federally or in another province also has a Nova Scotia registry ID. Its legal form is the extra-provincial type (`Extra-provincial Corporation Federal`, standardized as `Corporation`), it carries no incorporation date, and `status.statusDetails.additionalInfo` names its home jurisdiction (`CA-FED` for a federal corporation). |
| **Officers and their offices** | Officers hold one of the register's offices (President, Vice-president, Secretary, Treasurer) or an office in the filer's own words, returned as typed (`EXECUTIVE VICE PRESIDENT & CHIEF FINANCIAL OFFICER`) with the standardized role read from the title. A person with two offices appears once per office. |
| **No addresses for people** | The register publishes no address for directors and officers. |
| **The recognized agent is not returned** | The person or firm that accepts service in Nova Scotia is not a legal representative. |
| **No shareholders, no beneficial owners** | The register publishes neither. Nova Scotia companies keep their register of individuals with significant control themselves. |
| **No activity codes** | The register records no industry classification. |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes | Live from the register |
| `legalRepresentatives` | Yes | Directors, officers and partners, live from the register |
| `shareholders` | No | Not published |
| `ultimateBeneficialOwners` | No | Not public |
| Documents | Not yet | Filed documents and profile reports are sold by the register |
# Canada (Ontario)
Source: https://docs.topograph.co/essentials/canada-ontario
Identifiers, data sources, and integration details for companies incorporated in Ontario
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Ontario) reference is on the [Canada (Ontario) country page](https://www.topograph.co/countries/ca-on).
## Start here
This guide contains public integration notes for `CA-ON`, the Ontario register. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Ontario) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-ON` covers corporations incorporated in Ontario.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A federal corporation that registers in Ontario to do business there is a [Canada (Federal)](/essentials/canada-federal) company: use `countryCode: "CA-FED"` and its corporation number. `CA-ON` search does not return it, and its Ontario record, when asked for by Ontario Corporation Number, is flagged as an extra-provincial registration. `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Federal and other extra-provincial corporations](#federal-and-other-extra-provincial-corporations)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Ontario Business Registry (ServiceOntario) | **Primary source** for search and company data | Every corporation the register keeps, active and inactive: name and previous names, business type, status, incorporation or amalgamation date, governing jurisdiction, city of the registered or head office |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches |
Search and company data are read live from the register's public search. The public record carries **no street address, no Business Number and no people**. Directors and officers are not offered yet: the register lists them only on a report.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Ontario Corporation Number (OCN)** | Digits only, without leading zeros: 1 to 7 digits for corporations formed or registered before October 2021 (e.g. `294967`, `1216372`), 10 digits starting with `100` since then (e.g. `1001216372`) | `1216372` | Assigned by the Ontario Business Registry. `/v2/company` accepts spaces and hyphens and returns the canonical form |
A 9-digit number is **not** an OCN. On the Ontario register it is the Business Identification Number (BIN) of a business name or partnership, which `CA-ON` does not cover; elsewhere it is usually a Canada Revenue Agency Business Number, which the Ontario register does not publish.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `ontarioCorporationNumber` | 1 to 7 digits, or 10 digits starting with `100` | `1216372` | Every corporation. Same value as `company.id` |
| `lei` | 20 letters and digits | | When GLEIF has a unique match |
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `KUUS INC.` | Name | Ranked by the register's relevance; the first 50 results are read. Active and inactive corporations |
| By Ontario Corporation Number | `1216372` | `id` | Exact match. The register also matches longer numbers that contain the one searched; only the exact number is returned |
Search is free. Only company data retrieval is charged.
Search returns **corporations formed in Ontario only**. Extra-provincial corporations (formed federally, in another province or territory, or abroad, and registered in Ontario) are left out, and so are the register's business names, sole proprietorships and partnerships. Results carry the city, province and country of the registered office.
### Active companies only
Search returns inactive corporations too (dissolved, cancelled, amalgamated). With [`activeOnly=true`](/essentials/search#active-companies-only) they are removed from the answer, from the status the register prints for each result.
## Supported Entity Types
| Entity type | Search | Company data |
| - | - | - |
| Ontario business corporations | Yes | Yes |
| Not-for-profit and non-share corporations | Yes | Yes |
| Co-operative corporations | Yes | Yes |
| Extra-provincial corporations | No | Yes by OCN, flagged with the governing jurisdiction; for a federal corporation, use `CA-FED` |
| Business names, sole proprietorships, partnerships | No | No |
## Federal and other extra-provincial corporations
A corporation formed outside Ontario that does business there registers as an **extra-provincial corporation** and receives an Ontario Corporation Number from the same series. `CA-ON` never presents it as an Ontario incorporation:
* search does not return it;
* asked for by its OCN, `legalForm.localName` is the register's type (for example `Extra-Provincial Federal Corporation with Share`), standardized by its own form (`Corporation`, or `Nonprofit Organization` without share capital);
* `status.localName` is the register's `Refer to Home Jurisdiction`, with the standardized status `UNKNOWN`: the Ontario register does not hold the corporation's status;
* `status.statusDetails.additionalInfo` names the governing jurisdiction. For a federal corporation it reads *"Extra-provincial registration in Ontario of a corporation formed under federal law (governing jurisdiction: Canada - Federal). Its own record is Canada (Federal), CA-FED; the Ontario register does not publish its federal corporation number or Business Number."*
Search the corporation by name in [Canada (Federal)](/essentials/canada-federal) for its own record, directors and beneficial owners.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **City only** | The public record gives the city, province and country of the registered or head office. `legalAddress` carries those three. |
| **No people** | Directors and officers are not offered yet: the register lists them only on a report. |
| **Previous names** | Earlier names are returned in `legacyLegalNames`. |
| **Incorporation date** | `incorporationDate` is the incorporation or amalgamation date the register prints. For an extra-provincial corporation it is the date it was formed in its home jurisdiction. |
| **Amalgamations** | An amalgamated corporation is inactive; its status details name the successor corporation and its OCN. |
| **No shareholders** | The register does not record shareholders. |
| **No beneficial owners** | Ontario private corporations keep their register of individuals with significant control at their registered office; it is not filed and not public. |
| **No activity codes** | The public record carries no industry classification. |
## Mappings
### Company Status
| Local Status | `active` | Standardized Status |
| - | - | - |
| Active | `true` | `ACTIVE` |
| Inactive | `false` | `CLOSED`, on the inactive date; closure reason `MERGER` with the successor in `additionalInfo` after an amalgamation, else `UNKNOWN` (the public record does not say why) |
| Refer to Home Jurisdiction | absent | `UNKNOWN`: an extra-provincial corporation, whose status is kept by its home jurisdiction |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company data | Yes | Legal name, previous names, business type, status, incorporation date, governing jurisdiction and city of the registered office, live from the register. Verification mode only |
| Legal representatives | Not yet | Not offered yet: the register lists directors and officers only on a report. |
| Shareholders | No | Not recorded by the register |
| Ultimate beneficial owners | No | Not public in Ontario; for a federal corporation, see `CA-FED` |
| Documents | No | No document is offered yet |
# Canada (Prince Edward Island)
Source: https://docs.topograph.co/essentials/canada-prince-edward-island
Identifiers, data sources, and integration details for entities formed or registered in Prince Edward Island
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Prince Edward Island) reference is on the [Canada (Prince Edward Island) country page](https://www.topograph.co/countries/ca-pe).
## Start here
This guide contains public integration notes for `CA-PE`, the Prince Edward Island register. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Prince Edward Island) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-PE` covers entities formed or registered in Prince Edward Island.** A federal corporation registered in the province is a [Canada (Federal)](/essentials/canada-federal) company: use `countryCode: "CA-FED"` and its corporation number for the company itself. `CA` on its own is not a jurisdiction.
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Corporate/Business Names Registry (Prince Edward Island) | **Primary**, read live | Search, the entity record (company data, directors and officers) |
The register keeps two systems: its current one, and the original one, which still holds non-profit corporations and co-operative associations and the records made before the register moved. We read both and return one record per entity.
## Company Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Registration number** (`registrationNumber`) | 1 to 6 digits | `15854` | The register's own number, kept in the company identifiers. Current records use their printed Business Number as the company id. |
| **Business Number** (`businessNumber`) | 9 digits | `102535762` | Issued by the Canada Revenue Agency and printed by the register. A trade name is printed as its owner's Business Number, a hyphen and its own registration number (`102535762-130724`). |
Search and company data use the printed Business Number as the id for current records, including the registration suffix for a trade name. The native registration number remains in the company identifiers. Non-profit corporations, co-operatives and older records use their registration number as the id.
## Search Capabilities
Search is live, by name, registration number or Business Number. A name search covers both systems of the register and lists corporations, co-operatives, non-profits, partnerships, sole proprietorships, trade names and extra-provincial registrations, active and inactive. A Business Number search returns the business and the trade names registered under it.
Each system returns at most 20 matches, exact names first. Rarely, a search can take up to a minute.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefill and verification read the same record** | `company` and `legalRepresentatives` are read live from the register in both modes, and the answer is the same. A prefill request usually takes a few seconds. Rarely, the register cannot be reached within the time limit of prefill mode: the request then fails with a retryable `source_unavailable` error. Retry after a minute, or use verification mode, which waits for the register. |
| **People** | Directors and officers are returned by name, with the office as filed. The owner of a sole proprietorship is returned as owner. The register prints the partners of a partnership and the owner of a trade name as bare names, without saying whether each is a person or a company: they are not returned. |
| **Extra-provincial registrations** | Returned as registrations, with their home jurisdiction in the status details. A corporation incorporated under federal law is pointed to Canada (Federal). |
| **Former records** | A corporation that moved to the current system is read there. When its current record cannot be matched, the original record is returned with its status explained. |
| **Unknown number** | If the register has no entity with the number, the request ends as not found and is not charged. |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes, live (prefill and verification) | Name, former and trade names, type, status, registration date, address, nature of business |
| `legalRepresentatives` | Yes, live (prefill and verification) | Directors and officers, or the owner of a sole proprietorship |
| `shareholders` | No | The register prints shareholder names on some records, without holdings |
| `ultimateBeneficialOwners` | No | No public register |
| Documents | No | The register issues no downloadable document; its record is returned as company data |
# Canada (Quebec)
Source: https://docs.topograph.co/essentials/canada-quebec
Identifiers, data sources, and integration details for enterprises registered in Quebec
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Quebec) reference is on the [Canada (Quebec) country page](https://www.topograph.co/countries/ca-qc).
## Start here
This guide contains public integration notes for `CA-QC`, the enterprise register of Quebec. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Quebec) is in beta. Check the live pricing page or contact support before relying on it in production.
**A company's jurisdiction is where it was incorporated.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. The Quebec register also records every federal and out-of-province corporation that does business in Quebec: such a record is a **registration in Quebec**, not a Quebec incorporation. `CA-QC` returns it as the Quebec register prints it, says in the legal form where the corporation was constituted, and, for a federal corporation, links it to its [Canada (Federal)](/essentials/canada-federal) record when the link is unambiguous. `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Registraire des entreprises du Québec, état de renseignements | **Primary source** for company data, directors and officers, shareholders and beneficial owners | Names, status, legal form and constituting act, head office, registration and constitution dates, economic activities, employees in Quebec, annual updates, directors and their offices, officers, partners, the three main shareholders, ultimate beneficiaries |
| Registraire des entreprises du Québec, open data | **Search**, and `company` in prefill mode | Every registered enterprise, active and struck off, with its names, status, legal form, head office, dates and employees in Quebec, published by the register twice a month. A new NEQ is looked up on the register itself |
| Corporations Canada | Supplementary | The federal corporation number and Business Number of a federal corporation registered in Quebec |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches the NEQ |
In verification mode (the default), company data, directors and officers, shareholders and beneficial owners are read live from the enterprise's public record (its *état de renseignements*), so every request reflects the register as it stands. One read serves all four datapoints.
In prefill mode, `company` is answered from the register's open-data file instead, in about a second. Only `company` is offered in prefill mode: the open data names no person. See [Prefill mode](#quirks--gotchas) below.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Québec enterprise number (NEQ)** | 10 digits starting with `11` (legal persons), `22` (sole proprietorships), `33` (partnerships and associations) or `88` (some public bodies) | `1140710543` | Assigned by the Registraire des entreprises to every enterprise registered in Quebec, for life. `/v2/company` accepts it with spaces or hyphens. |
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `neq` | 10 digits | `1140710543` | Every enterprise. Same value as `company.id` |
| `federalCorporationNumber` | Digits only, 4 to 8 digits | `4261607` | A federal corporation registered in Quebec, when Corporations Canada holds exactly one active corporation under the same name. Use it with `countryCode: "CA-FED"` |
| `businessNumber` | 9 digits | `835752437` | With `federalCorporationNumber`, as Corporations Canada records it. The Quebec register does not publish the Business Number |
| `lei` | 20 letters and digits | | When GLEIF has a unique match |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier. `company.identifiers.lei` is returned when the NEQ has a unique match against a GLEIF record registered with the Registraire des entreprises. Coverage varies by entity; the field is omitted when no unambiguous match is available.
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `Alimentation Couche-Tard` | Name | Legal names, versions in another language and every other name used in Quebec, current and former |
| By NEQ | `1140710543` or `1140 710 543` | `id` | Exact match |
**Search runs on the register's open data, refreshed twice a month.** An enterprise registered since the latest publication is found by NEQ (searched on the register itself, which takes longer) but not yet by name. `/v2/company` reads the register live in verification mode, and the same open data in prefill mode.
Search is free. Only company data retrieval is charged.
### Active companies only
Search returns struck-off enterprises too. Each result carries the registration status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes them.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Business corporations (*société par actions*) | Yes | Directors and officers, three main shareholders, beneficial owners |
| Federal and out-of-province corporations registered in Quebec | Yes | Flagged in the legal form; federal ones linked to `CA-FED` when unambiguous |
| Partnerships (general, limited, limited liability, undeclared) | Yes | Partners as owners; the partners who bind the partnership as representatives |
| Sole proprietorships | Yes | The person running the business as owner, representative and 100% beneficial owner. Searchable by trade name only |
| Non-profits, cooperatives, co-ownership syndicates, associations | Yes | Directors and officers. No shareholders |
| Struck-off enterprises | Yes | Reported as closed, with the date and the cause the register prints |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefill mode: open data, `company` only** | In prefill mode, `company` comes from the register's open data, published twice a month: names (with former names and versions in another language), status, legal form and where the enterprise was constituted, head office, registration and constitution dates, and employees in Quebec. It includes the primary and secondary economic activity codes under `company.activities.CAE_QC`, when declared. It does not include annual updates or the `CA-FED` link of a federal corporation. An enterprise registered since the latest publication, or a sole proprietorship without a trade name, ends as not found in prefill mode: request it in verification mode. `legalRepresentatives`, `shareholders` and `ultimateBeneficialOwners` are verification mode only. |
| **A registration is not an incorporation** | A federal corporation registered in Quebec has `legalForm.englishTranslation` "Business corporation, constituted under federal law (Canada) and registered in Quebec". Its `incorporationDate` is the date it was constituted (federally); `registrationDate` is the date it was registered in Quebec. Its directors and beneficial owners filed in Quebec may differ from its federal record. |
| **A struck-off registration is not a dissolution** | For a corporation constituted outside Quebec, a struck-off status ends its registration in Quebec only: `closureReason` is `OTHER` and `additionalInfo` says so. Check its home jurisdiction for its existence. |
| **Shareholders: the three largest, no percentages** | A business corporation declares its three shareholders with the most votes, in order, and whether the first holds the majority. No percentage is published, so `sharePercentage` is not returned. |
| **Beneficial owners: bands, since 2023** | Ultimate beneficiaries have been declared and public since 31 March 2023. The register publishes a band (for example "more than 75% of the voting rights"), returned as `percentageRange`, separately for voting rights and fair market value. |
| **Beneficial owners: empty lists are answers** | `ultimateBeneficialOwners` succeeds with `[]` when the enterprise is exempt by law (reporting issuers, non-profits, financial institutions, co-ownership syndicates and others), has not declared yet, or declared only an enterprise the law treats as a natural person (a reporting issuer often declares itself). |
| **Withheld home addresses** | A person can ask the register to withhold their home address and publish a professional address instead. Only a published home address is returned, as `residenceAddress`. |
| **One representative per office** | A director who is also president is returned twice: once as `Director`, once as `President`. |
| **Several names** | The legal name, its version in another language and the other names used in Quebec (trade names, often many) are returned in `commercialNames`; former names in `legacyLegalNames` and `legacyCommercialNames`. |
| **Quebec activity codes** | The register’s primary and secondary codes are returned under `company.activities.CAE_QC`, with their descriptions and `isMainActivity` when the register identifies their rank. Live records also retain `activityDescription`. No classification edition is inferred. |
| **Employees in Quebec only** | `employeeCount` is the band the enterprise declares for its employees in Quebec. |
| **Annual updates** | `statutoryFilings.annualFiling` gives the year of the last annual update and the deadline of the next one, as the register prints them. Whether a filing is overdue is not derived. |
| **No documents yet** | Copies of filed documents and certificates are ordered from the register and delivered manually. They are not offered yet. |
## Mappings
### Company Status
The register publishes a registration status. When it prints a cause after it ("Radiée d'office suite à une dissolution volontaire"), the cause is kept in `status.statusDetails.additionalInfo` and refines the closure reason.
| Local Status | Meaning | `active` | Standardized Status |
| - | - | - | - |
| Immatriculée | Registered | `true` | `ACTIVE` |
| Radiée d'office | Struck off by the register | `false` | `CLOSED` (administrative dissolution, or the printed cause) |
| Radiée d'office (article 59) | Struck off under section 59 of the Act | `false` | `CLOSED` |
| Radiée sur demande | Struck off on request | `false` | `CLOSED` (voluntary) |
| Non immatriculée | In the register without a registration (mostly public bodies) | | `UNKNOWN` |
| Avis d'intention de constitution | Notice filed before a constitution | `false` | `INACTIVE_NOT_CLOSED` |
### Legal Forms
| Local Form | Standardized |
| - | - |
| Société par actions ou compagnie | Corporation |
| Personne morale sans but lucratif, Association, Société de secours mutuel, Syndicat professionnel | Nonprofit Organization |
| Coopérative | Cooperative |
| Société en nom collectif, Société en commandite, Société en nom collectif à responsabilité limitée, Société en participation, Société non constituée au Québec | Partnership |
| Entreprise individuelle | Sole Proprietorship |
| Mutuelle d'assurances, Syndicat de copropriété, Groupement de personnes, Autre | Other |
### Roles
| Local Role | Standardized |
| - | - |
| Administrateur | Director |
| Président | President |
| Vice-président | Vice President |
| Secrétaire | Secretary |
| Trésorier | Treasurer |
| Directeur général | Chief Executive Officer |
| Principal dirigeant (with the title the enterprise gave) | Other |
| Associé | Partner |
| Commandité | General Partner |
| Fondé de pouvoir | Authorized Signatory |
| Administrateur du bien d'autrui | Administrator |
| Personne physique exploitant l'entreprise individuelle | Owner |
A principal officer and a function the enterprise wrote in its own words keep the printed title in `role.localName`. When that title names a standard office (for example "Chef de la direction financière"), `role.standardized` is that office (Chief Financial Officer) instead of Other.
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes | Live from the register in verification mode; from the register's open data (twice a month) in prefill mode |
| `legalRepresentatives` | Yes | Directors with their offices, officers, explicitly declared current shareholders or third parties exercising board powers, binding partners, sole proprietors, attorneys. Verification mode only |
| `shareholders` | Yes | Three main shareholders of a business corporation, or the partners of a partnership. Not applicable to sole proprietorships and non-profits |
| `ultimateBeneficialOwners` | Yes | Declared since 31 March 2023 |
| Documents | Not yet | Ordered from the register and delivered manually |
# Canada (Saskatchewan)
Source: https://docs.topograph.co/essentials/canada-saskatchewan
Identifiers, data sources, and integration details for companies registered in Saskatchewan
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Saskatchewan) reference is on the [Canada (Saskatchewan) country page](https://www.topograph.co/countries/ca-sk).
## Start here
This guide contains public integration notes for `CA-SK`, the Saskatchewan register. Use it for identifier formats, search behavior, and register-specific caveats. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Saskatchewan) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-SK` covers entities registered in Saskatchewan.** In Canada a company is incorporated either federally or in one province or territory, and each keeps its own register. A federal corporation that registers in Saskatchewan to do business there keeps its own record in [Canada (Federal)](/essentials/canada-federal): its Saskatchewan registration is returned here flagged as such, with the federal corporation number and Business Number to use with `countryCode: "CA-FED"`. `CA` on its own is not a jurisdiction.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Canada's Business Registries | **Primary source** for search and company data | Name, entity type, status, incorporation or registration date, registered office city, Business Number when published, and the link between a company's registrations across provinces. Updated daily by the Saskatchewan register. |
| GLEIF | Supplementary | Legal Entity Identifier (LEI), when one matches the entity number |
**Directors and shareholders are not offered yet.** The Saskatchewan record does not list them; they are only on the register's Profile Report. A federal corporation registered in Saskatchewan has its directors and beneficial owners in [Canada (Federal)](/essentials/canada-federal).
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Entity number** | 9 digits, or 6 digits for older entities | `101227359`, `304749` | Assigned by the Saskatchewan Corporate Registry. Spaces and hyphens are ignored. |
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | 9 or 6 digits | `101227359` | All entities. Same value as `company.id` |
| `businessNumber` | 9 digits (the BN root) | `821182649` | When the register publishes it (as the program account `821182649SK0001`); for the Saskatchewan registration of a federal corporation, the federal corporation's BN |
| `lei` | 20 letters and digits | | When GLEIF has a unique match |
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By name | `WESTERN POTASH` | Name | Business corporations and limited partnerships, active and historical |
| By entity number | `101227359`, `304749` | `id` | Exact match |
| By Business Number | `821182649` or `821182649SK0001` | `id` | Returns the Saskatchewan records carrying that BN |
Search is free. Only company data retrieval is charged.
### Active companies only
Search returns inactive companies too, each with the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Saskatchewan business corporations | Yes | Company data with status |
| Saskatchewan limited partnerships | Yes | Company data with status |
| Saskatchewan registrations of federal or other-province corporations | Flagged | Returned with their home jurisdiction and, for a federal corporation, the number to use with `CA-FED` |
| Non-profit corporations, cooperatives, business names | No | Not searchable yet |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Extra-provincial registrations** | A corporation incorporated federally or in another province also has a Saskatchewan entity number. Its company record says so in `status.statusDetails.additionalInfo` (home jurisdiction and number there), its legal form is `Extra-provincial Corporation`, and its `businessNumber` links it to the home record. |
| **Registered office city only** | Canada's Business Registries publishes the city and province of the registered office, not the street address. |
| **No beneficial owners** | Saskatchewan has no public register of beneficial owners. |
| **No activity codes** | The register's public records carry no industry classification. |
## Mappings
### Company Status
| Local Status | `active` | Standardized Status |
| - | - | - |
| Active | `true` | `ACTIVE` |
| Inactive | `false` | `CLOSED` |
| Amalgamated, Inactive - Amalgamated | `false` | `CLOSED` (merger) |
| Dissolved/Ceased | `false` | `CLOSED` |
| Cancelled – Voluntary | `false` | `CLOSED` (other) |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes | Live |
| `legalRepresentatives` | Not yet | Not on the Saskatchewan record; only on the Profile Report |
| `shareholders` | Not yet | Not on the Saskatchewan record; only on the Profile Report |
| `ultimateBeneficialOwners` | No | No public beneficial-ownership register in Saskatchewan |
| Documents | No | No document is offered yet |
# Canada (Yukon)
Source: https://docs.topograph.co/essentials/canada-yukon
Identifiers, data sources, and integration details for entities formed in Yukon
This guide is outdated and will be removed on 1 November 2026. The up-to-date Canada (Yukon) reference is on the [Canada (Yukon) country page](https://www.topograph.co/countries/ca-yt).
## Start here
This guide contains public integration notes for `CA-YT`, the Yukon register. The live source of truth for coverage, pricing, data sources, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Canada (Yukon) is in beta. Check the live pricing page or contact support before relying on it in production.
**`CA-YT` covers entities formed in Yukon.** A federal corporation registered in Yukon to do business is a [Canada (Federal)](/essentials/canada-federal) company: use `countryCode: "CA-FED"` and its corporation number. `CA` on its own is not a jurisdiction.
## Data Sources
| Source | Role | What it provides |
| - | - | - |
| Yukon Corporate Online Registry, public search | **Primary register**, read live | Search, entity name, former names, type, status and jurisdiction |
| GLEIF | Supplementary | Legal Entity Identifier (LEI) |
## Company Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Registry number** (`registryNumber`) | 6 digits in the records we have seen on the register (e.g. 534417, 619942); some older GLEIF records show 5 digits | `534417` | Assigned to every registered entity, extra-territorial corporations, societies and business names included. |
## Search Capabilities
| Search Type | Example | Notes |
| - | - | - |
| By registry number | `534417` | Exact match |
| By name | `Air North` | The text is matched anywhere in a name |
The register lists at most 100 entities: a broader name is refused and must be made more specific. Each search takes several seconds. Inactive entities are returned with their status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Company data is a summary** | The public search publishes the name, former names, entity type, status and jurisdiction only: no address, no date, no people. |
| **Not in onboarding mode** | Each read takes several seconds, so `company` is served in verification mode only. |
| **No directors yet** | The public search shows no people. Directors are only on the Profile Report, which is not offered yet: `legalRepresentatives` is answered as not supported. |
| **Extra-territorial entities** | Returned as registrations, with their home jurisdiction in `status.statusDetails.additionalInfo`; a federal corporation is pointed to `CA-FED`. |
| **Changed Name** | A record the register marks "Changed Name" does not say whether the entity is active: `active` is left unset. |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| `company` | Yes, live (verification) | Summary from the public search |
| `legalRepresentatives` | Not yet | Directors are only on the Profile Report, not offered yet |
| `shareholders` | Not yet | Under review |
| `ultimateBeneficialOwners` | No | Kept by each corporation, not filed |
# Cayman Islands
Source: https://docs.topograph.co/essentials/cayman-islands
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Cayman Islands reference is on the [Cayman Islands country page](https://www.topograph.co/countries/ky).
## Start here
This guide contains public integration notes for Cayman Islands. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
All Cayman Islands company data is sourced from the **General Registry of the Cayman Islands**, the official registrar of companies, partnerships, and trusts. The registry maintains records of over 120,000 active companies.
The system uses three paid report types from the CIREGISTRY online portal (`online.ciregistry.gov.ky`), all delivered as PDF documents. Each report contains a distinct, non-overlapping subset of company data.
* **Detailed Search Report**. A summary of the company's constitutional documents: legal name, entity type, registration number and date, registered office, initial subscriber, authorised share capital, nature of business, financial year end, and status. Does **not** contain directors, officers, or members. This is the primary source for the `company` datapoint, which is AI-parsed from the report.
* **Basic Information / Company Details**. A lighter report with the same core identity fields as the Detailed Search Report. Useful as a cheaper alternative when no constitutional context is needed.
* **List of Directors / Director Details**. The only report that contains director and officer information. Lists **current directors only**, per the Companies Act. This is the source for the `legalRepresentatives` datapoint.
**The Detailed Search Report does not contain directors or shareholders.** Despite the name, this report is a summary of a company's constitutional records. To retrieve directors, the List of Directors report must be retrieved separately. Shareholders are not available from the Registry at all (see Quirks below).
**All reports require retrieve.** The General Registry does not provide a free public API. Every data retrieval requires retrieving a document from the CIREGISTRY online portal. Documents retrieved within the last 24 hours can be re-downloaded free of charge.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entities** | CIREGISTRY | Entity name (base64-encoded) | `QlVUVEVSRklFTEQgQkFOSyAoQ0FZTUFOKSBMSU1JVEVE` | Search is name-based; use the `id` returned by search |
**The lookup `id` is not the registration number.** Cayman search is name-based, so the `id` returned by search (and echoed as `company.id`) is the entity name encoded in base64 (standard alphabet, with `=` padding). The company's registration number is returned separately in `identifiers.registrationNumber`, and it cannot be used as a query identifier.
**Decoding the ID:** The `id` returned in search results and company profiles is the entity name encoded in base64. Decode it to get the entity's legal name (e.g., `QlVUVEVSRklFTEQgQkFOSyAoQ0FZTUFOKSBMSU1JVEVE` → `BUTTERFIELD BANK (CAYMAN) LIMITED`).
### Identifiers in API Response
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| `registrationNumber` | As printed on the Search Report: usually digits, sometimes with a two-letter prefix (e.g. `CR-72229`) | `320834` | Company registration number issued by the General Registry, as shown on the Search Report |
Cayman Islands entities do not have VAT numbers, tax IDs, or other secondary identifiers in the public registry.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the registration number returned from the Search Report matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
The base64 company lookup `id` is not the registration number used for this match.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | Text string (2-100 chars) | `"Cayman National"` | Contains | Multiple results |
| By Partial Name | Text string (min 2 chars) | `"Bank"` | Contains | Multiple results |
**Search is name-only.** The registration number is not searchable, so all searches are by entity name. The search queries the CIREGISTRY portal in real time. See the pricing page Speed section for current response times.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile. Search results carry only the entity name, so the company status is not known at search time.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Name-based lookup** | The lookup `id` is the base64-encoded entity name. The numeric registration number is returned in `identifiers.registrationNumber` but is not usable as a query key. |
| **Shareholders are not public** | The Cayman Islands Registrar does not make the register of members available to the public. The register is held by the company's registered office, not the Registry. `shareholders` cannot be delivered for any Cayman entity via this integration, regardless of entity type. |
| **Only current directors** | The Companies Act only requires the Registrar to make available the names of **current** directors. Historical / former directors are not available. |
| **Struck-off records are not public** | Records of companies removed from the register (struck, dissolved, de-registered) are not accessible. Requests for these entities will fail at source. |
| **All data is paid** | There is no free public API. Every report must be retrieved from the CIREGISTRY portal. |
| **Corporate directors** | Cayman Islands companies frequently have corporate entities as directors, especially exempted companies. Directors may be of type `company` rather than `individual`. |
| **24-hour re-download** | Reports retrieved from CIREGISTRY can be re-downloaded free of charge within 24 hours of the original retrieve. |
| **Registered Agent ≠ Director** | The Registered Agent is a required appointment but is not a legal representative. Do not confuse with directors. |
| **AI-parsed company data** | The `company` datapoint is AI-extracted from the Detailed Search Report. Some fields may be approximate. |
## Mappings
### Company Status
Status is read from the **Status** field of the Detailed Search Report.
| Local Status | Standardized Status | Notes |
| - | - | - |
| Active | Active | Entity is currently operating |
| Dissolved | Closed | Entity has been formally dissolved |
| Struck Off | Closed | Entity removed from register by the Registrar |
| In Liquidation | Under Insolvency Proceeding | Entity is being wound up |
### Legal Forms
Legal form is derived from the **Entity Type** field on the Detailed Search Report.
| Local Name | English Translation | Notes |
| - | - | - |
| Exempted Company | Exempted Company | Most common type for offshore entities; not required to hold annual meetings in Cayman |
| Exempted Limited Partnership | Exempted Limited Partnership | Partnership with at least one general and one limited partner |
| Ordinary Resident Company | Ordinary Resident Company | Company that carries on business within the Cayman Islands |
| Foreign Company | Foreign Company | Company incorporated outside Cayman but registered locally |
| Limited Liability Company (LLC) | Limited Liability Company | Hybrid entity combining corporate and partnership features |
| Segregated Portfolio Company (SPC) | Segregated Portfolio Company | Entity with legally segregated portfolios; common for funds |
| Foundation Company | Foundation Company | Entity without shareholders; governed by a supervisor and secretary |
### Legal Representatives
Legal representatives are extracted from the **List of Directors** report. The report publishes only the names of current directors and their alternates, with no titles, dates or addresses, so every representative is returned with the role Director.
| Role | Notes |
| - | - |
| Director | Every listed name, including alternates; may be individual or corporate |
**Corporate directors** are common in Cayman Islands companies. When a director is a legal entity rather than an individual, it is returned with `type: "company"` and the entity name in `company.legalName`. Individuals are returned with `type: "individual"` and `individual.name`.
**No historical directors.** The Companies Act only obliges the Registrar to publish the names of current directors. Former directors are not available from the registry.
### Shareholders
Shareholder data is **not available** for Cayman Islands entities. The Cayman Islands Registrar does not hold or publish the register of members. The register is kept privately at the company's registered office and is not accessible through the CIREGISTRY portal for any entity type.
If a customer needs shareholder information for a resident (local) Cayman company, a Certificate of Shareholders can be retrieved manually via the Cayman Business Portal (CBP), which is separate from the CIREGISTRY portal used by this integration. This is not currently offered as an automated datapoint.
## Data Availability
### Data Availability Matrix
| Data Point | Source | Available | Notes |
| - | - | - | - |
| Legal name | Detailed Search Report | Always | Primary identifier for the entity |
| Status | Detailed Search Report | Always | Active, Dissolved, Struck Off, In Liquidation |
| Legal form | Detailed Search Report | Always | From the Entity Type field |
| Registration number | Detailed Search Report | Always | Numeric, returned in `identifiers.registrationNumber` |
| Registration date | Detailed Search Report | Always | Date of original incorporation |
| Registered office | Detailed Search Report | Always | Always in Cayman Islands; postal code format KY#-#### |
| Authorised share capital | Detailed Search Report | Always | In Cayman dollars (CI\$) |
| Nature of business | Detailed Search Report | Always | Free-text description |
| Directors | List of Directors | Current only | Includes corporate directors; no historical data |
| Shareholders | Not available | Never | Register of members is not public in Cayman |
### Documents
| Document | API category | Content |
| - | - | - |
| Detailed Search Report | `tradeRegisterExtract` | Summary of constitutional documents: identity, registered office, share capital, status |
| Basic Information | `otherDocuments` | Lighter identity report: name, type, status, incorporation date, registered office |
| List of Directors | `otherDocuments` | Current directors only |
The `company` datapoint is delivered by retrieving the Detailed Search Report. The `legalRepresentatives` datapoint is delivered by retrieving the separate List of Directors report. Requesting both datapoints in the same call will result in two separate retrieves from the CIREGISTRY portal.
## Example API Responses
All examples use placeholder data. Query: `POST /v2/company` with `{ "id": "", "countryCode": "KY", "dataPoints": ["company", "legalRepresentatives"] }`. `shareholders` is not supported for the Cayman Islands.
```json theme={null}
{
"company": {
"id": "T0NFQU5JQyBIT0xESU5HUyAoQ0FZTUFOKSBMSU1JVEVE",
"countryCode": "KY",
"identifiers": {
"registrationNumber": "331245"
},
"legalName": "OCEANIC HOLDINGS (CAYMAN) LIMITED",
"status": {
"localName": "Active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Exempted Company",
"englishTranslation": "Exempted Company"
},
"incorporationDate": "2018-03-15",
"legalAddress": {
"addressLine1": "PO Box 309, Ugland House",
"city": "George Town",
"postalCode": "KY1-1104",
"countryCode": "KY"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Director",
"englishTranslation": "Director",
"standardized": "Director"
},
"individual": {
"name": {
"fullName": "John Smith",
"firstName": "John",
"lastName": "Smith"
}
}
},
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Director",
"englishTranslation": "Director",
"standardized": "Director"
},
"company": {
"legalName": "Corporate Services Ltd",
"countryCode": "KY"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "SVNMQU5EIFRSQURJTkcgQ08uIExJTUlURUQ=",
"countryCode": "KY",
"identifiers": {
"registrationNumber": "284519"
},
"legalName": "ISLAND TRADING CO. LIMITED",
"status": {
"localName": "Active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Ordinary Resident Company",
"englishTranslation": "Ordinary Resident Company"
},
"incorporationDate": "2015-07-22",
"legalAddress": {
"addressLine1": "45 Harbour Drive",
"city": "George Town",
"postalCode": "KY1-1205",
"countryCode": "KY"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Director",
"englishTranslation": "Director",
"standardized": "Director"
},
"individual": {
"name": {
"fullName": "Jane Doe",
"firstName": "Jane",
"lastName": "Doe"
}
}
}
]
}
```
All three reports are available for every active entity found via search:
| Document | API category | Format |
| - | - | - |
| Detailed Search Report | `tradeRegisterExtract` | PDF |
| Basic Information | `otherDocuments` | PDF |
| List of Directors | `otherDocuments` | PDF |
# China
Source: https://docs.topograph.co/essentials/china
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date China reference is on the [China country page](https://www.topograph.co/countries/cn).
## Start here
This guide contains public integration notes for China. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
For a given entity, **company data and legal representatives are AI-extracted from a single PDF document**: the Credit Information Report (信用信息报告) downloaded from the Credit China portal. Shareholders and ultimate beneficial owners are not published by Credit China. They are obtained separately from commercial reports supplied through a local partner, as manually fulfilled products.
### All entity types
* **Credit China (信用中国).** Official national credit information platform operated by the **National Development and Reform Commission (NDRC)** in collaboration with the People's Bank of China. The portal (`creditchina.gov.cn`) provides Credit Information Reports (信用信息报告) in PDF format. This is the data source for company profiles, legal representatives, and all structured company attributes.
* **Local partner (shareholders and beneficial owners).** A commercial shareholder report and a commercial beneficial owner report are retrieved by our local partner from a Chinese business-data platform that compiles national business register filings. Ownership data is AI-extracted from these reports. They are not official register certificates. Delivery typically takes a few business days.
Data is retrieved via automated portal access. Requests can take several minutes to complete due to portal complexity.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entities** | Credit China | 18 characters, digits and uppercase letters (USCC) | `9144030071526726XG` | Unified Social Credit Code (统一社会信用代码). Some codes are all digits, e.g. `911000001000013428` |
**USCC Format Breakdown:** The 18-character Unified Social Credit Code follows the **GB 32100-2015** standard:
* **Position 1:** Registration authority code (e.g., `9` = industry and commerce, `1` = public institutions and government bodies, `5` = civil affairs, `Y` = other; the standard also defines `2`, `3`, `4`, `6`, `7`, `8`, `A` and `N`)
* **Position 2:** Entity category within that authority (e.g., under `9`: `1` = enterprise, `2` = individual business, `3` = farmer cooperative)
* **Positions 3-8:** Administrative division code (6 digits, e.g., `110000` = Beijing)
* **Positions 9-17:** Entity identification code (9 alphanumeric characters, derived from the former organization code)
* **Position 18:** Check character (a digit or an uppercase letter, calculated using weighted modular arithmetic)
Codes use digits and uppercase letters only; `I`, `O`, `S`, `V` and `Z` are never used. A code can be all digits (e.g., `911000001000013428`) or carry letters (e.g., `9144030071526726XG`).
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `uscc` | 18 characters, digits and uppercase letters | `9144030071526726XG` | All entities registered in China |
The identifier key in the API response is `uscc` (Unified Social Credit Code). Its value always corresponds to the query USCC.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Unified Social Credit Code (USCC) matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By USCC | 18 characters, digits and uppercase letters | `9144030071526726XG` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Chinese name | Chinese characters | `腾讯` | Fuzzy | Multiple results |
| By full Chinese name | Chinese characters | `腾讯科技(深圳)有限公司` | Exact | Exact match returned first (matchType: exactLegalName); other results may follow |
**Search uses live portal access.** Both identifier and name searches query the Credit China portal in real time. There is no pre-built search index. Search is slower than in most countries and typically takes under a minute.
**USCC shape check.** An identifier search runs when the input has the USCC shape: 18 characters from digits and uppercase letters other than I, O, S, V and Z, with digits in positions 3 to 8. Codes made only of digits are valid (e.g. `911000001000013428`). Anything else is searched as a company name.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile. Search results carry no company status, so the active-only filter has no effect. Check the status on the company profile.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Profile data is AI-parsed from PDF** | Company profile and legal representative data are extracted from a Credit Information Report PDF by AI. Data quality depends on PDF quality and AI parsing accuracy. |
| **Processing time is high** | Company profile requests are asynchronous and can take **up to 7 minutes** per attempt due to portal latency. |
| **Single legal representative per company** | Chinese Company Law mandates exactly **one legal representative** (法定代表人) per company. This differs from jurisdictions that allow multiple legal representatives. |
| **Shareholders are a separate, manual product** | Credit China does not publish ownership. Shareholders are available in verification mode, AI-extracted from a commercial shareholder report retrieved through our local partner. Delivery typically takes a few business days, and they are billed separately from company data. |
| **UBOs are a separate, manual product** | Credit China does not publish beneficial ownership. Ultimate beneficial owners are available in verification mode, AI-extracted from a commercial beneficial owner report retrieved through our local partner. Delivery typically takes a few business days. |
| **Business scope instead of activity codes** | China has a national classification system (GB/T 4754) but the Credit Information Report provides free-text business scope (经营范围) rather than numeric codes. NACE and ISIC codes are therefore **always AI-inferred**. |
| **No establishment data** | Branch or subsidiary information is not extracted from the current data source. |
| **USCC replaced 3 old identifiers in 2015** | Before reforms in 2015, Chinese businesses needed separate IDs from SAIC (business permit), STA (tax ID), and AQSIQ (organization code). The USCC unified these into a single 18-character code. Legacy identifiers are not supported. |
## Mappings
### Company Status
Company status is **AI-extracted** from the Credit Information Report (信用信息报告) PDF. The AI parser reads the status field from the document and maps it to a standardized status.
| Local Status | English Translation | Standardized Status | Notes |
| - | - | - | - |
| 存续 | Existing / In Operation | Active | Company is registered and operating |
| 在业 | In Business | Active | Company is actively conducting business |
| 开业 | Open for Business | Active | Company has commenced operations |
| 正常 | Normal | Active | Normal operating status |
| 迁出 | Relocated Out | Active | Company relocated to another jurisdiction |
| 吊销 | Revoked | Closed | Business license revoked by authorities |
| 注销 | Deregistered | Closed | Voluntarily deregistered |
| 撤销 | Cancelled | Closed | Registration cancelled by authorities |
| 停业 | Ceased Operations | Closed | Company has ceased business operations |
| 清算 | In Liquidation | Under Insolvency Proceeding | Company is undergoing liquidation |
Status is AI-extracted from the trade register extract PDF. The local Chinese status term is preserved verbatim and mapped to a standardized status. The `isAIInferred` flag on status reflects this AI extraction.
### Legal Forms
China uses a variety of legal entity forms. Since company data is AI-extracted from the Credit Information Report PDF, the legal form is parsed from the document text. The mapping to standardized forms and **ISO 20275 (ELF)** codes is **AI-enriched**.
Legal form standardization and ISO 20275 assignment are AI-enriched. The local Chinese legal form name is preserved verbatim from the trade register extract. Because legal forms are AI-inferred, exact mappings may evolve.
#### Commercial Companies
| Chinese Name | English Translation | Standardized | Notes |
| - | - | - | - |
| 有限责任公司 | Limited Liability Company | Limited Liability Company | Most common form for SMEs |
| 股份有限公司 | Company Limited by Shares | Corporation | Joint stock companies, including listed companies |
| 有限责任公司(自然人投资或控股) | LLC (Natural Person Investment) | Limited Liability Company | Invested/controlled by individuals |
| 有限责任公司(法人独资) | LLC (Sole Legal Person) | Limited Liability Company | Wholly owned by a legal person |
| 有限责任公司(自然人独资) | LLC (Sole Natural Person) | Limited Liability Company | One-person LLC owned by an individual |
| 有限责任公司(外商投资) | LLC (Foreign Investment) | Limited Liability Company | Foreign-invested enterprise (FIE) |
| 有限责任公司(中外合资) | Sino-Foreign Joint Venture LLC | Limited Liability Company | Chinese-foreign equity joint venture |
| 有限责任公司(外商合资) | Foreign Joint Venture LLC | Limited Liability Company | Multiple foreign investors |
| 股份有限公司(上市) | Listed Company Limited by Shares | Corporation | Publicly listed corporation |
| 股份有限公司(非上市) | Unlisted Company Limited by Shares | Corporation | Private joint stock company |
#### Sole Entrepreneurs
| Chinese Name | English Translation | Standardized |
| - | - | - |
| 个体工商户 | Individual Industrial and Commercial Household | Sole Proprietorship |
| 个人独资企业 | Sole Proprietorship Enterprise | Sole Proprietorship |
#### Partnerships
| Chinese Name | English Translation | Standardized |
| - | - | - |
| 普通合伙企业 | General Partnership | Partnership |
| 有限合伙企业 | Limited Partnership | Partnership |
| 特殊普通合伙企业 | Special General Partnership | Partnership |
#### Non-Profits & Social Organizations
| Chinese Name | English Translation | Standardized |
| - | - | - |
| 民办非企业单位 | Private Non-Enterprise Unit | Nonprofit Organization |
| 社会团体 | Social Organization | Nonprofit Organization |
| 基金会 | Foundation | Nonprofit Organization |
#### State-Owned & Public Entities
| Chinese Name | English Translation | Standardized |
| - | - | - |
| 全民所有制 | State-Owned Enterprise (Wholly People-Owned) | Government-Owned Entity |
| 集体所有制 | Collectively-Owned Enterprise | Government-Owned Entity |
| 国有独资公司 | State-Owned Sole Proprietorship Company | Government-Owned Entity |
#### Foreign Entities
| Chinese Name | English Translation | Standardized |
| - | - | - |
| 外国(地区)企业在中国境内从事生产经营活动 | Foreign Enterprise Operating in China | Branch or Representative Office |
| 外国(地区)企业常驻代表机构 | Foreign Enterprise Representative Office | Branch or Representative Office |
### Legal Representatives
Legal representatives are **AI-extracted** from the Credit Information Report (信用信息报告) PDF. In China, the legal representative (法定代表人) is a single individual who has binding authority on behalf of the company under Chinese law.
| Role (Chinese) | Role (English) | Classification | Notes |
| - | - | - | - |
| 法定代表人 | Legal Representative | Authorized Signatory | The designated representative; one per company |
| 董事长 | Chairman of the Board | Legal Representative | When serving as legal representative |
| 总经理 | General Manager | Legal Representative | When serving as legal representative |
| 执行董事 | Executive Director | Legal Representative | Common in smaller LLCs without a board |
| 负责人 | Person in Charge | Legal Representative | Used for branches and representative offices |
Under Chinese Company Law, a company designates a director or manager who executes its affairs as its legal representative (法定代表人). The title does not identify which underlying management office that person holds. Known representative headings use the published role list and return `Authorized Signatory`; extraction of the person from the report still uses AI. Combined headings retain the alternatives printed in the source rather than assigning every listed office to that person.
### Other Key Persons
Not applicable. The Credit Information Report does not include structured data for supervisory board members, auditors, or other key persons beyond the legal representative. Board member or senior executive data is not currently extracted.
### Shareholders
The Credit Information Report does not include ownership. Request `shareholders` in **verification mode**: this is a separate, **manually fulfilled** product. Our local partner retrieves the full shareholder list (股东信息) as a commercial shareholder report, and shareholders are **AI-extracted** from it. Delivery typically takes a few business days.
Shareholders are billed separately from company data. The shareholder report itself is also available as the `certifiedTradeRegisterExtract` document. Verify AI-extracted ownership against the report before relying on it for compliance.
### Ultimate Beneficial Owners
Ultimate beneficial owners (受益所有人 / 最终受益人) follow the same model: a commercial beneficial owner report retrieved through our local partner, AI-extracted, and billed separately. This is not an official beneficial-ownership register certificate.
Request `ultimateBeneficialOwners` in verification mode for structured data, or order `ultimateBeneficialOwnersCertificate` from `availableDocuments` for the source PDF. Delivery is asynchronous and typically takes a few business days. Follow the existing request through webhooks or polling; do not submit repeated orders while it is pending. If the report cannot be obtained, the request reports an error rather than a successful empty result.
### Activity Code Mapping
China does not use a single standardized industry classification code in the Credit Information Report. Activity information is extracted as a free-text description from the business scope (经营范围) field, then mapped via AI:
```
Business Scope (经营范围, free text) → AI → NACE Rev. 2 + ISIC Rev. 4
```
| Classification | Source | AI Inferred? |
| - | - | - |
| **Business Scope** | Trade register extract (经营范围) | No (official text) |
| **NACE** | AI-derived from business scope text | Yes (always) |
| **ISIC** | AI-derived from business scope text | Yes (always) |
China has a national classification system (**GB/T 4754**, 国民经济行业分类) but the Credit Information Report typically provides a free-text business scope rather than a numeric code. Both NACE and ISIC codes are therefore **always AI-inferred** for Chinese companies. Every activity item includes an `isAIInferred: true` flag.
## Data Availability
### Data Availability Matrix
| Data Type | Availability | Notes |
| - | - | - |
| Company Profile | ✅ Async | Legal name, address, status, legal form, capital, activity description (AI-parsed from the Credit Information Report) |
| Legal Representatives | ✅ Async | AI-extracted from the Credit Information Report PDF |
| Shareholders | ✅ Manual | Verification mode. Commercial shareholder report retrieved through our local partner, AI-extracted; typically a few business days |
| Ultimate Beneficial Owners | ✅ Manual | Verification mode. Commercial beneficial owner report retrieved through our local partner, AI-extracted; typically a few business days |
| Establishments | ❌ | Not extracted from current data source |
| Activity Codes | ✅ Async | AI-inferred NACE/ISIC from business scope text |
**Legend:** ✅ Available | ❌ Not Available | Async = Asynchronous processing (up to 7 minutes) | Manual = fulfilled by a local partner, typically a few business days
### Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Credit Information Report** (信用信息报告) | `tradeRegisterExtract` | PDF | ✅ All entities | Official credit report from creditchina.gov.cn, included with company data |
| **Commercial shareholder report** (股东信息报告) | `certifiedTradeRegisterExtract` | PDF | ✅ All entities (manual) | Full shareholder list, retrieved through our local partner; typically a few business days |
| **Commercial beneficial owner report** (受益所有人报告) | `ultimateBeneficialOwnersCertificate` | PDF | ✅ All entities (manual) | Beneficial owner list, retrieved through our local partner; typically a few business days |
The Credit Information Report is used both as a standalone deliverable and as the source for AI-parsed company profile data. The shareholder report and the beneficial owner report are separate commercial documents, not official register certificates, and are the sources for the `shareholders` and `ultimateBeneficialOwners` datapoints. Ordering the document or the datapoint triggers the same partner request.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "CN", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "91110000710926094P",
"countryCode": "CN",
"identifiers": {
"uscc": "91110000710926094P"
},
"legalName": "北京示例科技有限公司",
"legalNameInEnglish": "Beijing Example Technology Co., Ltd.",
"registrationDate": "2018-05-15",
"activityDescription": "技术开发、技术咨询、技术服务；软件开发；销售自行开发的产品。",
"status": {
"localName": "存续",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "有限责任公司(自然人投资或控股)",
"englishTranslation": "Limited Liability Company (Natural Person Investment)",
"standardized": "Limited Liability Company",
"iso20275Code": "8888"
},
"capital": {
"amount": 10000000,
"currency": "CNY"
},
"activities": {
"NACE": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }],
"ISIC": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }]
},
"legalAddress": {
"addressLine1": "北京市海淀区中关村大街1号",
"city": "Beijing",
"countryCode": "CN"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "法定代表人",
"englishTranslation": "Legal Representative",
"standardized": "Authorized Signatory"
},
"individual": {
"name": {
"fullName": "张伟"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "91310000XXXXXXXXX1",
"countryCode": "CN",
"identifiers": {
"uscc": "91310000XXXXXXXXX1"
},
"legalName": "上海示例制造股份有限公司",
"legalNameInEnglish": "Shanghai Example Manufacturing Co., Ltd.",
"registrationDate": "2005-08-22",
"activityDescription": "金属材料的制造、加工和销售；钢铁冶炼。",
"status": {
"localName": "在业",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "股份有限公司(上市)",
"englishTranslation": "Listed Company Limited by Shares",
"standardized": "Corporation"
},
"capital": {
"amount": 500000000,
"currency": "CNY"
},
"activities": {
"NACE": [{ "code": "2410", "description": "Manufacture of basic iron and steel", "isAIInferred": true }],
"ISIC": [{ "code": "2410", "description": "Manufacture of basic iron and steel", "isAIInferred": true }]
},
"legalAddress": {
"addressLine1": "上海市宝山区工业路500号",
"city": "Shanghai",
"countryCode": "CN"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "董事长",
"englishTranslation": "Chairman of the Board",
"standardized": "Chairman"
},
"individual": {
"name": {
"fullName": "王强"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "91310000MA1FL8XQ30",
"countryCode": "CN",
"identifiers": {
"uscc": "91310000MA1FL8XQ30"
},
"legalName": "上海旧商贸有限公司",
"registrationDate": "2010-03-20",
"activityDescription": "日用百货、服装鞋帽的销售。",
"status": {
"localName": "吊销",
"active": false,
"statusDetails": {
"status": "CLOSED"
}
},
"legalForm": {
"localName": "有限责任公司",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "上海市浦东新区张江路100号",
"city": "Shanghai",
"countryCode": "CN"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "法定代表人",
"englishTranslation": "Legal Representative",
"standardized": "Authorized Signatory"
},
"individual": {
"name": {
"fullName": "李明"
}
}
}
]
}
```
**Note:** Revoked companies have `active: false` and status `吊销` (Revoked). The standardized status is `CLOSED`. Shareholders are not part of this request; request them separately in verification mode.
The table lists supported documents; the example shows a retrieved Credit Information Report. Available document IDs are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Credit Information Report (信用信息报告) PDF | All entities |
| `certifiedTradeRegisterExtract` | Commercial shareholder report PDF | All entities; partner order, typically a few business days |
| `ultimateBeneficialOwnersCertificate` | Commercial beneficial owner report PDF | All entities; partner order, typically a few business days |
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_cn_xxxxxxxx",
"name": "信用信息报告 (Credit Information Report)",
"format": "PDF",
"url": "https://..."
}
}
}
```
## Data Source Priority & Routing
China uses the Credit China portal (`creditchina.gov.cn`) for company data and legal representatives, and commercial reports obtained through our local partner for shareholders and ultimate beneficial owners. There is no priority chain or fallback mechanism.
**Single source per datapoint:** Company data and legal representatives come from the Credit Information Report (信用信息报告) PDF downloaded from Credit China. There is no cross-source merging or fallback. If the Credit China portal is unavailable, those datapoints fail; partner reports do not replace the profile source.
**Attribute-level source mapping:**
| Attribute | Source | AI Inferred? |
| - | - | - |
| Company name (Chinese + English) | Credit Information Report PDF | Yes |
| Legal form | Credit Information Report PDF | Yes |
| Status | Credit Information Report PDF | Yes |
| Registered address | Credit Information Report PDF | Yes |
| Registration date | Credit Information Report PDF | Yes |
| Share capital | Credit Information Report PDF | Yes |
| Business scope (活动描述) | Credit Information Report PDF | Yes |
| Activity codes (NACE/ISIC) | Derived from business scope | Yes (always) |
| Legal representative | Credit Information Report PDF | Yes |
| Shareholders | Commercial shareholder report (local partner) | Yes |
| UBOs | Commercial beneficial owner report (local partner) | Yes |
| Establishments | Not extracted | N/A |
# Compliance Signals & Statutory Filings
Source: https://docs.topograph.co/essentials/compliance-signals
Register-reported filing standing, charges, insolvency history, and the statutory filing calendar
Company registers publish more than a company's identity. They also publish **how the company stands with the register**: whether its filings are up to date, whether there are charges over its assets, and when the next statutory filing falls due.
Topograph exposes this in two country-agnostic fields on `company`:
| Field | What it carries |
| - | - |
| `complianceFlags` | Point-in-time signals: filings overdue, registered charges, insolvency history, past liquidation, and UBO compliance notices. |
| `statutoryFilings` | The filing calendar: the accounts and confirmation filings last made, and the ones next due. |
Neither is a passthrough of any one register. The same two obligations (file your accounts, periodically confirm your particulars are current) exist in nearly every jurisdiction under different local names, and both fields are modelled around those obligations rather than around any single register's field names.
## `complianceFlags`
Each signal has its own key, and each key holds its own object.
| Key | Meaning when `active` is `true` |
| - | - |
| `accountsOverdue` | The statutory annual accounts are overdue. |
| `annualFilingOverdue` | The periodic confirmation filing is overdue. |
| `registeredCharges` | The register records charges, mortgages or pledges over the company's assets. |
| `insolvencyHistory` | The register records insolvency proceedings in the company's history. |
| `liquidated` | The company has been through liquidation at some point. |
| `uboConfirmationOverdue` | The UBO register explicitly reports that annual confirmation is overdue. Consult country coverage before relying on this field. |
| `uboAdministrativeStrikingOff` | The business register publishes an administrative notice for non-compliance with UBO obligations. This does not itself mean the company is dissolved. |
Each flag object carries:
| Field | Description |
| - | - |
| `active` | The register's own answer. |
| `dueDate` | The date the filing was due and missed. Overdue flags only, and only while `active` is `true`. |
| `since` | The date the signal began, when the register reports it. |
| `source` | The register that reported it. |
| `observedAt` | UTC timestamp of the observed UBO statement or administrative notice, when available. |
| `lastConfirmedOn` | Last annual UBO confirmation date reported by the source, on `uboConfirmationOverdue`. |
| `lastUpdatedOn` | Last UBO declaration modification date reported by the source, independently of annual confirmation. |
**A key is present only when the register formally states the signal.**
`active: false` is a positive statement: the register says the company has no registered charges. An **absent key** means we hold no formal statement either way; it is **not** a clearance.
To tell the two apart before you integrate, check the country's entry in the coverage manifest: `complianceSignals.flags.values[].reportsNegative` tells you whether that register ever states the negative. Where it is `false`, a missing key carries no information.
```json theme={null}
{
"complianceFlags": {
"accountsOverdue": { "active": true, "dueDate": "2024-09-30", "source": "companies_house" },
"registeredCharges": { "active": false, "source": "companies_house" },
"insolvencyHistory": { "active": false, "source": "companies_house" }
}
}
```
`insolvencyHistory` is **historical**. A company *currently* in proceedings is reported through `status.statusDetails.status` (`UNDER_INSOLVENCY_PROCEEDING`). A company that has since recovered keeps `insolvencyHistory.active: true` while returning to an active status. That is exactly the signal a risk model wants.
### Country-specific coverage
Every country manifest contains `complianceSignals.flags.values`. Each entry includes its own country-specific `description`, the public register `source`, `reportsNegative`, available payload `fields`, and `providedBy` request paths (`datapoint` and `mode`). An empty list means no compliance flags are currently covered. Pricing details and the [Topograph Wizard](/guides/topograph-mcp) expose the same descriptions and request paths. Flags are included in the corresponding data request, rather than sold separately.
Belgium covers `uboAdministrativeStrikingOff` through the BCE public register with `company` in verification mode. Only an explicit notice produces `active: true`; an absent notice does not produce `active: false`. The notice can coexist with an active company and a normal legal situation. Correcting the UBO declaration does not automatically remove it.
Annual confirmation and modification are different events: an unchanged ownership declaration can be confirmed annually. An old modification date, a control-start date, or the time Topograph fetched data does not establish an overdue confirmation.
`uboConfirmationOverdue` is returned with `ultimateBeneficialOwners` in verification mode, including in a UBO-only request. The Belgian UBO Register explicitly reports overdue (`active: true`) or valid (`active: false`) confirmation; missing or unrecognised evidence remains unknown.
`lastConfirmedOn` records the confirmation date when available, and `observedAt` records the source observation without being refreshed when a result is reused. Successful live retrieval remains live even when the declaration is old; compliance flags do not change retrieval freshness or authority.
## `statutoryFilings`
Two obligations, each with what was last filed and what is next due.
| Key | The obligation |
| - | - |
| `accounts` | File the statutory annual accounts. |
| `annualFiling` | Periodically confirm the company still exists and its particulars are current. UK confirmation statement, Irish annual return, US state annual report, Guernsey annual validation. |
Each obligation carries:
| Field | Description |
| - | - |
| `financialYearEnd` | The recurring accounting reference date as `MM-DD` (e.g. `03-31`). Accounts only. It repeats every cycle, so it is not a full date. |
| `cadence` | `annual` or `biennial`. Confirmation filing only. |
| `lastFiled` | `{ year, periodStart, periodEnd, dueDate, filedOn }` |
| `next` | `{ year, periodStart, periodEnd, dueDate, overdue }` |
| `source` | The register that reported the obligation. |
```json theme={null}
{
"statutoryFilings": {
"accounts": {
"financialYearEnd": "03-31",
"lastFiled": { "periodStart": "2024-04-01", "periodEnd": "2025-03-31" },
"next": {
"periodStart": "2025-04-01",
"periodEnd": "2026-03-31",
"dueDate": "2026-12-31",
"overdue": false
},
"source": "companies_house"
},
"annualFiling": {
"cadence": "annual",
"lastFiled": { "periodEnd": "2025-10-25" },
"next": { "periodEnd": "2026-10-25", "dueDate": "2026-11-08", "overdue": false },
"source": "companies_house"
}
}
}
```
### Every sub-field is independently optional
Registers publish very different subsets, and we return exactly what the register states. Nothing is derived to fill a gap.
* A register that publishes only a due date populates `next.dueDate` and nothing else.
* A register that publishes only a filing **year** (several US states) populates `next.year`. No day or month is invented.
* `overdue` is only ever the register's own word. It is **never** computed by comparing `dueDate` to today, because filing deadlines carry jurisdiction-specific grace periods.
Check `complianceSignals.statutoryFilings.values[].fields` in the coverage manifest for the exact list a country populates before you build against it.
## Country availability
The manifest is the source of truth and is served live through the API and the Topograph Wizard. The table below is a snapshot.
### Compliance flags
| Country | Flags | States the negative? |
| - | - | - |
| 🇬🇧 United Kingdom | `accountsOverdue`, `annualFilingOverdue`, `registeredCharges`, `insolvencyHistory`, `liquidated` | Yes. `active: false` is a formal clearance |
| 🇧🇪 Belgium | `uboConfirmationOverdue` (UBOs), `uboAdministrativeStrikingOff` (company), verification mode | Confirmation: yes, valid means `active: false`. Striking-off: no, absent notices mean unknown |
### Statutory filings
| Country | Accounts | Confirmation filing | Fields published |
| - | - | - | - |
| 🇬🇧 United Kingdom | Yes | Annual | Full calendar: year end, both periods, due dates, overdue |
| 🇮🇪 Ireland | No | Annual | Last and next annual return date (NARD), as `periodEnd`. No due date: see note below |
| 🇬🇬 Guernsey | No | Annual | Next due date |
| 🇺🇸 Alaska | No | Biennial | Next due date |
| 🇺🇸 Washington DC | No | Biennial | Next due date, last filed date |
| 🇺🇸 Kansas | No | Annual | Next due date, last filed year |
| 🇺🇸 Kentucky | No | Annual | Last filed date |
| 🇺🇸 Louisiana | No | Annual | Last filed date |
| 🇺🇸 Montana | No | Annual | Next due date |
| 🇺🇸 Nebraska | No | Biennial | Next due date |
| 🇺🇸 New Hampshire | No | Annual | Next due **year**, last filed **year** |
| 🇺🇸 New Jersey | No | Annual | Last filed date + year (paid status report only) |
| 🇺🇸 New Mexico | No | Annual | Next due date |
| 🇺🇸 Nevada | No | Annual | Next due date |
| 🇺🇸 New York | No | Biennial | Next due date |
| 🇺🇸 Pennsylvania | No | Annual | Next due date |
| 🇺🇸 Vermont | No | Annual | Last filed due date, last filed date |
| 🇺🇸 Washington | No | Annual | Next due date |
| 🇨🇦 Canada (Federal) | No | Annual | Last filed **year**, next **year** and whether it is overdue |
| 🇳🇱 Netherlands | Yes | No | Filing period and last filed date, read from the filed accounts document |
| 🇯🇪 Jersey | No | Annual | Last filed date, read from the register extract |
| 🇸🇬 Singapore | No | Annual | Last filed date and the financial year end it covers, read from the business profile |
| 🇵🇹 Portugal | Yes | No | Filing period and last filed date, read from the accounts deposit notice. Verification mode only |
**Netherlands, Jersey, Singapore and Portugal are read from the document, not a structured register field.** Every other row in this table comes from a field the register publishes directly. For these four, the register's own document states the date, but we read it from the document text rather than a dedicated data field the register exposes. Treat these four with the same caution you would apply to reading the source document yourself, and verify independently before making a compliance decision on them.
**Ireland reports the annual return date as a period, not a deadline.** The Irish Annual Return Date (ARD) is the latest date to which a return must be *made up*; the return is then due within 56 days of it. So `annualFiling.next.periodEnd` carries the ARD and no `dueDate` is published. The deadline is not derived, because it is not a plain 56 days: it extends past weekends and public holidays, and where financial statements are annexed it is the earlier of ARD + 56 days and financial-year-end + 9 months + 56 days.
**US states publish no statutory accounts.** The `accounts` obligation is deliberately absent for every US state rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim from "this register does not hold it".
## Both fields are additive
`complianceFlags` and `statutoryFilings` are optional and appear only where a register publishes them. Adding a country, a flag, or a sub-field never changes an existing response shape.
`statutoryFilings.*.next.overdue` intentionally mirrors `complianceFlags.accountsOverdue` / `annualFilingOverdue`. Use `complianceFlags` when you want the alerting surface, `statutoryFilings` when you want the calendar.
# Coverage and pricing
Source: https://docs.topograph.co/essentials/coverage-and-pricing
Where to find live country coverage, pricing, sources, documents, and availability
Topograph coverage changes as registers, document access, and data products evolve. Use this page as the stable integration guide, and use the live pricing pages as the source of truth for country-specific details.
Open the live coverage matrix for supported countries, available data blocks, documents, sources, identifiers, monitoring availability, and pricing.
## What lives on the pricing pages
Use [topograph.co/pricing](https://topograph.co/pricing) before building country-specific flows. It contains the current product catalog:
* Supported countries, including beta jurisdictions. Beta countries may have gaps and are not covered by SLAs.
* Available data blocks for verification and prefill mode.
* Official sources and provider limitations.
* Accepted identifiers and searchable identifiers.
* Available document types and whether they are standalone or bundled with a data block.
* Monitoring eligibility.
* Which datapoints and documents are [manually delivered](/essentials/manual-delivery) (marked with a **Manual** badge).
* Country vocabularies such as legal forms, roles, activity codes, and status values.
For a specific country, open `https://topograph.co/pricing/{countryCode}` using the lowercase ISO country code, for example [France](https://www.topograph.co/countries/fr) or [Germany](https://www.topograph.co/countries/de).
## What lives in the API docs
These docs explain how to integrate:
* [Quickstart](/quickstart): make your first search and company data request.
* [Company data](/essentials/retrieve_company): request datapoints and documents through `/v2/company`.
* [Verification vs prefill mode](/essentials/modes): choose between authoritative retrieval and fast form-prefill retrieval.
* [Document retrieval](/essentials/document-guide): list and download official documents.
* [Webhooks](/guides/webhooks): receive asynchronous updates.
* [Reliability and errors](/guides/reliability-and-errors): handle in-progress results, register outages, and retries.
## API-side pricing checks
Use `GET /v2/pricing?countryCode=FR` when your application needs to decide what to request at runtime. The endpoint returns the same product model used by the live pricing pages: data blocks, mode availability, included documents, and per-country availability.
```bash theme={null}
curl --request GET \
--url 'https://api.topograph.co/v2/pricing?countryCode=FR' \
--header 'x-api-key: '
```
Prefer the live pricing pages for humans and `GET /v2/pricing` for application logic. Avoid hardcoding country availability or pricing in your own integration.
## Country guide role
Country guides in this documentation are integration notes. They highlight identifier formats, search behavior, important limitations, and local caveats that affect implementation. Exhaustive availability tables, source catalogs, document catalogs, and enum lists belong on the live pricing pages so they stay current.
# Croatia
Source: https://docs.topograph.co/essentials/croatia
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Croatia reference is on the [Croatia country page](https://www.topograph.co/countries/hr).
## Start here
This guide contains public integration notes for Croatia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Prefill mode (fast retrieval)](#prefill-mode-fast-retrieval)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Croatia uses four official sources: Sudreg for corporate data, FINA for financial filings, the UBO Register (RSV) for beneficial ownership, and EU VIES for VAT validation. **Company profile data comes from Sudreg**, the court register, which is the source of truth for structured company attributes. The `taxId` verification status on the company comes from EU VIES.
* **Sudreg (Sudski registar / Court Registry)**: Operated by the Ministry of Justice of the Republic of Croatia. We use two access methods:
* **Sudreg API**: Provides company identifiers, legal form, status, registered address, share capital, and business activities (NKD codes). Used for search by MBS/OIB, prefill profile, and as part of company profile. Accessible at [sudreg-data.gov.hr](https://sudreg-data.gov.hr/api/javni)
* **Sudreg portal**: Primary source for legal representatives, supervisory board members, shareholders, and document listings. Also used for name-based search. Accessible at [sudreg.pravosudje.hr](https://sudreg.pravosudje.hr)
* **RGFI/FINA (Registar godisnjih financijskih izvjestaja)**: The Annual Financial Statements Registry, operated by FINA (Financial Agency), accessible at [rgfi.fina.hr](https://rgfi.fina.hr). Used exclusively for **financial document retrieval** (balance sheets, profit & loss statements, notes to financial statements, profit distribution decisions). It is **not** a structured data source for company attributes.
* **RSV (Registar stvarnih vlasnika / Croatian UBO Register)**: The beneficial ownership register operated by FINA. Source of Ultimate Beneficial Owner data and the official Beneficial Ownership Certificate, delivered manually in about 1-3 business days.
* **EU VIES**: Used to validate the Croatian VAT number (HR + OIB) returned on the company.
Financial statements from FINA RGFI can take longer to deliver than register
data. Sudreg provides structured company data, while its web portal is used
for personnel and document data.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | Sudreg | 9 digits (MBS), leading zeros significant | `030163747` | Maticni broj subjekta (Company Registration Number): 2-digit court number, 6-digit sequence number, check digit |
**Use the MBS for company retrieval.** The company profile also resolves an OIB
or HR VAT number to the MBS, but documents and some datapoints require the MBS.
Search by OIB or company name first, then pass the returned MBS to `/v2/company`.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `mbs` | 9 digits | `030163747` | All companies |
| `oib` | 11 digits | `37034650117` | All companies |
| `mb` | 8 digits; a leading zero is dropped | `3805131` (MB `03805131`) | When available |
| `euid` | HRSR. + 9 digits | `HRSR.030163747` | When available |
| `VAT` | 11 digits (OIB) | `37034650117` | VAT-registered companies |
**VAT and OIB:** In Croatia, the OIB (Osobni identifikacijski broj) serves as
both the national tax ID and the EU VAT number. The VAT identifier in the
response is the same 11-digit OIB value. For EU VIES validation, prefix with
`HR` (e.g., `HR37034650117`).
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the court-register number (`mbs`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By MBS | 9 digits | `030163747` | Exact | Exact match returned first (matchType: id); other results may follow |
| By OIB | 11 digits | `37034650117` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 3 chars) | `"KONZUM"` | Starts with (approximate) | Multiple results |
**Search Performance:** Use identifier-based searches (MBS, OIB) for best
performance and exact matching. Name searches use an "approximately starts
with" operator and may return multiple results.
### Active companies only
The register itself excludes companies that are no longer active when you search with [`activeOnly=true`](/essentials/search#active-companies-only). Name searches ask the register for active companies only. Registration-number and tax-number lookups are filtered on the status the register reports.
## Prefill mode (fast retrieval)
Use [`POST /v2/company`](/essentials/retrieve_company) with [`mode: "prefill"`](/essentials/modes) for fast, cost-effective access to company profile data in Croatia, optimized for prefill requests.
Data comes from Sudreg structured company data only (no personnel data), providing company identifiers, legal form, status, address, share capital, and activity codes.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Use the MBS for company data** | The company profile also resolves an OIB or HR VAT number to the MBS, but documents and some datapoints require the MBS. Search by OIB or name first to get the MBS. |
| **EUID format** | Croatian EUID format is `HRSR.{MBS}`, where `SR` stands for "Sudski registar" (Court Registry). |
| **Struck-off companies have limited data** | When a company is deleted from the register (`Brisanje`), the company name at the time of deletion is returned. Legal representatives, shareholders, and activities are typically not returned. |
| **Some activity codes are AI-inferred** | Sudreg mixes structured NKD codes (the prevailing activity always has one) with free-text activity descriptions in Croatian. Free-text entries are processed via AI to derive NACE and ISIC codes. Always check the `isAIInferred` flag. |
| **Share capital dual currency (HRK/EUR)** | Croatia adopted the euro on January 1, 2023. Share capital comes from structured API fields (amount + currency). Historical entries may still reference HRK amounts alongside EUR. |
| **Legal representative roles are AI-enriched** | The official Court Register function catalogue fixes known Croatian office translations and standardized meanings. Unlisted portal titles may require enrichment. |
| **Supervisory board members are Other Key Persons** | Members of the nadzorni odbor (supervisory board) are mapped to `otherKeyPersons`, not `legalRepresentatives`. Classification is deterministic (based on which register section they appear in). Known role meanings are deterministic; unlisted titles may require enrichment. |
| **Company name sanitization in search** | In search results, status suffixes like `"u likvidaciji"` (in liquidation) and `"u stečaju"` (in bankruptcy) are stripped from company names. The company datapoint returns the legal name as registered. |
| **Financial documents may be HTML** | Some financial statements on RGFI/FINA are served as HTML rather than PDF. These are automatically converted to PDF during retrieval. |
| **Shareholder percentages not available** | Sudreg does not provide ownership percentages or capital contribution amounts. When a company has a single shareholder, `sharePercentage` is returned as 100. |
| **Beneficial ownership is a separate source** | The official RSV beneficial ownership certificate is obtained through a local partner. It is not part of Sudreg company data. |
| **No registration date** | Sudreg does not expose the company registration/incorporation date in the profile data. |
| **UBOs are delivered manually** | Ultimate Beneficial Owners and the Beneficial Ownership Certificate come from the Croatian UBO Register (RSV) and are delivered in about 1-3 business days, so they are not suited to real-time onboarding. |
| **Financial statements take longer** | Financial statements from FINA RGFI take longer to deliver than register data. |
## Mappings
### Company Status
Company status is determined **deterministically** from Sudreg data.
| Local Status | English | Standardized Status | Closure Reason | Notes |
| - | - | - | - | - |
| Aktivan | Active | Active | - | Standard active status |
| U likvidaciji | In liquidation | Under Insolvency Proceeding | Liquidation | Company undergoing liquidation process |
| U stečaju | In bankruptcy | Under Insolvency Proceeding | Bankruptcy | Company undergoing bankruptcy proceedings |
| Brisanje | Struck off / Deleted | Closed | Administrative dissolution | Removed from the register |
| Neaktivni podatak / Neaktivan | Inactive | Closed | - | Other inactive records |
Records the register flags as inconsistent are returned as inactive with a
standardized status of Unknown.
### Legal Forms
Croatia's Court Registry (Sudreg) maintains **26 standardized legal form types**. The mapping is **deterministic** (no AI inference) with ISO 20275 codes from the GLEIF Entity Legal Forms Code List. Unrecognized forms are enriched with ISO 20275 codes via database lookup.
#### Key Business Forms
| Croatian Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Drustvo s ogranicenom odgovornoscu | d.o.o. | Limited Liability Company | Limited Liability Company | OQWO |
| Jednostavno drustvo s ogranicenom odgovornoscu | j.d.o.o. | Simple Limited Liability Company | Limited Liability Company | OQWO |
| Dionicko drustvo | d.d. | Joint Stock Company | Corporation | LUMA |
| Sportsko dionicko drustvo | s.d.d. | Sports Joint Stock Company | Corporation | LUMA |
| Športsko dioničko društvo | š.d.d. | Sports Joint Stock Company | Corporation | LUMA |
#### Partnerships
| Croatian Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Javno trgovacko drustvo | j.t.d. | General Partnership | Partnership | KP34 |
| Komanditno drustvo | k.d. | Limited Partnership | Partnership | MF7P |
| Gospodarsko interesno udruzenje | GIU | Economic Interest Grouping | Partnership | 2FED |
#### Sole Proprietorships
| Croatian Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Trgovac pojedinac | Sole Trader | Sole Proprietorship | 9D9U |
#### Cooperatives
| Croatian Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Zadruga | Cooperative | Cooperative | G5RH |
| Savez zadruga | Cooperative Association | Cooperative | IVVD |
| Hrvatski savez zadruga | Croatian Cooperative Association | Cooperative | IVVD |
| Zadruzni savez | Cooperative Union | Cooperative | IVVD |
| Kreditna unija | Credit Union | Cooperative | 24EG |
#### Public & Institutional Entities
| Croatian Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Ustanova | Institution | Government-Owned Entity | ZFQS |
| Zajednica ustanova | Community of Institutions | Government-Owned Entity | YA9S |
| Fond | Fund | Nonprofit Organization | 28RA |
#### Branch & Foreign Entities
| Croatian Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Inozemna podruznica | Foreign Branch | Branch or Representative Office | NRTG |
| Inozemni osnivac | Foreign Founder | Other | - |
#### European Entity Forms
| Croatian Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Europsko drustvo | European Company (Societas Europaea) | Corporation | E9CM |
| Europsko gospodarsko interesno udruzenje | European Economic Interest Grouping | Partnership | 3OW3 |
| Europska zadruga | European Cooperative Society (SCE) | Cooperative | 8VRU |
| Holding SE | SE Holding Company | Corporation | E9CM |
#### Special & Administrative Forms
| Croatian Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Druga osoba za koje je upis propisan zakonom | Other Entity Required by Law | Other | - |
| Stecajna masa | Bankruptcy Estate | Other | EYKU |
| Likvidacijska masa | Liquidation Estate | Other | - |
### Legal Representatives
Legal representatives are extracted from Sudreg. The classification as legal representative (vs other key person) is **deterministic**, determined by which section of the profile the person appears in. Role names are preserved in Croatian. Known titles from the official Court Register function catalogue have **fixed English translations and standardized meanings**; unlisted portal titles may require enrichment. Recorded representation text, when explicit, supplies sole or joint signing mode and its original qualifications. A title alone supplies no signing mode.
When available, a `startDate` is extracted from the effective date published in the register (e.g., "od 27.12.2024. godine").
Common roles observed in the registry:
| Croatian Role | English Translation | Standardized |
| - | - | - |
| Direktor | Director | Director |
| Clan uprave | Member of the Management Board | Board Member |
| Predsjednik uprave | President of the Management Board | President |
| Prokurist | Authorized Signatory (Procurator) | Authorized Signatory |
| Likvidator | Liquidator | Liquidator |
Legal representatives are returned as individuals. Each representative
includes their OIB (when available) and residence address.
### Other Key Persons
Members of the supervisory board (`nadzorni odbor`) are mapped to `otherKeyPersons` with a default standardized role of `Supervisory Board Member`. Known titles have fixed English translations and standardized meanings; unlisted titles may require enrichment.
| Croatian Role | English Translation | Standardized |
| - | - | - |
| Clan nadzornog odbora | Supervisory Board Member | Supervisory Board Member |
| Predsjednik nadzornog odbora | Chairman of the Supervisory Board | Chairman of the Board |
### Shareholders
Shareholders are extracted from Sudreg for **all company types** that list them. Both individuals and corporate shareholders are supported.
| Field | Description | Source |
| - | - | - |
| `type` | Individual or Company | Determined from registry data (presence of country/registry number = corporate) |
| `individual.name` | Full name | Sudreg |
| `individual.identifiers.oib` | Tax ID | Sudreg (when available) |
| `individual.residenceAddress` | Address | Sudreg (parsed from text) |
| `company.legalName` | Company name | Sudreg |
| `company.identifiers.mbs` | Registry number (Croatian companies) | Sudreg |
| `company.identifiers.registrationNumber` | Registry number (foreign companies) | Sudreg |
| `company.countryCode` | Country of incorporation | Determined from country name (Croatian-to-code mapping) or parsed address |
**Shareholder percentages are not published.** Sudreg does not provide
ownership percentages or capital contribution amounts, so shareholders carry
names, addresses, and identifiers. When a company has a single shareholder,
`sharePercentage` is returned as 100.
### Activity Code Mapping
Sudreg declares one **prevailing activity** ("pretežita djelatnost") per company, always with a structured NKD code. The wider business scope mixes structured NKD entries with **free-text descriptions in Croatian** (e.g., "Racunalno programiranje; Savjetovanje u vezi s racunalima"). Sudreg stamps each structured NKD entry with the revision it was filed under (NKD 1994, NKD 2007 or NKD 2025). `NACE` is published as **Rev. 2.1**: NKD 2007 codes are converted through the official correspondence table (a code can change, and a class that Rev. 2.1 split is published at the closest group or division covering all its successors), NKD 2025 codes are already Rev. 2.1 and pass through unchanged, and NKD 1994 codes have no NACE equivalent and appear only under `NKD` and `NKD_1994`. Free-text descriptions are processed via **AI batch enrichment** to derive NACE and ISIC codes.
```
NKD 2007 codes (Sudreg) → NACE Rev. 2.1 (correspondence table) → ISIC
NKD 2025 codes (Sudreg) → NACE Rev. 2.1 (unchanged) → ISIC
NKD 1994 codes (Sudreg) → NKD / NKD_1994 only
Croatian free-text descriptions (Sudreg) → AI enrichment → NACE + ISIC
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NKD** | Sudreg structured codes, all revisions | `62.01` | No |
| **NKD\_1994 / NKD\_2007 / NKD\_2025** | Sudreg structured codes, grouped by stamped revision | `62.01` | No |
| **NACE** | NKD converted to Rev. 2.1, or AI-derived from Croatian text | `62.10` | Only for free-text entries |
| **ISIC** | Derived from NACE | `621` | Only for free-text entries |
**Main activity.** The prevailing activity ("pretežita djelatnost") declared
by Sudreg is flagged with `isMainActivity: true` on the NKD classification and
listed first. Sudreg does not stamp a revision on it, so it appears under
`NKD` but not under a revision-specific key. The NACE and ISIC codes derived from it inherit the flag. Codes
without the flag are not necessarily secondary: absence means the register did
not mark them. Codes derived from free-text descriptions carry
`isAIInferred: true`, and the original Croatian descriptions are preserved in
the `activityDescription` field, separated by semicolons.
## Ultimate Beneficial Owners
Beneficial ownership comes from the official Izvadak iz Registra stvarnih vlasnika (RSV). Request `ultimateBeneficialOwners` in verification mode for structured data, or order `ultimateBeneficialOwnersCertificate` from `availableDocuments` for the source PDF. Delivery is asynchronous and can take several business days. Follow the existing request through webhooks or polling; do not submit repeated orders while it is pending. If the certificate cannot be obtained, the request reports an error rather than a successful empty result.
## Data Availability
### Data Availability Matrix
| Data Type | Sudreg (Court Registry) | RGFI/FINA (Financial) | Notes |
| - | - | - | - |
| Company Profile | ✅ Async | ❌ | Full data from Sudreg |
| Legal Representatives | ✅ | ❌ | Directors, board members, signatories |
| Other Key Persons | ✅ | ❌ | Supervisory board members |
| Shareholders | ✅ | ❌ | Individuals and corporate (no percentages) |
| Ultimate Beneficial Owners | ❌ | ❌ | Available separately from the UBO Register (RSV) certificate through a local partner, delivered manually in about 1-3 business days |
| Establishments | ❌ | ❌ | Not currently available |
| Activity Codes | ✅ | ❌ | NKD/NACE codes plus AI-inferred codes from free text |
| Documents | ✅ | ✅ | Registry docs from Sudreg, financials from FINA |
**Legend:** ✅ Available | ❌ Not Available | Async = Asynchronous processing
### Documents by Company Type
Croatia provides document access through three official sources: **Sudreg** for corporate filings, **RGFI/FINA** for financial documents, and the **UBO Register (RSV)** for the Beneficial Ownership Certificate, obtained through a local partner.
#### All Company Types
| Document Type | API Category | Source | Format | Notes |
| - | - | - | - | - |
| **Certified Trade Register Extract** | `certifiedTradeRegisterExtract` | Sudreg | PDF | Always available for any company |
| **Financial Statements** | `financialStatements[]` | RGFI/FINA | PDF | Balance sheet, P\&L, notes, profit distribution decision |
| **Articles of Association** | `articlesOfAssociation[]` | Sudreg | PDF/TIFF | Company bylaws, founding documents |
| **Registry Documents** | `otherDocuments[]` | Sudreg | PDF/TIFF | Registration decisions, OIB certs, announcements, powers of attorney |
| **Beneficial Ownership Certificate** | `ultimateBeneficialOwnersCertificate` | RSV | PDF | Izvadak iz Registra stvarnih vlasnika. Listed for every company, obtained on request through a local partner and delivered manually in about 1-3 business days |
#### Financial Document Types (from FINA RGFI)
| Croatian Name | English Name | Format |
| - | - | - |
| Bilanca za poduzetnike | Balance Sheet | HTML (converted to PDF) |
| Racun dobiti i gubitka za poduzetnike | Profit and Loss Statement | HTML (converted to PDF) |
| Biljeske uz financijske izvjestaje | Notes to Financial Statements | PDF |
| Odluka o raspodjeli dobiti ili pokricu gubitaka | Decision on Profit Distribution | PDF |
#### Registry Document Types (from Sudreg)
| Croatian Name | English Name |
| - | - |
| Prijava | Application/Filing |
| Zapisnik o osnivanju | Minutes of Establishment |
| Osnivacki akt | Founding Act |
| Drustveni ugovor | Articles of Association |
| Rjesenje o upisu | Registration Decision |
| Prilog uz rjesenje o upisu | Attachment to Registration Decision |
| Opce rjesenje | General Decision |
| Oglas | Announcement (Official Gazette) |
| Potvrda o osobnom identifikacijskom broju | OIB Certificate |
| Potvrda o uplacenom ulogu | Capital Payment Certificate |
| Izjava o nepostojanju nepodmirenih dugovanja | Declaration of No Outstanding Debts |
| Punomoć | Power of Attorney |
| Dokaz o uplati sudske pristojbe | Court Fee Payment Proof |
| Popis clanova (osnivaca) | List of Members (Founders) |
| Popis clanova | List of Members |
| Popis osoba ovlastenih za zastupanje | List of Authorized Representatives |
| Obavijest o elektronickom upisu | Electronic Registration Notice |
| Financijska izvjesca | Financial Statements |
| Drugi prilog uz prijavu | Other Application Attachment |
#### Foreign Branch Documents
For foreign branches registered in Croatia, additional documents are available via `otherDocuments[]`. Certified translations of the founder's financial statements are returned under `financialStatements[]`:
| Document | Notes |
| - | - |
| Founder's Decision on Branch Establishment | Parent company decision |
| Certified Translation of Foreign Registry Extract | From parent company's home registry |
| Foreign Registry Extract | Original from parent company |
| Certified Signature of Branch Representative | Notarized signature specimen |
| Certified Translation of Financial Statements of Foreign Branch Founder | Parent company financials, under `financialStatements[]` |
All documents are delivered in PDF format. Some historical registry documents
may be in TIFF format. Document names are translated from Croatian to English
using a deterministic mapping with AI fallback for unrecognized names.
Financial documents from FINA that are served as HTML are automatically
converted to PDF.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "HR", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "080012345",
"countryCode": "HR",
"identifiers": { "VAT": "12345678901", "mbs": "080012345", "oib": "12345678901", "euid": "HRSR.080012345" },
"taxId": { "type": "eu_vat", "value": "12345678901", "country": "HR", "verification": { "status": "verified", "verifiedName": "PRIMJER TEHNOLOGIJA J.D.O.O." } },
"legalName": "PRIMJER TEHNOLOGIJA jednostavno društvo s ograničenom odgovornošću",
"commercialNames": ["PRIMJER TEHNOLOGIJA j.d.o.o."],
"status": { "localName": "Aktivan", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "jednostavno društvo s ograničenom odgovornošću", "englishTranslation": "Simple Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "OQWO" },
"capital": { "amount": 10, "currency": "EUR" },
"activityDescription": "Računalno programiranje; Savjetovanje u vezi s računalima; Obrada podataka",
"activities": {
"NACE": [
{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": true },
{ "code": "62.02", "description": "Computer consultancy activities", "isAIInferred": true },
{ "code": "63.11", "description": "Data processing, hosting and related activities", "isAIInferred": true }
],
"ISIC": [
{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true },
{ "code": "6202", "description": "Computer consultancy and computer facilities management activities", "isAIInferred": true },
{ "code": "6311", "description": "Data processing, hosting and related activities", "isAIInferred": true }
]
},
"legalAddress": { "addressLine1": "Ilica 10", "city": "Zagreb", "postalCode": "10000", "countryCode": "HR", "state": "Grad Zagreb" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "član uprave", "englishTranslation": "Member of the Management Board", "standardized": "Board Member" }, "individual": { "name": { "fullName": "MARKO HORVAT" }, "identifiers": { "oib": "98765432109" }, "residenceAddress": { "addressLine1": "Vukovarska 5", "city": "Zagreb", "postalCode": "10000", "countryCode": "HR" } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "individual": { "name": { "fullName": "MARKO HORVAT" }, "identifiers": { "oib": "98765432109" }, "residenceAddress": { "addressLine1": "Vukovarska 5", "city": "Zagreb", "postalCode": "10000", "countryCode": "HR" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "080054321",
"countryCode": "HR",
"identifiers": { "VAT": "11223344556", "mbs": "080054321", "oib": "11223344556", "euid": "HRSR.080054321" },
"legalName": "VELIKA KOMPANIJA dioničko društvo",
"status": { "localName": "Aktivan", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "dioničko društvo", "englishTranslation": "Joint Stock Company", "standardized": "Corporation", "iso20275Code": "LUMA" },
"capital": { "amount": 200000, "currency": "EUR" },
"activityDescription": "Trgovina na veliko; Zastupanje inozemnih tvrtki",
"activities": {
"NACE": [{ "code": "46.90", "description": "Non-specialized wholesale trade", "isAIInferred": true }],
"ISIC": [{ "code": "4690", "description": "Non-specialized wholesale trade", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Trg bana Jelačića 1", "city": "Zagreb", "postalCode": "10000", "countryCode": "HR" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "predsjednik uprave", "englishTranslation": "President of the Management Board", "standardized": "President" }, "individual": { "name": { "fullName": "ANA KOVAČEVIĆ" } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "član uprave", "englishTranslation": "Member of the Management Board", "standardized": "Board Member" }, "individual": { "name": { "fullName": "IVAN NOVAK" } } }
],
"otherKeyPersons": [
{ "entityId": "person_003", "type": "individual", "role": { "localName": "član nadzornog odbora", "englishTranslation": "Supervisory Board Member", "standardized": "Supervisory Board Member" }, "individual": { "name": { "fullName": "PETRA JURIĆ" } } },
{ "entityId": "person_004", "type": "individual", "role": { "localName": "predsjednik nadzornog odbora", "englishTranslation": "Chairman of the Supervisory Board", "standardized": "Chairman of the Board" }, "individual": { "name": { "fullName": "TOMISLAV BABIĆ" } } }
],
"shareholders": [
{ "entityId": "company_001", "type": "company", "company": { "id": "080099999", "legalName": "HOLDING PRIMJER d.o.o.", "countryCode": "HR", "identifiers": { "mbs": "080099999" } } },
{ "entityId": "person_001", "type": "individual", "individual": { "name": { "fullName": "ANA KOVAČEVIĆ" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "060098765",
"countryCode": "HR",
"identifiers": { "VAT": "98765432109", "mbs": "060098765", "oib": "98765432109", "euid": "HRSR.060098765" },
"legalName": "STARA TVRTKA d.o.o.",
"status": { "localName": "Brisanje", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "ADMINISTRATIVE_DISSOLUTION" } },
"legalForm": { "localName": "društvo s ograničenom odgovornošću", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "OQWO" },
"legalAddress": { "addressLine1": "Vukovarska 5", "city": "Split", "postalCode": "21000", "countryCode": "HR" }
}
}
```
**Note:** Struck-off companies have `active: false` and status `Brisanje`. The company name is the name at the time of deletion. No legal representatives, shareholders, or activities are returned for struck-off companies.
```json theme={null}
{
"company": {
"id": "040011111",
"countryCode": "HR",
"identifiers": { "VAT": "11111111111", "mbs": "040011111", "oib": "11111111111", "euid": "HRSR.040011111" },
"legalName": "NESOLVENTNA TVRTKA d.d.",
"status": { "localName": "U stečaju", "active": false, "statusDetails": { "status": "UNDER_INSOLVENCY_PROCEEDING", "closureReason": "BANKRUPTCY" } },
"legalForm": { "localName": "dioničko društvo", "englishTranslation": "Joint Stock Company", "standardized": "Corporation", "iso20275Code": "LUMA" },
"legalAddress": { "addressLine1": "Trg bana Jelačića 1", "city": "Zagreb", "postalCode": "10000", "countryCode": "HR" }
}
}
```
```json theme={null}
{
"company": {
"id": "130022222",
"countryCode": "HR",
"identifiers": { "VAT": "22222222222", "mbs": "130022222", "oib": "22222222222", "euid": "HRSR.130022222" },
"legalName": "FOREIGN CORP DOO BEOGRAD",
"status": { "localName": "Brisanje", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "ADMINISTRATIVE_DISSOLUTION" } },
"legalForm": { "localName": "inozemna podružnica", "englishTranslation": "Foreign Branch", "standardized": "Branch or Representative Office", "iso20275Code": "NRTG" },
"legalAddress": { "addressLine1": "Heinzelova 62", "city": "Zagreb", "postalCode": "10000", "countryCode": "HR" }
}
}
```
**Note:** Foreign branches registered in Croatia may have additional documents including certified translations of the parent company's registry extracts and financial statements.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Source | Notes |
| - | - | - | - |
| `certifiedTradeRegisterExtract` | Certified extract (Izvadak) | Sudreg | Always available |
| `financialStatements[]` | Balance sheet, P\&L, notes, profit distribution decision | RGFI/FINA | When filed, per fiscal year |
| `articlesOfAssociation[]` | Company bylaws, founding documents (Zapisnik o osnivanju, Osnivacki akt, Drustveni ugovor) | Sudreg | When available |
| `otherDocuments[]` | Registration decisions, OIB certs, announcements, powers of attorney, applications | Sudreg | Historical filings |
| `ultimateBeneficialOwnersCertificate` | Beneficial Ownership Certificate (Izvadak iz Registra stvarnih vlasnika) | RSV | Always listed, delivered manually in about 1-3 business days |
# Cyprus
Source: https://docs.topograph.co/essentials/cyprus
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Cyprus reference is on the [Cyprus country page](https://www.topograph.co/countries/cy).
## Start here
This guide contains public integration notes for Cyprus. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Cyprus company data comes from three official sources:
* **DRCOR (Department of Registrar of Companies and Official Receiver).** Operated by the Ministry of Energy, Commerce and Industry. In verification mode, company profile data (name, status, legal form, registered address, officers) is read live from the DRCOR register at [efiling.drcor.mcit.gov.cy](https://efiling.drcor.mcit.gov.cy). Shareholder data is extracted from the **Trade Register Extract (Study File)** PDF, which is retrieved from DRCOR and parsed with AI.
* **DRCOR Open Data.** A monthly open-data extract of the register (companies, business names, partnerships and their officials) published on [data.gov.cy](https://www.data.gov.cy/en/dataset/1026). In prefill mode, `company`, `legalRepresentatives` and `otherKeyPersons` are served from this extract. It is fast but not a live register query, so companies registered or changed since the last refresh can be missing or stale. Use verification mode for the live record.
* **Cyprus Register of Beneficial Owners.** Source of `ultimateBeneficialOwners`. The Beneficial Ownership Certificate is obtained through a local partner, typically within 1 to 3 business days, and beneficial owners are extracted from it by AI. The certificate itself is included.
## Company Identifiers
Domestic private and public limited companies can return `company.identifiers.euid`, for example `CYDRCOR.HE433437`. The EUID uses the Latin `HE` prefix even when `registrationNumber` uses Greek letters. Verification provides it for eligible companies; older prefill profiles may omit it. It is not a search key.
### Query Identifiers
Cyprus uses a unique identifier system where **Greek letter prefixes** are part of the registration number and indicate the company type:
| Prefix (as returned) | Latin look-alike | Register type | English Translation | Company Type | Example |
| - | - | - | - | - | - |
| **ΗΕ** | HE | Εταιρεία | Company | Private or public company | `ΗΕ433437` |
| **ΕΕ** | EE | Εμπορική Επωνυμία | Business Name | Business name (trade name) | `ΕΕ25556` |
| **Σ** | S | Συνεταιρισμός | Partnership | Partnership (limited or general) | `Σ2536` |
| **ΑΕ** | AE | Αλλοδαπή Εταιρεία | Overseas Company | Foreign company registered in Cyprus | `ΑΕ1677` |
| **BN** | (already Latin) | Συνεταιρισμός (BN) | Business-Name Partnership | Partnership registered as a business name | `BN1` |
**The registration number includes the prefix**
The canonical registration number is the prefix followed by 1 to 6 digits, with no space and no leading zeros (e.g. `ΗΕ433437`, `ΗΕ218`, `BN1`). The prefixes use Greek Unicode letters, not the Latin letters they resemble: **HE** = `ΗΕ` (U+0397 U+0395), **EE** = `ΕΕ`, **S** = `Σ` (U+03A3), **AE** = `ΑΕ` (U+0391 U+0395). Business-name partnerships use the Latin prefix `BN`. Search accepts the Latin spelling of the Greek prefixes (`HE433437` or `HE 433437`) and maps it to the Greek form. Responses always return the Greek form, so use the `id` returned by search when requesting company data.
**Same number, different companies:** The numeric portion of a registration number is NOT unique across prefixes. For example, `ΗΕ25556` (a company) and `ΕΕ25556` (a business name) are **two completely different entities**. The unique identifier is always the full prefix + number combination.
### Identifiers in API Response
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `registrationNumber` | Greek prefix (ΗΕ, ΕΕ, Σ, ΑΕ) or Latin `BN`, then 1 to 6 digits, no space | `ΗΕ433437` | All companies |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the full registration number (`registrationNumber`), including its prefix matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Full Registration Number | Prefix + digits (Greek prefix, its Latin spelling HE/EE/AE/S with an optional space, or `BN`) | `ΗΕ433437` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Number Only | Digits only | `433437` | Partial | Multiple results (all prefixes for that number) |
| By Company Name | Text string | `"YIAZOU GALAXY"` | Fuzzy | Multiple results, ranked |
| By VAT Number | `CY` + 8 digits + letter, or without `CY` | `CY12345678X` | Via registered name | Companies matching the name registered for that VAT number |
**Search Performance:** Use the full registration number with its prefix for exact matching. Latin-typed prefixes (`HE`, `EE`, `AE`, `S`) are accepted and mapped to the Greek form. Number-only searches return all companies sharing that numeric portion across different prefixes (ΗΕ, ΕΕ, Σ, ΑΕ, BN).
**Name search:** Name searches return a bounded, ranked set of results, match both Greek and Latin spellings of a name, and tolerate small spelling differences. A broad term returns results rather than an error. Use more specific search terms or the full registration number for best results.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies under liquidation or administration count as inactive and are filtered out too.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Registration numbers use Greek prefixes** | The canonical registration number includes the Greek letter prefix (ΗΕ, ΕΕ, Σ, ΑΕ), or `BN` for business-name partnerships. Search accepts the Latin spelling (HE, EE, S, AE) and returns the Greek form; use that returned `id` for company data requests. |
| **Same number, different companies** | Number `25556` with different prefixes (ΗΕ25556, ΕΕ25556) identifies **completely different entities**. Searching without a prefix returns all matching prefixes. |
| **No activity codes** | DRCOR does not provide structured activity codes (NACE, ISIC, etc.). Activity information is not available for Cypriot companies. |
| **No share capital in structured data** | Share capital is not extracted from the web portal. It is available within the Study File PDF but not parsed into structured fields. |
| **No VAT numbers** | DRCOR does not provide VAT identification numbers. The only identifier returned is the registration number. |
| **Shareholders require document retrieve** | Shareholders are extracted from the Study File PDF, which must be retrieved from DRCOR. They are billed as the Trade Register Extract. The shareholders datapoint itself does not incur additional charges beyond the document cost. |
| **Entity type classification is AI-powered** | DRCOR does not indicate whether a legal representative is an individual or a company. AI classifies entity type from name patterns (e.g., suffixes like "LIMITED", "LTD", "ΛΙΜΙΤΕΝΤ"). This may occasionally misclassify edge cases. |
| **Legal form, status and roles use fixed mappings** | DRCOR legal forms, statuses and officer roles come from small, closed register vocabularies. English translations, standardized values and ISO 20275 codes are assigned from fixed tables, not AI. The Greek local names are always preserved verbatim. |
| **Legacy legal names tracked** | When a company has changed its name, both current and previous names are returned. DRCOR search results include name history (Τελευταίο Όνομα = Current Name, Προηγούμενο Όνομα = Previous Name). |
| **Prefill data is refreshed monthly** | Prefill mode reads the monthly open-data extract of the register. Recent registrations and changes may not appear until the next refresh. Verification mode reads DRCOR live. |
| **Study File is in English** | Unlike many other country registries, the Cyprus Trade Register Extract (Study File) is provided in English, making it more accessible for international users. |
| **Names may be in Greek or English** | Company names, officer names, and addresses on DRCOR can appear in either Greek or English (or a mix). The system preserves whichever language is used in the registry. |
## Mappings
### Company Status
Company status is extracted from the DRCOR organisation status. The raw status is in Greek and is preserved verbatim in `localName`. The standardized status comes from a fixed mapping of the register's status values.
| Local Status (Greek) | English Translation | Standardized Status | Notes |
| - | - | - | - |
| Εγγεγραμμένη | Registered | Active | Company is actively registered |
| Στάληκε επιστολή Υπενθύμισης | Reminder Letter Sent | Active | Pre-strike-off warning; the company is still on the register |
| Δημοσιεύτηκε η Τρίμηνη | Three-Month Notice Published | Active | Pre-strike-off notice; the company is still on the register |
| Ευρωπαϊκή Εταιρεία | European Company (SE) | Active | |
| Υπο Διαχείριση | Under Administration | Under Insolvency Proceeding | |
| Υπο Εκκαθάριση | In Liquidation | Under Insolvency Proceeding | |
| Υπο Διαχείριση & Υπο Εκκαθάριση | Under Administration and In Liquidation | Under Insolvency Proceeding | |
| Εκούσια Εκκαθάριση από Μετόχους | Members' Voluntary Winding-Up | Under Insolvency Proceeding | |
| Εκούσια Εκκαθάριση από Πιστωτές | Creditors' Voluntary Winding-Up | Under Insolvency Proceeding | |
| Εκκαθάριση με Διάταγμα Δικαστηρίου | Compulsory Winding-Up by Court Order | Under Insolvency Proceeding | |
| Διορισμός Προσωρινού Εκκαθαριστή | Provisional Liquidator Appointed | Under Insolvency Proceeding | |
| Εκκαθάριση με Διάταγμα Δικαστηρίου& Διορ.Ειδικού Διαχειριστή | Court Winding-Up with Special Manager Appointed | Under Insolvency Proceeding | |
| Διαγραμμένη | Struck Off | Closed | Closure reason: administrative dissolution |
| Διάλυση λόγω Ολοκλήρωσης Εκούσιας Εκκαθάρισης | Dissolved after Voluntary Liquidation | Closed | Closure reason: liquidation |
| Διάλυση λόγω Ολοκλήρωσης Εκκαθάρισης | Dissolved after Liquidation | Closed | Closure reason: liquidation |
| Διαλύθηκε λόγω συγχώνευσης | Dissolved by Merger | Closed | Closure reason: merger |
| Αφαιρέθηκε από το Μητρώο ΕΕ με απόφαση Ανωτάτου Δικαστηρίου | Removed from the Register by Supreme Court Decision | Closed | Closure reason: court order |
A status value outside this list is returned with its local name and a standardized status of Unknown. Only Active statuses set `active: true`. When a company is closed, a closure date is captured when available from DRCOR.
### Legal Forms
The local legal form is preserved from DRCOR in Greek. English translations, standardized categories and ISO 20275 codes come from a fixed mapping of the register's type and sub-type. The type and optional sub-type are combined (e.g., "Εταιρεία - Ιδιωτική") to form the local name.
#### Private & Public Companies
| Greek Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Εταιρεία - Ιδιωτική | Private Company | Limited Liability Company | RCPI |
| Εταιρεία - Δημόσια | Public Company | Corporation | N/A |
| Εταιρεία - Δι΄ Εγγυήσεως | Company Limited by Guarantee | Nonprofit Organization | N/A |
#### Overseas Companies
| Greek Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Αλλοδαπή Εταιρεία | Overseas Company | Branch or Representative Office | HIL6 |
#### Business Names (Sole Traders)
| Greek Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Εμπορική Επωνυμία | Business Name | Sole Proprietorship | FV0K |
#### Partnerships
| Greek Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Συνεταιρισμός - Ομόρρυθμος | General Partnership | Partnership | N/A |
| Συνεταιρισμός - Ετερόρρυθμος | Limited Partnership | Partnership | N/A |
| Συνεταιρισμός (BN) - Ομόρρυθμος | General Partnership (Business Name) | Partnership | N/A |
| Συνεταιρισμός (BN) - Ετερόρρυθμος | Limited Partnership (Business Name) | Partnership | N/A |
The Greek local legal form name is always preserved verbatim from DRCOR. The sub-type (e.g., "Ιδιωτική" for Private, "Δημόσια" for Public, "Ομόρρυθμος" for General) distinguishes variants within the same base type. A partnership with no sub-type is returned as "Partnership".
### Legal Representatives
Legal representatives are extracted from the DRCOR company profile page ("Officials" section). Both **individuals and corporate entities** can hold these roles. Role names are preserved in the local language (Greek or English as provided by DRCOR) and translated and standardized through a fixed mapping of the register's role values. Only the individual vs. company classification is inferred.
The classification of a name as **individual vs. company** is **AI-powered** based on name patterns and context (e.g., suffixes like "LIMITED", "LTD", "ΠΕΡΙΟΡΙΣΜΕΝΗΣ", "ΛΤΔ", "ΕΤΑΙΡΕΙΑ" indicate a corporate entity).
| Local Role (Greek or English) | English Translation | Standardized Role | Context |
| - | - | - | - |
| Διευθυντής / Director | Director | Director | Legal Representative |
| Αντικαταστάτης Διευθυντής | Alternate Director | Director | Legal Representative |
| Διευθύνων Σύμβουλος | Managing Director | Managing Director | Legal Representative |
| Εξουσιοδοτημένο Πρόσωπο | Authorized Person | Authorized Signatory | Legal Representative |
| Ιδιοκτήτης / Owner | Owner | Owner | Legal Representative |
| Ομόρρυθμος Συνέταιρος / General Partner | General Partner | General Partner | Legal Representative |
| Γραμματέας / Secretary | Secretary | Secretary | Other Key Person |
| Βοηθός Γραμματέας | Assistant Secretary | Secretary | Other Key Person |
| Αναπληρωτής Γραμματέας | Deputy Secretary | Secretary | Other Key Person |
| Ετερόρρυθμος Συνέταιρος / Limited Partner | Limited Partner | Other | Other Key Person |
| Διαχειριστής | Manager | Other | Other Key Person |
Directors exercise the company powers subject to reserved matters and its articles; their title does not determine individual signing mode. Secretaries have separate administrative duties. Under [Partnership Law Cap.116, sections 8–9 and 49](https://www.cylaw.org/nomoi/enop/non-ind/0_116/full.html), general partners have ordinary-business agency, while limited partners do not bind the partnership. A separate authorized grant is distinct from that ownership capacity.
Unknown filed positions retain their local name and appear as other key persons with standardized `Other`. Corporate identities are preserved in both lists. Both live verification and the monthly prefill extract use this distinction.
### Shareholders
Shareholders are extracted from the **Trade Register Extract (Study File)** PDF using AI parsing. This is the only source for shareholder data in Cyprus.
#### Extraction Flow
1. The Trade Register Extract PDF is retrieved from DRCOR (billed as the Trade Register Extract)
2. Text is extracted from the PDF
3. AI parses the extracted text to identify shareholders, share counts, and percentages
#### Shareholder Data
| Field | Description | Source |
| - | - | - |
| `type` | Individual or Company | AI-classified from name patterns in Study File |
| `numberOfShares` | Number of shares held | Extracted from Study File |
| `sharePercentage` | Ownership percentage | Calculated from share count vs total shares, or extracted directly |
#### Greek Terms in Study File
| Greek Term | English Translation |
| - | - |
| Μέτοχοι | Shareholders |
| Μετοχικό Κεφάλαιο | Share Capital |
| Μετοχές | Shares |
| Ποσοστό | Percentage |
| Ιδιοκτήτης | Owner |
Shareholder extraction requires the Trade Register Extract to be retrieved, and is billed as the Trade Register Extract when the document is fetched. The shareholders datapoint itself does not incur additional charges beyond the document retrieve. Both individual and corporate shareholders are supported, including foreign corporate shareholders with international addresses.
### Activity Code Mapping
DRCOR **does not provide** structured activity codes (NACE, ISIC, or any national classification). Activity information is not available for Cypriot companies.
## Ultimate Beneficial Owners
The official certificate from the Register of Beneficial Owners is obtained through a local partner. Request `ultimateBeneficialOwners` in verification mode for structured data, or order `ultimateBeneficialOwnersCertificate` from `availableDocuments` for the source PDF. Delivery is asynchronous and typically takes 1 to 3 business days. Follow the existing request through webhooks or polling; do not submit repeated orders while it is pending. If the certificate cannot be obtained, the request reports an error rather than a successful empty result.
## Data Availability
### Data Availability Matrix
| Data Type | DRCOR (Live Register) | Study File (PDF) | Notes |
| - | - | - | - |
| Company Profile | ✅ Async | ❌ | Name, status, legal form, address, registration date. Prefill mode reads the monthly open-data extract; verification mode reads DRCOR live |
| Legal Representatives | ✅ | ❌ | Directors, general partners, authorized persons and proprietors. Prefill mode reads the monthly open-data extract; verification mode reads DRCOR live |
| Other Key Persons | ✅ | ❌ | Secretaries, limited partners and other non-representing appointments, in both modes |
| Shareholders | ❌ | ✅ | Extracted from Study File PDF via AI (verification mode) |
| Ultimate Beneficial Owners | ❌ | ❌ | Available separately in verification mode from the Register of Beneficial Owners through a local partner. Typically 1 to 3 business days; extracted by AI from the Beneficial Ownership Certificate |
| Establishments | ❌ | ❌ | Not available |
| Activity Codes | ❌ | ❌ | Not provided by DRCOR |
| Share Capital | ❌ | ⚠️ | Available in Study File but not parsed into structured fields |
| Documents | ❌ | ✅ | Trade Register Extract (Study File); a separate Beneficial Ownership Certificate is available through a local partner |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Documents by Company Type
All entity types (ΗΕ, ΕΕ, Σ, ΑΕ, BN) have access to the same documents. The Study File covers registration history. The Beneficial Ownership Certificate is a separate document from the Register of Beneficial Owners.
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract (Study File)** | `tradeRegisterExtract` | PDF | ✅ All companies | English language, delivery typically around 10 minutes (occasionally up to 24 hours), full registration history |
| **Beneficial Ownership Certificate** | `ultimateBeneficialOwnersCertificate` | PDF | ✅ All companies | From the Register of Beneficial Owners, obtained manually through a local partner and separate from the Study File, typically 1 to 3 business days |
The Trade Register Extract is commonly referred to as a "Study File" in Cyprus. It provides the most comprehensive view of a company's registration history from DRCOR, including company structure, officers, shareholders, filings, and status since incorporation. The document is always in English.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "CY", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "ΗΕ400001",
"countryCode": "CY",
"identifiers": {"registrationNumber": "ΗΕ400001"},
"legalName": "EXAMPLE VENTURES LTD",
"registrationDate": "2022-04-19",
"status": {"localName": "Εγγεγραμμένη", "active": true, "statusDetails": {"status": "ACTIVE"}},
"legalForm": {"localName": "Εταιρεία - Ιδιωτική", "englishTranslation": "Private Company", "standardized": "Limited Liability Company", "iso20275Code": "RCPI"},
"legalAddress": {"addressLine1": "25 Makariou Avenue", "city": "Nicosia", "postalCode": "1065", "countryCode": "CY"}
},
"legalRepresentatives": [
{"entityId": "person_001", "type": "individual", "role": {"localName": "Διευθυντής", "englishTranslation": "Director", "standardized": "Director"}, "individual": {"name": {"fullName": "Αντρέας Γεωργίου", "firstName": "Αντρέας", "lastName": "Γεωργίου"}}}
],
"otherKeyPersons": [
{"entityId": "person_002", "type": "individual", "role": {"localName": "Γραμματέας", "englishTranslation": "Secretary", "standardized": "Secretary"}, "individual": {"name": {"fullName": "Μαρία Χριστοδούλου", "firstName": "Μαρία", "lastName": "Χριστοδούλου"}}}
]
}
```
```json theme={null}
{
"company": {
"id": "ΗΕ100001",
"countryCode": "CY",
"identifiers": {"registrationNumber": "ΗΕ100001"},
"legalName": "OLD TRADING LIMITED",
"registrationDate": "2005-09-09",
"status": {"localName": "Διαγραμμένη", "active": false, "statusDetails": {"status": "CLOSED", "closureDate": "2014-09-15"}},
"legalForm": {"localName": "Εταιρεία - Ιδιωτική", "englishTranslation": "Private Company", "standardized": "Limited Liability Company", "iso20275Code": "RCPI"},
"legalAddress": {"addressLine1": "6 Michail Michailidi", "addressLine2": "Tower 3", "city": "Limassol", "postalCode": "3030", "countryCode": "CY"}
},
"legalRepresentatives": [
{"entityId": "company_001", "type": "company", "role": {"localName": "Διευθυντής", "englishTranslation": "Director", "standardized": "Director"}, "company": {"id": "CORPORATE DIRECTORS LIMITED", "legalName": "CORPORATE DIRECTORS LIMITED", "countryCode": "CY"}}
],
"otherKeyPersons": [
{"entityId": "company_002", "type": "company", "role": {"localName": "Γραμματέας", "englishTranslation": "Secretary", "standardized": "Secretary"}, "company": {"id": "CORPORATE SECRETARIAL SERVICES LIMITED", "legalName": "CORPORATE SECRETARIAL SERVICES LIMITED", "countryCode": "CY"}}
]
}
```
**Note:** Closed companies have `active: false`, status `Διαγραμμένη` (Struck Off), and `closureDate` when available. Corporate legal representatives are common in Cyprus, especially for holding structures.
```json theme={null}
{
"company": {
"id": "ΑΕ2001",
"countryCode": "CY",
"identifiers": {"registrationNumber": "ΑΕ2001"},
"legalName": "FOREIGN HOLDINGS PLC",
"registrationDate": "2011-09-21",
"status": {"localName": "Εγγεγραμμένη", "active": true, "statusDetails": {"status": "ACTIVE"}},
"legalForm": {"localName": "Αλλοδαπή Εταιρεία", "englishTranslation": "Overseas Company", "standardized": "Branch or Representative Office", "iso20275Code": "HIL6"},
"legalAddress": {"addressLine1": "2 Dramas", "city": "Nicosia", "postalCode": "1077", "countryCode": "CY"}
},
"legalRepresentatives": [
{"entityId": "person_001", "type": "individual", "role": {"localName": "Διευθυντής", "englishTranslation": "Director", "standardized": "Director"}, "individual": {"name": {"fullName": "John Smith", "firstName": "John", "lastName": "Smith"}}},
{"entityId": "company_001", "type": "company", "role": {"localName": "Εξουσιοδοτημένο Πρόσωπο", "englishTranslation": "Authorized Person", "standardized": "Authorized Signatory"}, "company": {"id": "LOCAL AGENT LTD", "legalName": "LOCAL AGENT LTD", "countryCode": "CY"}}
]
}
```
**Note:** Overseas companies (ΑΕ prefix) are foreign entities registered in Cyprus. They commonly have a mix of individual directors and corporate authorized persons acting as local agents.
```json theme={null}
{
"company": {
"id": "ΕΕ20001",
"countryCode": "CY",
"identifiers": {"registrationNumber": "ΕΕ20001"},
"legalName": "EXAMPLE TRADE & SERVICES",
"registrationDate": "2004-04-19",
"status": {"localName": "Εγγεγραμμένη", "active": true, "statusDetails": {"status": "ACTIVE"}},
"legalForm": {"localName": "Εμπορική Επωνυμία", "englishTranslation": "Business Name", "standardized": "Sole Proprietorship", "iso20275Code": "FV0K"},
"legalAddress": {"addressLine1": "70 Grivas Digenis Avenue", "city": "Nicosia", "postalCode": "2682", "countryCode": "CY"}
},
"legalRepresentatives": [
{"entityId": "person_001", "type": "individual", "role": {"localName": "Ιδιοκτήτης", "englishTranslation": "Owner", "standardized": "Owner"}, "individual": {"name": {"fullName": "Ελένη Παπαδοπούλου", "firstName": "Ελένη", "lastName": "Παπαδοπούλου"}}}
]
}
```
**Note:** Business names (ΕΕ prefix) are sole trader registrations. They typically have a single legal representative with role `Ιδιοκτήτης` (Owner).
```json theme={null}
{
"company": {
"id": "ΕΕ5001",
"countryCode": "CY",
"identifiers": {"registrationNumber": "ΕΕ5001"},
"legalName": "NIKOS RESTAURANT",
"registrationDate": "1985-06-20",
"status": {"localName": "Διαγραμμένη", "active": false, "statusDetails": {"status": "CLOSED"}},
"legalForm": {"localName": "Εμπορική Επωνυμία", "englishTranslation": "Business Name", "standardized": "Sole Proprietorship", "iso20275Code": "FV0K"}
}
}
```
**Note:** Inactive sole traders may not have address data or legal representatives in the registry. No closure date is provided for this entity type.
Shareholders are returned when `"dataPoints": ["shareholders"]` is requested. This requires retrieving the Trade Register Extract.
```json theme={null}
{
"shareholders": [
{"entityId": "person_001", "type": "individual", "numberOfShares": 500, "individual": {"name": {"fullName": "Αντρέας Γεωργίου"}}},
{"entityId": "company_001", "type": "company", "numberOfShares": 1000, "company": {"legalName": "FOREIGN HOLDING INC.", "countryCode": "US", "legalAddress": {"city": "Wilmington", "state": "Delaware", "countryCode": "US"}}}
]
}
```
**Note:** Shareholders extraction is billed as the Trade Register Extract. Share counts are extracted from the Study File; percentages are calculated when total share capital is available. Both Cypriot and foreign corporate shareholders are supported.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {"id": "doc-uuid-placeholder", "name": "Trade Register Extract", "format": "pdf", "description": "Study File - public registry record from DRCOR containing company structure, officers, shareholders, filings, and status since incorporation", "estimatedDeliverySeconds": 600},
"ultimateBeneficialOwnersCertificate": {"id": "doc-uuid-placeholder-2", "name": "BOR Beneficial Ownership Certificate", "format": "pdf", "description": "Official Cypriot beneficial ownership certificate from the Register of Beneficial Owners"}
}
}
```
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Study File (Trade Register Extract) | Typically around 10 minutes (occasionally up to 24 hours), English language, all company types |
| `ultimateBeneficialOwnersCertificate` | Beneficial Ownership Certificate | Obtained manually through a local partner, typically 1 to 3 business days, all company types |
# Czechia
Source: https://docs.topograph.co/essentials/czechia
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Czechia reference is on the [Czechia country page](https://www.topograph.co/countries/cz).
## Start here
This guide contains public integration notes for Czechia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Czechia uses multiple official registers orchestrated through ARES. For a given entity, data is assembled from ARES as the discovery layer, then enriched from the primary source register indicated by ARES. The primary source takes precedence for overlapping attributes.
### Registers
* **ARES (Administrative Register of Economic Subjects)** -- Operated by the Ministry of Finance (`ares.gov.cz`), ARES is the central discovery layer for all Czech entities. It aggregates data from over a dozen underlying registers and provides: company name, legal form, registered address, activity codes (CZ-NACE), registration/dissolution dates, tax identifiers (DIC/DPH), and registration statuses across all connected registers (VR, RZP, DPH, IR, etc.). ARES also indicates a **primary data source** per entity, which decides which register enriches the profile.
* **VR (Commercial Register)** -- The Obchodni rejstrik, operated by the Ministry of Justice (`or.justice.cz`). Contains detailed data for legal entities registered in the commercial register: legal name, registered address, share capital, legal form, business purpose, legal representatives (`Statutarni organ`), shareholders (`Spolecnici`), and dissolution/deletion information. Its collection of deeds (Sbirka listin) is the source for **Financial Statements** and **Articles of Association** documents.
* **RZP (Trade Licensing Register)** -- The Rejstrik zivnostenskeho podnikani (`rzp.cz`). Contains business license data for sole traders and other trade-licensed entities: legal name, registered address, registration date, licensed activities, and the licence holder. Also the source for **Trade Register Extract PDF** documents.
* **ESM (Register of Beneficial Owners)** -- The Evidence skutečných majitelů, operated by the Ministry of Justice (`esm.justice.cz`). Closed to the public since December 2025, so a local partner obtains the official full extract. Source of the **Ultimate Beneficial Owners** datapoint and the **Beneficial Ownership Extract** document.
* **VIES (EU VAT Information Exchange System)** -- When an entity is registered for VAT, its VAT number is validated against VIES and the result, including a consultation number, is returned in the `company` datapoint.
**ARES is the orchestration hub.** Every company profile request starts with ARES for discovery and base attributes. ARES indicates a primary source per entity (Commercial Register, Trade Licensing Register, or others), and complementary data is fetched from that source. If the primary source fetch fails, available data from ARES alone is used. If no primary source is indicated, both VR and RZP are queried (best-effort).
1. **ARES** is always queried first to discover the entity and get base attributes (name, address, legal form, activity codes, identifiers, status)
2. ARES indicates a **primary source**:
* Commercial Register (VR): VR data (legal reps, shareholders, capital, status, legal form) is merged into the ARES base
* Trade Licensing Register (RZP): RZP data (name, address, registration date, activities, licence holder) is merged
* Other or none: both VR and RZP are queried, and any available data is merged
3. For overlapping attributes (e.g., legal name, address), the **primary source takes precedence** over ARES
4. **Enrichment** is applied as a final step: activities get ISIC codes, status gets standardized classification, and a legal form that has no standardized category yet (Commercial Register legal-form text, or an ARES code outside the official mapping) is classified with a standardized category and ISO 20275 code
5. **VIES** validates the VAT number when the entity is registered for VAT
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Domestic s.r.o. and a.s. companies. Example: `CZVROR.04234651`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entities** | ARES | 8 digits (ICO) | `45274649` | Spaces are stripped (e.g., `19188 889` becomes `19188889`) |
**ICO Format:** The ICO (Identifikacni cislo osoby) is always 8 digits. Input with spaces is tolerated -- they are automatically stripped before processing.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `ico` | 8 digits | `45274649` | All entities |
| `dic` | CZ + 8-10 digits | `CZ45274649` | Tax-registered entities (normalized with CZ prefix) |
| `VAT` | 8-10 digits (CZ prefix removed) | `45274649` | Only when ARES confirms active DPH (VAT) status |
**VAT vs DIC:** The `dic` (Tax Identification Number) is always returned when available and keeps the CZ prefix. The `VAT` identifier carries the same number without the CZ prefix, and is only set when ARES confirms the entity has **active DPH (VAT) registration status**. We do not synthesize VAT from ICO or query the DPH register separately. For sole traders and individuals, the VAT number may have 9-10 digits and can differ from the ICO.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the IČO (`ico`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By ICO | 8 digits | `45274649` | Exact | Exact match returned first (matchType: id); other results may follow |
| By ICO (with spaces) | Digits with spaces | `19188 889` | Exact | Exact match returned first (matchType: id, spaces stripped); other results may follow |
| By Name | Text string (2-200 chars) | `"PalmApp Tech s.r.o."` | Contains/partial | Multiple results (up to 30) |
**Search Performance:** Use ICO-based searches for best performance and exact matching. Name searches query ARES and may return up to 30 results. If a name search returns too many results, ARES will return an error suggesting a more specific search term.
**VAT number search:** A VAT number with the CZ prefix (e.g. `CZ45274649`) is accepted as a search input and looked up as an ICO, so it finds companies whose VAT number is CZ + ICO. VAT numbers of individuals based on a birth number are not found; search those by ICO or name.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Every result carries the register status. Companies in liquidation still count as active until they are removed.
## Company Status
Company status is determined from ARES registration statuses across multiple registers (VR, RES, RZP, DPH, IR). The logic is **deterministic** -- no AI inference is involved for status determination. AI enrichment is applied afterward for standardization only.
### Status Determination Logic
| Condition | Local Status | Standardized Status | Notes |
| - | - | - | - |
| Active in any register (VR, RES, DPH, RZP) | Active | Active | Any active registration means the entity is active |
| In liquidation (VR or RES shows `V LIKVIDACI`) | In Liquidation | Active | Treated as active -- entity still exists |
| Insolvency register (IR) active AND entity active | Under Insolvency Proceedings | Under Insolvency Proceeding | Reflects proceedings, not outcome |
| VR or RES shows `ZRUSENY` (and not active elsewhere) | Dissolved | Closed | Entity has been removed from register |
| RES cessation date (`datumZaniku`) present | Dissolved | Closed | Overrides all other signals |
| Commercial Register shows a deletion date, a removal, or bankruptcy | Closed | Closed | Replaces the ARES status, with closure reason and closure date when available |
| None of the above | Unknown | Unknown | Insufficient data to determine status |
### Closure Reasons (from VR)
When a company is dissolved, the closure reason is determined by **parsing Czech legal text** from the Commercial Register:
| Czech Pattern | Standardized Closure Reason |
| - | - |
| konkurs / konkurz / insolvence / upadek | Bankruptcy |
| fuze / slouceni / splynut | Merger |
| prevod jmeni na jedineho spolecnika/akcionare | Acquisition |
| zrusena s likvidaci (rozhodnutim valne hromady) | Voluntary Dissolution |
| zrusena s likvidaci (general) | Liquidation |
| zrusena dle paragrafu / ex lege | Administrative Dissolution |
| rozhodnutim soudu / usneseni soudu | Court Order |
| Other patterns | Other |
**VR closure reasons** are extracted by pattern-matching normalized (diacritics-stripped) Czech text from the Commercial Register's "Ostatni skutecnosti" (Other facts) and insolvency sections. If no specific pattern matches, the closure reason defaults to "Other."
## Legal Forms
Czechia uses a deterministic legal form mapping via the ARES "Právní forma" codelist. The mapping provides the local Czech name, an English translation, a standardized category and, where GLEIF publishes one, the ISO 20275 (ELF) code for each code. For unrecognized codes, AI-based classification is used as fallback.
Legal forms are classified from official registry data. When the Commercial Register's legal-form text is used, or the ARES code is not in the mapping, the standardized category and ISO 20275 code are resolved by AI-assisted classification.
### Sole Proprietors (codes 100–110)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 100 | Podnikající fyzická osoba tuzemská | Domestic sole proprietor | Sole Proprietorship | 95G8 |
| 101 | Fyzická osoba podnikající dle živnostenského zákona | Sole trader under the Trade Licensing Act | Sole Proprietorship | 95G8 |
| 102 | Fyzická osoba podnikající dle živnostenského zákona zapsaná v obchodním rejstříku | Sole trader under the Trade Licensing Act (Commercial Register) | Sole Proprietorship | 95G8 |
| 103 | Samostatně hospodařící rolník nezapsaný v obchodním rejstříku | Self-employed farmer | Sole Proprietorship | AM3T |
| 104 | Samostatně hospodařící rolník zapsaný v obchodním rejstříku | Self-employed farmer (Commercial Register) | Sole Proprietorship | 95G8 |
| 105 | Fyzická osoba podnikající dle jiných zákonů než živnostenského a zákona o zemědělství | Sole proprietor under other laws | Sole Proprietorship | 95G8 |
| 106 | Fyzická osoba podnikající dle jiných zákonů než živnostenského a zákona o zemědělství zapsaná v obchodním rejstříku | Sole proprietor under other laws (Commercial Register) | Sole Proprietorship | 95G8 |
| 107 | Zemědělský podnikatel - fyzická osoba | Agricultural entrepreneur – natural person | Sole Proprietorship | 95G8 |
| 108 | Zemědělský podnikatel - fyzická osoba zapsaná v obchodním rejstříku | Agricultural entrepreneur – natural person (Commercial Register) | Sole Proprietorship | 95G8 |
| 109 | Fyzická osoba podnikající v oblasti vodního hospodářství | Natural person in water management | Sole Proprietorship | 95G8 |
| 110 | Fyzická osoba podnikající v oblasti vodního hospodářství zapsaná v obchodním rejstříku | Natural person in water management (Commercial Register) | Sole Proprietorship | 95G8 |
### Partnerships and Capital Companies (codes 111–121)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 111 | Veřejná obchodní společnost | General partnership | Partnership | 5KU5 |
| 112 | Společnost s ručením omezeným | Limited liability company | Limited Liability Company | 9HLU |
| 113 | Společnost komanditní | Limited partnership | Partnership | CD28 |
| 114 | Společnost komanditní na akcie | Partnership limited by shares | Partnership | 747U |
| 115 | Společný podnik | Joint venture | Partnership | Y18E |
| 116 | Zájmové sdružení | Association | Nonprofit Organization | 7OZQ |
| 117 | Nadace | Foundation | Nonprofit Organization | 3G3D |
| 118 | Nadační fond | Endowment fund | Nonprofit Organization | QS6A |
| 121 | Akciová společnost | Joint-stock company | Corporation | 6CQN |
### Cooperatives (codes 131–261)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 131 | Svépomocné zemědělské družstvo | Self-help agricultural cooperative | Cooperative | 1JK6 |
| 141 | Obecně prospěšná společnost | Public benefit company | Nonprofit Organization | BL4B |
| 145 | Společenství vlastníků jednotek | Association of unit owners | Cooperative | IQ9O |
| 151 | Komoditní burza | Commodity exchange | Other | NQHQ |
| 152 | Garanční fond obchodníků s cennými papíry | Securities Traders' Guarantee Fund | Government-Owned Entity | 4UB2 |
| 161 | Ústav | Institute | Nonprofit Organization | QJ0F |
| 201 | Zemědělské družstvo | Agricultural cooperative | Cooperative | Z3BF |
| 205 | Družstvo | Cooperative | Cooperative | 9RVC |
| 211 | Družstevní podnik zemědělský | Agricultural cooperative enterprise | Cooperative | WJ30 |
| 231 | Výrobní družstvo | Production cooperative | Cooperative | C7GZ |
| 232 | Spotřební družstvo | Consumer cooperative | Cooperative | 8K5T |
| 233 | Bytové družstvo | Housing cooperative | Cooperative | T3Q1 |
| 234 | Jiné družstvo | Other cooperative | Cooperative | ZU32 |
| 241 | Družstevní podnik (s 1 zakladatelem) | Cooperative enterprise (single founder) | Cooperative | RHFQ |
| 242 | Společný podnik (s více zakladateli) | Joint venture (multiple founders) | Partnership | NJ87 |
| 251 | Zájmová organizace družstev | Association of cooperatives | Cooperative | 4A26 |
| 261 | Společná zájmová organizace družstev | Joint interest organization of cooperatives | Cooperative | V6YH |
### State and Government Entities (codes 301–392)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 301 | Státní podnik | State enterprise | Government-Owned Entity | 6FAI |
| 302 | Národní podnik | National enterprise | Government-Owned Entity | UFDA |
| 311 | Státní banka československá | State Bank of Czechoslovakia | Corporation | KM6Z |
| 312 | Banka-státní peněžní ústav | State monetary institution (bank) | Corporation | FIPS |
| 313 | Česká národní banka | Czech National Bank | Government-Owned Entity | NPH3 |
| 314 | Česká konsolidační agentura | Czech Consolidation Agency | Government-Owned Entity | 2N9X |
| 321 | Rozpočtová organizace | Budgetary organization | Government-Owned Entity | H6WW |
| 325 | Organizační složka státu | State organizational unit | Government-Owned Entity | LJL0 |
| 326 | Stálý rozhodčí soud | Permanent Arbitration Court | Government-Owned Entity | 4YAK |
| 331 | Příspěvková organizace zřízená územním samosprávným celkem | Contributory organization of a municipality/region | Government-Owned Entity | MBUU |
| 332 | Státní příspěvková organizace | State contributory organization | Government-Owned Entity | H6WW |
| 333 | Státní příspěvková organizace ostatní | Other state contributory organization | Government-Owned Entity | 74W6 |
| 341 | Státní hospodářská organizace řízená okresním úřadem | State economic organization managed by a district office | Government-Owned Entity | 84J8 |
| 343 | Obecní podnik | Municipal enterprise | Government-Owned Entity | RP0E |
| 351 | Československé státní dráhy-státní organizace | Czechoslovak State Railways – state organization | Government-Owned Entity | LJ92 |
| 352 | Státní organizace Správa železnic | State organization Railway Administration | Government-Owned Entity | APEN |
| 353 | Rada pro veřejný dohled nad auditem | Public Audit Oversight Board | Government-Owned Entity | QJWK |
| 361 | Veřejnoprávní instituce | Public law institution | Government-Owned Entity | NI3I |
| 362 | Česká tisková kancelář | Czech News Agency | Government-Owned Entity | 917C |
| 381 | Státní fond ze zákona | Statutory state fund | Government-Owned Entity | 3RMA |
| 382 | Státní fond ze zákona nezapisující se do obchodního rejstříku | Statutory state fund not registered in the Commercial Register | Government-Owned Entity | AM3T |
| 391 | Zdravotní pojišťovna (mimo VZP) | Health insurance company (excluding VZP) | Government-Owned Entity | QQ49 |
| 392 | Všeobecná zdravotní pojišťovna | General Health Insurance Company | Government-Owned Entity | C4Q2 |
### Foreign / Branch Entities (codes 401–442)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 401 | Sdružení mezinárodního obchodu | International trade association | Nonprofit Organization | I32F |
| 411 | Podnik se zahraniční majetkovou účastí | Enterprise with foreign equity participation | Limited Liability Company | CHJR |
| 421 | Odštěpný závod zahraniční právnické osoby | Branch of a foreign legal entity | Branch or Representative Office | TNBA |
| 422 | Organizační složka zahraničního nadačního fondu | Organizational unit of a foreign endowment fund | Branch or Representative Office | HY6K |
| 423 | Organizační složka zahraniční nadace | Organizational unit of a foreign foundation | Branch or Representative Office | VQU7 |
| 424 | Zahraniční fyzická osoba | Foreign natural person | Sole Proprietorship | CZUA |
| 425 | Odštěpný závod zahraniční fyzické osoby | Branch of a foreign natural person | Branch or Representative Office | U95A |
| 426 | Zastoupení zahraniční banky | Representative office of a foreign bank | Branch or Representative Office | JJYB |
| 441 | Podnik zahraničního obchodu | Foreign trade enterprise | Branch or Representative Office | HSNC |
| 442 | Účelová zahraničně obchodní organizace | Purpose-specific foreign trade organization | Branch or Representative Office | WVZF |
### Branches and Sub-units (codes 501–541)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 501 | Odštěpný závod | Branch | Branch or Representative Office | WUFK |
| 521 | Samostatná drobná provozovna (obecního úřadu) | Independent small establishment (municipal office) | Branch or Representative Office | C5FE |
| 525 | Vnitřní organizační jednotka organizační složky státu | Internal unit of a state organizational component | Government-Owned Entity | HS5W |
| 531 | Oblastní organizační jednotka ČD | Regional organizational unit of Czech Railways | Government-Owned Entity | LJ92 |
| 532 | Účelová organizační jednotka ČD | Purpose-specific organizational unit of Czech Railways | Government-Owned Entity | LJ92 |
| 533 | Specializovaná organizační jednotka ČD | Specialized organizational unit of Czech Railways | Government-Owned Entity | LJ92 |
| 534 | Jednotka státní drážní -technická inspekce | State railway unit – technical inspection | Government-Owned Entity | APEN |
| 535 | Jednotka sboru ozbrojené ochrany železnic | Railway Armed Protection Corps unit | Government-Owned Entity | APEN |
| 536 | Jednotka drážního správního úřadu | Railway administrative authority unit | Government-Owned Entity | APEN |
| 541 | Podílový, penzijní fond | Mutual or pension fund | Other | SNWJ |
### Education (codes 601–671)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 601 | Vysoká škola (veřejná, státní) | University (public, state) | Government-Owned Entity | OVKW |
| 602 | Fakulta vysoké školy | University faculty | Government-Owned Entity | OVKW |
| 603 | Jiné pracoviště vysoké školy / fakulty | Other unit of university/faculty | Government-Owned Entity | OVKW |
| 611 | Střední škola | Secondary school | Government-Owned Entity | OVKW |
| 621 | Základní škola | Primary school | Government-Owned Entity | D1VK |
| 625 | Školské zařízení | School facility | Government-Owned Entity | D1VK |
| 631 | Předškolní zařízení | Preschool facility | Government-Owned Entity | NI3I |
| 641 | Školská právnická osoba | School legal entity | Government-Owned Entity | D1VK |
| 651 | Zdravotnické zařízení | Healthcare facility | Government-Owned Entity | H4XQ |
| 661 | Veřejná výzkumná instituce | Public research institution | Government-Owned Entity | CIO8 |
| 671 | Veřejné neziskové ústavní zdravotnické zařízení | Public non-profit institutional healthcare facility | Government-Owned Entity | H4XQ |
### Civil Society / Non-profits (codes 701–771)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 701 | Občanské sdružení | Civic association | Nonprofit Organization | 9XDB |
| 702 | Pojišťovací spolek | Mutual insurance association | Nonprofit Organization | C4Q2 |
| 703 | Odborová organizace a organizace zaměstnavatelů | Trade union and employers' organization | Nonprofit Organization | Q25I |
| 704 | Zvláštní organizace pro zastoupení českých zájmů v mezinárodních nevládních organizacích | Special organization representing Czech interests in international NGOs | Nonprofit Organization | WL83 |
| 705 | Podnik nebo hospodářské zařízení sdružení | Enterprise or economic facility of an association | Nonprofit Organization | 971Y |
| 706 | Spolek | Association | Nonprofit Organization | CATU |
| 707 | Odborová organizace | Trade union | Nonprofit Organization | Q25I |
| 708 | Organizace zaměstnavatelů | Employers' organization | Nonprofit Organization | CUKQ |
| 711 | Politická strana, politické hnutí | Political party, political movement | Nonprofit Organization | XRK7 |
| 715 | Podnik nebo hospodářské zařízení politické strany | Enterprise or economic facility of a political party | Nonprofit Organization | 2DK3 |
| 721 | Církve a náboženské společnosti | Churches and religious societies | Nonprofit Organization | FY1B |
| 722 | Evidované církevní právnické osoby | Registered church legal entities | Nonprofit Organization | JCAD |
| 723 | Svazy církví a náboženských společností | Unions of churches and religious societies | Nonprofit Organization | ET6Z |
| 731 | Organizační jednotka občanského sdružení | Organizational unit of a civic association | Nonprofit Organization | 6OMW |
| 732 | Organizační jednotka politické strany, politického hnutí | Organizational unit of a political party or movement | Nonprofit Organization | XRK7 |
| 733 | Pobočná odborová organizace a organizace zaměstnavatelů | Branch trade union and employers' organization | Nonprofit Organization | P3YF |
| 734 | Organizační jednotka zvláštní organizace pro zastoupení českých zájmů v mezinárodních nevládních organizacích | Organizational unit of a special organization representing Czech interests in international NGOs | Nonprofit Organization | I68R |
| 736 | Pobočný spolek | Branch association | Nonprofit Organization | G2I3 |
| 741 | Samosprávná stavovská organizace (profesní komora) | Self-governing professional chamber | Nonprofit Organization | O9PW |
| 745 | Komora (hospodářská, agrární) | Chamber of commerce or agriculture | Nonprofit Organization | HQPK |
| 751 | Zájmové sdružení právnických osob | Association of legal entities | Nonprofit Organization | VIE3 |
| 761 | Honební společenstvo | Hunting association | Nonprofit Organization | LEDI |
| 771 | Dobrovolný svazek obcí | Voluntary union of municipalities | Government-Owned Entity | MAVU |
### Municipalities and Regions (codes 801–811)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 801 | Obec | Municipality | Government-Owned Entity | J8PB |
| 802 | Okresní úřad | District office | Government-Owned Entity | 84J8 |
| 804 | Kraj | Region | Government-Owned Entity | QIEL |
| 805 | Regionální rada regionu soudržnosti | Regional Council of a Cohesion Region | Government-Owned Entity | 4OTK |
| 811 | Městská část, městský obvod | City district, municipal borough | Government-Owned Entity | PFE5 |
### Foreign and International Entities (codes 901–999)
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 901 | Zastupitelský orgán jiných států | Foreign diplomatic mission | Government-Owned Entity | LJL0 |
| 906 | Zahraniční spolek | Foreign association | Nonprofit Organization | D35X |
| 907 | Mezinárodní odborová organizace | International trade union organization | Nonprofit Organization | LPCQ |
| 908 | Mezinárodní organizace zaměstnavatelů | International employers' organization | Nonprofit Organization | CUKQ |
| 911 | Zahraniční kulturní, informační středisko, rozhlasová, tisková a televizní agentura | Foreign cultural/information center; radio, press and TV agency | Nonprofit Organization | NI3I |
| 921 | Mezinárodní nevládní organizace | International non-governmental organization | Nonprofit Organization | PQJE |
| 922 | Organizační jednotka mezinárodní nevládní organizace | Organizational unit of an international NGO | Nonprofit Organization | R2XE |
| 931 | Evropské hospodářské zájmové sdružení | European Economic Interest Grouping | Partnership | RBGQ |
| 932 | Evropská společnost | European Company (Societas Europaea) | Corporation | ZQO8 |
| 933 | Evropská družstevní společnost | European Cooperative Society | Cooperative | T1FT |
| 936 | Zahraniční pobočný spolek | Foreign branch association | Branch or Representative Office | JJYB |
| 937 | Pobočná mezinárodní odborová organizace | Branch international trade union organization | Nonprofit Organization | WO0T |
| 938 | Pobočná mezinárodní organizace zaměstnavatelů | Branch international employers' organization | Nonprofit Organization | 5AP3 |
| 941 | Evropské seskupení pro územní spolupráci | European Grouping of Territorial Cooperation | Government-Owned Entity | 3BX3 |
| 950 | Subjekt právním řádem výslovně neupravený | Entity not expressly regulated by law | Other | JCAD |
| 951 | Mezinárodní vojenská organizace vzniklá na základě mezinárodní smlouvy | International military organization established by international treaty | Government-Owned Entity | PQJE |
| 952 | Konsorcium evropské výzkumné infrastruktury | European Research Infrastructure Consortium | Government-Owned Entity | 3BX3 |
| 960 | Právnická osoba zřízená zvláštním zákonem zapisovaná do veřejného rejstříku | Legal entity established by special act entered in the public register | Government-Owned Entity | XG70 |
| 961 | Svěřenský fond | Trust | Trust | 6D9L |
| 962 | Zahraniční svěřenský fond | Foreign trust | Trust | 6D9L |
| 963 | Národní akreditační úřad pro terciární vzdělávání | National Accreditation Bureau for Higher Education | Government-Owned Entity | - |
| 999 | Ostatní | Other | Other | 74W6 |
## Legal Representatives
Legal representatives are extracted from the **Commercial Register (VR)** under the `Statutarni organ` (Statutory body) section. For sole traders and other trade-licensed entities, the licence holder published by the **Trade Licensing Register (RZP)** is returned instead.
### Extraction Details
* **Source**: VR (or.justice.cz), specifically the `Statutarni organ` section; RZP for the licence holder
* **Role detection**: In the Commercial Register, persons with the `Jednatel` (Managing Director) role label are extracted
* **Data extracted per person**: Full name, birth date (day/month/year), residential address, function start date (`Den vzniku funkce`), function end date (`Den zaniku funkce`). The RZP licence holder carries the full name only.
* **Role mapping**: `Jednatel` is mapped to `Managing Director` and `Podnikatel` to `Owner` (standardized)
| Czech Role | English Translation | Standardized Role |
| - | - | - |
| Jednatel | Managing Director | Managing Director |
| Podnikatel | Entrepreneur (trade licence holder) | Owner |
**Current limitation**: Only the `Jednatel` label is read in the Commercial Register's statutory body section. Other statutory roles (e.g., board members in a.s. companies, `Clen predstavenstva`, `Predseda predstavenstva`) may not be extracted in all cases.
## Other Key Persons
Czech registers currently return no other key persons (such as supervisory board members). The `otherKeyPersons` datapoint returns an empty array.
## Shareholders
Shareholders are extracted from the **Commercial Register (VR)** under the `Spolecnici` (Partners) section.
### Extraction Logic
* **Section detection**: Shareholders are read from the `Spolecnici` (Partners) or `Akcionar` (Shareholder) sections of the register
* **Sole shareholder**: When the section header contains `Jediny` (Sole), the shareholder is assigned 100% ownership if no explicit percentage is found
* **Multiple shares**: If a shareholder has multiple entries/shares, they are **summed into a single aggregate stake**
* **Corporate vs individual**: Determined by presence of ICO number or legal form suffix (a.s., s.r.o., etc.)
### Ownership Data
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage (from `Obchodni podil`) | VR (Commercial Register) |
| `nominalCapitalHeld` | Capital contribution amount in CZK (from `Vklad`) | VR (Commercial Register) |
| `type` | Individual or Company | Determined from register data (ICO presence, legal form suffix) |
Shareholder data is primarily available for **s.r.o. (Limited Liability Companies)** registered in the Commercial Register (VR). Joint-stock companies (a.s.) do not list individual shareholders in the public register. Both individual and corporate shareholders are supported. Sole traders and non-profit entities have no share capital, so a `shareholders` request for them returns a not-applicable response.
## Ultimate Beneficial Owners
Beneficial ownership is held in the ESM, separately from the Commercial Register. The ESM is no longer publicly searchable, so a local partner obtains the official full extract. Request `ultimateBeneficialOwners` in verification mode for structured data, or order `ultimateBeneficialOwnersCertificate` from `availableDocuments` for the source PDF. Delivery is asynchronous and typically takes 1-3 business days. Follow the existing request through webhooks or polling; do not submit repeated orders while it is pending. If the extract cannot be obtained, the request reports an error rather than a successful empty result.
## Activity Code Mapping
Czechia uses the **CZ-NACE** classification, which is the Czech adaptation of the European NACE Rev. 2 standard. The system maps activity codes across three levels:
```
CZ-NACE (Czech) -> NACE Rev. 2 (European) -> ISIC Rev. 4 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **CZ-NACE** | ARES (`czNace` field) | `62.01` | No (official) |
| **NACE** | Same as CZ-NACE (identical codes) | `62.01` | No (formal mapping) |
| **ISIC** | Derived from NACE or AI-inferred | `6201` | Sometimes |
**AI Enrichment:** When ISIC codes cannot be derived from NACE via formal mapping tables, the system uses an LLM to match activity descriptions to ISIC Rev. 4 codes. Every activity item includes an `isAIInferred` flag to distinguish official vs. AI-derived codes. CZ-NACE and NACE codes are **never** AI-inferred.
### Activity Codes by Source
| Source | Classifications Returned | Notes |
| - | - | - |
| **ARES** | CZ-NACE (as NACE) + ISIC | From `czNace` field, multiple codes per entity |
| **VR** | Activity description text | Free-text `Predmet podnikani` (business purpose) |
| **RZP** | Activity description text | Licensed activities from trade register XML |
## Data Availability Matrix
| Data Type | Commercial Companies (VR) | Sole Entrepreneurs (RZP) | Non-Profits / Associations | Notes |
| - | - | - | - | - |
| Company Profile | Yes Async | Yes Async | Yes Async | Full data for VR, limited for RZP-only |
| Legal Representatives | Yes | Yes (licence holder) | Limited | From VR `Statutarni organ` section, or the RZP licence holder |
| Shareholders | Yes (s.r.o. only) | No | No | From VR `Spolecnici` section |
| Other Key Persons | No | No | No | Not returned by Czech registers |
| Ultimate Beneficial Owners | Manual | Limited | Limited | From the official ESM extract, typically 1-3 business days. See the [pricing page](https://topograph.co/pricing/cz) for availability |
| Establishments | No | No | No | Not returned by Czech registers |
| Activity Codes | Yes | Yes | Yes | CZ-NACE from ARES + ISIC via AI |
| Documents | Yes | Yes | Limited | Financial Statements and Articles of Association (collection of deeds); Trade Register Extract (RZP) for trade-licensed entities; Beneficial Ownership Extract |
**Legend:** Yes = Available | No = Not Available | Limited = Conditionally Available | Async = Asynchronous processing
## Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | Trade-licensed entities | Extract from the Trade Licensing Register (RZP) |
| **Financial Statements** | `financialStatements` | PDF | Entities with filings in the collection of deeds | Filed with the Commercial Register's collection of deeds (Sbirka listin) |
| **Articles of Association** | `articlesOfAssociation` | PDF | Entities with filings in the collection of deeds | Filed with the Commercial Register's collection of deeds (Sbirka listin) |
| **Beneficial Ownership Extract** | `ultimateBeneficialOwnersCertificate` | PDF | Listed for every company | Official full extract from the Register of Beneficial Owners (ESM). Delivered manually, typically within 1-3 business days. |
The Trade Register Extract is sourced from the **Trade Licensing Register (RZP)** and contains current business license and registration information. It is returned only for entities holding a Czech trade licence. Companies without a trade licence (many holding companies) have no such extract, and it is not listed in available documents for them.
## Data Source Priority & Routing
For a given entity, data is assembled from multiple sources with a clear precedence hierarchy. ARES provides the base, and the primary source register enriches it.
**Orchestration Flow:**
1. **ARES** -- Always queried first. Provides base attributes: name, address, legal form, activities, identifiers, status
2. **Primary source** -- As indicated by ARES:
* Commercial Register (VR): provides legal reps, shareholders, capital, status override, legal form, activity description
* Trade Licensing Register (RZP): provides name, address, registration date, activity descriptions, licence holder
* Other or none: both VR and RZP are queried (best-effort). Any available data is merged
3. **Enrichment** -- Applied for:
* Activities: ISIC codes via formal derivation, with AI fallback
* Status: Standardized classification
* Legal form: standardized category and ISO 20275 code when the official mapping does not already provide them
4. **VIES** -- VAT validation for VAT-registered entities
**Merge behavior:** The primary source takes precedence over ARES for overlapping attributes. If a primary source fetch fails, ARES data alone is used (graceful degradation).
### Attribute-Level Source Mapping
| Attribute | Primary Source | Fallback | Notes |
| - | - | - | - |
| Company name | VR or RZP | ARES | Primary source overrides ARES |
| Legal form | VR | ARES | VR provides local name; ARES provides code-based mapping |
| Registered address | VR or RZP | ARES | Primary source overrides ARES |
| Share capital | VR | -- | Only available from Commercial Register |
| Activity codes (CZ-NACE) | ARES | -- | Always from ARES `czNace` field |
| Activity description (text) | VR or RZP | -- | From `Predmet podnikani` (VR) or license activities (RZP) |
| Legal representatives | VR | RZP | Commercial Register statutory body, or the RZP licence holder |
| Shareholders | VR | -- | Only from the Commercial Register |
| Registration date | VR or RZP | ARES | `datumVzniku` from ARES, or from primary source |
| Status | ARES + VR | ARES | ARES provides multi-register status; VR adds closure details |
| DIC / VAT | ARES | -- | Tax identifier and DPH status from ARES; VAT validated against VIES |
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "CZ", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "12345678",
"countryCode": "CZ",
"identifiers": { "ico": "12345678", "dic": "CZ12345678", "VAT": "12345678" },
"legalName": "Priklad s.r.o.",
"registrationDate": "2019-06-15",
"activityDescription": "Vyroba, obchod a sluzby neuvedene v prilohach 1 az 3 zivnostenskeho zakona",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Spolecnost s rucenim omezenym", "englishTranslation": "Limited liability company", "standardized": "Limited Liability Company", "iso20275Code": "9HLU" },
"capital": { "amount": 200000, "currency": "CZK", "formatted": "200 000 Kc" },
"activities": {
"NACE": [{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Vaclavske namesti 10", "city": "Praha", "postalCode": "11000", "countryCode": "CZ" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Jednatel", "standardized": "Managing Director" },
"startDate": "2019-06-15",
"individual": {
"name": { "fullName": "Jan Novak" },
"birthDate": { "day": 15, "month": 3, "year": 1982 },
"residenceAddress": { "addressLine1": "Narodni 5", "city": "Praha", "postalCode": "11000", "countryCode": "CZ" }
}
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"individual": { "name": { "fullName": "Jan Novak" }, "birthDate": { "day": 15, "month": 3, "year": 1982 } },
"sharePercentage": 60,
"nominalCapitalHeld": { "amount": 120000, "currency": "CZK", "formatted": "120 000 Kc" }
},
{
"entityId": "company_001",
"type": "company",
"company": {
"id": "87654321",
"countryCode": "CZ",
"legalName": "Holding a.s.",
"identifiers": { "ico": "87654321" }
},
"sharePercentage": 40,
"nominalCapitalHeld": { "amount": 80000, "currency": "CZK", "formatted": "80 000 Kc" }
}
]
}
```
```json theme={null}
{
"company": {
"id": "87654321",
"countryCode": "CZ",
"identifiers": { "ico": "87654321", "dic": "CZ87654321" },
"legalName": "Stara Firma a.s.",
"registrationDate": "2005-02-01",
"status": {
"localName": "Closed",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureDate": "2022-11-30",
"closureReason": "LIQUIDATION"
}
},
"legalForm": { "localName": "Akciova spolecnost", "englishTranslation": "Joint-stock company", "standardized": "Corporation", "iso20275Code": "6CQN" },
"capital": { "amount": 2000000, "currency": "CZK", "formatted": "2 000 000 Kc" },
"activities": {
"NACE": [{ "code": "46.90", "description": "Non-specialised wholesale trade", "isAIInferred": false }],
"ISIC": [{ "code": "4690", "description": "Non-specialized wholesale trade", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Narodni 5", "city": "Praha", "postalCode": "11000", "countryCode": "CZ" }
},
"legalRepresentatives": []
}
```
**Note:** Dissolved companies have `active: false` with a closure date and closure reason when determinable from the VR register text. Joint-stock companies (a.s.) do not list shareholders in the public register.
```json theme={null}
{
"company": {
"id": "19188889",
"countryCode": "CZ",
"identifiers": { "ico": "19188889", "dic": "CZ19188889", "VAT": "19188889" },
"legalName": "Jan Dvorak",
"registrationDate": "2020-03-01",
"activityDescription": "Poradenstvi v oblasti informacnich technologii; Koupeni zbozi za ucelem jeho dalsiho prodeje",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Fyzicka osoba podnikajici dle zivnostenskeho zakona", "englishTranslation": "Sole trader under the Trade Licensing Act", "standardized": "Sole Proprietorship" },
"activities": {
"NACE": [{ "code": "62.02", "description": "Computer consultancy activities", "isAIInferred": false }],
"ISIC": [{ "code": "6202", "description": "Computer consultancy and computer facilities management activities", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Husova 12", "city": "Brno", "postalCode": "60200", "countryCode": "CZ" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Podnikatel", "englishTranslation": "Entrepreneur (trade licence holder)", "standardized": "Owner" },
"individual": { "name": { "fullName": "Jan Dvorak" } }
}
]
}
```
**Note:** For sole traders (RZP primary source), the licence holder is returned under `legalRepresentatives` with the `Owner` role. Sole traders have no shareholders or capital data. The legal name is the individual's name. Activity description comes from licensed activities in the RZP.
```json theme={null}
{
"company": {
"id": "55667788",
"countryCode": "CZ",
"identifiers": { "ico": "55667788", "dic": "CZ55667788" },
"legalName": "Likvidovana s.r.o. v likvidaci",
"registrationDate": "2010-08-20",
"status": { "localName": "In Liquidation", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Spolecnost s rucenim omezenym", "englishTranslation": "Limited liability company", "standardized": "Limited Liability Company" },
"legalAddress": { "addressLine1": "Karlova 8", "city": "Praha", "postalCode": "11000", "countryCode": "CZ" }
}
}
```
**Note:** Entities in liquidation are treated as **active** (`active: true`) with local status "In Liquidation." The entity still legally exists during the liquidation process.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Trade Register Extract (RZP) PDF | Returned only for entities holding a Czech trade licence; not listed for other companies |
| `financialStatements` | Financial Statements PDF | From the Commercial Register's collection of deeds, when filed |
| `articlesOfAssociation` | Articles of Association PDF | From the Commercial Register's collection of deeds, when filed |
## Fast search data
Czech company data is **periodically synchronized** from the ARES open dataset into a fast search index.
### Search
Search combines results from the fast search index with a live ARES lookup and merges them. When both return the same company, the live data is preferred.
### Companies in fast search data
The fast search index contains **all non-terminated Czech entities** from ARES. The filtering is based on the dissolution date:
| Condition | Included? | Description |
| - | - | - |
| `datum_zaniku` IS NULL | Yes | Entity has not been dissolved |
| `datum_zaniku` IS NOT NULL | No | Entity has been dissolved/terminated |
This means active entities, entities in liquidation, and entities under insolvency proceedings are all included; only fully terminated entities (with a recorded dissolution date) are excluded.
### Prefill Mode
Prefill and verification requests both return live register data with the same enrichment. The fast search index is used for search only. In prefill mode, VAT validation against VIES gets a shorter time budget, so the VAT check can come back as unavailable when VIES is slow.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Multi-source orchestration** | Data is merged from up to three sources (ARES, VR, RZP). The primary source indicated by ARES takes precedence for overlapping attributes. If a source fetch fails, available data from other sources is used (graceful degradation). |
| **ICO spaces are stripped** | Input ICOs may contain spaces (e.g., `19188 889`) which are normalized to `19188889` before processing. |
| **VAT only for active DPH registrants** | The `identifiers.VAT` field (digits only, without the CZ prefix) is only set when ARES confirms active DPH (VAT) status. We do not synthesize VAT from ICO or query the DPH register separately. |
| **Shareholders only for s.r.o.** | Shareholder data with ownership percentages is only available for Limited Liability Companies (s.r.o.) in the Commercial Register. Joint-stock companies (a.s.) do not list shareholders publicly. |
| **ISIC codes may be AI-inferred** | CZ-NACE codes from ARES are official. ISIC codes are derived via formal mapping when possible, with AI fallback. Check the `isAIInferred` flag. |
| **Closure reasons from register text** | When a company is dissolved, the closure reason is determined by pattern-matching normalized Czech text from the VR "Ostatni skutecnosti" and insolvency sections (e.g., bankruptcy, merger, acquisition, liquidation, court order). |
| **Legal form mapping is deterministic** | Czech legal forms are mapped deterministically using the official ARES legal form codelist (140+ forms), including ISO 20275 codes. Legal forms without a standardized category (Commercial Register legal-form text or unmapped codes) are classified with AI assistance. |
| **UBO data is delivered manually** | The ESM has been closed to the public since December 2025. Beneficial owners are available as the `ultimateBeneficialOwners` datapoint and as the Beneficial Ownership Extract document, both taken from the official ESM extract obtained by a local partner, typically within 1-3 business days. Datapoint values are extracted from the extract, so verify them against the document before relying on them for compliance. |
| **In Liquidation = Active** | Entities with status "V LIKVIDACI" in VR or RES are treated as active (`active: true`) because the entity still legally exists during the liquidation process. |
| **Capital in CZK only** | Share capital from the VR is always expressed in Czech Koruna (CZK) with formatted strings using Czech locale (e.g., `200 000 Kc`). |
| **Sole shareholder default to 100%** | When the Commercial Register lists a `Jediny spolecnik` (sole partner) and no explicit ownership percentage is found, the shareholder defaults to 100% ownership. |
# Denmark
Source: https://docs.topograph.co/essentials/denmark
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Denmark reference is on the [Denmark country page](https://www.topograph.co/countries/dk).
## Start here
This guide contains public integration notes for Denmark. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Fast search data](#fast-search-data)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Denmark uses official registers operated by the **Danish Business Authority (Erhvervsstyrelsen)**. For a given entity, **company data comes from the CVR**, and the Danish VAT number is verified against **VIES**. Financial documents are sourced separately from the ERST publication index.
### All entity types
* **CVR (Det Centrale Virksomhedsregister / Central Business Register)** -- Operated by the Danish Business Authority (Erhvervsstyrelsen), the CVR is the central government register containing primary data on all businesses in Denmark and Greenland. This is the **sole primary source** for company profile data. The CVR provides comprehensive structured data including: company name, legal form, status, incorporation date, registered address, share capital, activity codes, management (legal representatives), legal shareholders, beneficial owners (UBOs), contact information, employee counts, and production units (establishments). The CVR covers all entity types: commercial companies (A/S, ApS), sole proprietorships (ENK), partnerships (I/S, K/S), non-profits, cooperatives, and public institutions.
* **ERST (Erhvervsstyrelsens Offentliggorelsesindeks / Financial Publication Index)** -- Operated by the Danish Business Authority. Used exclusively for **financial statement retrieval** (annual reports in XBRL, XHTML, and PDF formats). The ERST indexes all financial publications filed with the Danish Business Authority. It is **not** a structured data source for company attributes.
* **VIES (EU VAT Information Exchange System)** -- Secondary source for the `company` datapoint. It verifies the Danish VAT number and returns it in `taxId` with its verification status.
The CVR records every field with a validity period (`gyldigFra` / `gyldigTil`). Topograph returns the values that are current today.
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Domestic A/S and ApS companies. Example: `DKCVR.25450442`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entities** | CVR | 8 digits (CVR number), no separators; the last digit is a modulus-11 check digit | `40715355` | Unique identifier for all Danish entities |
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `cvr` | 8 digits | `40715355` | All entities |
| `enhedsNummer` | Up to 10 digits | `4001459308` | Internal CVR unit number (all entities) |
| `VAT` | 8 digits (same as CVR, no `DK` prefix) | `40715355` | All entities |
The CVR number and VAT number share the same 8 digits. The response returns `VAT` without the `DK` prefix. Search accepts either `40715355` or `DK40715355`.
`VAT` is derived from the CVR number for every entity, so its presence alone does not mean the entity is registered for VAT.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the CVR number (`cvr`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By CVR Number | 8 digits | `40715355` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 3 chars) | `"Maersk"` | Fuzzy | Multiple results (up to 20) |
**Name search** combines exact, fuzzy, prefix and former-name matching, with exact matches ranked first. Searches by CVR number are exact and faster.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Fast search data
Denmark company data is **periodically synchronized** from the CVR open data into a fast search index.
### Search
Search queries hit the **fast search index first** for instant results, with automatic fallback to the live CVR if the fast search index misses.
### Companies in fast search data
The fast search index contains **all Danish entities** from the CVR, regardless of status. No entities are excluded. For the authoritative company status, request the `company` datapoint, which reads the live CVR.
### Prefill Mode
In prefill mode, requests for the `company` datapoint use the **live CVR**, not the fast search dataset. Data is always real-time from the CVR.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Full legal form names returned** | The system returns `langBeskrivelse` (full description, e.g., "Anpartsselskab") rather than `kortBeskrivelse` (abbreviation, e.g., "ApS"). |
| **Decimal ownership percentages** | CVR stores ownership as decimals (0.25 = 25%). The system converts automatically. Data quality issues can occasionally cause totals exceeding 100%. |
| **UBO vs. shareholder separation** | The same `deltagerRelation` structure contains both legal shareholders and beneficial owners. They are distinguished by the `FUNKTION` attribute: `Reel ejer` = UBO, others with ownership data = shareholders. |
| **Management as beneficial owners** | When a company has no registered beneficial owners (for example, when ownership runs through a foreign parent), Danish anti-money-laundering law treats the company's registered management as the beneficial owners. In that case `ultimateBeneficialOwners` returns the directors and board members, each marked in `control.description` as designated management with no ownership percentage. This applies to **active** companies only — closed or dissolving companies return no beneficial owners — and any appointed liquidator is excluded. |
| **Current roles only** | Legal representatives are the current officers. Roles that have ended in the CVR are not returned. |
| **Capital in DKK** | Capital amounts are formatted in Danish locale (e.g., `DKK 250.000` using periods as thousand separators). Default currency is DKK. |
| **Employee count lag** | Employee counts (`nyesteAarsbeskaeftigelse`) represent the most recent annual employment data, which may be 1-2 years old. |
| **Production units as establishments** | Establishments are mapped from CVR `produktionsenheder` (production units), each identified by a P-number. |
| **Trade register extract delivery** | The CVR Erhvervsudtog is generated on demand and takes approximately 2 minutes. |
| **Financial document format mismatch** | CVR MIME types for financial documents can be incorrect (e.g., documents labeled XHTML may actually be PDFs). The system detects the actual file format from magic bytes. |
| **AI-enriched fields** | Activity code ISIC mapping and role English translations use AI classification for unrecognized values. Company status is mapped deterministically. The local Danish values are always preserved verbatim. |
| **Document retrieval time** | Document downloads and publication retrieval can be slower than company data lookups. |
## Mappings
### Company Status
Company status is determined **deterministically** from the CVR `sammensatStatus` field and lifespan data. `status.localName` carries the readable Danish label, and `statusDetails` carries the standardized status and, for closed companies, the closure reason.
| Local Status (`localName`) | English | Standardized Status | Closure Reason |
| - | - | - | - |
| Normal | Normal | `ACTIVE` | - |
| Aktiv | Active | `ACTIVE` | - |
| Under konkurs | In bankruptcy | `UNDER_INSOLVENCY_PROCEEDING` | - |
| Under tvangsopløsning | In compulsory dissolution | `UNDER_INSOLVENCY_PROCEEDING` | - |
| Under frivillig likvidation | In voluntary liquidation | `UNDER_INSOLVENCY_PROCEEDING` | - |
| Under rekonstruktion | In reconstruction | `UNDER_INSOLVENCY_PROCEEDING` | - |
| Under reassumering | In reassumption | `UNDER_INSOLVENCY_PROCEEDING` | - |
| Ophørt | Ceased | `CLOSED` | - |
| Opløst | Dissolved | `CLOSED` | `OTHER` |
| Opløst efter konkurs | Dissolved after bankruptcy | `CLOSED` | `BANKRUPTCY` |
| Opløst efter erklæring | Dissolved by declaration | `CLOSED` | `VOLUNTARY_DISSOLUTION` |
| Opløst efter frivillig likvidation | Dissolved after voluntary liquidation | `CLOSED` | `LIQUIDATION` |
| Opløst efter fusion | Dissolved after merger | `CLOSED` | `MERGER` |
| Opløst efter spaltning | Dissolved after demerger | `CLOSED` | `SPLIT` |
| Opløst efter grænseoverskridende fusion | Dissolved after cross-border merger | `CLOSED` | `MERGER` |
| Opløst efter grænseoverskridende spaltning | Dissolved after cross-border demerger | `CLOSED` | `SPLIT` |
| Tvangsopløst | Compulsorily dissolved | `CLOSED` | `ADMINISTRATIVE_DISSOLUTION` |
| Slettet | Deleted | `CLOSED` | `OTHER` |
**Status determination logic:** (1) Use `sammensatStatus` if available; (2) Fall back to the current `virksomhedsstatus` entry; (3) Check `livsforloeb` (lifespan): if the latest lifespan period has an end date, status is `Ophørt`. A value outside this list returns status `UNKNOWN`, with the register's raw value kept in `localName`.
### Legal Forms
Denmark uses the `virksomhedsformkode` from the CVR. The system returns the **full description** (`langBeskrivelse`) rather than the abbreviation (`kortBeskrivelse`). The English translation and standardized type are mapped deterministically from the code for all 41 CVR legal forms, and the ISO 20275 (ELF) code is added when one matches.
The local Danish legal form name (`langBeskrivelse`) is always preserved verbatim. For an unrecognized code, AI-based classification is used as fallback.
#### Key Business Forms
| Code | Danish Name (langBeskrivelse) | English | Standardized |
| - | - | - | - |
| 60 | Aktieselskab | Public Limited Company (A/S) | Corporation |
| 80 | Anpartsselskab | Private Limited Company (ApS) | Limited Liability Company |
| 81 | Iværksætterselskab | Entrepreneurial Company (IVS) | Limited Liability Company |
| 70 | Kommanditaktieselskab/Partnerselskab | Partnership Limited by Shares (P/S) | Partnership |
| 45 | Medarbejderinvesteringsselskab | Employee Investment Company | Limited Liability Company |
#### Sole Proprietorships
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 10 | Enkeltmandsvirksomhed | Sole Proprietorship | Sole Proprietorship |
| 15 | Personligt ejet Mindre Virksomhed | Personally Owned Small Business (PMV) | Sole Proprietorship |
#### Partnerships
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 30 | Interessentskab | General Partnership (I/S) | Partnership |
| 40 | Kommanditselskab | Limited Partnership (K/S) | Partnership |
| 50 | Partrederi | Shipping Partnership (Partrederi) | Partnership |
#### Cooperatives & Limited Liability Associations
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 130 | Andelsselskab (-forening) | Cooperative Society | Cooperative |
| 140 | Andelsselskab (-forening) med begrænset ansvar | Cooperative Society with Limited Liability (AMBA) | Cooperative |
| 150 | Forening eller selskab med begrænset ansvar | Association or Company with Limited Liability | Cooperative |
| 151 | Selskab med begrænset ansvar | Company with Limited Liability (SMBA) | Limited Liability Company |
| 152 | Forening med begrænset ansvar | Association with Limited Liability (FMBA) | Cooperative |
#### Non-Profits, Foundations & Trusts
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 90 | Fonde og andre selvejende institutioner | Foundations and Other Self-Governing Institutions | Nonprofit Organization |
| 95 | Trust | Trust | Trust |
| 100 | Erhvervsdrivende fond | Commercial Foundation | Nonprofit Organization |
| 110 | Forening | Association | Nonprofit Organization |
| 115 | Frivillig forening | Voluntary Association | Nonprofit Organization |
#### Foreign Entities & Branches
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 170 | Filial af udenlandsk aktieselskab, kommanditaktieselskab | Branch of a Foreign Public Limited Company | Branch or Representative Office |
| 180 | Filial af udenlandsk anpartsselskab eller selskab | Branch of a Foreign Private Limited Company | Branch or Representative Office |
| 190 | Filial af udenlandsk virksomhed med begrænset ansvar | Branch of a Foreign Company with Limited Liability | Branch or Representative Office |
| 210 | Anden udenlandsk virksomhed | Other Foreign Company | Other |
| 220 | Fast forretningssted af Europæisk økonomisk Firmagruppe | Permanent Establishment of an EEIG | Branch or Representative Office |
| 520 | Grønlandsk afdeling af udenlandsk selskab eller virksomhed | Greenlandic Branch of a Foreign Company | Branch or Representative Office |
#### European Legal Forms
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 160 | Europæisk Økonomisk Firmagruppe | European Economic Interest Grouping (EEIG) | Partnership |
| 195 | SCE-selskab | European Cooperative Society (SCE) | Cooperative |
| 290 | SE-selskab | European Company (SE) | Corporation |
| 291 | Filial af SE-selskab | Branch of a European Company (SE) | Branch or Representative Office |
#### Public & Special Entities
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 230 | Statslig administrativ enhed | State Administrative Unit | Government-Owned Entity |
| 235 | Selvstændig offentlig virksomhed eller dattervirksomhed heraf | Independent Public Enterprise or Subsidiary Thereof | Government-Owned Entity |
| 240 | Amtskommune | County Authority | Government-Owned Entity |
| 245 | Region | Region | Government-Owned Entity |
| 250 | Primærkommune | Municipality | Government-Owned Entity |
| 260 | Folkekirkelige Institutioner | National Church Institution | Other |
| 285 | Særlig finansiel virksomhed | Special Financial Entity | Other |
#### Other
| Code | Danish Name | English | Standardized |
| - | - | - | - |
| 20 | Dødsbo | Estate of a Deceased Person | Other |
| 270 | Enhed under oprettelse i Erhvervsstyrelsen | Entity Under Formation | Other |
| 280 | Øvrige virksomhedsformer | Other Legal Forms | Other |
| 990 | Uoplyst virksomhedsform | Unspecified Legal Form | Other |
### Legal Representatives
Legal representatives are extracted **deterministically** from the CVR `deltagerRelation` data. Persons and companies in organizations of type `LEDELSESORGAN` (management body: executive board, board of directors, liquidator) and `FULDT_ANSVARLIG_DELTAGERE` (fully liable partners of partnerships) are returned as legal representatives. Their roles are read from the `FUNKTION` attribute within `medlemsData`. Only current roles are returned.
The English translation and standardized role are mapped deterministically for known roles. Unmapped roles are AI-enriched, and the local Danish value is always preserved in `role.localName`.
| Danish Role (FUNKTION) | English Translation | Standardized Role |
| - | - | - |
| Direktør | Managing Director | Managing Director |
| Administrerende direktør (adm. dir.) | Chief Executive Officer | Chief Executive Officer |
| Likvidator | Liquidator | Liquidator |
| Filialbestyrer | Branch Manager | Manager |
| Danish Role (FUNKTION) | English Translation | Standardized Role |
| - | - | - |
| Formand | Chairman | Chairman |
| Næstformand | Deputy Chairman | Board Member |
| Bestyrelsesmedlem | Board Member | Board Member |
| Suppleant | Alternate Board Member | Board Member |
| Danish Role (FUNKTION) | English Translation | Standardized Role |
| - | - | - |
| Interessent | Partner | Partner |
| Komplementar | General Partner | General Partner |
Role enrichment (ISO 5009 code) is AI-enriched. In prefill mode, roles carry `localName` only. Ceased roles are not returned, and `endDate` is set only when a role has a known future end date.
### Other Key Persons
Denmark does not return other key persons. Auditors are not part of the CVR management data used for legal representatives.
### Shareholders
Shareholders are extracted **deterministically** from the CVR `deltagerRelation` data. Persons or companies associated with organizations of type `REGISTER` are evaluated for ownership. The system explicitly **excludes beneficial owners** (those with `FUNKTION = "Reel ejer"`) from the shareholder list.
| Source | When Used | Data Extracted |
| - | - | - |
| **deltagerRelation** (REGISTER orgs) | Always | Entities with `EJERANDEL` or `EJERANDEL_PROCENT` attributes |
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | `EJERANDEL` / `EJERANDEL_PROCENT` (stored as decimal, e.g., 0.25 = 25%) |
| `type` | Individual or Company | Determined from `enhedstype` (`PERSON` = individual, otherwise company) |
CVR stores ownership percentages as decimals (0.25 = 25%). The system automatically converts these to percentages. Only current ownerships (no end date or future end date) are included. Beneficial owners (`Reel ejer`) are excluded from the shareholder list and appear only in the UBO data point. Both individual and corporate shareholders are supported.
### Activity Code Mapping
Denmark uses **Dansk Branchekode 2025 (DB25)**, the Danish extension of NACE Rev. 2.1. The CVR moved from DB07 to DB25 on 1 January 2025. The system maps activity codes across three levels:
```
DB25 (Danish) → NACE Rev. 2.1 (European) → ISIC Rev. 5 (International)
```
| Classification | Keys | Source | Example | AI Inferred? |
| - | - | - | - | - |
| **Dansk Branchekode 2025** | `DB25` | CVR `hovedbranche.branchekode` | `621000` | No (official) |
| **NACE Rev. 2.1** | `NACE` | Derived from the CVR code | `62.10` | Sometimes |
| **ISIC Rev. 5** | `ISIC` | Derived from NACE or AI | `6219` | Sometimes |
**AI Enrichment:** When a code cannot be derived through the formal correspondence tables, the system uses an LLM to match the activity description to a standard code. Every activity item includes an `isAIInferred` flag to distinguish official vs. AI-derived codes. DB25 codes are **never** AI-inferred.
**Main activity flag:** The CVR publishes one main branch per company (the *hovedbranche*), so the returned DB25 and NACE code is flagged with `isMainActivity: true`, and the derived ISIC code inherits the flag.
## Data Availability
### Data Availability Matrix
| Data Type | Commercial Companies | Sole Entrepreneurs | Non-Profits | Notes |
| - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | Full data from CVR |
| Legal Representatives | ✅ | ✅ | ✅ | From `LEDELSESORGAN` and `FULDT_ANSVARLIG_DELTAGERE` relations |
| Shareholders | ✅ | ❌ | ⚠️ Limited | From `REGISTER` relations with ownership data |
| Ultimate Beneficial Owners | ✅ | ❌ | ⚠️ Limited | From `REGISTER` relations with `Reel ejer` function |
| Establishments | ✅ | ✅ | ✅ | From `produktionsenheder` (P-numbers) |
| Activity Codes | ✅ | ✅ | ✅ | DB25 + NACE + ISIC |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **CVR Erhvervsudtog (Trade Register Extract)** | `tradeRegisterExtract` | PDF | ✅ Always available | Certified CVR extract (\~2 min delivery), included with company data |
| **Financial Statements (Arsrapport)** | `financialStatements[]` | XBRL/XHTML/PDF | ✅ When filed | Annual/periodic reports with period data, ordered per document |
| **Official Publications** | `officialPublications[]` | PDF/ZIP | ✅ When filed | Corporate documents, AI-classified by type, ordered per document |
**Trade Register Extract Delivery:** The CVR Erhvervsudtog is generated on demand as a PDF. Estimated delivery time is approximately 120 seconds (2 minutes). The extract is included with company data; see the [pricing page](https://topograph.co/pricing/dk) for billing.
**Financial Document Formats:** Danish financial statements can be in XBRL (machine-readable), XHTML (human-readable), or PDF format. Each document includes period information (`startDate` and `endDate`) for the fiscal year it covers. The system detects the actual file format from magic bytes because CVR MIME types can be inaccurate.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "DK", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "12345678",
"countryCode": "DK",
"identifiers": { "cvr": "12345678", "VAT": "12345678", "enhedsNummer": "4001234567" },
"legalName": "Nordisk Software ApS",
"registrationDate": "2019-06-01",
"incorporationDate": "2019-06-01",
"activityDescription": "Udvikling af software og IT-losninger.",
"status": { "localName": "Normal", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Anpartsselskab", "englishTranslation": "Private Limited Company (ApS)", "standardized": "Limited Liability Company", "iso20275Code": "LR8H" },
"capital": { "amount": 40000, "currency": "DKK", "formatted": "DKK 40.000" },
"employeeCount": { "exact": 5, "isEstimate": false },
"activities": {
"DB25": [{ "code": "621000", "description": "Computerprogrammering", "isAIInferred": false }],
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "6219", "description": "Other computer programming activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Vestergade 10", "city": "Kobenhavn", "postalCode": "1456", "countryCode": "DK" },
"phones": ["+4512345678"],
"website": "https://www.example.dk",
"commercialNames": ["Nordisk IT Solutions"]
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"startDate": "2019-06-01",
"role": { "localName": "DIREKTØR", "englishTranslation": "Managing Director", "standardized": "Managing Director" },
"individual": {
"name": { "fullName": "Lars Nielsen" },
"residenceAddress": { "addressLine1": "Noerrebrogade 25", "city": "Kobenhavn", "countryCode": "DK" }
}
}
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 100, "individual": { "name": { "fullName": "Lars Nielsen" } } }
],
"establishments": [
{ "id": "1012345678", "name": "Nordisk Software ApS", "address": { "addressLine1": "Vestergade 10", "city": "Kobenhavn", "postalCode": "1456", "countryCode": "DK" } }
]
}
```
```json theme={null}
{
"company": {
"id": "87654321",
"countryCode": "DK",
"identifiers": { "cvr": "87654321", "VAT": "87654321", "enhedsNummer": "4009876543" },
"legalName": "Dansk Industri Holding A/S",
"registrationDate": "2005-01-15",
"incorporationDate": "2005-01-15",
"activityDescription": "Holdingselskab med kapitalandele i datterselskaber.",
"status": { "localName": "Normal", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Aktieselskab", "standardized": "Corporation", "iso20275Code": "8888" },
"capital": { "amount": 500000, "currency": "DKK", "formatted": "DKK 500.000" },
"employeeCount": { "exact": 120, "isEstimate": false },
"activities": {
"DB25": [{ "code": "642100", "description": "Holdingselskaber", "isAIInferred": false }],
"NACE": [{ "code": "64.21", "description": "Activities of holding companies", "isAIInferred": false }],
"ISIC": [{ "code": "6421", "description": "Activities of holding companies", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Bredgade 42", "city": "Kobenhavn K", "postalCode": "1260", "countryCode": "DK" },
"website": "https://www.example-holding.dk"
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "startDate": "2005-01-15", "role": { "localName": "ADM. DIR.", "englishTranslation": "Chief Executive Officer", "standardized": "Chief Executive Officer" }, "individual": { "name": { "fullName": "Henrik Andersen" } } },
{ "entityId": "person_002", "type": "individual", "startDate": "2010-06-01", "role": { "localName": "FORMAND", "standardized": "Chairman" }, "individual": { "name": { "fullName": "Birgitte Sorensen" } } },
{ "entityId": "person_003", "type": "individual", "startDate": "2015-03-20", "role": { "localName": "BESTYRELSESMEDLEM", "standardized": "Board Member" }, "individual": { "name": { "fullName": "Peter Christensen" } } }
],
"shareholders": [
{ "entityId": "company_001", "type": "company", "sharePercentage": 60, "company": { "id": "11223344", "countryCode": "DK", "legalName": "Nordisk Kapital ApS" } },
{ "entityId": "person_001", "type": "individual", "sharePercentage": 40, "individual": { "name": { "fullName": "Henrik Andersen" } } }
],
"establishments": [
{ "id": "1087654321", "name": "Dansk Industri Holding A/S", "address": { "addressLine1": "Bredgade 42", "city": "Kobenhavn K", "postalCode": "1260", "countryCode": "DK" } },
{ "id": "1087654322", "name": "Dansk Industri - Aarhus", "address": { "addressLine1": "Europaplads 8", "city": "Aarhus C", "postalCode": "8000", "countryCode": "DK" } }
]
}
```
```json theme={null}
{
"company": {
"id": "11223344",
"countryCode": "DK",
"identifiers": { "cvr": "11223344", "VAT": "11223344" },
"legalName": "Gammel Handel (ophoert)",
"registrationDate": "2010-03-15",
"status": { "localName": "Ophørt", "active": false, "statusDetails": { "status": "CLOSED" } },
"legalForm": { "localName": "Enkeltmandsvirksomhed", "standardized": "Sole Proprietorship", "iso20275Code": "SV8C" },
"legalAddress": { "addressLine1": "Hovedgaden 5", "city": "Aarhus", "postalCode": "8000", "countryCode": "DK" }
},
"legalRepresentatives": []
}
```
**Note:** Closed companies have `active: false`, local status `Ophørt`. Roles that ended when the company closed are not returned, so closed companies often have no legal representatives. Sole proprietorships typically do not have shareholders or UBO data.
```json theme={null}
{
"company": {
"id": "55667788",
"countryCode": "DK",
"identifiers": { "cvr": "55667788", "VAT": "55667788" },
"legalName": "Kobenhavns Idraetsforening",
"registrationDate": "2015-08-20",
"incorporationDate": "2015-08-20",
"activityDescription": "Sportsaktiviteter i ovrigt.",
"status": { "localName": "Normal", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Frivillig forening", "standardized": "Nonprofit Organization" },
"activities": {
"DB25": [{ "code": "931900", "description": "Andre sportsaktiviteter", "isAIInferred": false }],
"NACE": [{ "code": "93.19", "description": "Sports activities n.e.c.", "isAIInferred": false }],
"ISIC": [{ "code": "9319", "description": "Other sports activities", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Idraetvej 12", "city": "Kobenhavn", "postalCode": "2100", "countryCode": "DK" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "startDate": "2015-08-20", "role": { "localName": "FORMAND", "standardized": "Chairman" }, "individual": { "name": { "fullName": "Karen Pedersen" } } }
]
}
```
**Note:** Non-profits typically do not have shareholders. Legal representatives are extracted from the same `LEDELSESORGAN` management data.
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "Lars Nielsen" },
"residenceAddress": { "addressLine1": "Noerrebrogade 25", "city": "Kobenhavn", "countryCode": "DK" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"description": "Beneficial owner with 100% ownership",
"details": [
{ "type": "shares", "percentageValue": 100, "nature": "direct" },
{ "type": "voting-rights", "percentageValue": 100, "nature": "direct" }
]
}
}
]
}
```
**Note:** UBOs are always individuals (never corporate entities). They are identified by `FUNKTION = "Reel ejer"` in the CVR `REGISTER` organizations. Ownership and voting rights percentages are derived from the CVR `EJERANDEL` data and returned in `control.details[].percentageValue`. A beneficial owner registered through a role, without an ownership stake, carries `control.types: ["significant-influence-or-control"]` and no percentage. The beneficial ownership percentage may differ from the legal shareholding percentage.
When a company has **no registered beneficial owners**, the registered management is returned instead (see below). These entries carry `control.types: ["significant-influence-or-control"]` and no ownership percentage, and `control.description` notes they are designated management.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | CVR Erhvervsudtog PDF | Always available (\~2 min delivery) |
| `financialStatements[]` | Annual reports (XBRL/XHTML/PDF) | When filed, with period data |
| `officialPublications[]` | Corporate documents (articles, decisions) | When filed, AI-classified |
## Data Source Priority & Routing
For a given entity, **company data comes from the CVR**. Denmark does not have multiple competing registers. VIES is a secondary source that verifies the VAT number on the `company` datapoint, and financial statements come from the separate ERST publication index.
**Data Flow:**
1. **Company Profile, legal representatives, shareholders, establishments and UBOs** -- CVR
2. **VAT verification** -- VIES
3. **Financial Statements** -- ERST Offentliggorelsesindeks
4. **Official Publications & Trade Register Extract** -- CVR
**Shared data fetch:** The company profile, legal representatives, shareholders, and UBOs all share the same raw CVR data fetch. CVR data is fetched only once per request, regardless of how many data points need it.
### Ultimate Beneficial Owners
UBOs are extracted from the same CVR data as shareholders but are filtered specifically for individuals with `FUNKTION = "Reel ejer"` (beneficial owner). UBO ownership percentages may differ from legal shareholding percentages.
**When a company has no registered beneficial owners.** Under Danish anti-money-laundering law, if no beneficial owner can be identified — a common case when ownership runs up through a foreign parent — the company's **registered management is recorded as the beneficial owners**. Topograph mirrors this: when there are no beneficial owners to return, `ultimateBeneficialOwners` falls back to the company's current directors and board members, each with `control.types: ["significant-influence-or-control"]`, no ownership percentage, and a `control.description` indicating they are designated management.
Two safeguards keep this faithful to the register:
* **Active companies only.** The management substitution is applied only to companies that are currently active. Companies that are closed or being wound up return no beneficial owners (their management is no longer current).
* **Liquidators excluded.** A liquidator appointed to dissolve a company is never returned as a beneficial owner.
| Field | Description | Source |
| - | - | - |
| `control.details[].percentageValue` (type `shares`) | Beneficial ownership percentage | `EJERANDEL` / `EJERANDEL_PROCENT` from the "Reel ejer" org entry |
| `control.details[].percentageValue` (type `voting-rights`) | Voting rights percentage | Same as ownership (assumed equal) |
| `control.types` | Control types | `ownership-of-shares` and `voting-rights` when a stake is registered; `significant-influence-or-control` with no percentage for role-based or management beneficial owners |
UBOs are available as a separate data point (`ultimateBeneficialOwners`), so you can fetch UBO data independently of the full company profile.
# Document Retrieval
Source: https://docs.topograph.co/essentials/document-guide
List and download official company documents, signed URLs, progressive delivery, and block-based included documents
Topograph gives you access to official company documents (trade register extracts, financial statements, articles of association, UBO certificates, and more) directly from government registers across 30+ countries.
For live document coverage, country-specific availability, and pricing, see [Coverage and pricing](/essentials/coverage-and-pricing).
**Key things to know before you start:**
* **The document list is dynamic.** It depends on what the register actually holds for each company. A company may have 10 financial statements or none.
* **Document categories are a fixed set.** Every document is returned under one of the fixed keys of the `documents` object (`financialStatements`, `tradeRegisterExtract`, etc.), with a `subType` that classifies it more precisely. See [Document categories](#document-categories).
* **Retrieval is asynchronous** because we query real government registers, not a cache. Use webhooks or polling.
* **Documents are sorted newest first** within each category. This is guaranteed.
* **Document IDs are opaque.** Always discover them via `availableDocuments` before requesting a download. IDs are generally stable across consecutive requests but we do not guarantee long-term stability, so do not store them permanently.
* **Prices are shown upfront.** Each listed document includes a `price` in credits (or a `priceMarkup` when the price depends on the register's fee). You are only charged when you request the download.
* **Documents arrive progressively.** A company's documents may come from multiple underlying sources (e.g., trade register + financial filings authority). Results are delivered incrementally via webhooks or polling. You don't need to wait for the full list: act as soon as the document you need appears.
* **Every document names its issuing register.** Each document carries a `source` object identifying the register it comes from, in the same format as `dataSources`. See [Document source](#document-source).
## How it works
Document retrieval follows a two-step process:
```mermaid theme={null}
sequenceDiagram
participant Client
participant Topograph
participant Register
Note over Client,Register: Step 1 - Discover available documents
Client->>Topograph: POST /v2/company
dataPoints: ["availableDocuments"]
Topograph->>Register: Query register
Register-->>Topograph: Document list
Topograph-->>Client: Document list in documents
(via webhook or polling)
Note over Client,Register: Step 2 - Download specific documents
Client->>Topograph: POST /v2/company
documents: ["doc-id-1", "doc-id-2"]
Topograph->>Register: Fetch documents
Register-->>Topograph: PDF / files
Topograph-->>Client: Document URLs
(via webhook or polling)
```
Always request `availableDocuments` first to get valid document IDs. Document IDs are **opaque identifiers** (typically UUIDs) specific to each company. While they are generally stable short-term, do not hardcode them or rely on long-term persistence.
### Progressive delivery
For many countries, Topograph queries **multiple underlying sources** to build the full document list. For example, France combines the INPI register (for trade register extracts and articles of association) and the JOAFE (for official publications of associations).
This means `availableDocuments` results arrive **incrementally**. Each webhook (or polling response) may contain more documents than the previous one. You don't need to wait for the `availableDocuments` status to reach `succeeded` before acting: if the document you need is already in the list, you can request it immediately.
Build your integration to process documents as they arrive rather than waiting for the full list. This is especially useful for slow countries where the complete list can take minutes.
### Step 1: List available documents
Request the `availableDocuments` data point to discover which documents the register holds for a given company:
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "FR",
"id": "928020932",
"dataPoints": ["availableDocuments"]
}'
```
The listed documents are returned in the `documents` object of the response, grouped by category (see [Document categories](#document-categories)). Each entry describes a document. Listed documents that you have not requested yet carry no `url`:
```json theme={null}
{
"documents": {
"financialStatements": [
{
"id": "1c932de4-4610-5506-b48d-4e62529d58e8",
"name": "Bilan annuel 2024",
"description": "Annual financial statement for fiscal year 2024",
"format": "pdf",
"date": "2024-12-31",
"price": 0,
"estimatedDeliverySeconds": 15,
"source": {
"type": "live_from_registry",
"register": "inpi"
}
}
],
"tradeRegisterExtract": {
"id": "a7f3b2c1-9e8d-4a5f-b6c0-d1e2f3a4b5c6",
"name": "Certificat INPI",
"description": "Uncertified trade register extract from INPI",
"format": "pdf",
"price": 0,
"estimatedDeliverySeconds": 5,
"source": {
"type": "live_from_registry",
"register": "inpi"
}
}
}
}
```
### Step 2: Request specific documents
Use the `id` values from step 1 to request the documents you need:
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "FR",
"id": "928020932",
"documents": [
"1c932de4-4610-5506-b48d-4e62529d58e8"
]
}'
```
Each requested document appears in the `documents` object of the response, grouped by category (see [Document categories](#document-categories) below). The document includes a temporary download URL.
You can combine both steps in a single request by including both `dataPoints: ["availableDocuments"]` and `documents: ["doc-id"]`. The available documents list will arrive first, and the requested documents will follow.
## Document categories
Documents carry no `type` field. Their category is the key they sit under in the `documents` object, both when listed and when downloaded:
| Field | Type | Description |
| - | - | - |
| `tradeRegisterExtract` | Single document | Latest uncertified trade register extract |
| `certifiedTradeRegisterExtract` | Single document | Latest certified trade register extract |
| `tradeRegisterHistory` | Single document | Historical trade register extract (full record of changes), where the register publishes one |
| `financialStatements` | Array | Financial statements, **sorted newest first** |
| `articlesOfAssociation` | Array | Articles of association / statutes, **sorted newest first** |
| `ultimateBeneficialOwnersCertificate` | Single document | Latest UBO certificate |
| `officialPublications` | Array | Official publications, **sorted newest first** |
| `annualReturns` | Array | Annual returns, **sorted newest first** |
| `certificateOfGoodStanding` | Single document | Latest certificate of good standing |
| `otherDocuments` | Array | Other documents |
Within each array category, documents are **always sorted by date descending** (most recent first), so the most recent financial statement is `financialStatements[0]`. The one exception is `otherDocuments` in Ireland, which follows the register's own priority order.
Array categories can hold documents of several kinds. Each document carries a `subType`, a stable per-country classifier of the document kind. Use it rather than `name` to tell documents apart or to match them against the country's documents catalog.
While the categories are fixed, the **list of documents** for a given company is dynamic. A company may have zero financial statements or ten. It depends entirely on what the register holds. This is why the `availableDocuments` step exists.
## Document source
Every document in the `documents` object (listed or downloaded) carries a `source` field identifying the register that issues it. This is the same format as the `dataSources` section for company data:
```json theme={null}
{
"source": {
"type": "live_from_registry",
"register": "companies_house"
}
}
```
| Field | Description |
| - | - |
| `register` | Machine-readable code of the issuing register (e.g. `companies_house`, `inpi`, `handelsregister`). The registers behind each country are listed on the country's coverage page. |
| `type` | How the document is obtained: `live_from_registry` (retrieved live from the register), `cached_from_registry` (served from data the register publishes, such as an open data extract), or `private_source` (obtained through a partner). |
Use `source.register` to display the issuing authority to your users, or to apply per-register logic in countries where documents come from more than one register (e.g. France, where extracts come from INPI and certified K-bis extracts from Infogreffe).
Documents downloaded before this field was introduced may omit `source` when re-read via `GET /v2/company/{requestId}`. Re-running the request returns the attributed version.
## Document IDs
Document IDs are **opaque identifiers**, typically UUIDs like `1c932de4-4610-5506-b48d-4e62529d58e8`. They are:
* Generated when you request `availableDocuments` for a company
* Generally stable across consecutive requests for the same company, so you can reuse them short-term
* **Not guaranteed to be stable long-term.** If you need a document days or weeks later, call `availableDocuments` again to get fresh IDs
The correct flow is always: **list available documents, then pick the IDs you need**.
## Downloading documents
Document download links are **signed URLs with a 15-minute lifespan**. To handle this:
1. **Download immediately** after receiving the URL, or
2. **Refresh the URL** by calling `GET /v2/company/{requestId}`. This regenerates fresh signed URLs at no additional cost
```bash theme={null}
curl --request GET \
--url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114 \
--header 'x-api-key: '
```
Re-fetching a request by `requestId` is free and will not be billed again. Store your request IDs to refresh download links as needed.
## Document pricing
Each listed document includes a `price` field indicating its cost **in credits**. Many documents are free (price = 0), while others (typically certified extracts or documents from paid registers) have a cost. For documents priced on the register's fee, `price` can be absent until the fee is known; `priceMarkup` then gives the percentage applied to it.
You can check the price before purchasing by inspecting the documents listed after an `availableDocuments` request. Credits are only charged when you actually request the document for download.
Some documents are **included at no extra cost** when the matching **data block** is requested in the same call (or linked via 24-hour deduplication). Coverage is country-specific; see [`GET /v2/pricing`](/essentials/pricing-and-caching) and [Coverage and pricing](/essentials/coverage-and-pricing).
For details on blocks, deduplication, and budgets, see [Pricing & Caching](/essentials/pricing-and-caching).
## Automatic PDF conversion
Some registers publish documents in non-PDF formats. Topograph automatically converts them to PDF. Supported source formats:
* **Images**: JPG, JPEG, PNG, TIFF, TIF
* **Spreadsheets**: CSV, XLS, XLSX
* **Documents**: DOC, DOCX, RTF, TXT, XPS
* **Presentations**: PPT, PPTX
* **Web pages**: HTML, HTM
* **Signed containers**: EDOC, ASiC-E
When conversion is needed, the document status stays `in_progress` until processing completes (typically \~20 seconds). Once done, the document includes:
* `url`: the original file from the register
* `pdfUrl`: the PDF generated by Topograph
If the source is already a PDF, both fields point to the same file.
## AI-powered financial data extraction
Financial statements are automatically parsed using AI to extract structured data: revenue, assets, liabilities, ratios, and more. This happens during document post-processing with no additional configuration.
For the full data model and available fields, see [Financial Data Extraction](/essentials/financial-data-extraction).
## Performance expectations
Document retrieval speed depends on the country and the register being queried:
* **Fast countries** (France, Finland, Estonia...): available documents listed in seconds, documents downloaded in under a minute
* **Medium countries** (Belgium, Netherlands, Ireland...): 10-30 seconds for available documents, 1-2 minutes for downloads
* **Slow countries** (Germany, Spain...): available documents can take several minutes due to slow government registers
If you have tight response time requirements, request `availableDocuments` as a separate step and handle the wait asynchronously. Use [webhooks](/guides/webhooks) rather than polling for the best experience with slower countries.
For country-specific details on available documents and expected response times, browse the [Country Guides](https://www.topograph.co/countries/at).
## Best practices
* **Always start with `availableDocuments`**: This ensures you have valid, current document IDs and know what's available before purchasing.
* **Store request IDs**: Keep the `requestId` to refresh download URLs for free within 24 hours.
* **Monitor document status**: Check `request.dataStatus.documents[docId].status`. Documents may be `in_progress` while being fetched or converted.
* **Handle timeouts gracefully**: For slower registers, use webhooks or increase your polling timeout rather than abandoning the request.
* **Check prices before downloading**: Inspect the `price` (or `priceMarkup`) field of the listed documents to avoid unexpected charges.
For a broader picture of how document retrieval fits into the company data flow, see the [Verification Data](/essentials/retrieve_company) guide.
# Sole Entrepreneurs & Non-Profits
Source: https://docs.topograph.co/essentials/entity-types
How each datapoint behaves for natural-person businesses and non-profit entities
Not every registered entity has shareholders, and not every entity has a board. Topograph applies one consistent convention across all countries for the two entity families where the standard company data model doesn't map one-to-one: **sole entrepreneurs** (natural-person businesses) and **non-profits** (associations, foundations, and similar forms).
This page describes exactly what each datapoint returns for these entity types, so you don't need entity-type-specific business rules on your side.
## Sole entrepreneurs
A sole entrepreneur (French *entrepreneur individuel*, German *eingetragener Kaufmann*, Bulgarian *едноличен търговец (ЕТ)*, Italian *ditta individuale*, Greek *ατομική επιχείρηση*, Ukrainian *ФОП*, and equivalents) is a natural person doing business without a separate legal personality. There is no share capital, no equity instrument, and no shareholder register anywhere.
| Datapoint | Behavior |
| - | - |
| `company` | Returned normally. `legalForm.standardized` is `Sole Proprietorship`, so you can recognize the entity type from the response. |
| `legalRepresentatives` | **Always the person.** The owner is returned as the legal representative with the identity fields the register publishes (name, and where available date of birth, address, nationality). This is the record you need for sanctions/PEP screening. |
| `ultimateBeneficialOwners` | **The person, at 100%.** AML frameworks deem the sole trader the beneficial owner of the business, so where the country exposes a UBO datapoint, the owner is returned with 100% direct ownership, even when no separate UBO declaration exists in the register. **Exception:** in countries where beneficial owners come from an official certificate obtained manually (Croatia, Cyprus, Germany without your own register access, Ireland, Portugal, Slovakia, Slovenia, China), a sole trader has no certificate, so the request returns `datapoint_not_applicable` at no charge. Read the owner from `legalRepresentatives`. |
| `shareholders` | **Not applicable.** The request completes with a `datapoint_not_applicable` error (see below). No shareholder record is ever synthesized. |
### The `datapoint_not_applicable` response
Requesting `shareholders` for a sole entrepreneur does not fail silently and does not return a misleading empty array. The datapoint completes as `failed` with a dedicated, machine-readable error code:
```json theme={null}
{
"request": {
"dataStatus": {
"dataPoints": {
"shareholders": {
"status": "failed",
"error": {
"code": "datapoint_not_applicable",
"message": "Sole entrepreneurs have no share capital, so no shareholder record exists. The owner is returned under legalRepresentatives and, where available, ultimateBeneficialOwners.",
"retryable": false
}
}
}
}
}
}
```
Key properties:
* **It is not a fault.** The code is a definitive answer derived from the entity's legal form, not a register outage. Do not retry.
* **You are not charged** when `shareholders` is the only datapoint of its billing block in the request: the block is automatically refunded like any other unfulfilled datapoint. When `shareholders` shares a block with datapoints that did deliver (for example `company`), the block is billed once, as usual.
* **The ownership answer still exists**: read it from `legalRepresentatives` and `ultimateBeneficialOwners` instead.
If your pipeline iterates all datapoints uniformly, branch on `error.code === "datapoint_not_applicable"` to skip the ownership module for these entities, or rely on `ultimateBeneficialOwners`, which answers "who owns this business" for sole entrepreneurs too, except in the manual-certificate countries listed above, where `legalRepresentatives` carries the owner.
## Non-profits
Associations, foundations, and similar non-profit forms (French *association loi 1901*, German *e.V.*, Irish CLGs, and equivalents) have members and boards, not shareholders.
| Datapoint | Behavior |
| - | - |
| `company` | Returned normally, with the non-profit legal form. |
| `legalRepresentatives` | The officers/board members the register publishes (president, treasurer, directors, ...). |
| `shareholders` | **Not applicable** where the legal form has no share capital: same `datapoint_not_applicable` semantics as sole entrepreneurs. Where a register genuinely publishes founder or member equity records (some countries do for specific forms), those records are returned as published. |
| `ultimateBeneficialOwners` | Follows each country's register rules. Some beneficial-ownership registers include non-profit officers, others don't. Check the country guide. |
## Coverage notes
Brazil returns the identified sole proprietor and published non-profit officers or board members under `legalRepresentatives` in prefill mode. Their `shareholders` datapoint returns `datapoint_not_applicable` while company and representative results can succeed. Certified UBO is unavailable. See the [Brazil guide](https://www.topograph.co/countries/br).
* Some countries structurally cannot serve sole entrepreneurs because no public register holds them (for example UK sole traders, or Hong Kong sole proprietorships, which live outside the companies register). Those return `resource_not_found`: a coverage fact, not an entity-type rule. Country-level coverage is on each [country guide](/essentials/coverage-and-pricing).
* The rollout of the explicit `datapoint_not_applicable` response is per-country. Countries not yet converted may still return an empty `shareholders` array for these entity types; treat an empty array for a `Sole Proprietorship` legal form the same way you would treat the explicit code.
## Related pages
* [Reliability & Errors](/guides/reliability-and-errors): the full error-code catalog
* [Shareholders Extraction](/essentials/shareholders-extraction): how shareholder data is sourced for regular companies
* [Coverage & Pricing](/essentials/coverage-and-pricing): per-country entity coverage
# Estonia
Source: https://docs.topograph.co/essentials/estonia
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Estonia reference is on the [Estonia country page](https://www.topograph.co/countries/ee).
## Start here
This guide contains public integration notes for Estonia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Fast search data](#fast-search-data)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
All Estonian register data comes from the e-Äriregister (Estonian Business Register). In verification mode, the VAT number is also checked against the EU VIES system to fill `taxId.verification`. Prefill mode skips that check.
* **RIK (Registrite ja Infosüsteemide Keskus / Centre of Registers and Information Systems)**, operated under the Estonian Ministry of Justice since 1995, RIK maintains the Commercial Register (Ariregister), the Non-Profit Associations and Foundations Register, and the Commercial Pledge Register. It is the **sole data source** for all Estonian entity data including commercial companies, sole entrepreneurs, non-profits, foundations, and cooperatives. The API provides structured company profile data, legal representatives, shareholders, beneficial owners, activity codes, and documents.
All register data comes from RIK. If an entity is not found in RIK, it does
not exist in the Estonian business register. VIES is used only to verify the
VAT number, in verification mode.
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Domestic OÜ and AS companies. Example: `EEARIREG.12417834`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | RIK | 8 digits (Registrikood) | `12417834` | Primary registration number |
**Registrikood Format:** The registry code is always exactly 8 digits. Both
commercial companies and non-profits use the same format. No letters, no
prefixes.
### Identifiers in API Response
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `registryCode` | 8 digits | `12417834` | All entities |
| `VAT` | 9 digits (without EE prefix) | `102090374` | VAT-registered companies |
The VAT number is returned **without** the `EE` country prefix, both in
`identifiers.VAT` and in `taxId.value`. The country is in `taxId.country`
(`EE`) and the VIES verification result is in `taxId.verification`.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the register code (`registryCode`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Registrikood | 8 digits | `12417834` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | EE + 9 digits | `EE102090374` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 3 chars) | `"Bolt Technology"` | Fuzzy | Multiple results |
**Search Performance:** Use identifier-based searches (Registrikood, VAT) for
best performance and exact matching. Name searches query the RIK registry live
and may return multiple results. Name queries must be at least 3 characters
long.
**Search reads the fast index and the live register in parallel.** Every
search (by name, by ID, by VAT) queries both and returns the merged results.
When a company appears in both, the live register data is returned.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Fast search data
Estonia company data is **periodically synchronized** from the e-Business Register (Ariregister) open dataset into a fast search index.
### Search
Each search reads the fast search index (active entities only) and the live RIK register in parallel, then returns the merged results.
### Companies in fast search data
The fast search index contains **only active Estonian entities** from the Ariregister. Companies are filtered by status:
| Included Status | Code | Description |
| - | - | - |
| Active | `R` | Registrisse kantud (Entered into register) |
All other statuses are **excluded** from the fast search dataset:
| Excluded Status | Code | Description |
| - | - | - |
| In liquidation | `L` | Likvideerimisel |
| In bankruptcy | `N` | Pankrotis |
| Deleted | `K` | Kustutatud |
### Prefill Mode
The fast search index above backs `/v2/search`. It does **not** serve the
`company` datapoint: in prefill mode that datapoint still reads the
Ariregister company data live, with a lighter parse to stay inside the
prefill deadline. Company data is therefore as fresh in
prefill as in verification, and carries the register's availability rather
than an index's.
See the prefill example response below for exactly what the shallower parse
changes (raw addresses, no `taxId`, no UBOs).
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Single register source** | All register data comes from RIK. If a company is not in RIK, it does not exist in the Estonian business register. VIES is used only for the VAT check in verification mode. |
| **Status code R = Active** | The status code `R` means "Registrisse kantud" (Entered into register) and is the only active status. All other codes (`L`, `N`, `K`) indicate inactive states. |
| **Bankruptcy vs. Liquidation** | Status code `N` (bankruptcy) maps to Under Insolvency Proceeding with closure reason BANKRUPTCY. Status code `L` (liquidation) also maps to Under Insolvency Proceeding but without a specific closure reason. Both are treated as inactive. |
| **EMTAK is 5-digit NACE** | RIK provides EMTAK, NACE and an edition stamp per assignment. EMTAK 2025 is based on NACE Rev. 2.1 and feeds `activities.NACE` directly. Explicitly labelled EMTAK 2008 assignments retain `NACE_REV2` and are formally transitioned; unknown editions preserve native `EMTAK` and `NACE_EE` without a guessed revision. |
| **Employee count from annual reports** | Employee count is extracted from the most recent annual report data (`info_majandusaasta_aruannetest`) in RIK, not from a dedicated employee register. Data can be 1-2 years old. |
| **Shareholder zero-percent filtering** | Shareholders with 0% ownership (`osaluse_protsent = 0.000000`) are automatically filtered out. Only shareholders with a declared positive ownership percentage are returned. |
| **Partnership shareholders from partners** | For TÜ (general partnerships) and UÜ (limited partnerships), shareholders are extracted from `kaardile_kantud_isikud` (TOSAN/UOSAN/EUSOS/EUSOS2 roles) instead of `kaardivalised_isikud`. Partners appear in both `legalRepresentatives` and `shareholders`. This is intentional as partners serve both governance and ownership roles. Partnership shareholders have no `sharePercentage`; only limited partners (UOSAN/EUSOS/EUSOS2) have a capital contribution (`nominalCapitalHeld`). When the same person holds multiple roles, they are deduplicated by registry code; the entry with capital contribution data is preferred. |
| **FIE (sole entrepreneurs)** | Sole proprietors do not have separate legal representatives or shareholders. The entrepreneur themselves is the entity. |
| **UBO data deleted after 5 years** | Beneficial owner data is automatically deleted by RIK 5 years after a legal person is deleted from the register. Querying UBOs for long-closed companies returns an empty array. |
| **Legal form deterministic** | All 22 official RIK legal form codes (20 active + 2 discontinued) are deterministically mapped to English translations, standardized categories, and ISO 20275 codes. AI enrichment is only used as a fallback for unrecognized codes. |
| **ISIC sometimes AI-inferred** | EMTAK codes are official source assignments. NACE is passed through for EMTAK 2025 and formally transitioned for explicitly labelled EMTAK 2008. ISIC is derived centrally from standardized NACE using formal tables. Native codes are not inferred. |
| **Birth date from isikukood** | Estonian nationals' birth dates are algorithmically extracted from their personal ID code (isikukood, format `GYYMMDDSSSC`). Foreign individuals use the birth date recorded by the register instead. Both are returned as `birthDate` on individuals. |
| **Country of residence from alpha-3** | RIK provides country codes in ISO 3166-1 alpha-3 format (`EST`, `GBR`, `CYM`, etc.). These are deterministically mapped to alpha-2 `CountryCode` values (\~80 countries covered). For individual shareholders, this populates `residenceAddress.countryCode`. For company shareholders and legal reps, it sets the correct `countryCode` instead of defaulting to `EE`. |
| **Most recent data wins** | When multiple historical entries exist for addresses, names, or capital, the system takes the most recent entry based on start date. |
| **Document formats** | Annual reports are available in both PDF and XBRL formats. Articles of association are typically PDF only. |
## Mappings
**The `Code` column is reference only — it is never returned by the API.** RIK
classifier codes (`R`, `OÜ`, `JUHL`, `JAH`, `O`, ...) are documented here so
you can trace a value back to the Ariregister, but no response field carries
them. What you actually get:
| Field | Shape |
| - | - |
| `company.status` | `{ localName: "Registrisse kantud", active: true, statusDetails: { status: "ACTIVE" } }` |
| `company.legalForm` | `{ localName: "Osaühing", englishTranslation, standardized, iso20275Code }` |
| `legalRepresentatives[].role`, `otherKeyPersons[].role` | `{ localName: "Juhatuse liige", englishTranslation, standardized }` |
| `legalRepresentatives[].representationMode` | `{ mode: "sole" }`, or the field is absent |
| `ultimateBeneficialOwners[].control` | `{ types: ["ownership-of-shares"], description, details }` |
`localName` is the register's Estonian label (`Osaühing`, not `OÜ`).
`company.status` has no `englishTranslation`.
**`standardized` uses two different vocabularies.** On
`legalRepresentatives[].role` it is the standard role enum; on
`otherKeyPersons[].role` it is the narrower other-key-person enum, which has
no `Managing Director`, `Owner` or `Liquidator`. The
same register code therefore standardizes differently depending on which array
it lands in — `Nõukogu esimees` is `Chairman of the Board` as a legal
representative but `Board Member` as an other key person. Key off
`localName` + the array you found it in if you need to tell those apart.
**`representationMode` is sole-or-absent in Estonia.** RIK's `JAH` maps to
`{ mode: "sole" }`; `EI` and `EI TEA` omit the field entirely rather than
emitting a value. Estonia never returns `mode: "joint"`, `namedCoSigners`,
`minimumSignatories` or `particularity`, and the field is only ever set for
individuals, never for corporate legal representatives.
**UBO control has no `localName`.** The human-readable field is
`control.description`, and it is the one local field that comes back in
English. `control.types` is an array but Estonia always populates exactly one
entry, and `control.details` is present only for the ownership types (`O`,
`K`), not for voting-rights or significant-influence entries.
**On bankruptcy `statusDetails` grows.** It gains `closureReason`,
`insolvencyStartDate` and an `additionalInfo` string that is free text from
the register, in Estonian (e.g. `"Harju Maakohtu kohtumäärusega (2-26-14436)
kuulutati välja ... pankrot 27.08.2026 kell 11.00."`). Do not parse it; branch
on `statusDetails.status` and `closureReason`.
### Possible values
The complete set Estonia can return for each field. The per-code tables below
give the full `localName` list; these are the standardized vocabularies you would
branch on.
**`company.status.statusDetails.status`** — 4 reachable of the shared enum:
`ACTIVE` (`R`), `UNDER_INSOLVENCY_PROCEEDING` (`L` and `N`), `CLOSED` (`K`),
`UNKNOWN` (defensive default, not observed in production). Estonia never returns
`INACTIVE_NOT_CLOSED` or `PENDING_DISSOLUTION`. The only `closureReason` Estonia
sets is `BANKRUPTCY`, on `N`. The matching `localName` values are the four in the
table below.
**`legalRepresentatives[].role.standardized`** — 11 values: `Administrator`,
`Auditor`, `Board Member`, `Chairman of the Board`, `Director`, `General
Partner`, `Limited Partner`, `Liquidator`, `Managing Director`, `Other`, `Owner`.
**`otherKeyPersons[].role.standardized`** — 7 values, from a different and
narrower enum: `Auditor`, `Board Member`, `C-Level Executive`, `General Partner`,
`Limited Partner`, `Liquidator`, `Other`.
The two role vocabularies are **not** interchangeable. `C-Level Executive`
exists only for other key persons; `Managing Director`, `Chairman of the
Board`, `Owner`, `Director` and `Administrator` only for legal
representatives. 19 of the 57 register codes standardize differently depending
on which array they appear in, so the same person in the same role can carry a
different `standardized` value in each. For example `Nõukogu esimees` (`E`) is
`Chairman of the Board` as a legal representative and `Board Member` as an
other key person; `Juhatuse liige (juhataja)` (`JUHJ`) is `Managing Director`
vs `C-Level Executive`. Key off `localName` plus the array if you need to tell
them apart.
**`ultimateBeneficialOwners[].control.types`** — all 4 of the shared enum are
reachable: `ownership-of-shares`, `voting-rights`, `appoint-and-remove-directors`,
`significant-influence-or-control`. Estonia always populates exactly one entry.
**`company.legalForm.standardized`** — 9 values: `Branch or Representative
Office`, `Cooperative`, `Corporation`, `Government-Owned Entity`, `Limited
Liability Company`, `Nonprofit Organization`, `Other`, `Partnership`, `Sole
Proprietorship`.
**No AI produces these sets.** Status, roles and UBO control types are resolved
by deterministic lookup tables, and the legal form map covers all 19 forms
present in the register today, so the AI enrichment fallback does not fire in
practice.
Two open-ended cases exist at the edges. An unrecognised role code returns
`localName: "Tundmatu roll: "` with `standardized: "Other"`, so the role
sets above stay closed. An unrecognised **legal form** code is the one place
the register can outrun us: `localName` falls back to the raw code, the AI
fallback picks `standardized`, and `isAIEnriched: true` is set on the object.
Check that flag if you need to know whether a legal form was inferred rather
than mapped.
### Company Status
Company status is extracted **deterministically** from the RIK register `staatus` field. No AI inference is involved.
| Status Code | Local Status (Estonian) | English Translation | Standardized Status | Active? |
| - | - | - | - | - |
| `R` | Registrisse kantud | Entered into register | Active | Yes |
| `L` | Likvideerimisel | In liquidation | Under Insolvency Proceeding | No |
| `N` | Pankrotis | In bankruptcy | Under Insolvency Proceeding (closure reason: Bankruptcy) | No |
| `K` | Kustutatud | Deleted from register | Closed | No |
When status is `N` (bankruptcy), the system also searches for the bankruptcy
declaration event (`PANKV`) in the status change history to extract the
insolvency start date and additional context.
### Legal Forms
The local legal form (`oiguslik_vorm`) is preserved from the register and deterministically mapped to an English translation. For known codes, standardized classification is applied directly; for unrecognized codes, AI-based classification is used as fallback. `iso20275Code` is returned when an ISO 20275 (ELF) code exists for the form, and is absent otherwise.
Legal forms are classified from official registry data. For known codes,
standardized classification is applied directly; for unrecognized codes,
AI-based classification is used as fallback.
#### Companies
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `OÜ` | Osaühing | Private limited company | Limited Liability Company | JC0Y |
| `AS` | Aktsiaselts | Public limited company | Corporation | 9LJA |
#### Sole Proprietorships
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `FIE` | Füüsilisest isikust ettevõtja | Sole proprietorship | Sole Proprietorship | 3UPJ |
#### Partnerships
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `TÜ` | Täisühing | General partnership | Partnership | I1UP |
| `UÜ` | Usaldusühing | Limited partnership | Partnership | LVEQ |
#### Cooperatives
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `KÜ` | Korteriühistu | Apartment association | Cooperative | 8ZQE |
| `TÜH` | Tulundusühistu | Commercial cooperative | Cooperative | VSEV |
| `MPÜ` | Maaparandusühistu | Land improvement association | Cooperative | - |
#### Non-profit Organizations
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `MTÜ` | Mittetulundusühing | Non-profit association | Nonprofit Organization | PRTB |
| `SA` | Sihtasutus | Foundation | Nonprofit Organization | 1NKP |
| `ERAK` | Erakond | Political party | Nonprofit Organization | - |
| `AMETÜ` | Ametiühing | Trade union | Nonprofit Organization | - |
#### Government & Public Law Entities
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `TRAS` | Täidesaatva riigivõimu asutus või riigi muu institutsioon | Executive government agency or other state institution | Government-Owned Entity | - |
| `AVOIG` | Avalik-õiguslik juriidiline isik, põhiseaduslik institutsioon või nende asutus | Public law legal entity, constitutional institution or their agency | Government-Owned Entity | - |
| `KOVAS` | Kohaliku omavalitsuse asutus | Local government agency | Government-Owned Entity | - |
#### European Legal Forms
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `SE` | Euroopa äriühing (Societas Europaea) | European Company (Societas Europaea) | Corporation | 752Q |
| `SCE` | Euroopa ühistu | European Cooperative Society | Cooperative | RXTT |
| `EMÜ` | Euroopa majandushuviühing | European Economic Interest Grouping | Partnership | - |
| `TKR` | Euroopa territoriaalse koostöö rühmitus | European Grouping of Territorial Cooperation | Other | - |
#### Branch Offices
| Code | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| `FIL` | Välismaa äriühingu filiaal | Branch of a foreign company | Branch or Representative Office | - |
#### Discontinued
| Code | Local Name | English Translation | Notes |
| - | - | - | - |
| `FA` | Välismaa äriühingu filiaal | Branch of a foreign company | Replaced by `FIL` (2013) |
| `HÜ` | Hooneühistu | Building cooperative | Replaced by `TÜH` (2012) |
### Legal Representatives
Legal representatives are determined using **two data sources** from RIK:
1. **Role Data** (the register's company data service): Provides role codes from `kaardile_kantud_isikud` (persons entered on the card)
2. **Representation Rights** (the register's representation rights service): Provides the `ainuesindusoigus_olemas` field indicating exclusive representation rights
#### Classification Logic
A person is classified as a **legal representative** if either:
* They have **JAH** (exclusive/sole representation rights) from the representation rights data
* **OR** Their role code implies representation rights (see tables below)
#### Representation Mode
For **individuals** (not companies), the `representationMode` field is set based on the `ainuesindusoigus_olemas` value:
| Status | Meaning | Legal Representative? | `representationMode` Set? |
| - | - | - | - |
| **JAH** | Has exclusive representation rights | ✅ Yes | ✅ Yes (`mode: "sole"`) |
| **EI** | No representation rights | Only if role implies | ❌ No |
| **EI TEA** | Unknown / Cannot determine | Only if role implies | ❌ No |
**Companies** (corporate legal representatives) are classified based on role
only. They do not have personal representation rights data. The
`representationMode` field is only applicable to individuals.
**EI TEA (Unknown)** is returned for roles where representation rights cannot
be clearly determined (procurators, branch directors, certain board
positions). These individuals ARE legal representatives due to their roles,
but we cannot determine if they have sole or joint representation rights.
**Partnership representation rights:** General partners (`TOSAN`) have
inherent representation rights under [Estonian Commercial Code
(Äriseadustik)](https://www.riigiteataja.ee/en/eli/ee/Riigikogu/act/527022024004/consolide)
§98(1): each partner may represent the partnership in all transactions unless
the agreement restricts it. §100 allows a court to deprive this right on
request of the other partners, confirming it is inherent, not granted. Limited
partners (`UOSAN`) have no representation rights by default. `EUSOS`/`EUSOS2`
("esindama *volitatud* usaldusosanik" = limited partner *authorized* to
represent) are the exception: the authorization is explicitly entered in the
commercial register, which is why the role code exists. Regular limited
partners (`UOSAN`) are classified as shareholders only.
These roles trigger automatic classification as a legal representative when the person does not have `JAH` in the representation rights data.
#### Explicit representation roles
The role name itself contains "represent" in the RIK ISIKROLLID classifier.
| Code | RIK English Description | Why |
| - | - | - |
| `ESIS2` | Person entitled to represent the undertaking | Primary board/management role since 2000; explicitly entitled to represent |
| `SJESI` | Legal representative of the company | Directly labelled as legal representative |
| `ASES` | Person with right to represent the agency | Explicitly granted representation right for the agency |
| `EUSOS` | A limited partner authorized to represent | Limited partner with an explicit representation grant |
| `EUSOS2` | A limited partner authorized to represent | Same as EUSOS, introduced in 2000 |
| `ESIS` | Person delegated to represent the undertaking | Deprecated predecessor of ESIS2 (ended 2012-01-01), kept for historical data |
| `ESOI` | Person(s) entitled to represent the undertaking | Deprecated (ended 1997-01-01), kept for historical data |
#### Implied representation roles
These roles do not mention "represent" in their classifier name but carry representation authority by the nature of the role.
| Code | RIK English Description | Why |
| - | - | - |
| `JUHL` | Management board member | Estonian Commercial Code (ÄS §181) grants board members representation rights by default; primary legal representatives of an OÜ or AS |
| `TOSAN` | General partner | ÄS §98(1): each partner may represent the partnership in all transactions unless the agreement restricts it; §100 allows courts to deprive this right, confirming it is inherent |
| `PROK` | Procurator | Procurators hold commercial representation authority; the representation rights data returns `EI TEA` for them, so role code is the fallback |
| `VFILJ` | Director of branch | Represents the foreign company's Estonian branch; sole person with authority since a branch has no separate legal personality |
| Code | Local Name (Estonian) | English Translation | Standardized Role |
| - | - | - | - |
| `JUHA` | Juhatuse ainuliige | Sole member of the board | Chairman of the Board |
| `JUHE` | Juhatuse esimees | Chairman of the board | Chairman of the Board |
| `JUHJ` | Juhatuse liige (juhataja) | Management board member (director) | Managing Director |
| `VALIT` | Valitseja | Administrator | Administrator |
| `TVH` | Tagatisvara haldur | Cover pool administrator | Administrator |
| `UOSAN` | Usaldusosanik | Limited partner | Limited Partner |
| `OSAN` | Osanik | Shareholder | Owner |
`JUHA`, `JUHE`, and `JUHJ` are sub-roles of management board membership. In
practice they always receive `JAH` in the representation rights data and are classified as
legal representatives via that path, not via the role code.
| Code | Local Name (Estonian) | English Translation | Standardized Role |
| - | - | - | - |
| `LIKV` | Likvideerija | Liquidator | Liquidator |
| `LIKVJ` | Juhatuse liikmest likvideerija | The liquidators are the members of the management board | Liquidator |
| `PANKR` | Pankrotihaldur | Trustee in bankruptcy | Liquidator |
| `JPNKR` | Järelevalveõiguslik pankrotihaldur | Trustee in bankruptcy with the right to supervise | Liquidator |
| `AJPH` | Ajutine pankrotihaldur likvideerija ülesannetes | The interim trustee in bankruptcy acting as a liquidator | Liquidator |
| `ERIH` | Erirežiimihaldur | Special regime trustee | Liquidator |
| `HUL` | Hooneühistu liige | Member of building association | Liquidator |
| `ESOI` | esindama õigustatud isik(ud) | person(s) entitled to represent the undertaking | Liquidator |
| Code | Local Name (Estonian) | English Translation | Standardized Role |
| - | - | - | - |
| `ESIS` | Esindama õigustatud isik | Person delegated to represent the undertaking | Other |
| `MORAH` | Moratooriumihaldur | Trustee in moratorium | Other |
| `KOAS` | Kõrgemalseisev asutus | Superior agency | Other |
| `ETTEV` | ettevõtja | undertaking | Other |
| `ASES` | Asutuse esindusõiguslik isik | Person with right to represent the agency | Other |
| `FV` | Fondivalitseja | The Management Company | Other |
| `YFI` | Ühendav füüsiline isik | Acquiring natural person | Other |
| `ORP` | Osade registripidaja | The registrar of the units of the fund | Other |
| `ARP` | Aktsiaraamatu pidaja | The registrar of the shares of the fund | Other |
| `AJUTPH` | Ajutine pankrotihaldur | Interim trustee | Other |
| `PANTP` | Pandipidaja | Holder of the pledge | Other |
| `DOKH` | Dokumentide hoidja | Depositary of documents | Other |
| `KISIK` | Kontaktisik | Contact person | Other |
| `MDKPI` | Menetlusdokumentide kättesaamiseks pädev isik | A person competent to receive procedural documents | Other |
| `FIE` | Füüsilisest isikust ettevõtja | Sole trader | Owner |
| `V` | Volitatud isik | Authorised person | Other |
| `YHLLV` | Lisavastutusega ühistu liige | A member of association with additional liability | Other |
| `YHL` | Ühistu liige | The member of a commercial association | Other |
Legal representative classification is **deterministic**, based on the role
code and the `ainuesindusoigus_olemas` field. No AI is involved. Both
individuals (`isiku_tyyp = F`) and corporate entities (`isiku_tyyp != F`) can
hold legal representative roles.
### Other Key Persons
Other key persons come from two sections of the RIK data: the `kaardivalised_isikud` (off-card persons) section, and any person from `kaardile_kantud_isikud` (persons entered on the card) who is not classified as a legal representative. Off-card persons with roles `O` (Shareholder) and `OSAN` (Shareholder) are excluded since they are processed as shareholders instead, and on-card partners (`TOSAN`, `UOSAN`, `EUSOS`, `EUSOS2`) are returned as shareholders, not as other key persons.
| Code | Local Name (Estonian) | English Translation | Standardized Role |
| - | - | - | - |
| `HNKL` | Haldusnõukogu liige | Member of administrative board | Board Member |
| `JUHL` | Juhatuse liige | Management board member | Board Member |
| `JUHA` | Juhatuse ainuliige | Sole member of the board | Board Member |
| `JUHE` | juhatuse esimees | Chairman of the board | Board Member |
| `N` | Nõukogu liige | Member of the supervisory board | Board Member |
| `E` | Nõukogu esimees | Chairman of the supervisory board | Board Member |
| `YHLLV` | Lisavastutusega ühistu liige | A member of association with additional liability | Board Member |
| Code | Local Name (Estonian) | English Translation | Standardized Role |
| - | - | - | - |
| `JUHJ` | Juhatuse liige (juhataja) | Management board member (director) | C-Level Executive |
| `VFILJ` | Filiaali juhataja | Director of branch | C-Level Executive |
| Code | Local Name (Estonian) | English Translation | Standardized Role |
| - | - | - | - |
| `D` | Audiitorettevõtja | Audit firm | Auditor |
| Code | Local Name (Estonian) | English Translation | Standardized Role |
| - | - | - | - |
| `A` | Asutaja | Founder | Other |
| `B` | Asutaja (sissemakseta) | Founder (without contribution) | Other |
| `H` | Hooneühistu liige | Member of building association | Other |
| `J` | Revident | Controller | Other |
| `K` | Kohaliku omavalitsuse liidu liige | Member of local authorities' association | Other |
| `L` | Liikmeskogudus | Member congregation | Other |
| `M` | Mitterahalist sissemakset hinnanud audiitor | Auditor of valuation of non-monetary contribution | Other |
| `P` | Pankrotitoimkonna liige | Members of the bankruptcy committee | Other |
| `R` | Revisjonikomisjoni liige | Member of the auditing commission | Other |
| `S` | Aktsionär | Stockholder | Other |
| `W` | Tegelik kasusaaja | Beneficial owner | Other |
| `YHL` | Ühistu liige | The member of a commercial association | Other |
| `ESIS` | Esindama õigustatud isik | Person delegated to represent the undertaking | Other |
| `MORAH` | Moratooriumihaldur | Trustee in moratorium | Other |
| `KOAS` | Kõrgemalseisev asutus | Superior agency | Other |
| `ETTEV` | ettevõtja | undertaking | Other |
| `ASES` | Asutuse esindusõiguslik isik | Person with right to represent the agency | Other |
| `FV` | Fondivalitseja | The Management Company | Other |
| `YFI` | Ühendav füüsiline isik | Acquiring natural person | Other |
| `ORP` | Osade registripidaja | The registrar of the units of the fund | Other |
| `JPNKR` | Järelevalveõiguslik pankrotihaldur | Trustee in bankruptcy with the right to supervise | Other |
| `HUL` | Hooneühistu liige | Member of building association | Other |
| `ESOI` | esindama õigustatud isik(ud) | person(s) entitled to represent the undertaking | Other |
| `ERIH` | Erirežiimihaldur | Special regime trustee | Other |
| `ARP` | Aktsiaraamatu pidaja | The registrar of the shares of the fund | Other |
| `AJUTPH` | Ajutine pankrotihaldur | Interim trustee | Other |
| `PANTP` | Pandipidaja | Holder of the pledge | Other |
| `PANKR` | Pankrotihaldur | Trustee in bankruptcy | Other |
| `DOKH` | Dokumentide hoidja | Depositary of documents | Other |
| `VALIT` | Valitseja | Administrator | Other |
| `EUSOS` | Esindama volitatud usaldusosanik | A limited partner authorized to represent | Other |
| `TOSAN` | Täisosanik | General partner | Other |
| `UOSAN` | Usaldusosanik | Limited partner | Other |
| `TVH` | Tagatisvara haldur | Cover pool administrator | Other |
| `SJESI` | Äriühingu seadusjärgne esindaja | Legal representative of the company | Other |
| `EUSOS2` | Esindama volitatud usaldusosanik | A limited partner authorized to represent | Other |
| `ESIS2` | Esindama õigustatud isik | Person entitled to represent the undertaking | Other |
| `AJPH` | Ajutine pankrotihaldur likvideerija ülesannetes | The interim trustee in bankruptcy acting as a liquidator | Other |
| `LIKVJ` | Juhatuse liikmest likvideerija | The liquidators are the members of the management board | Other |
| `PROK` | Prokurist | Procurator | Other |
| `KISIK` | Kontaktisik | Contact person | Other |
| `LIKV` | Likvideerija | Liquidator | Other |
| `MDKPI` | Menetlusdokumentide kättesaamiseks pädev isik | A person competent to receive procedural documents | Other |
| `FIE` | Füüsilisest isikust ettevõtja | Sole trader | Other |
| `V` | Volitatud isik | Authorised person | Other |
Other key persons include off-card persons (`kaardivalised_isikud`) and
on-card persons who are neither legal representatives nor partners.
Off-card persons with role code `O` or `OSAN` (both mean "Shareholder") are
**excluded** from other key persons and processed as shareholders instead. Both individuals and corporate entities can appear as
other key persons.
### Shareholders
Shareholders are extracted from two different sections of the RIK data depending on the company type:
* **OÜ / AS**: Shareholders come from `kaardivalised_isikud` (off-card persons) with role `O` or `OSAN` and a positive ownership percentage.
* **TÜ / UÜ (partnerships)**: Partners come from `kaardile_kantud_isikud` (card-registered persons) with roles `TOSAN` (general partner), `UOSAN` (limited partner), `EUSOS` or `EUSOS2` (limited partner authorized to represent). These are returned as shareholders since partners are the owners of partnerships. When the same person appears under multiple roles (e.g. both `EUSOS` and `UOSAN`), they are deduplicated, keeping the entry with capital contribution data.
**Supported entity types:** OÜ (private limited companies), AS (public limited companies), TÜ (general partnerships), and UÜ (limited partnerships). For sole traders (FIE) and non-profits (MTÜ, SA, ERAK, AMETÜ) with no equity records, the `shareholders` datapoint is not applicable and returns an explicit not-applicable response at no charge instead of an empty array.
### Ownership Fields
| Field | Description | Source | Availability |
| - | - | - | - |
| `sharePercentage` | Ownership percentage | `osaluse_protsent` from RIK | OÜ/AS only |
| `nominalCapitalHeld` | Nominal capital amount held | `osaluse_suurus` + `osaluse_valuuta` (OÜ/AS) or `osamaks` + `osamaksu_valuuta` (UÜ) | OÜ/AS and UÜ limited partners |
| `type` | Individual or Company | Determined from `isiku_tyyp` (`F` = individual, other = company) | All |
| `individual.birthDate` | Birth date of individual shareholder | Parsed from `synniaeg` (foreign) or extracted from `isikukood` (Estonian) | Individuals only |
| `individual.residenceAddress` | Country of residence | Parsed from `aadress_riik` (alpha-3) with address text fallback | Individuals only |
| `company.countryCode` | Registration country of corporate shareholder | From `valis_kood_riik` or `aadress_riik` (alpha-3), defaults to `EE` | Companies only |
For **OÜ/AS**: Shareholders with `osaluse_protsent = 0.000000` or no ownership percentage are automatically filtered out. Both individual and corporate shareholders are supported, with address parsing for both types.
For **TÜ/UÜ partnerships**: Partners do not have ownership percentages (`sharePercentage` is absent). General partners (TOSAN) have unlimited liability and no capital contribution. Limited partners (UOSAN, EUSOS, EUSOS2) have a capital contribution (`osamaks`) returned as `nominalCapitalHeld`.
### UBO Control Types
Ultimate Beneficial Owner (UBO) data is sourced from the RIK beneficial owner service. Each UBO has a control type code (`kontrolli_teostamise_viis`) defined by the Estonian Money Laundering and Terrorist Financing Prevention Act (RahaPTS §9).
| Code | Estonian | English | Standardized Control Type | Details |
| - | - | - | - | - |
| `O` | Otsene osalus | Direct ownership | `ownership-of-shares` | nature: `direct` |
| `K` | Kaudne osalus | Indirect ownership | `ownership-of-shares` | nature: `indirect` |
| `F` | Muul viisil kontroll või mõju | Control through other means (contractual, family relations, etc.) | `significant-influence-or-control` | - |
| `J` | Kõrgema juhtorgani liige | Senior managing official (management or supervisory board member) | `significant-influence-or-control` | Fallback when no >25% owner identifiable |
| `C` | Juhatuse liige või liikmed | Management board member(s) | `significant-influence-or-control` | Fallback when no >25% owner identifiable |
| `X` | Suurem kui 50% osalus hääleõiguses | >50% voting rights in consolidated entity | `voting-rights` | - |
| `Y` | Õigus nimetada või tagasi kutsuda tegevjuhtkonda | Right to appoint or remove majority of management | `appoint-and-remove-directors` | - |
| `S` | Soodustatud isik | Beneficiary (of trust or foundation) | `significant-influence-or-control` | Trust/foundation-specific |
| `Z` | Asutajaõiguste teostaja | Founder rights exerciser, supervisory/management board member | `significant-influence-or-control` | Trust/foundation-specific |
**Commercial Register only.** UBO data is queried from the Äriregister
(Commercial Register), which covers commercial entities: OÜ, AS, TÜ, UÜ, FIE,
and branches of foreign companies. Non-profit associations (MTÜ) and
foundations (SA) are registered in a separate register (Mittetulundusühingute
ja sihtasutuste register) and are **not** covered by this service. As a
result, control type codes `S`, `Z`, and `C` (which are specific to
foundations and non-profits) are unlikely to appear in practice through our
integration.
### Activity Code Mapping
Estonia uses the **EMTAK (Eesti Majanduse Tegevusalade Klassifikaator)** classification, which is Estonia’s national extension of NACE. RIK supplies the edition on each assignment: EMTAK 2008 corresponds to NACE Rev. 2; EMTAK 2025 corresponds to NACE Rev. 2.1. The system maps activity codes across three levels:
```
EMTAK (Estonian, 5-digit) --> NACE Rev. 2.1 (European, 4-digit) --> ISIC Rev. 5 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **EMTAK** | RIK register (`emtak_kood` field) | `62011` | No (official) |
| **NACE** | RIK NACE code, using the assignment’s EMTAK edition | `62.10` | No |
| **ISIC** | Derived from standardized NACE via formal mapping | `621` | No |
The native code remains under `activities.EMTAK`; recognized edition stamps also
produce `EMTAK_2008` or `EMTAK_2025`. EMTAK 2025 NACE classes feed standardized
`NACE` directly. Explicitly labelled EMTAK 2008 classes are preserved under
`NACE_REV2` and transitioned into `NACE` with the formal correspondence.
`NACE_EE` always preserves the register’s original NACE string. Unknown or
conflicting editions do not receive a guessed standardized class. ISIC is
derived centrally from standardized NACE using formal tables.
Registered card activity and object text is returned as `activityDescription`
when present, independently of the legal-form label.
## Data Availability
### Data Availability Matrix
| Data Type | Commercial Companies (OU, AS) | Sole Entrepreneurs (FIE) | Non-Profits (MTU) | Foundations (SA) | Cooperatives (TUH, KU) | Notes |
| - | - | - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | ✅ Async | ✅ Async | Full data from RIK |
| Legal Representatives | ✅ | ⚠️ Limited | ✅ | ✅ | ✅ | FIE: entrepreneur is the entity |
| Shareholders | ✅ | ❌ | ❌ | ❌ | ❌ | OU, AS, TÜ, and UÜ; not applicable for FIE, MTU, SA |
| Ultimate Beneficial Owners | ✅ | ❌ | ⚠️ Limited | ⚠️ Limited | ⚠️ Limited | Declared by entity; deleted after 5 years of closure |
| Activity Codes | ✅ | ✅ | ✅ | ✅ | ✅ | EMTAK + NACE mapping |
| Documents | ✅ | ✅ | ✅ | ✅ | ✅ | Trade register extract, articles, annual reports |
| Employee Count | ✅ | ✅ | ⚠️ Limited | ⚠️ Limited | ⚠️ Limited | From annual report data |
| Phone / Website | ⚠️ When registered | ⚠️ When registered | ⚠️ When registered | ⚠️ When registered | ⚠️ When registered | Contact data is optional in RIK |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | ✅ All entities | Official registration document with full company history. Sold with the company data block, so it adds no charge when you also request company data |
| **Articles of Association** | `articlesOfAssociation[]` | PDF | ✅ When filed | Company bylaws and governance rules. Billed per document |
| **Annual Reports** | `financialStatements[]` | PDF or XBRL | ✅ When filed | Financial statements and annual filings, available for multiple years. Billed per document |
**Annual reports** are available in both PDF and XBRL formats when both exist.
The documents list is sorted by year descending (newest first). Historical
annual reports going back many years may be available.
**Delivery time:** Documents are retrieved from the register when you request
them, so they can take longer to arrive than datapoints. Use webhooks or poll
the request until each document is delivered.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "EE", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "12345678",
"countryCode": "EE",
"identifiers": { "registryCode": "12345678", "VAT": "123456789" },
"taxId": { "type": "eu_vat", "value": "123456789", "country": "EE", "verification": { "status": "verified", "verifiedName": "Näidis Tehnoloogia OU", "verifiedAddress": "Narva mnt 5 10117 Kesklinna linnaosa Tallinn" } },
"legalName": "Näidis Tehnoloogia OU",
"registrationDate": "2020-05-15",
"status": { "localName": "Registrisse kantud", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Osaühing", "englishTranslation": "Private limited company", "standardized": "Limited Liability Company", "iso20275Code": "JC0Y" },
"capital": { "amount": 2500, "currency": "EUR", "formatted": "2,500.00 EUR" },
"activities": {
"EMTAK": [{ "code": "62011", "description": "Programmeerimine", "isAIInferred": false }],
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Narva mnt 5", "city": "Tallinn", "postalCode": "10117", "countryCode": "EE", "state": "Harju maakond" },
"phones": ["+372 51234567"],
"website": "https://www.example.ee",
"employeeCount": { "exact": 12, "isEstimate": false, "lastUpdated": "2024-12-31" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Juhatuse liige", "englishTranslation": "Management board member", "standardized": "Board Member" }, "startDate": "2020-05-15T00:00:00.000Z", "individual": { "name": { "fullName": "Marten Tamm", "firstName": "Marten", "lastName": "Tamm" }, "birthDate": { "day": 15, "month": 3, "year": 1985 } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 60, "nominalCapitalHeld": { "amount": 1500, "currency": "EUR", "formatted": "1500 EUR" }, "individual": { "name": { "fullName": "Marten Tamm", "firstName": "Marten", "lastName": "Tamm" }, "birthDate": { "day": 15, "month": 3, "year": 1985 }, "residenceAddress": { "countryCode": "EE" } } },
{ "entityId": "company_001", "type": "company", "sharePercentage": 40, "nominalCapitalHeld": { "amount": 1000, "currency": "EUR", "formatted": "1000 EUR" }, "company": { "id": "87654321", "legalName": "Investor Holding OU", "countryCode": "EE" } }
],
"otherKeyPersons": [
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Nõukogu liige", "englishTranslation": "Member of the supervisory board", "standardized": "Board Member" }, "startDate": "2021-01-10T00:00:00.000Z", "individual": { "name": { "fullName": "Katrin Kask", "firstName": "Katrin", "lastName": "Kask" }, "birthDate": { "day": 22, "month": 7, "year": 1990 } } }
]
}
```
```json theme={null}
{
"company": {
"id": "12417834",
"countryCode": "EE",
"identifiers": { "registryCode": "12417834", "VAT": "102090374" },
"taxId": { "type": "eu_vat", "value": "102090374", "country": "EE", "verification": { "status": "verified" } },
"legalName": "Bolt Technology OÜ",
"registrationDate": "2013-02-06",
"status": { "localName": "Registrisse kantud", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Osaühing", "englishTranslation": "Private limited company", "standardized": "Limited Liability Company", "iso20275Code": "JC0Y" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Juhatuse liige",
"englishTranslation": "Management board member",
"standardized": "Board Member"
},
"representationMode": {
"mode": "sole"
},
"startDate": "2013-02-06",
"individual": {
"identifiers": { "isikukood": "37502126022" },
"name": {
"fullName": "Ahto Kink",
"firstName": "Ahto",
"lastName": "Kink"
},
"birthDate": { "day": 12, "month": 6, "year": 1975 }
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Juhatuse liige",
"englishTranslation": "Management board member",
"standardized": "Board Member"
},
"representationMode": {
"mode": "sole"
},
"startDate": "2013-02-06",
"individual": {
"identifiers": { "isikukood": "39312170011" },
"name": {
"fullName": "Markus Villig",
"firstName": "Markus",
"lastName": "Villig"
},
"birthDate": { "day": 17, "month": 12, "year": 1993 }
}
}
]
}
```
**Note:** This example shows `representationMode` set to `"sole"` for legal representatives who have **JAH (exclusive/sole representation rights)** in the RIK representation rights data. Both board members can sign independently on behalf of the company. The `representationMode` field is only set for individuals (not companies) who have confirmed sole representation rights.
```json theme={null}
{
"company": {
"id": "87654321",
"countryCode": "EE",
"identifiers": { "registryCode": "87654321" },
"taxId": { "type": "eu_vat", "value": "", "country": "EE", "verification": { "status": "unavailable" } },
"legalName": "Vana Kaubandus OU",
"registrationDate": "2005-03-10",
"status": { "localName": "Kustutatud", "active": false, "statusDetails": { "status": "CLOSED" } },
"legalForm": { "localName": "Osaühing", "englishTranslation": "Private limited company", "standardized": "Limited Liability Company", "iso20275Code": "JC0Y" },
"legalAddress": {},
"employeeCount": { "exact": 1, "isEstimate": false, "lastUpdated": "2013-12-31" }
},
"legalRepresentatives": [],
"otherKeyPersons": []
}
```
**Note:** Closed companies have `active: false` and status "Kustutatud" (Deleted from register). Address data may be empty. VAT verification is unavailable for closed entities. UBO data is deleted 5 years after closure.
```json theme={null}
{
"company": {
"id": "80111222",
"countryCode": "EE",
"identifiers": { "registryCode": "80111222" },
"legalName": "Eesti Spordiklubi",
"registrationDate": "2018-09-01",
"status": { "localName": "Registrisse kantud", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Mittetulundusühing", "englishTranslation": "Non-profit association", "standardized": "Nonprofit Organization", "iso20275Code": "PRTB" },
"activities": {
"EMTAK": [{ "code": "93120", "description": "Spordiklubide tegevus", "isAIInferred": false }],
"NACE": [{ "code": "93.12", "description": "Activities of sport clubs", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Staadioni 2", "city": "Tartu", "postalCode": "51008", "countryCode": "EE", "state": "Tartu maakond" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Juhatuse liige", "englishTranslation": "Management board member", "standardized": "Board Member" }, "startDate": "2018-09-01T00:00:00.000Z", "individual": { "name": { "fullName": "Katrin Kask", "firstName": "Katrin", "lastName": "Kask" }, "birthDate": { "day": 22, "month": 7, "year": 1990 } } }
]
}
```
**Note:** Non-profits do not have shareholders or capital information. Legal representatives (board members) are available. Birth dates are extracted from Estonian personal ID codes (isikukood).
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"request": {
"companyId": "12345678",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"dataStatus": {
"dataPoints": { "ultimateBeneficialOwners": { "status": "succeeded" } }
},
"countryCode": "EE"
},
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": {
"fullName": "Marten Tamm",
"firstName": "Marten",
"lastName": "Tamm"
},
"control": {
"types": ["ownership-of-shares"],
"description": "Direct ownership",
"details": [{ "nature": "direct", "type": "shares" }]
}
},
{
"entityId": "person_002",
"name": {
"fullName": "Katrin Kask",
"firstName": "Katrin",
"lastName": "Kask"
},
"control": {
"types": ["ownership-of-shares"],
"description": "Indirect ownership",
"details": [{ "nature": "indirect", "type": "shares" }]
}
},
{
"entityId": "person_003",
"name": {
"fullName": "Jaan Mets",
"firstName": "Jaan",
"lastName": "Mets"
},
"control": {
"types": ["significant-influence-or-control"],
"description": "Control or influence through other means (contractual, family relations etc)"
}
}
]
}
```
**Note:** UBOs are available for commercial companies registered in the Äriregister (Commercial Register). UBO data is automatically deleted 5 years after a legal person is removed from the register. See the [UBO Control Types](#ubo-control-types) section below for the full mapping of control type codes.
Query with `"dataPoints": ["availableDocuments"]`:
```json theme={null}
{
"request": {
"companyId": "12345678",
"requestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"dataStatus": {
"dataPoints": { "availableDocuments": { "status": "succeeded" } }
},
"countryCode": "EE"
},
"documents": {
"tradeRegisterExtract": {
"id": "abc12345-1111-2222-3333-444455556666",
"name": "Trade Register Extract",
"format": "pdf",
"description": "Trade register extract from the Estonian Business Registry (RIK)"
},
"financialStatements": [
{
"id": "abc12345-2222-3333-4444-555566667777",
"name": "Annual Report - 2024 - PDF",
"format": "pdf",
"description": "Annual report from the Estonian Business Registry (RIK) - 2024"
},
{
"id": "abc12345-3333-4444-5555-666677778888",
"name": "Annual Report - 2024 - XBRL",
"format": "xbrl",
"description": "Annual report from the Estonian Business Registry (RIK) - 2024"
},
{
"id": "abc12345-4444-5555-6666-777788889999",
"name": "Annual Report - 2023 - PDF",
"format": "pdf",
"description": "Annual report from the Estonian Business Registry (RIK) - 2023"
}
],
"articlesOfAssociation": [
{
"id": "abc12345-5555-6666-7777-888899990000",
"name": "Articles of Association - PDF",
"format": "pdf",
"description": "Articles of association from the Estonian Business Registry (RIK)"
}
]
}
}
```
**Note:** The list comes back under `documents`: the trade register extract in `tradeRegisterExtract`, annual reports in `financialStatements[]` and articles in `articlesOfAssociation[]`. Annual reports include both PDF and XBRL versions and are sorted by year descending. Historical reports may go back many years. Pass a document's `id` in the `documents` field of a follow-up request to download it.
```json theme={null}
{
"company": {
"id": "12417834",
"countryCode": "EE",
"identifiers": { "VAT": "102090374", "registryCode": "12417834" },
"legalName": "Bolt Technology OÜ",
"registrationDate": "2013-02-06",
"status": { "localName": "Registrisse kantud", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Osaühing", "englishTranslation": "Private limited company", "standardized": "Limited Liability Company", "iso20275Code": "JC0Y" },
"legalAddress": { "addressLine1": "Vana-Lõuna tn 15", "city": "Kesklinna linnaosa, Tallinn, Harju maakond", "postalCode": "10134", "countryCode": "EE" }
}
}
```
**Prefill is the same register call, parsed shallower — not a different data source.**
Both modes read the same Ariregister company data; prefill parses it
lighter to stay inside the prefill deadline, not to read a cheaper
dataset. The fast search index built from the Ariregister open data backs
`/v2/search` only.
So `status`, `legalForm` and every `role` are identical to verification,
`standardized` and `iso20275Code` included, and shareholders and activity
codes are returned.
What actually differs in prefill:
| | Prefill | Verification |
| - | - | - |
| Addresses | as the register publishes them — no geocoding, no `region` or coordinates, `city` may be one locality string | geocoded, split into `city` / `region`, with coordinates |
| `taxId` | `null` — VIES is not called | VIES-verified |
| `ultimateBeneficialOwners` | **unavailable** — fails `fast_source_unavailable` | returned |
Request UBOs in verification mode; there is no fast source for them.
# European Unique Identifier (EUID)
Source: https://docs.topograph.co/essentials/euid
Retrieve European company identifiers, understand coverage, and handle missing values
The European Unique Identifier (EUID) identifies a company or branch across the European Business Registers Interconnection System (BRIS). Topograph returns it as `company.identifiers.euid` when supported for the company and the source used by your request.
## Retrieve an EUID
Request the `company` datapoint using the company's national identifier. The EUID appears alongside its other identifiers in the company response. This response excerpt shows an Italian company:
```json theme={null}
{
"company": {
"id": "00484960588",
"countryCode": "IT",
"identifiers": {
"codiceFiscale": "00484960588",
"euid": "ITRI.00484960588"
}
}
}
```
`euid` is optional. A missing value does not mean the company is invalid or that no EUID exists. Availability depends on the entity type, source, request mode and available record.
This coverage applies to the queried company. Identifiers on related entities, such as shareholders or representatives, may differ.
EUID is an output identifier. It is not supported as an input to `/v2/search` or as the company ID for a company request. Use the national identifier described in the country's guide.
## Country coverage
Coverage means the field can be returned. It does not guarantee an EUID for every company or every request mode.
| Country | Availability |
| - | - |
| [Austria](https://www.topograph.co/countries/at) | Firmenbuch entities when the register supplies the EUID. This does not extend to sole traders or associations in other registers. |
| [Croatia](https://www.topograph.co/countries/hr) | When supplied by the court register. Verification can include values absent from the prefill record. |
| [Finland](https://www.topograph.co/countries/fi) | When the company record supplies the EUID. |
| [Germany](https://www.topograph.co/countries/de) | When a register-supplied EUID is available for the company. |
| [Hungary](https://www.topograph.co/countries/hu) | Court-registered companies whose record includes an EUID. Sole traders are excluded. |
| [Italy](https://www.topograph.co/countries/it) | Derived from the register number for supported domestic limited-company forms. See the rules below. |
| [Luxembourg](https://www.topograph.co/countries/lu) | When available in the company record or extract. |
| [Romania](https://www.topograph.co/countries/ro) | When available in the company record or extract. |
| [Spain](https://www.topograph.co/countries/es) | When published in the register data. |
| [Belgium](https://www.topograph.co/countries/be) | Domestic SA/NV, SRL/BV, SCA, SE and new-statute cooperative forms. Foreign entities and old-statute cooperatives are excluded. |
| [Czechia](https://www.topograph.co/countries/cz) | Domestic s.r.o. and a.s. companies. |
| [Denmark](https://www.topograph.co/countries/dk) | Domestic A/S and ApS companies. |
| [Estonia](https://www.topograph.co/countries/ee) | Domestic OÜ and AS companies. |
| [Ireland](https://www.topograph.co/countries/ie) | Supported domestic private and public companies limited by shares, including DACs limited by shares. Business names are excluded. |
| [Netherlands](https://www.topograph.co/countries/nl) | Supported domestic BV and NV forms. Uses the KVK number, not an establishment number or RSIN. |
| [Norway](https://www.topograph.co/countries/no) | Domestic AS and ASA companies. |
| [Poland](https://www.topograph.co/countries/pl) | Domestic sp. z o.o. and S.A. companies with a KRS number. |
| [Portugal](https://www.topograph.co/countries/pt) | Verification only, for domestic sociedades por quotas, including unipessoais, and sociedades anónimas when the source confirms the identity and legal form. Not returned in prefill mode. Availability depends on the source used. |
| [Sweden](https://www.topograph.co/countries/se) | Domestic aktiebolag (AB) with an organisation number. Personal identity numbers are excluded. |
| [Greece](https://www.topograph.co/countries/gr) | Domestic AE and IKE companies with confirmed GEMI identity and non-branch status. Uses the `ELGEMI` prefix and a 12-digit GEMI number. |
| [Latvia](https://www.topograph.co/countries/lv) | Domestic SIA and AS companies with confirmed register identity and legal form. |
| [Lithuania](https://www.topograph.co/countries/lt) | Domestic UAB and AB companies with confirmed legal-entity code and legal form. |
| [Bulgaria](https://www.topograph.co/countries/bg) | Supported domestic OOD, EOOD, AD and EAD companies registered in the Commercial Register. |
| [Slovakia](https://www.topograph.co/countries/sk) | Domestic s.r.o. and a.s. companies with confirmed Commercial Register identity. |
| [Slovenia](https://www.topograph.co/countries/si) | Domestic d.o.o. and d.d. companies with confirmed register identity. Branch units are excluded. |
| [Cyprus](https://www.topograph.co/countries/cy) | Domestic private and public limited companies. Verification supports eligible companies; older prefill records may omit EUID. |
| [Malta](https://www.topograph.co/countries/mt) | Domestic private and public limited liability companies in prefill and verification. |
| [Liechtenstein](https://www.topograph.co/countries/li) | Prefill only, for Aktiengesellschaft companies with confirmed register identity. Verification and other legal forms are not covered. |
France is not currently supported for this field. For countries not listed, Topograph does not currently declare EUID support. This does not establish whether the national register assigns EUIDs.
## Derived EUIDs
Belgium, Bulgaria, Cyprus, Czechia, Denmark, Estonia, Greece, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Malta, the Netherlands, Norway, Poland, Portugal, Slovakia, Slovenia and Sweden use country-specific derivation from the source company identity and a supported legal form. Unknown forms and foreign branches are outside this derivation's scope, even where the register may assign them an EUID.
The national number is preserved with the punctuation and leading zeros required by that country. Derivation does not perform a new BRIS lookup for each request. Older cached records may omit the field until refreshed.
## Italy: derived from the national register number
For supported Italian companies, the EUID is `ITRI.` followed by the 11-digit Registro Imprese number, which is the company's Codice Fiscale. Leading zeros are preserved.
Topograph derives the value only when the returned tax code is valid and the company's legal form is supported: SRL, single-member SRL, SRLS, SpA, single-member SpA, SApA, limited-liability or joint-stock consortium companies, and Italian European companies (SE).
The field is omitted for sole traders, partnerships, cooperatives, foreign-law entities and unknown legal forms. Some excluded entities, such as Italian branches of foreign companies, may have an EUID; their availability is outside this derivation's scope.
The tax code, VAT number and REA number are distinct identifiers. The derivation uses the Codice Fiscale returned for the company. It does not substitute a VAT number or the provincial REA number.
## What the value establishes
An EUID identifies a register entry. Its presence does not establish that the company is active, solvent, VAT-registered or eligible for a particular transaction. Check the company's status and the relevant verification data separately.
The EUID field is not a per-request BRIS validation result. The countries listed under Derived EUIDs use the rules described above; the remaining supported countries return values available from their company sources. The field does not include a BRIS consultation timestamp or validation certificate.
Store the full value as a string, including its prefix, punctuation and leading zeros. Formats vary by country, so the Italian derivation should not be applied to other countries.
## References
* [European Commission: business registration numbers and EUIDs](https://energy-efficient-products.ec.europa.eu/faqs-0/where-can-i-find-my-business-registration-number-and-id_en)
* [BRIS company search](https://webgate.ec.europa.eu/bris?lang=en)
* [Registro Imprese: Codice Fiscale, VAT and REA](https://www.registroimprese.it/codice-fiscale-p.iva-rea)
# Financial Data Extraction
Source: https://docs.topograph.co/essentials/financial-data-extraction
Documentation on the structured extraction of data from financial statements
## Overview
Topograph extracts financial data automatically from company annual statements. We analyze filed statements (PDF and structured XBRL or inline XBRL filings) and extract key financial metrics into a structured, machine-readable format.
## How It Works
When a financial statement document is processed:
1. **Document Classification** - The AI first determines if the document is a financial statement
2. **Data Extraction** - If identified as a financial statement, key metrics are extracted
3. **Structured Output** - Data is returned in the `extractedFinancialData` field on each financial statement
Non-financial documents will not have the `extractedFinancialData` field populated.
## Data Model
The structure for extracted data covers all major components of financial statements as presented below.
### Top-Level Structure
```typescript theme={null}
{
extractedFinancialData: {
// Metadata
fiscalYear: FiscalYear;
approvalDate: string | null;
currency: string | null;
accountingStandard: AccountingStandard;
statementType: StatementType;
// Financial sections
incomeStatement: IncomeStatement;
balanceSheet: BalanceSheet;
}
}
```
### Metadata Fields
#### Fiscal Year
```typescript theme={null}
fiscalYear: {
startDate: string; // Format: "YYYY-MM-DD"
endDate: string; // Format: "YYYY-MM-DD"
}
```
#### Accounting Standard
* `"IFRS"` - International Financial Reporting Standards
* `"French GAAP"` - French Generally Accepted Accounting Principles
* `"US GAAP"` - United States GAAP
* `"Swiss GAAP"` - Swiss GAAP
* `"Lux GAAP"` - Luxembourg GAAP
* `"Other"` - Other accounting standards
#### Statement Type
* `"consolidated"` - Group/consolidated financial statements
* `"simplified"` - Individual/standalone statements
### Income Statement
```typescript theme={null}
incomeStatement: {
revenue: {
amount: number | null; // Current period
previousAmount: number | null; // Prior period
localName: string; // Original term from document
}
depreciationAndAmortization: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
operatingIncome: {
amount: number | null;
previousAmount: number | null;
localName: string;
standardDefinition: string | null; // How it's calculated
notes: string | null; // Additional context
}
netIncome: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
}
```
### Balance Sheet
The balance sheet is organized into two main sections.
#### Assets
```typescript theme={null}
assets: {
fixedAssets: {
total: {
amount: number | null;
previousAmount: number | null;
}
components: {
tangible: {
// Property, plant, equipment
amount: number | null;
previousAmount: number | null;
localName: string;
}
intangible: {
// Goodwill, patents, software
amount: number | null;
previousAmount: number | null;
localName: string;
}
financialAssets: {
// Long-term investments
amount: number | null;
previousAmount: number | null;
localName: string;
}
}
}
currentAssets: {
total: {
amount: number | null;
previousAmount: number | null;
}
components: {
cashAndEquivalents: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
tradeReceivables: {
// Accounts receivable
amount: number | null;
previousAmount: number | null;
localName: string;
}
inventory: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
otherCurrentAssets: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
}
}
}
```
#### Equity and Liabilities
```typescript theme={null}
equityAndLiabilities: {
equity: {
total: {
amount: number | null;
previousAmount: number | null;
}
components: {
shareCapital: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
retainedEarnings: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
otherReserves: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
}
}
liabilities: {
nonCurrent: {
// Long-term (> 1 year)
total: {
amount: number | null;
previousAmount: number | null;
}
components: {
financialDebt: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
otherNonCurrentLiabilities: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
}
}
current: {
// Short-term (< 1 year)
total: {
amount: number | null;
previousAmount: number | null;
}
components: {
tradePayables: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
currentFinancialDebt: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
otherCurrentLiabilities: {
amount: number | null;
previousAmount: number | null;
localName: string;
}
}
}
}
}
```
## AI Financial Analysis
In addition to extracting raw financial data, Topograph provides AI-powered analysis that includes insights, ratios, trends, and risk assessments.
### Analysis Structure
```typescript theme={null}
analysis: {
// Executive summary (2-3 sentences)
summary: string;
// Concise narrative analysis covering key points
narrativeAnalysis: string;
// Overall financial health score (1-10)
healthScore: number;
// Risk assessment
overallRisk: "low" | "medium" | "high" | "critical";
// Key financial ratios
ratios: {
currentRatio: number | null; // Current Assets / Current Liabilities
quickRatio: number | null; // (Current Assets - Inventory) / Current Liabilities
debtToEquity: number | null; // Total Liabilities / Total Equity
netProfitMargin: number | null; // Net Income / Revenue (%)
returnOnEquity: number | null; // Net Income / Total Equity (%)
revenueGrowth: number | null; // YoY Revenue Change (%)
}
// Year-over-year trend directions
trends: {
revenueDirection: "increasing" | "stable" | "decreasing" | "unknown";
profitabilityDirection: "improving" | "stable" | "declining" | "unknown";
debtDirection: "increasing" | "stable" | "decreasing" | "unknown";
}
// Specific insights with risk levels
insights: Array<{
category: "liquidity" | "profitability" | "solvency" | "efficiency" | "growth" | "risk";
title: string;
description: string;
riskLevel: "low" | "medium" | "high" | "critical";
metricValue?: string | null;
recommendation?: string | null;
}>
// Key strengths identified
strengths: string[];
// Areas of concern
concerns: string[];
}
```
### Ratio Explanations
| Ratio | Formula | Good | Watch | Risk |
| - | - | - | - | - |
| Current Ratio | Current Assets / Current Liabilities | > 1.5 | 1.0 - 1.5 | \< 1.0 |
| Quick Ratio | (Current Assets - Inventory) / Current Liabilities | > 1.0 | 0.5 - 1.0 | \< 0.5 |
| Debt to Equity | Total Liabilities / Total Equity | \< 1.0 | 1.0 - 2.0 | > 2.0 |
| Net Profit Margin | Net Income / Revenue | > 10% | 5% - 10% | \< 5% |
| Return on Equity | Net Income / Total Equity | > 15% | 10% - 15% | \< 10% |
### Health Score
The health score ranges from 1 to 10:
* **8-10**: Excellent financial health
* **6-7**: Good, with some areas to monitor
* **4-5**: Fair, requires attention
* **2-3**: Weak financial position
* **1**: Critical condition
## Important Notes
### Data Quality
* **Null Values** - Fields return `null` when data is missing, unclear, or not applicable
* **Numeric Values** - All amounts are numeric values without currency symbols or thousand separators
* **Negative Values** - Losses and deficits preserve the negative sign
* **Local Terms** - The `localName` field presents the exact wording used in the source document
### Multi-Language Support
The extraction works across multiple languages and accounting frameworks:
* Recognizes financial terms in various languages
* Maps local terminology to standardized fields
* Preserves original terms in `localName` fields
### Current Limits
* Processes financial statements filed as PDF and as structured filings (XBRL / inline XBRL)
* Extraction accuracy depends on document quality and structure
* Complex or non-standard formats may have reduced accuracy
* Currently focuses on core financial metrics
## Example Usage
When retrieving documents with financial statements:
```bash theme={null}
POST https://api.topograph.co/v2/company
{
"id": "your-company-id",
"countryCode": "DE",
"dataPoints": [],
"documents": ["financial_statement_id"]
}
```
The response will include the extracted data and AI analysis:
```jsonc theme={null}
{
"documents": {
"financialStatements": [
{
"id": "financial_statement_id",
"extractedFinancialData": {
"fiscalYear": {
"startDate": "2023-01-01",
"endDate": "2023-12-31"
},
"currency": "EUR",
"accountingStandard": "IFRS",
"statementType": "consolidated",
"incomeStatement": { /* ... */ },
"balanceSheet": { /* ... */ },
"analysis": {
"summary": "Company shows strong profitability with 15% revenue growth...",
"healthScore": 7.5,
"overallRisk": "low",
"ratios": {
"currentRatio": 1.52,
"quickRatio": 1.17,
"debtToEquity": 1.84,
"netProfitMargin": 3.02,
"returnOnEquity": 11.87,
"revenueGrowth": 3.16
},
"trends": {
"revenueDirection": "stable",
"profitabilityDirection": "improving",
"debtDirection": "decreasing"
},
"insights": [
{
"category": "profitability",
"title": "Strong Profit Growth",
"description": "Net income increased by 302% year-over-year...",
"riskLevel": "low",
"metricValue": "+302% YoY"
}
],
"strengths": [
"Exceptional profitability growth",
"Healthy liquidity position"
],
"concerns": [
"Trade receivables growing faster than revenue"
]
}
}
}
]
}
}
```
## Feedback
This is a beta feature and we're actively collecting feedback to improve extraction accuracy and expand coverage.
Please share your experiences and suggestions on support channels or to your account manager.
# Finland
Source: https://docs.topograph.co/essentials/finland
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Finland reference is on the [Finland country page](https://www.topograph.co/countries/fi).
## Start here
This guide contains public integration notes for Finland. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
Finland uses three official data sources: the PRH Trade Register (with the YTJ business information system), the PRH Beneficial Owner Register, and the EU VIES system for VAT verification. Company profile data and legal representatives are **AI-parsed** from the official Trade Register Extract (kaupparekisteriote) PDF document, while activity codes are fetched from the YTJ open data API.
* **PRH VIRRE (Trade Register).** The Finnish Trade Register, maintained by PRH since 1896, is the **primary source** for Finnish entity data. PRH operates the VIRRE information service for fetching Trade Register Extracts and Articles of Association, and for searching companies by name. The Trade Register Extract PDF is AI-parsed to produce structured company data including company name, legal form, status, registered address, share capital, activity description, and legal representatives.
* **PRH ESR (Beneficial Owner Register).** PRH's separate Beneficial Owner Register provides Ultimate Beneficial Owner (UBO) data. Companies are required to register their beneficial owners with PRH. The ESR API returns structured ownership and voting rights data for natural persons who hold significant control over a company.
* **YTJ (Yritys- ja yhteisötietojärjestelmä / Finnish Business Information System).** The YTJ open data API provides structured company data including official TOL (Toimialaluokitus) activity classification codes assigned by Statistics Finland. It is used to search by id and for fetching TOL codes, from which NACE and ISIC codes are derived deterministically.
Finland's data extraction is **document-based**: the system fetches the
official Trade Register Extract PDF from PRH's VIRRE service and uses AI to
parse structured company data from it. This means company profile and legal
representatives are extracted from the same authoritative document. Legal
form, status, activity descriptions, and role classifications are all
AI-parsed from the extract. Activity codes (TOL) are sourced separately from
the YTJ API and mapped deterministically to NACE and ISIC. UBO data comes from
the separate PRH ESR register.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | PRH Trade Register | 7 digits + hyphen + check digit, leading zeros significant | `0112038-9` | Business ID (Y-tunnus), validated with check digit algorithm. `/v2/company` also accepts the 8 digits without the hyphen. |
**Business ID (Y-tunnus) Format:** `0112038-9` = 7 digits + hyphen + 1 check
digit. The check digit is calculated using a modulo-11 algorithm. All Finnish
entities registered with PRH receive a Y-tunnus, including limited companies,
partnerships, sole traders, cooperatives, foundations, and associations.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `businessId` | 7 digits + hyphen + check digit | `0112038-9` | All companies |
| `VAT` | 8 digits (FI prefix stripped) | `01120389` | VAT-registered companies |
| `euid` | Register-issued European identifier | `FIFPRO.0112038-9` | When available |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Business ID (`businessId`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Business ID (Y-tunnus) | 7 digits + hyphen + check digit | `1505551-4` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT number | `FI` + 8 digits | `FI15055514` | Exact | Resolves to the company with that Business ID |
| By Name | Text string (2-200 chars) | `"Alko"` | Fuzzy | Multiple results |
**Search Performance:** Use Business ID search for best performance and exact
matching. Name searches may return multiple results and support Finnish,
Swedish, and English company names.
Name and Business ID searches cover the full register, including private
traders.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Business ID searches are filtered. Name searches are filtered for companies whose status is known; a company found only by the live name lookup is returned whatever its status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **AI-parsed data** | All company data (profile, status, legal form, legal representatives, activity description) is AI-extracted from the Trade Register Extract PDF. Field availability depends on what is present in the document. |
| **No shareholders** | PRH does not provide shareholder information through the Trade Register. Share ownership is privately held by each company. Only total share capital and share classes are registered with PRH. |
| **UBO availability varies by entity type** | UBO data comes from PRH's ESR register, which is separate from the Trade Register. Only entities required to register beneficial owners will have data. Public limited companies (Oyj), state-owned companies, associations (ry), and foundations (sr) typically declare no beneficial owners or are not in the ESR registry. Sole entrepreneurs (Tmi) are not required to register UBOs. Private limited companies (Oy) are the most likely to have UBO data. |
| **No employee count** | PRH does not provide employee count data. |
| **Processing time** | Company profile and legal representatives are extracted from the Trade Register Extract. See the Speed section of the [pricing page](https://topograph.co/pricing/fi) for current latency. |
| **Trade Register Extract is dual-purpose** | The Trade Register Extract is both the source of structured data (AI-parsed) and a downloadable document. Company profile and legal representatives come from the same document. |
| **Bilingual data** | Finland is bilingual (Finnish and Swedish). Company names, activity descriptions, and legal forms may appear in either language in the Trade Register Extract. Commercial names may include Finnish, Swedish, and English variants. |
| **Articles of Association availability** | Articles of Association are listed for every company registered in the Trade Register, including closed ones, but actual content depends on the company having filed them with PRH. |
| **Pending registrations** | A company whose Trade Register registration is still pending has a Business ID and is searchable, but lists no documents and returns no legal representatives. Its `company` profile comes back with `active: false` and status `INACTIVE_NOT_CLOSED`. |
| **Legal form AI-enriched** | The local Finnish legal form name and its English translation are the labels PRH publishes. Only the standardized category and the ISO 20275 code are AI-enriched. |
| **Activity codes deterministic** | TOL codes are fetched from the YTJ API. NACE and ISIC codes are derived deterministically (TOL first 4 digits = NACE, then formal ISIC mapping). All activity codes have `isAIInferred: false`. Falls back to AI inference if the YTJ API does not return a TOL code. |
| **VAT number format** | The VAT number in the identifiers uses the format without country prefix (e.g., `15055514`), while the `taxId` object includes verification against VIES. |
| **Incorporation date** | Some companies return both `registrationDate` (Trade Register entry) and `incorporationDate` (company formation date), which may differ. |
## Mappings
### Company Status
Company status is **AI-parsed** from the Trade Register Extract document. The AI extracts the current registration status and maps it to standardized status values.
| Local Status | English Translation | Standardized Status | Notes |
| - | - | - | - |
| Rekisterissa | Registered | Active | Company is currently registered and operating |
| Active | Active | Active | Alternative status text in English-language extracts |
| Lakkautettu | Dissolved | Closed | Company has been dissolved |
| Selvitystilassa | In Liquidation | Under Insolvency Proceeding | Liquidation proceedings in progress |
| Konkurssissa | In Bankruptcy | Under Insolvency Proceeding | Bankruptcy proceedings in progress |
| Rekisterista poistettu | Removed from Register | Closed | Company has been removed from the Trade Register |
| Rekisteröimätön | Unregistered | Inactive Not Closed | Business ID issued, registration still pending |
Because status extraction is AI-parsed from the Trade Register Extract
document, the exact local status text may vary. The AI maps Finnish or Swedish
status descriptions to standardized values. The `active` boolean is derived
from the `statusDetails.status` field.
### Legal Forms
Finland uses a variety of legal forms defined in the Trade Register. The local name and English translation are the labels PRH publishes. The standardized category and ISO 20275 code are **AI-enriched**.
#### Key Business Forms
| Finnish Name | Abbreviation | English Translation | Standardized | Notes |
| - | - | - | - | - |
| Osakeyhtiö | Oy | Limited company | Limited Liability Company | Most common Finnish company type |
| Julkinen osakeyhtiö | Oyj | Public Limited Company | Corporation | Listed or public company |
#### Partnerships
| Finnish Name | Abbreviation | English Translation | Standardized | Notes |
| - | - | - | - | - |
| Avoin yhtiö | Ay | General Partnership | Partnership | All partners jointly liable |
| Kommandiittiyhtiö | Ky | Limited Partnership | Partnership | At least one general and one limited partner |
#### Sole Proprietorships
| Finnish Name | Abbreviation | English Translation | Standardized | Notes |
| - | - | - | - | - |
| Yksityinen elinkeinonharjoittaja | Tmi | Sole Trader | Sole Proprietorship | Individual business operator |
#### Cooperatives
| Finnish Name | Abbreviation | English Translation | Standardized | Notes |
| - | - | - | - | - |
| Osuuskunta | Osk | Cooperative | Cooperative | Member-owned cooperative |
#### Non-Profits & Foundations
| Finnish Name | English Translation | Standardized | Notes |
| - | - | - | - |
| Yhdistys | Association | Nonprofit Organization | Registered association |
| Säätiö | Foundation | Nonprofit Organization | Registered foundation |
#### Branch Offices & European Forms
| Finnish Name | English Translation | Standardized | Notes |
| - | - | - | - |
| Sivuliike | Branch | Branch or Representative Office | Branch of a foreign company |
| Eurooppayhtiö (SE) | European Company (SE) | Corporation | Societas Europaea |
| Eurooppaosuuskunta (SCE) | European Cooperative (SCE) | Cooperative | Societas Cooperativa Europaea |
Because legal form standardization and ISO 20275 assignment are AI-enriched,
exact mappings may evolve. The local Finnish legal form name and its English
translation are always PRH's own published labels.
### Legal Representatives
Legal representatives are **AI-parsed** from the Trade Register Extract document. The AI extracts persons from sections such as "Hallitus" (Board), "Toimitusjohtaja" (CEO), and "Edustaminen" (Representation rules), and uses the recorded representation rules to identify legal representatives. Known Finnish and Swedish office titles have fixed English translations and standardized meanings; unfamiliar titles may require enrichment. Finland currently returns no other-key-person list.
| Finnish Role | English Translation | Standardized Role | Classification |
| - | - | - | - |
| Hallituksen puheenjohtaja / Puheenjohtaja | Chairman of the Board | Chairman of the Board | Legal Representative |
| Jäsen (under Hallitus) | Board Member | Board Member | Legal Representative |
| Toimitusjohtaja | Chief Executive Officer | Chief Executive Officer | Legal Representative |
| Varatoimitusjohtaja / Toimitusjohtajan sijainen | Deputy / Substitute CEO | Chief Executive Officer | Legal Representative when acting with recorded authority |
| Finnish Role | English Translation | Standardized Role | Classification |
| - | - | - | - |
| Nimenkirjoittaja / Nimenkirjoitusoikeus | Authorized Signatory | Authorized Signatory | Legal Representative |
| Prokuristi / Prokura | Procuration Holder | Authorized Signatory | Legal Representative |
| Finnish Role | English Translation | Notes |
| - | - | - |
| Tilintarkastaja | Auditor | Excluded from legal representative extraction |
| Varajäsen | Deputy Board Member | Excluded unless representation text explicitly grants rights |
A board's statutory power to represent the company is a power of the board as
a body. An individual board member or chair is included only when the extract
grants that person or role category individual or joint representation rights.
The CEO's statutory authority is limited to the CEO's duties. Procuration also
has a statutory scope. A title alone does not establish unrestricted sole
signing authority. Named signatories with joint rights are included, with the
recorded restrictions preserved.
#### Representation Mode
Legal representatives include a `representationMode` field extracted from the "Edustaminen" (Representation) section of the Trade Register Extract:
* **`{ mode: "sole" }`**: Can sign alone ("yksin")
* **`{ mode: "joint", minimumSignatories: 2 }`**: Must sign jointly with one other ("kaksi yhdessä" / "two jointly")
* **`{ mode: "joint", minimumSignatories: 3 }`**: Must sign jointly with two others ("kolme yhdessä" / "three jointly")
* **`null`**: No signing authority explicitly stated
The field is extracted via AI parsing from Finnish-language text in the Trade Register Extract PDF.
#### Enrichment from Trade Register Extract
The AI parser also extracts:
* **Start dates**: From person-level "Rekisteröity DD.MM.YYYY" dates or section-level registration dates
* **Nationality**: From "Voimassa olevat henkilötiedot" section (e.g., "Suomen kansalainen" = FI)
* **Residence**: City and country from personal details section
### Other Key Persons
Finland currently has no other-key-person output. Auditors ("Tilintarkastajat") are excluded from legal representatives. Board members and deputies without recorded representation powers are also excluded; a deputy with explicit representation rights may appear as a legal representative.
### Shareholders
The Finnish Trade Register (PRH) does **not** provide structured shareholder data. Individual shareholder information is not available through the PRH VIRRE API or the Trade Register Extract.
Shareholder details may appear within the **Articles of Association** document if the company's bylaws reference specific shareholders or share classes, but this is not extracted as structured data.
Finland's Trade Register does not maintain a shareholder register. Share
ownership information is held privately by each company. Only the total share
capital and share classes are registered with PRH.
### Activity Code Mapping
The official TOL (Toimialaluokitus) code is fetched from the YTJ open data API. NACE and ISIC codes are then derived **deterministically** -- no AI inference is involved when TOL is available.
```
TOL (from YTJ API) → NACE Rev. 2.1 (deterministic) → ISIC Rev. 5 (formal mapping)
```
The derivation is straightforward: TOL codes at 4 digits are identical to NACE Rev. 2 class codes (5-digit TOL codes are truncated to 4 digits, as the 5th digit is a Finnish sub-class). ISIC is then derived from NACE using the official UN correspondence table.
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **TOL** | YTJ API (official, assigned by Statistics Finland) | `47250` | No |
| **NACE** | Derived from TOL (first 4 digits → XX.YY) | `47.25` | No |
| **ISIC** | Derived from NACE (formal UN mapping) | `4722` | No |
**One code in, one code out.** You get one `NACE` and one `ISIC` code per declared TOL code. Where a TOL code has no single equivalent in the target revision, the shared parent class is returned rather than every candidate — see [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
**Main activity.** YTJ publishes only the company's main line of business (päätoimiala), so the TOL code carries `isMainActivity: true`, and the NACE and ISIC codes derived from it inherit the flag.
**Deterministic mapping:** When the YTJ API returns a TOL code, all activity
codes (TOL, NACE, ISIC) have `isAIInferred: false`. If the YTJ API does not
return a TOL code for a given company, the system falls back to AI inference
from the Finnish activity description text (in which case `isAIInferred` will
be `true`).
## Supported Entity Families
| Entity Family | Supported | Notes |
| - | - | - |
| Companies | ✅ | Oy, Oyj, Ay, Ky, Osk, SE, SCE, all commercial entity forms |
| Sole traders / entrepreneurs | ✅ | Tmi (Yksityinen elinkeinonharjoittaja) |
| Associations / organisations | ✅ | Yhdistys (associations), Säätiö (foundations) |
| Closed / dissolved entities | ✅ | Lakkautettu (dissolved), Rekisterista poistettu (removed from register) |
## Data Availability
### Data Availability Matrix
| Data Type | All Company Types | Notes |
| - | - | - |
| Company Profile | ✅ Async | AI-parsed from Trade Register Extract |
| Prefill Profile | ✅ Async | Company profile + legal representatives in a single request |
| Legal Representatives | ✅ Async | AI-parsed from Trade Register Extract |
| Shareholders | ❌ | Not available from PRH |
| Ultimate Beneficial Owners | ⚠️ | From PRH ESR register. Available for private limited companies (Oy). Not available for Oyj, state-owned, associations, foundations, or sole entrepreneurs. Verification mode only; not available in prefill mode. |
| Establishments | ❌ | Not available from PRH |
| Activity Codes | ✅ | TOL from YTJ, NACE + ISIC derived deterministically |
| Employee Count | ❌ | Not available from PRH |
| Phone / Website | ❌ | Not available from PRH |
| Commercial Names | ✅ | Finnish, Swedish, and English name variants from PRH |
| Share Capital | ✅ | Amount and currency from Trade Register Extract |
| VAT Verification | ✅ | Verified against EU VIES system |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing (see the pricing page for current latency)
**Why UBOs are not always available:** Finnish law requires a natural person
to hold >25% of shares or voting rights (or exercise other significant
control) to be registered as a UBO. Public companies (Oyj) have dispersed
ownership below this threshold. State-owned companies have no natural person
owner. Associations, foundations, and cooperatives have no "owners" in the
legal sense. Sole entrepreneurs (Tmi) are not separate legal entities from
their owner, so UBO registration does not apply.
### Documents by Company Type
All Finnish company types registered in the Trade Register have the same documents available:
| Document Type | API Category | Format | Notes |
| - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | Official kaupparekisteriote from PRH. Comes with the company data block. Also used as source for AI-parsed company data. |
| **Articles of Association** | `articlesOfAssociation` | PDF | Company bylaws (yhtiöjärjestys), share classes, governance rules. Ordered separately; see the [pricing page](https://topograph.co/pricing/fi). |
**Trade Register Extract Language:** The Trade Register Extract is provided in
Finnish (or Swedish for Swedish-registered companies). There is no English
translation available from PRH. The AI parser handles Finnish/Swedish text
extraction.
Both documents are listed for every company registered in the Trade Register,
including closed ones. Actual content depends on PRH having the document on
file. A company whose registration is still pending lists no documents.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "FI", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "1234567-8",
"countryCode": "FI",
"identifiers": { "businessId": "1234567-8", "VAT": "12345678" },
"taxId": { "type": "eu_vat", "value": "12345678", "country": "FI", "verification": { "status": "verified", "verifiedName": "Esimerkki Teknologia Oy" } },
"legalName": "Esimerkki Teknologia Oy",
"commercialNames": ["Esimerkki Teknologia Oy", "Example Technology Ltd"],
"registrationDate": "2019-06-15",
"activityDescription": "Ohjelmistojen suunnittelu ja valmistus",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Osakeyhtiö", "englishTranslation": "Limited company", "standardized": "Limited Liability Company", "iso20275Code": "DKUW" },
"capital": { "amount": 2500, "currency": "EUR", "formatted": "2 500.00 EUR" },
"activities": {
"TOL": [{ "code": "62010", "description": "Computer programming activities", "isAIInferred": false }],
"NACE": [{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Mannerheimintie 10", "city": "Helsinki", "postalCode": "00100", "countryCode": "FI" }
},
"legalRepresentatives": [
{ "type": "individual", "entityId": "person_001", "startDate": "2023-04-04", "role": { "localName": "Puheenjohtaja", "englishTranslation": "Chairman of the Board", "standardized": "Chairman of the Board" }, "representationMode": { "mode": "joint", "minimumSignatories": 2 }, "individual": { "name": { "fullName": "Mikko VIRTANEN", "firstName": "Mikko", "lastName": "VIRTANEN" }, "birthDate": { "day": 15, "month": 3, "year": 1980 }, "nationality": "FI", "residenceAddress": { "city": "Helsinki", "countryCode": "FI" } } },
{ "type": "individual", "entityId": "person_002", "startDate": "2023-04-04", "role": { "localName": "Jäsen", "englishTranslation": "Board Member", "standardized": "Board Member" }, "representationMode": { "mode": "joint", "minimumSignatories": 2 }, "individual": { "name": { "fullName": "Anna KORHONEN", "firstName": "Anna", "lastName": "KORHONEN" }, "birthDate": { "day": 22, "month": 7, "year": 1985 }, "nationality": "FI", "residenceAddress": { "city": "Espoo", "countryCode": "FI" } } },
{ "type": "individual", "entityId": "person_003", "startDate": "2019-06-15", "role": { "localName": "Toimitusjohtaja", "englishTranslation": "Chief Executive Officer", "standardized": "Chief Executive Officer" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Pekka MÄKELÄ", "firstName": "Pekka", "lastName": "MÄKELÄ" }, "birthDate": { "day": 1, "month": 11, "year": 1975 }, "nationality": "FI", "residenceAddress": { "city": "Helsinki", "countryCode": "FI" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "9876543-1",
"countryCode": "FI",
"identifiers": { "businessId": "9876543-1", "VAT": "98765431" },
"taxId": { "type": "eu_vat", "value": "98765431", "country": "FI", "verification": { "status": "verified", "verifiedName": "Suuri Teollisuus Oyj" } },
"legalName": "Suuri Teollisuus Oyj",
"commercialNames": ["Suuri Teollisuus Oyj", "Grand Industry Plc"],
"registrationDate": "1990-03-20",
"incorporationDate": "1985-11-01",
"activityDescription": "Teollisuuskoneiden valmistus ja myynti",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Julkinen osakeyhtiö", "englishTranslation": "Public Limited Company", "standardized": "Corporation", "iso20275Code": "K6VE" },
"capital": { "amount": 500000, "currency": "EUR", "formatted": "500 000.00 EUR" },
"activities": {
"TOL": [{ "code": "28990", "description": "Manufacture of other special-purpose machinery n.e.c.", "isAIInferred": false }],
"NACE": [{ "code": "28.99", "description": "Manufacture of other special-purpose machinery n.e.c.", "isAIInferred": false }],
"ISIC": [{ "code": "2899", "description": "Manufacture of other special-purpose machinery", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Teollisuuskatu 5", "city": "Espoo", "postalCode": "02150", "countryCode": "FI" }
},
"legalRepresentatives": [
{ "type": "individual", "entityId": "person_001", "startDate": "2022-05-10", "role": { "localName": "Puheenjohtaja", "englishTranslation": "Chairman of the Board", "standardized": "Chairman of the Board" }, "representationMode": { "mode": "joint", "minimumSignatories": 2 }, "individual": { "name": { "fullName": "Jukka NIEMI", "firstName": "Jukka", "lastName": "NIEMI" }, "birthDate": { "day": 8, "month": 4, "year": 1968 }, "nationality": "FI", "residenceAddress": { "city": "Espoo", "countryCode": "FI" } } },
{ "type": "individual", "entityId": "person_002", "startDate": "2022-05-10", "role": { "localName": "Jäsen", "englishTranslation": "Board Member", "standardized": "Board Member" }, "representationMode": { "mode": "joint", "minimumSignatories": 2 }, "individual": { "name": { "fullName": "Liisa HÄKKINEN", "firstName": "Liisa", "lastName": "HÄKKINEN" }, "birthDate": { "day": 30, "month": 9, "year": 1972 }, "nationality": "FI", "residenceAddress": { "city": "Helsinki", "countryCode": "FI" } } },
{ "type": "individual", "entityId": "person_003", "startDate": "2020-01-15", "role": { "localName": "Toimitusjohtaja", "englishTranslation": "Chief Executive Officer", "standardized": "Chief Executive Officer" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Markus LAINE", "firstName": "Markus", "lastName": "LAINE" }, "birthDate": { "day": 17, "month": 6, "year": 1970 }, "nationality": "FI", "residenceAddress": { "city": "Helsinki", "countryCode": "FI" } } }
]
}
```
**Note:** Public limited companies (Oyj) follow the same data structure as private limited companies (Oy). The `incorporationDate` may differ from `registrationDate` for older companies.
```json theme={null}
{
"company": {
"id": "5551234-7",
"countryCode": "FI",
"identifiers": { "businessId": "5551234-7", "VAT": "55512347" },
"legalName": "Kauppa ja Palvelut Oy",
"commercialNames": ["Kauppa ja Palvelut Oy"],
"registrationDate": "2005-02-14",
"activityDescription": "Tukkukauppa ja varastointi",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Osakeyhtiö", "englishTranslation": "Limited company", "standardized": "Limited Liability Company", "iso20275Code": "DKUW" },
"capital": { "amount": 50000, "currency": "EUR", "formatted": "50 000.00 EUR" },
"activities": {
"TOL": [{ "code": "46900", "description": "Non-specialised wholesale trade", "isAIInferred": false }],
"NACE": [{ "code": "46.90", "description": "Non-specialised wholesale trade", "isAIInferred": false }],
"ISIC": [{ "code": "4690", "description": "Non-specialized wholesale trade", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Satamakatu 12", "city": "Turku", "postalCode": "20100", "countryCode": "FI" }
},
"legalRepresentatives": [
{ "type": "individual", "entityId": "person_001", "startDate": "2023-06-01", "role": { "localName": "Puheenjohtaja", "englishTranslation": "Chairman of the Board", "standardized": "Chairman of the Board" }, "representationMode": { "mode": "joint", "minimumSignatories": 2 }, "individual": { "name": { "fullName": "Heikki SALMINEN", "firstName": "Heikki", "lastName": "SALMINEN" }, "nationality": "FI" } },
{ "type": "individual", "entityId": "person_002", "startDate": "2023-06-01", "role": { "localName": "Toimitusjohtaja", "englishTranslation": "Chief Executive Officer", "standardized": "Chief Executive Officer" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Sari NIEMINEN", "firstName": "Sari", "lastName": "NIEMINEN" }, "nationality": "FI" } },
{ "type": "individual", "entityId": "person_003", "startDate": "2023-06-01", "role": { "localName": "Prokuristi", "englishTranslation": "Authorized Signatory", "standardized": "Authorized Signatory" }, "representationMode": { "mode": "joint", "minimumSignatories": 2 }, "individual": { "name": { "fullName": "Timo LAHTINEN", "firstName": "Timo", "lastName": "LAHTINEN" }, "nationality": "FI" } }
]
}
```
**Note:** Procurists (prokura holders) are included as legal representatives with the standardized role "Authorized Signatory". Recorded signing rules appear in `representationMode`; its `particularity` preserves conditions such as required co-signer classes and limits on scope.
Query with `"dataPoints": ["ultimateBeneficialOwners"]` for Holvi Retrieval Services Oy (`2193756-4`):
```json theme={null}
{
"request": {
"companyId": "2193756-4",
"countryCode": "FI",
"requestId": "ca738be0-d117-4f41-8076-61f51e2a6b52",
"dataStatus": {
"dataPoints": {
"ultimateBeneficialOwners": { "status": "succeeded" }
}
}
},
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"nationality": "FI",
"name": {
"fullName": "Tuomas Matti Toivonen",
"firstName": "Tuomas Matti",
"lastName": "Toivonen"
},
"birthDate": { "day": 25, "month": 2, "year": 1976 },
"residenceAddress": { "city": "Kauniainen", "countryCode": "FI" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"description": "Ownership: 100%. Voting rights: 100%. Role: ES",
"details": [
{ "type": "shares", "percentageValue": 100, "nature": "direct" },
{
"type": "voting-rights",
"percentageValue": 100,
"nature": "direct"
}
]
}
}
]
}
```
**Note:** UBO data comes from PRH's ESR register (separate from Trade Register). Control types include `ownership-of-shares`, `voting-rights`, and `significant-influence-or-control`. The `residenceAddress.city` is resolved from the Finnish municipality code (kuntanumero). Companies that declare no beneficial owners return an empty array. Public companies (Oyj), state-owned entities, associations, and foundations typically have no UBO data.
Query with `"dataPoints": ["availableDocuments"]`:
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc-uuid-001",
"name": "Trade Register Extract",
"format": "pdf",
"description": "Trade register extract from the Finnish Business Registry (PRH)"
},
"articlesOfAssociation": [
{
"id": "doc-uuid-002",
"name": "Article of Association",
"format": "pdf",
"description": "Article of Association from the Finnish Business Registry (PRH)"
}
]
}
}
```
**Note:** Both documents are listed for every company registered in the Trade Register, including closed ones. A company whose registration is still pending lists no documents. The Trade Register Extract is the source document for AI-parsed company data.
# France
Source: https://docs.topograph.co/essentials/france
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date France reference is on the [France country page](https://www.topograph.co/countries/fr).
## Start here
This guide contains public integration notes for France. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Prefill mode (fast retrieval)](#prefill-mode-fast-retrieval)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
France uses multiple official registries. For a given entity, **company data comes from a single primary source**, chosen by a deterministic priority chain that returns data from the first matching source. A few enrichments are layered on top: the employee count from SIRENE, collective proceedings from BODACC on the company status, and the VIES VAT check in verification mode.
### Commercial companies & sole entrepreneurs
* **RNE (Registre National des Entreprises)** -- Operated by the INPI since January 1, 2023, the RNE replaced and unified three former registries: the RNCS (Registre National du Commerce et des Societes), the Repertoire des Metiers, and the Registre des Actifs Agricoles. This is our **primary source for the vast majority of French entities**. When a company is found in the RNE, all structured attributes come from the RNE: company name, legal form, status, incorporation date, registered address, share capital, activity codes, legal representatives, UBOs, and establishments.
* **SIRENE (INSEE)** -- The SIRENE repertoire, managed by the INSEE since 1973, covers \~25 million enterprises. Used in two ways: **(1)** as a **supplement to RNE** for employee count range (expressed in tranches, e.g. "50 to 99 employees" -- note: figures can be 2-3 years old per INSEE methodology); **(2)** as a **standalone fallback** for entities that exist in INSEE but are not yet in the RNE, providing a limited dataset only (company name, legal form, activity code, status, employee count, and the entrepreneur as legal representative for sole entrepreneurs -- no other legal representatives, and no UBOs).
* **BODACC (Bulletin Officiel des Annonces Civiles et Commerciales)** -- Operated by the DILA. Used in two ways: **(1)** its collective-proceeding announcements (redressement, liquidation judiciaire, sauvegarde) update the status of companies found in the RNE or SIRENE; **(2)** as an **exceptional last resort** when an entity appears in none of the above registries (not in RNE, not in SIRENE, not in RNA). This represents a negligible fraction of queries. When used as the source, company data and current office holders are extracted from legal announcement text, with representative and other key person capacities returned separately.
* **Infogreffe** -- Used only for **documents**: the K-Bis (certified trade register extract) and the trade register history (Historique des modifications). It is **not** a structured data source for company attributes.
### Non-profits
* **RNA Waldec** -- Non-profits (associations declarees) that have been created or have declared a modification since 2009. Our primary source for non-profits. Enriched with SIRENE data when a SIREN is available.
* **RNA Import** -- Historical non-profits created since 1901 that have not declared any change since 2009. Fallback when not found in RNA Waldec.
* **RNA Alsace-Moselle** -- Non-profits (associations de droit local) in departments 57 (Moselle), 67 (Bas-Rhin), and 68 (Haut-Rhin), which operate under local law and are excluded from the national RNA.
**RNA data is periodically synchronized** (monthly from data.gouv.fr) because no live API exists for the RNA registries. This is the only available access method provided by the French government for non-profit data.
* **RNA**: All non-profits are automatically registered when declared at the prefecture (RNA number: W + 9 digits)
* **SIRENE**: Non-profits must register if they seek public subsidies, employ staff, or are subject to VAT/corporate tax (SIREN: 9 digits)
* **RNE**: Non-profits with SIRENE registration and business-like activities may also appear in INPI's unified register, which provides comprehensive data including UBOs
**Key Takeaway:** All non-profits are in RNA, but only those with economic activities may also appear in RNE. Prefer the RNA number as the API identifier.
### Data Source Priority & Routing
For a given entity, **data comes from a single primary source** -- the system does not merge attributes from multiple registries (all-or-nothing model). The exceptions are the **employee count**, always sourced from SIRENE; the **company status**, which BODACC collective-proceeding announcements can update; and the **VIES VAT check**, added in verification mode.
**Source Priority for Commercial Companies & Sole Entrepreneurs (SIREN lookup):**
1. **RNE (INPI)** -- Query to the INPI registry (with automatic fallback if the live API is temporarily unavailable)
2. **SIRENE-only** -- For entities in INSEE but not in RNE (limited dataset: name, legal form, activity, status, employee count)
3. **RNA tables** -- Waldec, Import, and Alsace-Moselle (first match wins)
4. **BODACC** -- Last resort, for entities with legal announcements but no registry data (data extracted from announcement text)
**Source Priority for Non-profits (RNA lookup):**
1. Check if the RNA number has a SIREN in SIRENE. If yes, check if that SIREN exists in RNE. If yes, use RNE data
2. **RNA Waldec** -- Non-profits created or modified since 2009
3. **RNA Import** -- Historical non-profits (no changes declared since 2009)
4. **RNA Alsace-Moselle** -- Local law non-profits (departments 57, 67, 68)
**Recommended:** query non-profits by their RNA number. It reaches the RNA records and the JOAF publications. A SIREN also resolves, but returns the trade register or SIRENE view of the entity.
### Verification Status and Source Labels
In verification mode, current RNE data is reported as `live_from_registry` with `register: "inpi"`, including when its freshness has been confirmed without a new register lookup. This applies to RNE fields in company details, legal representatives, other key persons, and establishments.
Check `request.dataStatus.dataPoints` for each requested datapoint's `status` and `authoritative` value. Check `dataSources` for the source of individual fields. These describe different aspects of the response: an authoritative result can still contain fields from other sources, such as INSEE employee counts or BODACC proceedings.
If RNE freshness cannot be confirmed and a previous record is returned as a fallback, its fields retain `cached_from_registry`. Prefill results can also carry this label. Selecting verification mode does not make every fallback or supplementary field live.
### Attribute-Level Source Mapping
When data comes from the RNE (the vast majority of commercial companies and sole entrepreneurs), the following table shows the source for each attribute:
| Attribute | Source | Notes |
| - | - | - |
| Company name, legal form, status | **RNE** | From formality data |
| Registered address | **RNE** | Registered address from the RNE filing |
| Share capital | **RNE** | Amount, currency, variable/fixed |
| Activity codes (APE/NAF) | **RNE** | Supplemented by SIRENE for some entities |
| Business purpose description | **RNE** | Corporate purpose from the RNE filing |
| Legal representatives | **RNE** | From formality *pouvoirs* data |
| Shareholders | **Filed documents at INPI** | AI-extracted from the documents the company filed (statutes, capital changes, annual filings) |
| UBOs | **RNE** | From *beneficiaires effectifs* with ownership modalities |
| Establishments | **RNE** | Main + secondary, each with its own activity codes (APE/NAF, NACE, ISIC) when the register records them |
| **Employee count range** | **SIRENE (INSEE)** | Always from SIRENE, even when RNE is primary -- expressed in tranches, can be 2-3 years old |
| **Former legal names** | **SIRENE (INSEE)** | `legacyLegalNames`, most recent first. Legal names a company held before its current one, from INSEE's name history. Not returned for sole entrepreneurs or associations. Changes to this list do not trigger monitoring notifications; a rename is reported through `legalName` |
When the primary source is SIRENE-only or BODACC, the available attributes are significantly more limited (see Data Availability Matrix below).
### UBO Data Handling
**Live UBO Fetching:** When UBO data is not yet available for a company, the system automatically fetches it live from the INPI registry. This ensures UBO data is always current, even for newly registered companies.
**Data Lineage (Upcoming):** We are planning to add explicit source traceability to our data model, so that each attribute group in the API response will carry metadata indicating the source registry name and retrieval timestamp.
#### Enriched UBO data with customer INPI credentials
By default, Topograph queries INPI with a service account that returns UBO
data with personal fields (date of birth, full address, nationality, place
of birth) redacted per RGPD. If your organisation has one or more INPI
accounts that carry the `ROLE_RBE_BENEFICIAL_OWNERS` and
`ROLE_RBE_BENEFICIAL_OWNERS_PDF` roles (granted by INPI to obliged
entities), you can provide those credentials to unlock the full UBO dataset
and a richer synthesis PDF (`ultimateBeneficialOwnersCertificate` document) for your own requests.
You can register several INPI accounts. Requests are spread across them and
fail over automatically if one account expires, is locked, or hits its
rate limit, so your enriched UBO access stays available.
When customer credentials are provisioned:
* The `ultimateBeneficialOwners` datapoint is fetched under your INPI
account and carries the un-redacted personal fields.
* The `ultimateBeneficialOwnersCertificate` document (synthesis PDF) is fetched under your INPI
account and contains the richer content that INPI reserves for
RBE-authorised accounts.
* Both the datapoint result and the downloaded PDF are isolated to your account.
No other customer can observe or read your enriched response.
When no customer credentials are provisioned, Topograph returns the default redacted INPI response. Switching from the default path to customer credentials, or rotating them, always produces a fresh INPI fetch; no stale cross-regime data is ever served.
The `inpi_extract` (uncertified trade register extract) document always
uses the default service account, even when customer credentials are
provisioned. RBE enrichment only affects the UBO-focused synthesis PDF.
You add your INPI accounts yourself, on the workspace that should use them:
in the dashboard under **Workspaces → Vault**, or with
`PUT /v2/workspaces/{name}/vault/fr_inpi`. Credentials are encrypted on
write, are never returned back, and can be rotated at any time without data
loss. See [Register Credentials](/essentials/register-credentials) for the
payload shape and how a workspace inherits credentials. If you are not sure
which RBE roles your INPI account carries, contact **[support@topograph.co](mailto:support@topograph.co)**.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **Commercial companies & sole entrepreneurs** | RNE | 9 digits (SIREN), leading zeros significant | `932884117` | Standard business identifier. The ninth digit is a check digit (Luhn) |
| **Non-profits** | RNA | W + 9 digits | `W073000441` | Recommended, even if a SIREN exists. In Corsica: `W2A` or `W2B` + 7 digits |
| **Older non-profits (RNA Import)** | RNA | Up to 15 letters, digits and hyphens, typically 3 digits + a letter + digits | `332P2214500` | Non-profits with no change declared since 2009. Other shapes we return: `382S03394`, `051S00-011`, `623S0623001470` |
| **Alsace-Moselle non-profits** | RNA AM | A + year(4) + court(3) + seq(6), 14 characters | `A2002THI000075` | AMALIA number, the id search returns for these non-profits |
**Alsace-Moselle Format Breakdown:** `A2002THI000075` = `A` (prefix) + `2002` (usually the year of registration) + `THI` (code of the registering court, e.g. THI = Thionville, MET = Metz, SAG = Sarreguemines) + `000075` (sequence)
**Strict format validation on `/v2/company`**
The `id` of a company request must be a 9-digit SIREN or an RNA non-profit id, exactly as `/v2/search` returns it. A 14-digit SIRET, a VAT number (`FRXX` + SIREN or 11 bare digits) or any other all-digit input is rejected immediately with **HTTP 400 (`invalid_request`)**, before any request is created or billed. This is distinct from `resource_not_found`, which means the identifier was well-formed but no entity exists behind it.
SIRET and VAT numbers are supported in `/v2/search`, which resolves them to the canonical SIREN. Pass that SIREN to `/v2/company`. For a SIRET you can also simply take its first 9 digits.
**Critical: RNA vs SIREN for Non-profits**
Non-profits may have both an RNA number and a SIREN number. **Use the RNA number as the API ID**: it reaches the RNA records and the JOAF publications. Querying by SIREN also resolves, but returns the trade register or SIRENE view of the entity.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `siren` | 9 digits, leading zeros significant | `932884117` | Commercial companies, sole entrepreneurs, some non-profits |
| `siret` | 14 digits (head office SIRET); the last digit is a check digit | `93288411700023` | Entities registered in SIRENE, some non-profits |
| `VAT` | 11 digits (2 check digits + SIREN; the FR prefix is stripped) | `21932884117` | Commercial companies, sole entrepreneurs |
| `rna` | W + 9 digits (W + 2A/2B + 7 digits in Corsica), or an RNA-Import id of up to 15 letters, digits and hyphens | `W073000441` | Non-profits |
| `rnaAlsaceMoselle` | A + year(4) + court(3) + seq(6) | `A2002THI000075` | Alsace-Moselle non-profits (with `rna` when one exists) |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the SIREN (`siren`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By SIREN | 9 digits | `932884117` | Exact | Exact match returned first (matchType: id); other results may follow |
| By SIRET | 14 digits | `93288411700023` | Exact | Exact match returned first (matchType: id, converted to parent SIREN); other results may follow |
| By RNA | W + 9 characters, or an RNA-Import id | `W073000441` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Alsace-Moselle ID | A + year(4) + court(3) + seq(6) | `A2002THI000075` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | FR + 11 digits, or 11 digits | `FR21932884117` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"TOPOGRAPH"` | Fuzzy | Multiple results across all sources |
### Search Source Priority
Search queries are dispatched across five sources in priority order:
1. **Index lookup by ID** -- Pre-built search index for identifier-based searches (SIREN, SIRET, VAT, RNA, Alsace-Moselle)
2. **RNE by ID** -- Live INPI API lookup for identifier-based searches
3. **Index search by Name** -- Pre-built search index for name-based fuzzy searches
4. **RNE by Name** -- Live INPI API for name-based searches
5. **BODACC by ID** -- Last resort, SIREN/SIRET only
**Search Performance:** Use identifier-based searches (SIREN, RNA, VAT) for
best performance and exact matching. Name searches may return multiple results
from different registers (RNE, RNA Waldec, RNA Import, Alsace-Moselle).
**Search uses both pre-built indexes and live lookups.** Name searches query a pre-built index for fast results. Identifier searches (SIREN, RNA, VAT) also perform live registry lookups to ensure the most up-to-date data.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Status is known for nearly every result. A registration-number match found only in official announcements (typically a very recent company) may be returned whatever its status, as may a company whose only closure signal is a dormancy declaration.
## Prefill mode (fast retrieval)
Use [`POST /v2/company`](/essentials/retrieve_company) with [`mode: "prefill"`](/essentials/modes) for low-latency access in prefill flows. Prefill mode covers `company`, `legalRepresentatives`, `otherKeyPersons`, `establishments` and `ultimateBeneficialOwners`. `shareholders` and `subsidiaries` are available in verification mode only.
Prefill reads the same register data as verification, and its results are authoritative. Both modes use our daily-synchronized copy of the INPI RNE and read INPI live when that copy is behind or does not have the company yet, with SIRENE, RNA and BODACC for entities outside the RNE. RNE fields are labelled `live_from_registry` when INPI answered live or our daily copy is confirmed up to date. `cached_from_registry` appears on activity codes and employee counts from INSEE, on insolvency status from BODACC, on companies outside the RNE (SIRENE-only entities and associations), and on RNE fields whenever our copy is behind and INPI cannot be reached live, which can affect most requests during an INPI outage (see [Verification Status and Source Labels](#verification-status-and-source-labels)).
The one difference is VAT. In prefill mode, `company` carries the calculated VAT number without the VIES check and its consultation number. Request verification mode when you need that proof.
UBOs are the same in both modes: personal fields are redacted per RGPD by default, and un-redacted for accounts that have provided their own INPI credentials (see [Enriched UBO data with customer INPI credentials](#enriched-ubo-data-with-customer-inpi-credentials)).
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **All-or-nothing data model** | Data comes from a single source per entity -- no cross-registry merging. Exceptions: employee count always from SIRENE, BODACC collective proceedings on the company status, and the VIES VAT check in verification mode. |
| **Query non-profits by RNA number** | Even if a non-profit has a SIREN, prefer its RNA number: it reaches the RNA records and JOAF publications. A SIREN query returns the trade register or SIRENE view. |
| **Non-diffusible sole entrepreneurs** | \~30% of EIs are marked non-diffusible by INSEE. Only minimal data returned (identifiers + VAT). No workaround. |
| **SIRENE employee data lag** | Employee count ranges (tranches) from SIRENE can be **2-3 years old** per INSEE methodology. |
| **BODACC = AI-extracted text** | When BODACC is the source (rare last resort), company data and legal reps are extracted from announcement text by AI. Quality is lower. |
| **Register extracts only for active companies** | The K-Bis (`certifiedTradeRegisterExtract`), the uncertified extract (`tradeRegisterExtract`) and the UBO extract are unavailable for closed/dissolved companies. Filed actes and financial statements stay available. |
| **Alsace-Moselle is separate** | Departments 57/67/68 non-profits use local law (German heritage). Different identifier format, different activity codes, different registry. |
| **ISIC sometimes AI-inferred** | NAF\_REV2-to-NACE mapping is deterministic. NACE-to-ISIC uses formal tables when possible, but falls back to AI. Check `isAIInferred` flag. |
| **RNE replaced 3 registries in 2023** | Since Jan 1 2023, RNE unified RNCS + Repertoire des Metiers + Registre des Actifs Agricoles. Some legacy data may still reference old registries. |
| **JOAF docs are paid** | Non-profit documents from Journal Officiel are paid per document — see the pricing page for current rates. Not all non-profits publish to JOAF. |
| **SIRET auto-converted to SIREN (search only)** | In `/v2/search`, a 14-digit SIRET is automatically resolved to its parent 9-digit SIREN. In `/v2/company`, a SIRET is rejected with HTTP 400: pass the SIREN instead. |
## Mappings
### Company Status
Company status is determined **deterministically** from RNE and SIRENE data, updated by BODACC collective-proceeding announcements -- no AI inference is involved.
#### RNE (primary source)
Status is derived from historical events, cessation indicators, and dormancy flags:
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| Actif | Active | Active | No closure indicators |
| En sommeil | Dormant | Closed | Dormancy is the only closure signal; see the dormancy note below |
| Fermé | Closed | Closed | Has cessation events, radiation dates, or closure events |
| Fermé or En sommeil | Under insolvency | Under Insolvency Proceeding | A closed company whose register history shows a faillite, redressement or sauvegarde |
A dormancy declaration ("en sommeil") does not always get updated when the company resumes activity. To avoid reporting a resumed company as inactive, dormancy is only treated as Closed when no other closure indicator is present **and** SIRENE's independent administrative status does not also confirm the company as active. If SIRENE confirms activity, the standardized status is Active. Any stronger closure signal (radiation, liquidation, insolvency, an explicit dissolution event) always takes precedence over this check.
**Closure reasons** (when status is Closed or Under Insolvency Proceeding):
| French Event | Standardized Closure Reason |
| - | - |
| Faillite | Bankruptcy |
| Redressement judiciaire / Sauvegarde | Court Order |
| Dissolution avec liquidation | Liquidation |
| Dissolution volontaire / sur decision | Voluntary Dissolution |
| Radiation / dissolution administrative | Administrative Dissolution |
| Nature cessation code (fallback) | Other |
#### SIRENE (fallback source)
| Code | Local Status | Standardized Status |
| - | - | - |
| A | Actif | Active |
| C | Cessé | Closed |
SIRENE provides only a binary active/ceased status with no closure reasons or detailed dates. When RNE is the primary source (vast majority of cases), the richer RNE status logic is used.
#### BODACC collective proceedings
RNE and SIRENE keep a company active until it is struck off, even during a redressement or liquidation judiciaire. When the RNE or SIRENE status is still active, the latest collective-proceeding judgment published in BODACC (redressement, liquidation judiciaire, sauvegarde) updates it: an open proceeding moves the status to Under Insolvency Proceeding (the company stays `active: true`), and the closure of a liquidation moves it to Closed. A status the register already reports as closed is never changed.
| Latest judgment | Local Status | Standardized Status | `active` |
| - | - | - | - |
| Liquidation judiciaire (opening, conversion, extension) | En liquidation judiciaire | Under Insolvency Proceeding | `true` |
| Redressement judiciaire | En redressement judiciaire | Under Insolvency Proceeding | `true` |
| Sauvegarde | En procédure de sauvegarde | Under Insolvency Proceeding | `true` |
| Plan (continuation, safeguard or sale) | Sous plan (procédure collective) | Under Insolvency Proceeding | `true` |
| Clôture of a liquidation (insufficient assets) | Clôturée (liquidation judiciaire) | Closed | `false` |
#### RNA Waldec / RNA Import
| Code | Local Status | `active` |
| - | - | - |
| A | Active | `true` |
| D | Dissoute | `false` |
| S | Supprimée | `false` |
| other | Inconnu | `false` |
The RNA records no closure reason, so association statuses carry `active` and no standardized status.
#### RNA Alsace-Moselle
| Code | Local Status | `active` |
| - | - | - |
| INSCRITE | Inscrite | `true` |
| DISSOUTE | Dissoute | `false` |
| RADIEE | Radiée | `false` |
| other | Inconnu | `false` |
### Legal Forms
France uses the **INSEE catégorie juridique nomenclature** (4-digit codes covering all entity types). Every code is mapped **deterministically** to a standardized legal form, English translation, and **ISO 20275 (ELF)** code via a static lookup table -- no AI is involved at runtime. The table covers the 260 INSEE codes and the 209 additional codes of the RNE (INPI) nomenclature, 469 in all. Each INPI code carries the ISO 20275 code of its INSEE parent form, checked against GLEIF's French list; forms GLEIF does not list carry none.
Legal form mapping is **fully deterministic**. `localName` is the label of the RNE (INPI) nomenclature, which the register's formalities use; for some INSEE codes it is worded differently from INSEE's own label (for example 5599, "Société anonyme à conseil d'administration (sans autre indication)"). A company known only from BODACC announcements gets the listed form its announcement names; an announcement wording no listed form keeps its own text.
#### Key Business Forms
| Code | French Name | Abbr. | Standardized |
| - | - | - | - |
| 5710 | SAS, société par actions simplifiée | SAS / SASU | Corporation |
| 5499 | SARL, Société à responsabilité limitée (sans autre indication) | SARL | Limited Liability Company |
| 5498 | Société d'attribution d'immeuble en jouissance à temps partagé à responsabilité limitée | -- | Limited Liability Company |
| 5599 | Société anonyme à conseil d'administration (sans autre indication) | SA | Corporation |
| 5308 | SCA, Société en commandite par actions | SCA | Partnership |
| 5202 | SNC, Société en nom collectif | SNC | Partnership |
| 5306 | SCS, Société en commandite simple | SCS | Partnership |
| 5485 | SELARL, Société d'exercice libéral à responsabilité limitée | SELARL | Limited Liability Company |
| 5310 | SLP, Société en libre partenariat | SLP | Partnership |
#### Sole Entrepreneurs
| Code | French Name | Standardized |
| - | - | - |
| 1000 | Entrepreneur individuel | Sole Proprietorship |
#### Cooperatives
| Code | French Name | Abbr. | Standardized |
| - | - | - | - |
| 5458 | Société coopérative ouvrière de production (SCOP) à responsabilité limitée | SCOP | Cooperative |
| 5462 | Société coopérative d'intérêt collectif à responsabilité limitée | SCIC | Cooperative |
| 5461 | Société coopérative à responsabilité limitée | -- | Cooperative |
| 5192 | Société coopérative de banque populaire | -- | Cooperative |
| 5195 | Association coopérative inscrite (droit local Alsace Moselle) | -- | Cooperative |
| 5463 | Société coopérative d'activité et d'emploi à responsabilité limitée | -- | Cooperative |
| 5465 | Société coopérative d'habitants à responsabilité limitée | -- | Cooperative |
#### Civil Companies
| Code | French Name | Abbr. | Standardized |
| - | - | - | - |
| 6540 | Société civile immobilière (SCI) | SCI | Partnership |
| 6561 | SCP d'avocats | SCP | Partnership |
| 6533 | GAEC, Groupement agricole d'exploitation en commun | GAEC | Cooperative |
#### Non-Profits
| Code | French Name | Standardized |
| - | - | - |
| 9220 | Association déclarée | Nonprofit Organization |
| 9221 | Association déclarée d'insertion par l'économique | Nonprofit Organization |
| 9222 | Association intermédiaire | Nonprofit Organization |
| 9230 | Association déclarée, reconnue d'utilité publique | Nonprofit Organization |
| 9300 | Fondation | Nonprofit Organization |
#### RNA Non-Profit Legal Forms (deterministic, no AI)
| Nature Code | French Name | ISO 20275 |
| - | - | - |
| R | Association reconnue d'utilité publique | XH8C |
| U, C | Association cultuelle | BEWI |
| M | Association de recherche médicale | BEWI |
| X (RNA Import) | Congrégation | PWKL |
| any other (D, A, B, G, I, L, S, …) | Association déclarée | BEWI |
A union or a federation of associations (`groupement` U or F) carries a prefix: "Union d'associations - Association déclarée", "Fédération d'associations - Association reconnue d'utilité publique", and so on. Every association legal form is standardized as Nonprofit Organization. Associations of Bas-Rhin, Haut-Rhin and Moselle, registered outside the RNA, are returned as "Association de droit local Alsace-Moselle" (ISO 20275 `HF2L`).
RNA legal form mapping is **stable and deterministic** -- no AI parsers. The Ministry of the Interior does not publish the meaning of each `nature` letter, so a letter gets its own label only where the register data confirms it; every other association is returned as "Association déclarée", which holds for every association in the RNA.
#### Public Entities
| Code | French Name | Standardized |
| - | - | - |
| 4110 | Établissement public national à caractère industriel ou commercial doté d'un comptable public | Government-Owned Entity |
| 4120 | Établissement public national à caractère industriel ou commercial non doté d'un comptable public | Government-Owned Entity |
| 4130 | Exploitant public | Government-Owned Entity |
| 4140 | Établissement public local à caractère industriel ou commercial | Government-Owned Entity |
| 4150 | Régie d'une collectivité locale à caractère industriel ou commercial | Government-Owned Entity |
| 4160 | Institution Banque de France | Government-Owned Entity |
#### Foreign Entities
| Code | French Name | Standardized |
| - | - | - |
| 3110 | Représentation ou agence commerciale d'état ou organisme public étranger immatriculé au RCS | Branch or Representative Office |
| 3120 | Société commerciale étrangère immatriculée au RCS | Branch or Representative Office |
| 3205 | Organisation internationale | Other |
| 3210 | État, collectivité ou établissement public étranger | Government-Owned Entity |
| 3220 | Société étrangère non immatriculée au RCS | Branch or Representative Office |
| 3290 | Personne morale de droit étranger (autre que société étrangère) non immatriculée au registre du commerce et des sociétés | Other |
#### Other Private Structures
| Code | French Name | Standardized |
| - | - | - |
| 2110 | Indivision entre personnes physiques | Other |
| 2210 | Société créée de fait entre personnes physiques | Partnership |
| 2310 | Société en participation entre personnes physiques | Partnership |
| 2400 | Fiducie | Trust |
| 2700 | Paroisse hors zone concordataire | Nonprofit Organization |
| 2800 | Assujetti unique à la TVA | Other |
#### Social Security & Mutual Organizations
| Code | French Name | Standardized |
| - | - | - |
| 8110 | Régime général de la Sécurité Sociale | Government-Owned Entity |
| 8210 | Mutuelle | Cooperative |
| 8250 | Assurance mutuelle agricole | Cooperative |
The full INSEE nomenclature is available at [INSEE](https://www.insee.fr/fr/information/2028129). All 469 codes (260 INSEE, 209 RNE) are statically mapped with English translations, standardized categories, and ISO 20275 (ELF) codes. The [pricing page](https://topograph.co/pricing/fr) lists every code.
### Legal Representatives
Legal representatives are extracted from the officers (*pouvoirs*) recorded in the RNE. The classification of a role as **legal representative vs. other key person** is **fully deterministic** -- a static mapping covers all 84 RNE role codes, each with a standardized role, English translation, and `isLegalRepresentative` flag based on French corporate law. No AI is involved.
#### Complete RNE Role Mapping (84 roles)
| Code | French Role | English | Standardized | Notes |
| - | - | - | - | - |
| 30 | Gérant | Manager (Gérant) | Managing Director | Most common for SARL/SNC |
| 28 | Gérant et associé indéfiniment et solidairement responsable | Manager and Unlimited Joint-Liability Partner | Managing Director | SNC gérant |
| 29 | Gérant et associé indéfiniment responsable | Manager and Unlimited Liability Partner | Managing Director | SCS gérant |
| 52 | Président du directoire | President of the Management Board | President | SA with directoire |
| 53 | Directeur Général | Chief Executive Officer (Directeur Général) | Chief Executive Officer | SA executive |
| 60 | Président du conseil d’administration et directeur général | Chairman and CEO (PDG) | Chief Executive Officer | Combined role in SA |
| 69 | Directeur général unique de SA à directoire | Sole General Director (SA with Management Board) | Chief Executive Officer | SA directoire variant |
| 70 | Directeur général délégué | Deputy CEO (Directeur Général Délégué) | Managing Director | SA deputy executive |
| 73 | Président de SAS | President of SAS | President | Most common for SAS |
| 55 | Dirigeant à l’étranger d’une personne morale étrangère | Director of Foreign Entity (Abroad) | Managing Director | Foreign entity management |
| 56 | Dirigeant en France d’une personne morale étrangère | Director of Foreign Entity (in France) | Managing Director | Foreign entity French branch |
| 66 | Personne ayant le pouvoir d’engager à titre habituel la société | Authorized Signatory (Company) | Authorized Signatory | General signing authority |
| 67 | Personne ayant le pouvoir d’engager l'établissement | Authorized Signatory (Establishment) | Authorized Signatory | Establishment-level authority |
| 100 | Repreneur | Business Acquirer (Repreneur) | Owner | Business acquisition |
| 101 | Entrepreneur | Entrepreneur | Owner | Individual entrepreneur |
| 140 | Président de l'EPIC | President of Public Commercial Establishment | President | EPIC entity |
| 200 | Fiduciaire | Fiduciary | Managing Director | Trust management |
| 201 | Dirigeant | Director (Dirigeant) | Managing Director | Generic executive |
| 203 | Membre bénéficiant d'un mandat général d'administration | Member with General Administration Mandate | Administrator | Non-profit admin |
| 204 | Personne capable d'engager l'entité | Person Authorized to Bind the Entity | Authorized Signatory | Non-profit signing authority |
| 205 | Président | President | President | Non-profit/generic president |
| 206 | Directeur | Director | Director | Generic director |
| 212 | Personne désignée par les statuts | Person Designated by Bylaws | Managing Director | Bylaws-designated authority |
| 214 | Personne ayant le pouvoir d’engager à titre habituel l’entité | Person Authorized to Habitually Bind the Entity | Authorized Signatory | Non-profit habitual signing authority |
| 215 | Personne ayant le pouvoir de représenter l’entité | Person Authorized to Represent the Entity | Authorized Signatory | Non-profit representation authority |
| 40 | Liquidateur | Liquidator | Liquidator | Legal rep during liquidation |
| 86 | Exploitant pour le compte de l’indivision | Operator on behalf of Joint Ownership | Managing Director | Joint ownership operator |
| 90 | Personne physique, exploitant en commun | Joint Operator (Individual) | Partner | Joint exploitation |
| 98 | Administrateur provisoire | Provisional Administrator | Administrator | Court-appointed, scope defined by the order |
| 231 | Gouverneur | Governor | President | Banque de France |
| Code | French Role | English | Standardized |
| - | - | - | - |
| 61 | Président du conseil de surveillance | Chairman of the Supervisory Board | Chairman of the Board |
| 63 | Membre du directoire | Member of the Management Board | C-Level Executive |
| 64 | Membre du conseil de surveillance | Member of the Supervisory Board | Supervisory Board Member |
| 65 | Administrateur | Board Member (Administrateur) | Board Member |
| 110 | Vice-Président | Vice-President | Vice Chairman of the Board |
| 111 | Vice-Président du Directoire | Vice-President of the Management Board | Vice Chairman of the Board |
| 120 | Vice-Président du Conseil d'Orientation et de Surveillance | Vice-President of Orientation and Supervision Board | Vice Chairman of the Board |
| 121 | Président du Conseil d'Orientation et de Surveillance | President of Orientation and Supervision Board | Chairman of the Board |
| 122 | Membre du Conseil d'Orientation et de Surveillance | Member of Orientation and Supervision Board | Board Member |
| 210 | Membre du conseil syndical | Member of the Syndicate Council | Board Member |
| 211 | Président du conseil syndical | President of the Syndicate Council | Chairman of the Board |
| 135 | Administrateurs représentant les salariés | Employee Representative Director | Board Member |
| 213 | Vice-Président du conseil de surveillance | Vice-Chairman of the Supervisory Board | Vice Chairman of the Board |
| 218 | Membre de l’organe collégial de contrôle | Member of the Collegial Control Body | Supervisory Board Member |
| 219 | Président de l’organe collégial de contrôle | Chairman of the Collegial Control Body | Chairman of the Board |
| 51 | Président du conseil d’administration | Chairman of the Board of Directors | Chairman of the Board |
| 232 | Premier sous-gouverneur | First Deputy Governor | C-Level Executive |
| 233 | Deuxième sous-gouverneur | Second Deputy Governor | C-Level Executive |
| 234 | Conseiller général | Member of the General Council | Board Member |
| Code | French Role | English | Standardized |
| - | - | - | - |
| 71 | Commissaire aux comptes titulaire | Statutory Auditor (Titular) | Auditor |
| 72 | Commissaire aux comptes suppléant | Statutory Auditor (Substitute) | Auditor |
| 13 | Contrôleur de gestion | Management Controller | Auditor |
| 14 | Contrôleur des comptes | Accounts Controller | Auditor |
| 104 | Personne chargée du contrôle | Person in Charge of Control | Auditor |
| 220 | Auditeur de durabilité | Sustainability Auditor | Auditor |
| Code | French Role | English | Standardized |
| - | - | - | - |
| 74 | Associé indéfiniment et solidairement responsable | Unlimited Joint-Liability Partner | Other |
| 75 | Associé indéfiniment responsable | Unlimited Liability Partner | Other |
| 131 | Associé commandité | General Partner (Commandité) | Other |
| 132 | Associé commanditaire | Limited Partner (Commanditaire) | Other |
| 23 | Autre associé majoritaire | Other Majority Partner | Other |
| 95 | Associé qui participe à la gestion | Partner Participating in Management | Other |
| 96 | Associé non salarié | Non-Salaried Partner | Other |
| 130 | Associé unique qui récupère le patrimoine | Sole Associate Recovering Assets | Other |
| 41 | Associé unique (qui participe à l’activité EURL) | Sole Associate (Active in EURL) | Other |
| Code | French Role | English | Standardized |
| - | - | - | - |
| 207 | Trésorier | Treasurer | Other |
| 208 | Secrétaire | Secretary | Secretary |
| 209 | Secrétaire général | Secretary General | Secretary |
| 216 | Trésorier adjoint | Deputy Treasurer | Other |
| 217 | Secrétaire adjoint | Deputy Secretary | Secretary |
| 202 | Représentant de l'assujetti unique | Representative of VAT Group | Other |
| Code | French Role | English | Standardized |
| - | - | - | - |
| 11 | Membre | Member | Other |
| 77 | Représentant fiscal d’une entreprise personne étrangère sans établissement en France | Tax Representative of Foreign Entity | Other |
| 82 | Indivisaire | Joint Owner (Indivisaire) | Other |
| 94 | Membre non salarié participant aux travaux | Non-Salaried Worker-Member | Other |
| 97 | Mandataire ad hoc | Ad Hoc Agent (Mandataire) | Other |
| 99 | Autre | Other | Other |
| 103 | Suppléant | Substitute | Other |
| 105 | Personne décisionnaire désignée | Designated Decision-Maker | Other |
| 106 | Comptable | Accountant | Other |
| 107 | Héritier indivisaire | Joint Heir (Indivisaire) | Other |
| 108 | Loueur | Lessor | Other |
| 109 | Mandataire fiscal | Tax Representative | Other |
| 150 | Avocat | Lawyer | Other |
| 76 | Représentant social d’une entreprise personne étrangère sans établissement en France | Social Representative of Foreign Entity | Other |
The classification of each role as **legal representative** or **other key person** is **deterministic** and based on French corporate law. For example, a "Gérant" (code 30) is always a legal representative, while an "Administrateur" (code 65) is always an other key person. Representation is qualified by the legal form and source: foreign offices follow their governing law; association offices depend on statutes or delegation; establishment signatories act within the establishment mandate; provisional administrators within the court order. No sole or joint signing rule is inferred from an office title. A secretary general (209) is an other key person unless a separately recorded office establishes representation. A member of a management board (63) is kept as an other key person; a separate appointment as director general carries representation under [Code de commerce L225-66](https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000006224266). A person the register records with a second role (`secondRoleEntreprise`, for example a gérant who is also empowered to bind the company) is returned once per role, each entry under the datapoint its role belongs to. An officer with an unknown or absent role code is retained as "Autre" rather than dropped. For individual entrepreneurs (catégorie juridique 1000), the register records no role code: the entrepreneur is always returned as the sole legal representative with the role "Entrepreneur Individuel" (English "Sole Proprietor", standardized Managing Director).
All 84 codes from the RNE role nomenclature (INPI dictionary, June 2026) are statically mapped with standardized roles, English translations, and legal representative classification. No code is missing and no AI is involved. The `standardized` value of a legal representative comes from the legal-representative role list; the `standardized` value of an other key person comes from the other-key-person role list (`otherKeyPersons[].role.standardized`), where a role with no closer equivalent is `Other` and keeps its meaning in `localName` and `englishTranslation`.
### Shareholders
Shareholders are **AI-extracted from the documents the company filed at INPI** (statutes, capital changes, annual filings). They are not read from structured register data, so verify them against the filing before relying on them for compliance. Not all legal forms must file an updated shareholder list each year. Shareholders are available in verification mode only.
Non-profits (queried by RNA number) and sole entrepreneurs have no share capital: the `shareholders` datapoint returns `datapoint_not_applicable` at no charge. A sole entrepreneur appears under `legalRepresentatives` and `ultimateBeneficialOwners` instead.
Both individual and corporate shareholders are supported.
### Activity Code Mapping
France uses the **NAF\_REV2** (Nomenclature d'Activites Francaise, Revision 2) classification, which extends the European NACE Rev. 2 standard with a trailing letter suffix. The system maps activity codes across three levels:
```
NAF_REV2 (French) -> NACE Rev. 2.1 (European) -> ISIC Rev. 5 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NAF\_REV2** | RNE / SIRENE (APE code) | `5829C` | No (official) |
| **NACE** | The NACE Rev. 2.1 class of the company's NAF 2025 code (first four digits); INSEE's NAF rev. 2 -> NAF 2025 correspondence when INSEE has not assigned one | `58.29` | No (register / formal mapping) |
| **NAF\_2025** | INSEE's NAF 2025 code for the company (Sirene, provisional until 2027-01-01) | `58.29Y` | No (official) |
| **NACE\_REV2** | The APE code's own class level (first four digits) | `58.29` | No (the register's own class) |
| **ISIC** | Derived from NACE (formal mapping) or AI | `5829` | Sometimes |
| **RNA** | RNA Waldec / Import (objet\_social codes) | `011000` (Sports) | No (official) |
| **ALSACE\_MOSELLE** | RNA Alsace-Moselle (regional classification) | `SOCIAL-SOLIDARITE` | No (official) |
**One code in, one code out.** You get one `NACE` and one `ISIC` code per declared NAF/APE code. Where a NAF/APE code has no single equivalent in the target revision, the shared parent class is returned rather than every candidate — see [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
**Your NACE class is the one INSEE assigned the company, not a conversion of its old code.** INSEE has published NAF 2025, the French implementation of NACE Rev. 2.1: « la structure de la NAF 2025 s'emboîte strictement dans celle de la nomenclature européenne NACE Rev.2.1 ; jusqu'au niveau le plus détaillé de la NACE (niveau des classes ; codes à 4 chiffres), les deux nomenclatures coïncident rigoureusement » ([INSEE, Structure de la NAF 2025](https://www.insee.fr/fr/information/8181066)). A NAF 2025 code is therefore a NACE Rev. 2.1 class followed by one French letter (`Y` when the class has no French subdivision, `G`/`H`/`J`... when it has), and INSEE already assigns every active company its NAF 2025 code in Sirene, « à titre informatif » until NAF 2025 becomes the reference nomenclature for APE codes on 1 January 2027 ([INSEE, Sirene open data](https://www.insee.fr/fr/information/9019311)).
We read that assignment directly. For a company INSEE recorded as `86.90F` (NAF rev. 2) and assigned `86.93Y` (NAF 2025):
```json theme={null}
"activities": {
"NAF_REV2": [{ "code": "8690F", "description": "Activités de santé humaine non classées ailleurs" }],
"NAF_2025": [{ "code": "86.93Y", "description": "Activités des psychologues et psychothérapeutes, à l'exception des médecins" }],
"NACE": [{ "code": "86.93", "description": "Activities of psychologists and psychotherapists, except medical doctors" }],
"NACE_REV2": [{ "code": "86.90", "description": "Other human health activities" }]
}
```
This is more precise than any conversion of the old code can be, because INSEE recodes each company on its actual activity: a consultancy filed as `62.02A` can come back as `73.12Y` (media representation). In a live sample of 598 units (2026-09-03), 99.5 % of active companies carried a NAF 2025 code; the ones that don't are units still coded in a pre-2008 nomenclature, almost all ceased, and for those the correspondence rules below apply.
**The APE sub-class letter is used, not discarded.** The letter on an APE code is a French subdivision of the NACE class, and it often pins the NACE Rev. 2.1 class that the bare class cannot. We resolve it through INSEE's own *Table de correspondances NAF rev.2 -> NAF 2025* (NAF 2025 sits strictly inside NACE Rev. 2.1), which names a single Rev. 2.1 class for 541 of the 732 French sub-classes:
| APE code | NACE from the class alone | NACE we publish |
| - | - | - |
| `6420Z` Activites des societes holding | `64.2` (group) | `64.21` |
| `8690A` Ambulances | `86.9` (group) | `86.92` |
| `1071B` Cuisson de produits de boulangerie | `10.71` (food manufacturing) | `47.24` (retail) |
| `8690F` Activites de sante humaine n.c.a. | `86.9` (group) | `86.9` — INSEE itself splits this sub-class across `86.93`, `86.96` and `86.99`, so no 4-digit class is supported by the data |
Where the sub-class straddles several Rev. 2.1 classes the class-level answer stands, so this is never less precise than the code alone. The register's own 5-character APE code is always published in full under `NAF_REV2`, with INSEE's official French label.
**Need a 4-digit class on every company, including units INSEE has not assigned a NAF 2025 code? Read `NACE_REV2`.** NAF rev. 2 is the French implementation of NACE Rev. 2, so an APE code's first four digits *are* a NACE Rev. 2 class. We publish that class verbatim under `NACE_REV2` whenever we hold an APE code — no conversion, no guessing:
```json theme={null}
"activities": {
"NAF_REV2": [{ "code": "8690F", "description": "Activites de sante humaine non classees ailleurs" }],
"NACE_REV2": [{ "code": "86.90", "description": "Other human health activities" }],
"NACE": [{ "code": "86.9", "description": "Other human health activities" }]}
```
This is the key to read when your parser needs a 4-digit class for every company. It also answers for the classes NACE Rev. 2.1 dropped entirely — `41.20A` (construction de maisons individuelles), `45.11Z` (car sales), `96.01A/B` (laundry) and others have no honest Rev. 2.1 code, so `NACE` is absent for them while `NACE_REV2` is not.
The two are different revisions of the same classification: `86.90` is not a NACE Rev. 2.1 code, and `86.9` is not a Rev. 2 class. Do not mix them in one field.
**Main activity:** the APE code is the company's declared main activity ("activite principale exercee"): the register publishes exactly one per company. The NAF\_REV2 entry carries `isMainActivity: true`, and the NACE and ISIC codes derived from it inherit the flag.
**AI Enrichment:** When ISIC codes cannot be derived from NACE via formal mapping tables, the system uses AI to match activity descriptions to ISIC Rev. 5 codes. Every activity item includes an `isAIInferred` flag to distinguish official vs. AI-derived codes. NAF\_REV2 and NACE codes are **never** AI-inferred for France.
**Establishment-level activity:** in France each establishment (SIRET) can have its own activity, which may differ from the company-level activity. When the register records it, every establishment in `company.establishments[]` carries its own `activities` object (NAF\_REV2 + NACE + ISIC), in the same shape as the company-level `activities`.
#### Activity Codes by Source
| Source | Classifications returned | Notes |
| - | - | - |
| **RNE** | NAF\_REV2 + NACE + ISIC | APE code from the RNE filing |
| **SIRENE** | NAF\_REV2 + NACE + ISIC | APE code from the SIRENE directory |
| **RNA Waldec** | RNA + (NAF\_REV2 + NACE if SIREN exists) + ISIC | RNA nomenclature codes + SIRENE APE if available |
| **RNA Import** | RNA + ISIC | RNA nomenclature codes only |
| **RNA Alsace-Moselle** | ALSACE\_MOSELLE + ISIC | Regional classification codes (DOMAINES/THEMES) |
## Data Availability
### Data Availability Matrix
| Data Type | Commercial companies (RNE) | SIRENE-only | BODACC | RNA Waldec | RNA Import | Alsace-Moselle |
| - | - | - | - | - | - | - |
| Company Profile | ✅ Full | ⚠️ Limited | ⚠️ Announcement fields | ✅ Basic | ✅ Basic | ✅ Basic |
| Legal Representatives | ✅ Comprehensive | ⚠️ Sole entrepreneurs only | ⚠️ AI-extracted | ❌ | ❌ | ❌ |
| Other Key Persons | ✅ Available non-representative offices | ❌ | ✅ Available administration offices | ❌ | ❌ | ❌ |
| Shareholders | ⚠️ AI-extracted from filings | ❌ | ❌ | ❌ | ❌ | ❌ |
| Subsidiaries | ⚠️ From filed bilans | ❌ | ❌ | ❌ | ❌ | ❌ |
| Ultimate Beneficial Owners | ✅ (live fetch) | ❌ | ❌ | ❌ | ❌ | ❌ |
| Establishments | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Activity Codes | ✅ NAF\_REV2/NACE/ISIC | ✅ NAF\_REV2/NACE/ISIC | ❌ | ✅ RNA + NACE/ISIC | ✅ RNA + ISIC | ✅ ALSACE\_MOSELLE + ISIC |
| Employee Count | ✅ (from SIRENE) | ✅ | ❌ | ⚠️ Via SIRENE | ❌ | ❌ |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available
#### Other Key Persons
`otherKeyPersons` carries board, supervisory, functional and unclassified offices for which no separate representation capacity is established. A person may also have a separately recorded representative office. The main source is the RNE role mapping. On the exceptional BODACC-only fallback, available administration office holders are classified using the same known offices; unfamiliar source titles retain contextual classification. SIRENE-only entities and RNA associations return an empty list. The full role split is in the [Complete RNE Role Mapping](#complete-rne-role-mapping-84-roles) above.
#### Subsidiaries
`subsidiaries` is available for France. It returns the equity participations the queried company holds in other entities, AI-extracted from the "Filiales et participations" annex of the latest annual financial statement (bilan) filed at INPI. Verify the values against the filing before relying on them for compliance.
Availability depends on the filing, not on our coverage: a company that has filed no bilan returns no subsidiaries, and associations (loi 1901) do not file bilans at all. `subsidiaries` is a separate data block from `company`, and it is available in verification mode only. See the [Subsidiaries](/essentials/subsidiaries-extraction) guide for the response shape.
#### Employee Count Tranches (SIRENE)
| Tranche Code | Range |
| - | - |
| 00 | 0 employees |
| 01 | 1-2 employees |
| 02 | 3-5 employees |
| 03 | 6-9 employees |
| 11 | 10-19 employees |
| 12 | 20-49 employees |
| 21 | 50-99 employees |
| 22 | 100-199 employees |
| 31 | 200-249 employees |
| 32 | 250-499 employees |
| 41 | 500-999 employees |
| 42 | 1,000-1,999 employees |
| 51 | 2,000-4,999 employees |
| 52 | 5,000-9,999 employees |
| 53 | 10,000+ employees |
### Documents by Company Type
#### Commercial companies & sole entrepreneurs (SIREN)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **K-Bis (Certified Extract)** | `certifiedTradeRegisterExtract` | PDF | ✅ Active + in RNE + on Infogreffe | Official certified trade register extract |
| **Trade Register History (Historique des modifications)** | `tradeRegisterHistory` | PDF | ✅ Active + in RNE + on Infogreffe | Chronological history of the modifications registered at the RCS |
| **INPI Extract (Uncertified)** | `tradeRegisterExtract` | PDF | ✅ Active + in RNE | Non-certified trade register extract, priced as company data |
| **UBO Extract** | `ultimateBeneficialOwnersCertificate` | PDF | ✅ Active + in RNE | Ultimate beneficial owners certificate, priced as UBO data |
| **Avis de situation INSEE** | `otherDocuments[]` | PDF | ✅ Active | Identity sheet from the SIRENE directory, priced as company data |
| **Financial Statements (Bilans)** | `financialStatements[]` | PDF | ✅ When filed | Annual accounts filed with RNE (formal mapping) |
| **Company Documents (Actes)** | `articlesOfAssociation[]` | PDF | ✅ When filed | Statutes, decisions, formalities (classified by the register's document type) |
#### Non-profits (RNA Waldec, RNA Import, Alsace-Moselle)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Avis de situation INSEE** | `otherDocuments[]` | PDF | ✅ Active + in SIRENE | Identity sheet from the SIRENE directory, same document as for commercial companies, independent of RNE registration |
| **JOAF Official Publications** | `officialPublications[]` | PDF | ⚠️ If published | Gazette publications (paid, see [pricing](https://www.topograph.co/pricing)) |
| **JOAF Financial Statements** | `financialStatements[]` | PDF | ⚠️ If published | Annual accounts in JOAF, priced as financial statements (see [pricing](https://www.topograph.co/pricing)) |
**K-Bis Availability:** The certified K-Bis extract (`certifiedTradeRegisterExtract`) requires three conditions: company is **active**, is **in RNE**, and is **available on Infogreffe**. The uncertified extract (`tradeRegisterExtract`) and the UBO extract are also offered only for active companies in the RNE. For inactive, dissolved, or liquidated companies, the filed actes and financial statements stay available.
**Avis de situation INSEE:** Available for any active company registered in the SIRENE directory, regardless of K-Bis availability or RNE registration. This includes non-profits that are not registered in RNE: an active association registered in SIRENE always has at least this document, even when it has no trade register extract and no JOAF publication on file. Associations with no SIRENE registration have no Avis de situation. Returned in `otherDocuments[]`. It contains registration details, activity code, and address from the SIRENE directory.
**JOAF Documents:** The Journal Officiel des Associations et Fondations (JOAF) publishes official documents for non-profits. These documents are conditionally available -- not all non-profits publish to JOAF, and a non-profit that has never filed a modification or published annual accounts can legitimately have none. When available, they appear under `officialPublications` and `financialStatements` categories and stay there for as long as the non-profit exists: a later administrative name change on the same registration number does not remove an earlier publication. JOAF documents are paid (see [pricing](https://www.topograph.co/pricing)) and include two sources: JOAFE (gazette publications) and DCA (annual accounts).
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "FR", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "123456789",
"countryCode": "FR",
"identifiers": { "VAT": "XX123456789" },
"taxId": { "type": "eu_vat", "value": "XX123456789", "country": "FR", "verification": { "status": "verified", "verifiedName": "SAS EXAMPLE CORP" } },
"legalName": "Example Corp",
"registrationDate": "2023-03-15",
"activityDescription": "Developpement et commercialisation de logiciels professionnels.",
"status": { "localName": "Actif", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "SAS, société par actions simplifiée", "standardized": "Corporation", "iso20275Code": "6CHY" },
"capital": { "amount": 10000, "currency": "EUR" },
"activities": {
"NAF_REV2": [{ "code": "6201Z", "description": "Programmation informatique", "isAIInferred": false }],
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "621", "description": "Computer programming activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "10 Rue de la Paix", "city": "Paris", "postalCode": "75002", "countryCode": "FR" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Président de SAS", "standardized": "President" }, "individual": { "name": { "fullName": "Jean DUPONT" }, "birthDate": { "month": 6, "year": 1985 } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Directeur Général", "standardized": "Chief Executive Officer" }, "individual": { "name": { "fullName": "Marie MARTIN" }, "birthDate": { "month": 9, "year": 1990 } } }
],
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "Jean DUPONT", "firstName": "Jean", "lastName": "DUPONT" },
"birthDate": { "month": 6, "year": 1985 },
"nationality": "FR",
"control": { "types": ["ownership-of-shares", "voting-rights"], "description": "Ultimate beneficial owner", "details": [{ "type": "shares", "percentageValue": 75, "nature": "direct" }, { "type": "voting-rights", "percentageValue": 75, "nature": "direct" }] }
},
{
"entityId": "person_002",
"name": { "fullName": "Marie MARTIN", "firstName": "Marie", "lastName": "MARTIN" },
"birthDate": { "month": 9, "year": 1990 },
"nationality": "FR",
"control": { "types": ["ownership-of-shares", "voting-rights"], "description": "Ultimate beneficial owner", "details": [{ "type": "shares", "percentageValue": 25, "nature": "direct" }, { "type": "voting-rights", "percentageValue": 25, "nature": "direct" }] }
}
],
"establishments": [
{ "id": "12345678900011", "name": "Example Corp", "creationDate": "2023-03-15", "active": true, "address": { "addressLine1": "10 Rue de la Paix", "city": "Paris", "postalCode": "75002", "countryCode": "FR" } }
]
}
```
```json theme={null}
{
"company": {
"id": "987654321",
"countryCode": "FR",
"identifiers": { "VAT": "YY987654321" },
"taxId": { "type": "eu_vat", "value": "YY987654321", "country": "FR", "verification": { "status": "unverified" } },
"legalName": "Ancienne Boutique",
"registrationDate": "2015-01-10",
"activityDescription": "Commerce de detail de vetements.",
"status": { "localName": "Fermé", "active": false, "statusDetails": { "status": "CLOSED" } },
"legalForm": { "localName": "SARL, Société à responsabilité limitée (sans autre indication)", "standardized": "Limited Liability Company", "iso20275Code": "V9QP" },
"capital": { "amount": 5000, "currency": "EUR" },
"activities": {
"NAF_REV2": [{ "code": "4771Z", "description": "Commerce de detail d'habillement en magasin specialise", "isAIInferred": false }],
"NACE": [{ "code": "47.71", "description": "Retail sale of clothing", "isAIInferred": false }],
"ISIC": [{ "code": "4771", "description": "Retail sale of clothing", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "25 Rue du Commerce", "city": "Lyon", "postalCode": "69002", "countryCode": "FR" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Gérant", "standardized": "Managing Director" }, "individual": { "name": { "fullName": "Pierre DURAND" }, "birthDate": { "month": 3, "year": 1978 } } }
],
"establishments": [
{ "id": "98765432100015", "name": "Ancienne Boutique", "creationDate": "2015-01-10", "endDate": "2023-06-30", "active": false, "address": { "addressLine1": "25 Rue du Commerce", "city": "Lyon", "postalCode": "69002", "countryCode": "FR" } }
]
}
```
**Note:** Closed companies have `active: false`, status `Fermé`, and `endDate` on establishments. The K-Bis, the uncertified extract and the UBO extract are **not available** for closed companies.
Sole entrepreneurs (personnes physiques) are often **non-diffusible** in SIRENE, returning minimal data. Below is a diffusible example.
```json theme={null}
{
"company": {
"id": "111222333",
"countryCode": "FR",
"identifiers": { "VAT": "ZZ111222333" },
"legalName": "Sophie BERNARD",
"registrationDate": "2020-09-01",
"activityDescription": "Activites de conseil en gestion.",
"status": { "localName": "Actif", "active": true },
"legalForm": { "localName": "Entrepreneur individuel", "standardized": "Sole Proprietorship", "iso20275Code": "ZY9X" },
"activities": {
"NAF_REV2": [{ "code": "7022Z", "description": "Conseil pour les affaires et autres conseils de gestion", "isAIInferred": false }],
"NACE": [{ "code": "70.20", "description": "Business and other management consultancy activities", "isAIInferred": false }],
"ISIC": [{ "code": "7020", "description": "Business and other management consultancy activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "5 Impasse des Lilas", "city": "Nantes", "postalCode": "44000", "countryCode": "FR" }
},
"establishments": [
{ "id": "11122233300012", "name": "Sophie BERNARD", "creationDate": "2020-09-01", "active": true }
]
}
```
**Note:** The entrepreneur is returned as the sole legal representative (role "Entrepreneur Individuel") and as the ultimate beneficial owner (100%, direct). The `shareholders` datapoint returns `datapoint_not_applicable` at no charge. `legalName` is the individual's name.
```json theme={null}
{
"company": {
"id": "W751000001",
"countryCode": "FR",
"identifiers": { "rna": "W751000001" },
"legalName": "ASSOCIATION SPORTIVE DU QUARTIER",
"registrationDate": "2016-10-20",
"activityDescription": "Promouvoir la pratique sportive et organiser des evenements.",
"status": { "localName": "Active", "active": true },
"legalForm": { "localName": "Association déclarée", "englishTranslation": "Declared association", "standardized": "Nonprofit Organization", "iso20275Code": "BEWI" },
"activities": {
"RNA": [{ "code": "011000", "description": "SPORTS, ACTIVITES DE PLEIN AIR" }],
"NACE": [{ "code": "93.12", "description": "Activities of sports clubs", "isAIInferred": true }],
"ISIC": [{ "code": "9312", "description": "Activities of sports clubs", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "21 Rue des Associations", "city": "Paris", "postalCode": "75007", "countryCode": "FR" }
}
}
```
**Note:** No legal representatives, shareholders, UBOs, or establishments. Activity codes use RNA nomenclature + AI-inferred NACE/ISIC.
```json theme={null}
{
"company": {
"id": "A2002THI000001",
"countryCode": "FR",
"identifiers": { "rnaAlsaceMoselle": "A2002THI000001" },
"legalName": "ENTRAIDE SOLIDAIRE DE THIONVILLE",
"registrationDate": "2002-11-03",
"activityDescription": "Soutien aux familles en difficulte et aide alimentaire.",
"status": { "localName": "Inscrite", "active": true },
"legalForm": { "localName": "Association de droit local Alsace-Moselle", "iso20275Code": "HF2L" },
"activities": {
"ALSACE_MOSELLE": [{ "code": "SOCIAL-SOLIDARITE", "description": "Divers social" }],
"NACE": [{ "code": "88.99", "description": "Other social work activities without accommodation", "isAIInferred": true }],
"ISIC": [{ "code": "889", "description": "Other social work activities without accommodation", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "1 Rue de la Gare", "city": "Thionville", "postalCode": "57100", "countryCode": "FR" }
}
}
```
**Note:** Uses `ALSACE_MOSELLE` classification instead of RNA nomenclature. Status `Inscrite` (not `Active`). Court codes: THI (Thionville), MET (Metz), SAG (Sarreguemines).
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "Jean DUPONT", "firstName": "Jean", "lastName": "DUPONT" },
"birthDate": { "month": 6, "year": 1985 },
"nationality": "FR",
"residenceAddress": { "city": "Paris", "postalCode": "75002", "countryCode": "FR" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"description": "Ultimate beneficial owner",
"details": [
{ "type": "shares", "percentageValue": 75, "nature": "direct" },
{ "type": "voting-rights", "percentageValue": 75, "nature": "direct" }
]
}
}
]
}
```
**Note:** UBOs are only available for commercial companies in the RNE. Fetched live from INPI if not already available. Ownership and voting-right percentages are in `control.details`, each marked `direct` or `indirect`.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
**Commercial companies & sole entrepreneurs (SIREN):**
| API Category | Document | Notes |
| - | - | - |
| `certifiedTradeRegisterExtract` | K-Bis PDF | Active + in RNE + on Infogreffe |
| `tradeRegisterHistory` | Historique des modifications PDF | Active + in RNE + on Infogreffe |
| `tradeRegisterExtract` | INPI extract PDF | Active + in RNE |
| `ultimateBeneficialOwnersCertificate` | UBO declaration PDF | Active + in RNE |
| `otherDocuments[]` | Avis de situation INSEE | Active |
| `financialStatements[]` | Annual accounts (bilans) | When filed (formal mapping) |
| `articlesOfAssociation[]` | Statutes, decisions (actes) | Classified by the register's document type |
**Non-profits (RNA):**
| API Category | Document | Notes |
| - | - | - |
| `otherDocuments[]` | Avis de situation INSEE | Active and in SIRENE, regardless of RNE registration |
| `officialPublications[]` | JOAF gazette publications | If published, paid (see [pricing](https://www.topograph.co/pricing)) |
| `financialStatements[]` | JOAF annual accounts | If published, priced as financial statements (see [pricing](https://www.topograph.co/pricing)) |
# Germany
Source: https://docs.topograph.co/essentials/germany
Country-specific identifiers, data sources, and data availability for Germany
This guide is outdated and will be removed on 1 November 2026. The up-to-date Germany reference is on the [Germany country page](https://www.topograph.co/countries/de).
## Start here
This guide contains public integration notes for Germany. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Germany uses a multi-source strategy combining official registers for comprehensive company coverage. Requests are routed to the appropriate register based on the company's register type. Company profile data is extracted from official trade register documents.
* **Unternehmensregister** (Company Register): Germany's central commercial register portal, operated by the Bundesanzeiger Verlag. Primary source for all companies in HRB, HRA, GnR (Genossenschaftsregister), PR (Partnerschaftsregister), and GsR (Gesellschaftsregister). Provides search, company status (active/deleted), the **Aktueller Abdruck** (current trade register extract), the **Chronologischer Abdruck** (chronological trade register extract / register history), Dokumentenansicht documents (filed corporate documents), and publications (financial statements, announcements).
* **Handelsregister** (Trade Register): The federal register of all German companies, operated by the federal states. Used specifically for **VR (Vereinsregister / associations)** companies, which are not available via Unternehmensregister. Provides the **Aktueller Abdruck** and **Chronologischer Abdruck** for VR companies, and is also used as a fallback source for Aktueller Abdruck retrieval for non-VR companies. Provides live search by partial ID or name.
* **Transparenzregister** (Transparency Register): Germany's register of beneficial owners. Source of `ultimateBeneficialOwners`; see [Ultimate Beneficial Owners](#ultimate-beneficial-owners).
* **Bundesanzeiger** (Federal Gazette): Publishes the annual and consolidated financial statements of German companies. Primary source for `subsidiaries`, with the Unternehmensregister as a fallback.
* **Document extraction**: Company profile data (legal name, registration date, activity description, registered address, share capital, legal representatives) is read directly from the text of the Aktueller Abdruck, so the same extract always yields the same values. Legal form is likewise read deterministically from the extract's Rechtsform section, with hybrid forms (GmbH & Co. KG, UG & Co. KG) resolved from the company name and the general-partner entries; AI is used only as a fallback for rare wordings outside the standardized list. Activity codes remain **AI-inferred from a standardized list**.
Both Unternehmensregister and Handelsregister are third-party registers with variable availability. Automatic retries are used to maximize reliability. For Aktueller Abdruck retrieval, non-VR companies query both sources and use whichever returns first.
## Company Identifiers
### Query Identifiers
German companies are identified by a composite registration number in the format: `{RegisterCourt} {RegisterType} {RegisterNumber}`. The court name is written as the register writes it and can contain spaces, parentheses, dots and slashes (`Bad Homburg v.d.H. HRB 16392`). The number has up to 6 digits in the records we have seen, and keeps any letter suffix the court adds after a space.
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **Corporations (GmbH, AG, etc.)** | Unternehmensregister | Court + HRB + Number | `München HRB 228960` | Registered at one of 129 Amtsgerichte |
| **Partnerships & sole proprietors** | Unternehmensregister | Court + HRA + Number | `Hamburg HRA 127146` | Includes KG, OHG, e.K., etc. |
| **Associations (e.V.)** | Handelsregister | Court + VR + Number | `Berlin (Charlottenburg) VR 20057` | Routed to Handelsregister |
| **Cooperatives** | Unternehmensregister | Court + GnR (or GenR) + Number | `Kiel GnR 201` | Genossenschaftsregister |
| **Professional partnerships** | Unternehmensregister | Court + PR + Number | `Essen PR 3002` | Partnerschaftsregister |
| **Civil law partnerships** | Unternehmensregister | Court + GsR + Number | `Freiburg GsR 241` | Gesellschaftsregister (eGbR) |
### Register Sections
German companies file in one of six register sections. The section abbreviation is part of every company's registration identifier and is the exact value the federal portals (handelsregister.de, unternehmensregister.de) use.
| Code | Local name | English | Scope |
| - | - | - | - |
| HRA | Handelsregister Abteilung A | Commercial Register, Section A | Sole proprietors and partnerships (e.K., OHG, KG, GmbH & Co. KG) |
| HRB | Handelsregister Abteilung B | Commercial Register, Section B | Limited-liability and stock companies (GmbH, UG, AG, KGaA, SE) |
| VR | Vereinsregister | Register of Associations | Registered non-profit associations (e.V.) |
| GnR | Genossenschaftsregister | Cooperative Register | Registered cooperatives (eG). Some courts write it `GenR`; such an id is accepted and returned as `GnR` |
| PR | Partnerschaftsregister | Partnership Register | Professional partnerships (PartG, PartG mbB) |
| GsR | Gesellschaftsregister | Civil-Law Partnership Register | Registered civil-law partnerships (eGbR) |
### Register Courts
Companies are registered at one of 129 Amtsgerichte (local courts). The court name is part of the registration identifier and matches the canonical form used on official register extracts, including parenthetical disambiguators (`Berlin (Charlottenburg)`, `Oldenburg (Oldenburg)`) and abbreviated saint names (`St. Ingbert`, `St. Wendel`).
Fuzzy matching is supported for common variations (for example `Munchen` for `München`, `Berlin Charlottenburg` for `Berlin (Charlottenburg)`).
Search also accepts the abbreviated court code (Ortskennzeichen) that appears on certified register extracts, where the code trails the number instead of preceding it. For example, `HRB 23591 KI` (KI = Kiel) resolves to the same company as `Kiel HRB 23591`. The codes follow the official handelsregister.de scheme and cover the courts in Berlin, Brandenburg, Bremen, and Schleswig-Holstein (for example `B` = Berlin, `HB` = Bremen, `HL` = Lübeck, `FL` = Flensburg).
Aachen, Amberg, Ansbach, Arnsberg, Aschaffenburg, Augsburg, Aurich, Bad Hersfeld, Bad Homburg v.d.H., Bad Kreuznach, Bad Oeynhausen, Bamberg, Bayreuth, Berlin (Charlottenburg), Bielefeld, Bochum, Bonn, Braunschweig, Bremen, Bremerhaven, Chemnitz, Coburg, Coesfeld, Cottbus, Darmstadt, Deggendorf, Dortmund, Dresden, Duisburg, Düren, Düsseldorf, Eschwege, Essen, Flensburg, Frankfurt am Main, Frankfurt/Oder, Freiburg, Friedberg, Fritzlar, Fulda, Fürth, Gelsenkirchen, Gießen, Göttingen, Gütersloh, Hagen, Hamburg, Hamm, Hanau, Hannover, Hildesheim, Hof, Homburg, Ingolstadt, Iserlohn, Jena, Kaiserslautern, Kassel, Kempten (Allgäu), Kerpen, Kiel, Kleve, Koblenz, Köln, Königstein, Korbach, Krefeld, Landau, Landshut, Langenfeld, Lebach, Leipzig, Lemgo, Limburg, Lübeck, Ludwigshafen a.Rhein (Ludwigshafen), Lüneburg, Mainz, Mannheim, Marburg, Memmingen, Merzig, Mönchengladbach, Montabaur, München, Münster, Neubrandenburg, Neunkirchen, Neuruppin, Neuss, Nürnberg, Offenbach am Main, Oldenburg (Oldenburg), Osnabrück, Ottweiler, Paderborn, Passau, Pinneberg, Potsdam, Recklinghausen, Regensburg, Rostock, Saarbrücken, Saarlouis, Schleiden, Schweinfurt, Schwerin, Siegburg, Siegen, Stadthagen, Steinfurt, Stendal, St. Ingbert (St Ingbert), Stralsund, Straubing, Stuttgart, St. Wendel (St Wendel), Tostedt, Traunstein, Ulm, Völklingen, Walsrode, Weiden i. d. OPf., Wetzlar, Wiesbaden, Wittlich, Wuppertal, Würzburg, Zweibrücken.
The list is stable. Changes occur only when a court is renamed or an Amtsgericht is dissolved by a federal-state administrative act.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains the three parts of the German registration number and the EUID when available:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `registerCourt` | Court name string | `München` | All companies |
| `registerType` | Register abbreviation (HRB, HRA, VR, PR, GnR, GsR) | `HRB` | All companies |
| `registerNumber` | Number, up to 6 digits seen (may include a letter suffix) | `228960` | All companies |
| `euid` | `DE` + court code + `.` + register type and number, as published by the register | `DED2601V.HRB180911` | When available |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the full registration identity (`registerCourt`, `registerType` and `registerNumber` together) matches exactly one LEI through a GLEIF registration or validation reference.
The register court is part of the match. A register type and number alone do not identify a German entity.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By full ID | Court + Type + Number | `München HRB 228960` | Exact | Exact match returned first (matchType: id); other results may follow |
| By partial ID | Type + Number (no court) | `HRB 228960` | Fuzzy | Results from live search sources |
| By Name | Text string | `"Siemens AG"` | Fuzzy | Multiple results across all sources |
**Search Performance:** Use full ID searches (court + type + number) for best performance and exact matching. Partial ID searches (type + number without court) fall back to live register lookups. Name searches query Unternehmensregister and Handelsregister VR.
Search queries are parsed to extract and validate ID components:
1. **Full ID Match**: If all three components (court, register type, number) are detected and yield an exact match, the **exact match is returned first** (with `matchReason.matchType = "id"`); other results may follow.
2. **Partial ID**: If 1-2 components are present (e.g., "HRB 228960" without court), results are found via live register lookups.
3. **Name Search Fallback**: If no valid ID parts are detected or the full ID lookup fails, a comprehensive name search is performed across all sources.
Court names are validated against the official list of 129 courts (with fuzzy matching for variations) and register types against the canonical set (HRA, HRB, VR, GsR, GnR, PR).
Name searches query both Unternehmensregister (for HRB, HRA, GnR, PR, GsR) and Handelsregister (for VR associations) in parallel.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. The filter removes companies deleted from the register. A company that is dissolved or in insolvency proceedings but not yet deleted is still returned.
## Company Status
Company status is determined **deterministically** from the Unternehmensregister or Handelsregister search results -- no AI inference is involved.
The `Local Status` column below is the exact string returned in `company.status.localName`. It is a closed list: the API always returns exactly one of these values, including the German umlauts.
### Non-VR Companies (HRB, HRA, GnR, PR, GsR)
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| `Aktiv` | Active | Active | Company found in register without deletion flag |
| `Gelöscht` | Deleted | Closed | Company marked as deleted in Unternehmensregister |
| `Geschlossenes Registerblatt` | Closed register sheet | Closed | The register closed this sheet, for example after the company moved its seat to another court (it then continues under a new registration number) or was merged. `legalRepresentatives` and `otherKeyPersons` are returned empty |
| `Insolvenzverfahren` | Insolvency proceedings | Under Insolvency Proceeding | Insolvency proceedings noted in the trade register extract |
| `Aufgelöst` | Dissolved | Closed | Dissolution noted in the trade register extract |
| `In Liquidation` | In liquidation | Closed | Liquidation noted in the trade register extract |
### VR Companies (Associations)
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| `Aktiv` | Active | Active | VR company found in Handelsregister search results |
For VR companies (associations), deleted entries are **not included in search results**. Therefore, any VR company found in search results is by definition active. The Aktueller Abdruck (trade register extract) may contain additional status details (e.g., "In Liquidation").
## Legal Forms
Legal form is **read deterministically from the trade register extract** and resolved against a standardized list of recognized German legal forms; AI is used only as a fallback for rare wordings outside that list. Each legal form is mapped to its full local name, English translation, standardized category, and ISO 20275 code. This ensures high accuracy, particularly for hybrid forms.
The `Local Name` column below is the **exact string returned in `company.legalForm.localName`**, character for character, including German umlauts (ä, ö, ü) and the abbreviation in parentheses where one exists. Forms without a common abbreviation (for example `Stille Gesellschaft`) are returned without parentheses. This is a closed list: the API always returns exactly one of these values, so you can map on `localName` directly.
### Corporations (Kapitalgesellschaften)
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| `Gesellschaft mit beschränkter Haftung (GmbH)` | Limited Liability Company | Limited Liability Company | 2HBR |
| `Unternehmergesellschaft (UG)` | Entrepreneurial Company with Limited Liability | Limited Liability Company | 63KS |
| `Aktiengesellschaft (AG)` | Public Limited Company | Corporation | 6QQB |
| `Kommanditgesellschaft auf Aktien (KGaA)` | Partnership Limited by Shares | Corporation | T0YJ |
| `Europäische Aktiengesellschaft (SE)` | European Company | Corporation | SGST |
| `Investmentaktiengesellschaft (InvAG)` | Investment Stock Corporation | Corporation | JMVF |
| `REIT-Aktiengesellschaft (REIT-AG)` | Real Estate Investment Trust Corporation | Corporation | AMKW |
| `Gemeinnützige Gesellschaft mit beschränkter Haftung (gGmbH)` | Non-Profit Limited Liability Company | Nonprofit Organization | SCE1 |
| `Gemeinnützige Unternehmergesellschaft (gUG)` | Non-Profit Entrepreneurial Company | Nonprofit Organization | 63KS |
| `Gemeinnützige Aktiengesellschaft (gAG)` | Non-Profit Public Limited Company | Nonprofit Organization | YA01 |
### Partnerships (Personengesellschaften)
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| `Gesellschaft bürgerlichen Rechts (GbR)` | Civil Law Partnership | Partnership | FR3V |
| `Eingetragene Gesellschaft bürgerlichen Rechts (eGbR)` | Registered Civil Law Partnership | Partnership | PDNU |
| `Offene Handelsgesellschaft (OHG)` | General Commercial Partnership | Partnership | 40DB |
| `Kommanditgesellschaft (KG)` | Limited Partnership | Partnership | 8Z6G |
| `Partnerschaftsgesellschaft (PartG)` | Professional Partnership | Partnership | 8CM0 |
| `Partnerschaftsgesellschaft mit beschränkter Berufshaftung (PartG mbB)` | Professional Partnership with Limited Professional Liability | Partnership | 2YZO |
| `Europäische wirtschaftliche Interessenvereinigung (EWIV)` | European Economic Interest Grouping | Partnership | JNDX |
| `Partenreederei` | Ship Partnership | Partnership | -- |
| `Stille Gesellschaft` | Silent Partnership | Partnership | -- |
### Sole Proprietorships
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| `Einzelunternehmen` | Sole Proprietorship | Sole Proprietorship | OL20 |
| `Eingetragener Kaufmann (e.K.)` | Registered Merchant | Sole Proprietorship | OL20 |
| `Eingetragene Kauffrau (e.Kfr.)` | Registered Merchant (Female) | Sole Proprietorship | OL20 |
| `Freiberufler` | Freelancer / Liberal Profession | Sole Proprietorship | -- |
### Hybrid Forms (Mischformen)
Hybrid forms are returned with the constituent forms written out in full, with the common short form in parentheses. For example a GmbH & Co. KG is returned as `Gesellschaft mit beschränkter Haftung & Co. Kommanditgesellschaft (GmbH & Co. KG)`, not as `GmbH & Co. KG`.
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| `Gesellschaft mit beschränkter Haftung & Co. Kommanditgesellschaft (GmbH & Co. KG)` | Limited Liability Company & Co. Limited Partnership | Partnership | 8Z6G |
| `Unternehmergesellschaft & Co. Kommanditgesellschaft (UG & Co. KG)` | Entrepreneurial Company & Co. Limited Partnership | Partnership | 8Z6G |
| `Aktiengesellschaft & Co. Kommanditgesellschaft (AG & Co. KG)` | Public Limited Company & Co. Limited Partnership | Partnership | 8Z6G |
| `Stiftung & Co. Kommanditgesellschaft (Stiftung & Co. KG)` | Foundation & Co. Limited Partnership | Partnership | 8Z6G |
| `Kommanditgesellschaft auf Aktien & Co. Kommanditgesellschaft (KGaA & Co. KG)` | Partnership Limited by Shares & Co. Limited Partnership | Partnership | 8Z6G |
| `Gesellschaft mit beschränkter Haftung & Co. Offene Handelsgesellschaft (GmbH & Co. OHG)` | Limited Liability Company & Co. General Commercial Partnership | Partnership | 40DB |
| `Aktiengesellschaft & Co. Offene Handelsgesellschaft (AG & Co. OHG)` | Public Limited Company & Co. General Commercial Partnership | Partnership | 40DB |
| `Gesellschaft mit beschränkter Haftung & Co. Kommanditgesellschaft auf Aktien (GmbH & Co. KGaA)` | Limited Liability Company & Co. Partnership Limited by Shares | Corporation | T0YJ |
| `Aktiengesellschaft & Co. Kommanditgesellschaft auf Aktien (AG & Co. KGaA)` | Public Limited Company & Co. Partnership Limited by Shares | Corporation | T0YJ |
| `Stiftung & Co. Kommanditgesellschaft auf Aktien (Stiftung & Co. KGaA)` | Foundation & Co. Partnership Limited by Shares | Corporation | T0YJ |
### Associations & Cooperatives
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| `Eingetragener Verein (e.V.)` | Registered Association | Nonprofit Organization | QZ3L |
| `Nicht eingetragener Verein` | Unregistered Association | Nonprofit Organization | 79H0 |
| `Wirtschaftlicher Verein` | Economic Association | Nonprofit Organization | 7J3S |
| `Verein alten Rechts` | Association under Old Law | Nonprofit Organization | D40E |
| `Eingetragene Genossenschaft (eG)` | Registered Cooperative | Cooperative | AZFE |
| `Genossenschaft` | Cooperative | Cooperative | US8E |
| `Europäische Genossenschaft (SCE)` | European Cooperative Society | Cooperative | SUA1 |
| `Versicherungsverein auf Gegenseitigkeit (VVaG)` | Mutual Insurance Association | Cooperative | 13AV |
### Public Law Entities & Foundations
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| `Körperschaft des öffentlichen Rechts (KdöR)` | Public Law Corporation | Government-Owned Entity | SQKS |
| `Anstalt des öffentlichen Rechts (AöR)` | Public Law Institution | Government-Owned Entity | XLWA |
| `Stiftung des öffentlichen Rechts` | Public Law Foundation | Trust | FEBD |
| `Stiftung des privaten Rechts` | Private Foundation | Trust | V2YH |
| `Kirchliche Stiftung des öffentlichen Rechts` | Ecclesiastical Public Law Foundation | Trust | YJ4C |
| `Landesinnungsverband` | State Guild Association | Nonprofit Organization | 9JGX |
| `Innung` | Guild | Nonprofit Organization | -- |
| `Zweckverband` | Special Purpose Association | Government-Owned Entity | -- |
Legal form is read deterministically from the trade register extract and resolved against this standardized list, with AI as a fallback for rare wordings outside it. The company name, the Rechtsform section, and the general-partner (persönlich haftender Gesellschafter) entries are used to correctly identify hybrid forms like a GmbH & Co. KG versus a plain Kommanditgesellschaft.
## Legal Representatives
Legal representatives come from the **Aktueller Abdruck** (current trade register extract). Every representative carries the German title as the register writes it in `role.localName`, plus `role.englishTranslation` and `role.standardized`.
### Legal Representative Roles
The tables below list the known catalogue of register titles; source wordings remain open. Build your mapping on `role.standardized`, which is a closed list, rather than on the German label.
**Managing bodies**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Geschäftsführer / Geschäftsführerin | Managing Director | Managing Director | GmbH, UG, gGmbH |
| Geschäftsleiter | Head of Management | Managing Director | GmbH, public-sector entities |
| Vorstand | Board Member | Board Member | AG, SE, eG, e.V. |
| Vorstandsmitglied | Board Member | Board Member | AG, SE |
| Vorstandsvorsitzender / Vorstandsvorsitzende | Chairman of the Board | Chairman of the Board | AG, SE |
| Mitglied des Leitungsorgans | Member of the Management Organ | Board Member | SE |
| Verwaltungsrat | Administrative Board | Board Member | SE (one-tier), eG |
| Verwaltungsratsmitglied | Administrative Board Member | Board Member | SE (one-tier), eG |
| Mitglied des Verwaltungsrats / Mitglied des Verwaltungsrates | Member of the Administrative Board | Board Member | SE (one-tier), eG |
| Präsident des Verwaltungsrats / Präsident des Verwaltungsrates | President of the Administrative Board | Chairman of the Board | SE (one-tier) |
| Geschäftsführender Direktor / Geschäftsführende Direktorin | Managing Director | Managing Director | SE (one-tier) |
| Direktor / Direktorin / Director | Director | Managing Director | Branches of foreign companies |
**Sole traders**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Inhaber / Inhaberin | Owner | Owner | e.K., e.Kfr., Einzelunternehmen |
**Partnerships**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Persönlich haftender Gesellschafter / Persönlich haftende Gesellschafterin | General Partner | General Partner | KG, OHG, GmbH & Co. KG |
| Komplementär / Komplementärin | General Partner | General Partner | KG, GmbH & Co. KG |
| Gesellschafter / Gesellschafterin | Partner | Partner | GbR, eGbR |
| Partner / Partnerin | Partner | Partner | PartG, PartG mbB |
**Prokura (§§ 48 ff. HGB)**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Prokurist / Prokuristin | Authorized Signatory | Authorized Signatory | All |
| Prokurist (Einzelprokura) | Authorized Signatory with sole Prokura | Authorized Signatory | All |
| Prokurist (Gesamtprokura) | Authorized Signatory with joint Prokura | Authorized Signatory | All |
**Winding-up**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Liquidator / Liquidatorin | Liquidator | Liquidator | All, when in liquidation |
| Abwickler / Abwicklerin | Liquidator | Liquidator | AG, SE, when in liquidation |
**Association boards (e.V.)**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Vorsitzender / Vorsitzende | Chairman / Chairwoman | Chairman of the Board | e.V. |
| Stellvertretender Vorsitzender / Stellvertretende Vorsitzende | Deputy Chairman / Deputy Chairwoman | Board Member | e.V. |
| Zweiter Vorsitzender / 2. Vorsitzender | Deputy Chairman | Board Member | e.V. |
| Präsident / Präsidentin | President | President | e.V. |
| Vizepräsident / Vizepräsidentin | Vice President | Vice President | e.V. |
| Schatzmeister / Schatzmeisterin | Treasurer | Treasurer | e.V. |
| Kassenwart / Kassierer | Treasurer | Treasurer | e.V. |
| Schriftführer / Schriftführerin | Secretary | Secretary | e.V. |
| Beisitzer / Beisitzerin | Board Member | Board Member | e.V. |
**Public-sector operating entities**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Betriebsleiter / Betriebsleiterin | Operations Manager | Managing Director | Eigenbetrieb, Zweckverband |
| Werkleiter / Werkleiterin | Works Manager | Managing Director | Eigenbetrieb, Zweckverband |
| Bürgermeister | Mayor | Managing Director | Eigenbetrieb, Regiebetrieb |
| Stadtrat | City Councillor | Board Member | Eigenbetrieb, Regiebetrieb |
| Verbandsvorsteher | Association Director | Managing Director | Zweckverband, KdöR |
**Foreign branches (§ 13e HGB)**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Ständiger Vertreter / Ständige Vertreterin | Permanent Representative of the branch | Other | German branch of a foreign company |
| Hauptbevollmächtigter | General Representative | Authorized Signatory | German branch of a foreign insurer |
### Supervisory Board Roles (`otherKeyPersons`)
Ordinary supervisory-board office is returned on `otherKeyPersons`, including wording variants resolved against the published catalogue. This does not mean the board has no statutory representation in any circumstances: [AktG §112](https://www.gesetze-im-internet.de/aktg/__112.html) gives it representation toward executive-board members. A supervisory title alone is not a general company signing mandate.
For a positively identified German monistic SE, administrative-board titles (`Verwaltungsrat` and its member/chair variants) also go to `otherKeyPersons` as `Board Member` or `Chairman of the Board` unless the extract separately records representation authority. [SEAG §41](https://www.gesetze-im-internet.de/seag/__41.html) gives ordinary representation to executive directors and limited representation to the administrative board. The exact per-person clause is retained when present. Foreign branches and unknown legal forms keep the source's representative-section context; a German SE rule is not applied to an unverified foreign-law office.
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Aufsichtsrat | Supervisory Board | Supervisory Board Member | AG, SE, KGaA |
| Aufsichtsratsmitglied | Supervisory Board Member | Supervisory Board Member | AG, SE, KGaA |
| Mitglied des Aufsichtsrats / Mitglied des Aufsichtsrates | Member of the Supervisory Board | Supervisory Board Member | AG, SE, KGaA |
| Pächter | Leaseholder | Other | e.K., Einzelkaufmann |
`otherKeyPersons` shares the verification extract source with `legalRepresentatives`, so requesting both requires no additional extract. The fast prefill people source currently returns only legal representatives. `role.standardized` on this datapoint comes from the other-key-person role list, which is separate from the legal-representative one.
**Other register wordings**
| `role.localName` | `role.englishTranslation` | `role.standardized` | Typical legal forms |
| - | - | - | - |
| Geschäftsführung | Management | Managing Director | GmbH, UG |
| Mitglied der Geschäftsleitung | Member of the Management | Manager | AG |
| Manager | Manager | Manager | GmbH |
| Verwalter | Administrator | Administrator | AG, GmbH |
| Stellvertreter | Deputy | Board Member | eG |
| Besonders bevollmächtigt Zeichnungsberechtigter | Specially Authorized Signatory | Authorized Signatory | AG |
| Vertretungsberechtigter | Authorized Representative | Other | Any, when the extract states no office |
**Feminine forms.** The register writes the gendered title and we return it as written, so `Geschäftsführerin` and `Geschäftsführer` are two distinct `localName` values with the same `standardized` value. Match on `standardized` and you never have to handle both.
**Inhaber applies to sole traders.** It is the role a registered sole trader carries in their own HRA entry: `Eingetragener Kaufmann (e.K.)`, `Eingetragene Kauffrau (e.Kfr.)` and `Einzelunternehmen` account for more than 99% of the Inhaber representatives in the German register. A company registered as a GmbH, AG or KG has a Geschäftsführer, Vorstand or persönlich haftender Gesellschafter instead.
The German label in `role.localName` is **not a closed list**, but `role.standardized` is.
The register writes the role as free text, so a company can carry a wording that is not in the tables above: a rare statutory title, a foreign-language rendering, a court typo. Under 0.1% of German legal representatives do. Those come back in `role.localName` exactly as the extract has them, and we match them onto the published list so `role.standardized` and `role.englishTranslation` are still filled with published values. A `Geschäftsfüherin` (missing an umlaut in the register) keeps that spelling in `role.localName` and gets `Managing Director` as its standardized role.
If a label cannot be resolved to a published office, the customer-facing extract parser fails rather than returning an invented office or a generic Other fallback. `role.standardized` is one of the published values. Map on it, and register spelling never reaches your data model.
Signing authority is not a role. `Einzelvertretungsberechtigt` and `Gesamtvertretungsberechtigt` are returned in the separate `representationMode` field described below, not in `role`.
### Representation Mode
Legal representatives include a `representationMode` field extracted from signing authority clauses in the **Aktueller Abdruck** (trade register extract). This field indicates how the representative can sign for the company:
* **`{ mode: "sole" }`**: Can sign alone ("Einzelvertretungsberechtigt", "Alleinvertretungsberechtigt" or "Einzelprokura")
* **`{ mode: "joint" }`**: Must sign jointly with others ("Gesamtvertretungsberechtigt" or "Gesamtprokura")
* **field absent**: The extract states no representation rule we could read for this person. This does not mean the person has no authority.
For Germany these are the only values. `minimumSignatories` and `namedCoSigners` are never set: a German joint rule such as "durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen" comes back as `{ mode: "joint" }`, and the exact combination is only in the trade register extract.
A per-person clause in the extract (for example "einzelvertretungsberechtigt" next to a name) takes precedence. Otherwise managing and board members get the company's general representation rule (*Allgemeine Vertretungsregelung*). When that rule says a single manager signs alone and several managers sign jointly, the mode depends on how many managers are registered. Prokuristen get their mode from Einzel- or Gesamtprokura, never from the general rule.
## Shareholders
German shareholder extraction uses a **multi-source strategy** that adapts based on the company's legal form.
### Extraction Logic
1. **Legal Form Analysis** -- The company's legal form determines:
* Whether it requires public shareholder disclosure (AG, SE, KGaA do **not**)
* Whether it is a partnership structure (KG, OHG, etc.) or corporate structure (GmbH, UG, etc.)
2. **Primary Source: Gesellschafterliste (Shareholder List)** -- For companies with disclosure requirements:
* The "Liste der Gesellschafter" document is used when available among filed documents
* This is the most comprehensive and authoritative source
* If found with shareholders, it is used exclusively
3. **Fallback Strategy** -- If no Gesellschafterliste is found or it returns empty:
**For Partnership Structures** (KG, GmbH & Co. KG, OHG):
* **First Priority**: Trade register extract (Aktueller Abdruck) -- Extracts Kommanditisten (limited partners) with capital contributions, identifies profit transfer agreements (100% control)
* **Last Resort**: Financial statements (only if trade register has no partners)
**For Corporate Structures** (GmbH, UG, AG, SE, KGaA):
* Both sources are checked: Trade register extract (for control statements) and Financial statements (for parent company identification)
### Data Sources Explained
| Source | When Used | Data Available |
| - | - | - |
| **Gesellschafterliste** | Companies with disclosure requirements (GmbH, UG, KG, OHG) | Complete shareholder list with percentages and capital contributions |
| **Trade Register Extract** | Partnerships (KG, OHG) and corporate control statements | Kommanditisten with capital, profit transfer agreements |
| **Financial Statements** | Fallback for parent company identification | Parent companies through control relationships |
### Partnership Structures (KG) -- Important Notes
German **KG (Kommanditgesellschaft)** and **GmbH & Co. KG** have two types of partners:
1. **Komplementar** (General Partner):
* Manages the company with unlimited personal liability
* **NOT included in shareholder results** -- they are managers, not economic owners
* Example: In "ABC GmbH & Co. KG", the "ABC GmbH" is the Komplementar
2. **Kommanditisten** (Limited Partners):
* Provide capital and own the economic value
* Have limited liability (only lose their capital contribution)
* **These ARE included as shareholders** with calculated percentages
When multiple Kommanditisten are listed with capital contribution amounts (Kommanditeinlage/Haftsumme), ownership percentages are automatically calculated from the capital amounts:
**Example:** VREF Germany ACB GmbH & Co. KG
* ACB Verwaltungs GmbH (Komplementar) -- **Excluded** (manager, not owner)
* Swiss Life AG -- **Included** as 5.1% shareholder (5,100 / 100,000)
* VREF Germany Real Estate Acquico -- **Included** as 94.9% shareholder (94,900 / 100,000)
Percentages are rounded to 1 decimal place. If a single shareholder holds 100%, only that shareholder is returned.
### Key Features
* **Smart prioritization**: Partnership structures prioritize the trade register over financial statements
* **Economic ownership focus**: Only returns actual shareholders/owners, excludes Komplementare
* **Automatic percentage calculation**: For KG structures, calculates ownership percentages from capital contributions
* **Deduplication**: Multiple sources are combined and deduplicated by shareholder identity
* **Company ID enrichment**: Company-type shareholders are enriched with full German registration IDs via search
* **Source attribution**: Each shareholder record includes the source document and extraction method
## Ultimate Beneficial Owners
UBOs are sourced from the Transparenzregister, which by law only grants access to obliged entities (Verpflichtete) carrying out their own AML check. Your account reaches it by one of two paths, and they differ in how long the data point takes to settle.
### Two delivery paths
| | Your own credentials | Partner-sourced |
| - | - | - |
| Applies to | Accounts with Transparenzregister credentials configured | Accounts without them |
| How | We query the register under your account's own obliged-entity access | A local partner obtains the official Transparenzregisterauszug under their own access, and we extract the owners from it |
| Time to settle | Seconds to minutes, within the same request | 1 to 3 business days |
| Setup | Configure credentials on your workspace (see [Register Credentials](/essentials/register-credentials)) | None |
| Response | `ultimateBeneficialOwners`, shape below | `ultimateBeneficialOwners`, same shape, plus the extract as a document |
| Request modes | Verification and prefill | Verification only |
The path is chosen for you from your account configuration. No request parameter selects it, and the response shape does not change.
Two consequences of the partner path being verification-only. Prefill mode needs your own credentials, and fails with `account_configuration_required` without them, because no partner order can settle inside a prefill window. Scheduled monitoring rechecks use the credentialed path for the same reason, so monitoring a German company's beneficial owners requires your own access.
### The partner-sourced wait
On the partner-sourced path `ultimateBeneficialOwners` stays `in_progress` for **several business days**. A request in that state is progressing normally. It is not a stalled or failed request.
* **Other data points in the same request are unaffected.** `companyProfile` reaching `succeeded` while `ultimateBeneficialOwners` is still `in_progress` is the ordinary shape of a German UBO request, not a partial failure.
* **The requestId stays valid throughout.** Keep polling it, or wait for the webhook. Re-issuing the same request does not make it faster: a second call for the same company attaches to the extract already in flight rather than ordering another one.
* **On delivery**, `ultimateBeneficialOwners` moves to `succeeded` and the webhook fires.
* **If the company has no beneficial ownership entry to give**, the data point fails with `no_document_available`.
* **The wait is capped at 7 days.** Past that the data point fails with `manual_document_timeout`, which is not retried automatically. Contact support if you still need the extract.
* **Billing follows the outcome.** The charge is reserved when the request is made and settles only on delivery. A data point that ends in failure is refunded automatically.
Plan for this on the partner-sourced path: treat a German UBO fetch as an asynchronous order with a multi-day horizon rather than a call you can block on, and drive it from the webhook.
### Registered owners and the German fallback
German law defines a beneficial owner as a natural person holding more than 25% of the capital, controlling more than 25% of the voting rights, or exercising control in a comparable way. Where no such person exists, the German AML act (§ 3 Abs. 2 S. 5 GwG) treats the company's legal representatives, managing partners and partners as the beneficial owners instead. The register calls these *fiktive wirtschaftlich Berechtigte* and records them in place of a real owner.
Both kinds are returned on `ultimateBeneficialOwners`. Read `control` to tell them apart:
| | Registered owner | Fallback (fiktiv) |
| - | - | - |
| `control.description` | The register's own German wording for the interest held | Starts with `Fictitious UBO (§ 3 Abs. 2 S. 5 GwG)` |
| `control.details` | The percentage, where the register states one | No percentage. The register states none for the fallback |
| `control.types` | `ownership-of-shares` or `voting-rights` | `significant-influence-or-control` |
`control.types` alone does not separate the two. `significant-influence-or-control` also covers a registered owner who controls the company through dominant influence rather than through shares. Match on the `control.description` prefix.
The fallback is applied by the German register under German law, so the set of people is the one the German act names: legal representatives, managing partners and partners. It follows the same principle as the senior managing official fallback in EU AML rules, but it is not defined by them. We return what the register recorded. Whether that set satisfies your own obligation is your determination.
## Subsidiaries
`subsidiaries` is available for Germany. It returns the equity participations the queried company holds in other entities, taken from the shareholdings list (Anteilsbesitzliste, §285 Nr. 11 HGB) in the notes of the company's annual financial statement, or from the subsidiaries list (§313 HGB) in a published consolidated group statement. Values are AI-extracted, so verify them against the filing before relying on them for compliance.
Availability follows German disclosure law, not our coverage:
* A company that has published no annual or consolidated accounts returns no subsidiaries.
* Small and micro companies are exempt from disclosing the shareholdings list, so they return none even when they hold participations.
* Micro-company balance-sheet deposits carry no notes, so they never contain a shareholdings list.
`subsidiaries` is a separate data block from `company`, and it is available in verification mode only. See the [Subsidiaries](/essentials/subsidiaries-extraction) guide for the response shape.
## Data Availability Matrix
| Data Type | HRB/HRA/GnR/PR/GsR | VR (Associations) | Notes |
| - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | Extracted from the Aktueller Abdruck |
| Legal Representatives | ✅ Async | ✅ Async | Extracted from the Aktueller Abdruck |
| Other Key Persons | ✅ Async | ✅ Async | Supervisory board and other non-binding roles, from the same extract. See [Supervisory Board Roles](#supervisory-board-roles-otherkeypersons) |
| Shareholders | ✅ Multi-source | ❌ | Gesellschafterliste, trade register, financial statements |
| Subsidiaries | ⚠️ Depends on published accounts | ⚠️ Depends on published accounts | From the shareholdings list (Anteilsbesitzliste, §285 Nr. 11 HGB) in the annual accounts, or the subsidiaries list (§313 HGB) in consolidated group accounts. See [Subsidiaries](#subsidiaries) |
| Ultimate Beneficial Owners | ✅ Async | ✅ Async | From the Transparenzregister. Both modes with your own credentials; otherwise partner-sourced over 1 to 3 business days in verification mode only. See [Ultimate Beneficial Owners](#ultimate-beneficial-owners) |
| Establishments | ❌ | ❌ | Not available from German registers |
| Activity Codes | ⚠️ AI-inferred | ⚠️ AI-inferred | Derived from Gegenstand des Unternehmens |
| Documents | ✅ | ⚠️ Limited | VR: Aktueller Abdruck, Chronologischer Abdruck and UBO extract; Others: full document set |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
## Register Documents
Two register extracts are available for every company (all entity types, including VR associations) and delivered as PDF. Retrieve them by listing `availableDocuments` and ordering the returned document id through `/v2/company`.
| Document | Local name | Response field | Contents |
| - | - | - | - |
| **Trade Register Extract** | Aktueller Abdruck | `documents.tradeRegisterExtract` | The currently valid register entries only -- current name, legal form, registered seat, management and representation, share capital or partners, and current status. |
| **Trade Register History** | Chronologischer Abdruck | `documents.tradeRegisterHistory` | The full chronological record of register entries since the register moved to electronic record-keeping (around 2002/2003) -- former and current names, legal forms, registered seats, managing directors and authorised signatories, capital changes, and incorporation and dissolution dates. |
The Trade Register History (Chronologischer Abdruck) covers the chronological record from the register's switch to electronic record-keeping onward. For entities registered before then, entries predating that switch are held in a separate historical extract (Historischer Abdruck), which is not currently offered.
### Ordering the beneficial ownership certificate
`availableDocuments` lists `ultimateBeneficialOwnersCertificate`. With your own Transparenzregister credentials, it uses your account’s access. Without credentials, it offers the partner-supplied certificate instead, with delivery over several business days. For the partner option, the document and the structured `ultimateBeneficialOwners` datapoint use the same certificate. Follow the request through webhooks or polling until it completes.
## Activity Code Mapping
Germany does not use a structured national activity code in the Handelsregister. Activity codes are **AI-inferred** from the company's `Gegenstand des Unternehmens` (company purpose) field, which is a free-text description extracted from the Aktueller Abdruck document.
```
Gegenstand des Unternehmens (free text) → ISIC Rev. 5 (AI-inferred) → NACE Rev. 2.1 (mapped from ISIC)
→ WZ 2008 (AI-inferred) → WZ 2025 (derived)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NACE** | NACE Rev. 2.1, mapped from the ISIC code through the ISIC/NACE correspondence table | `62.10` | Yes (always, inherited from the ISIC code) |
| **ISIC** | ISIC Rev. 5, derived from activity description via AI | `6219` | Yes (always) |
| **WZ\_2008** | German national classification, derived from activity description via AI | `62.01.9` | Yes (always) |
| **WZ\_2025** | German national classification (current edition), up-converted from the WZ 2008 code | `62.10.9` | Yes (always) |
All German activity codes are **AI-inferred** because the trade register provides only a free-text business purpose description, not structured activity codes. The `isAIInferred` flag is always `true`.
`WZ_2025` is the current edition of the German Klassifikation der Wirtschaftszweige (the national implementation of NACE Rev. 2.1). It is returned alongside `WZ_2008` and up-converted from it using the official Destatis correspondence table. A WZ 2008 code that splits into several WZ 2025 codes returns all of them, so `company.activities.WZ_2025` can contain more than one entry.
**Main activity.** Each classification returns a single best-match code for the company purpose, so that code carries `isMainActivity: true` (always together with `isAIInferred: true`, since the judgment is the model's, not the register's). A WZ 2008 code with exactly one WZ 2025 successor passes the flag on; when it splits into several WZ 2025 codes, none of them is flagged because the main successor cannot be determined.
## Documents by Company Type
### Non-VR Companies (HRB, HRA, GnR, PR, GsR)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Aktueller Abdruck** | `tradeRegisterExtract` | PDF | ✅ All companies | Official trade register extract |
| **Chronologischer Abdruck** | `tradeRegisterHistory` | PDF | ✅ All companies | Chronological register history (see [Register Documents](#register-documents)) |
| **Dokumentenansicht Documents** | `articlesOfAssociation[]`, `financialStatements[]`, `otherDocuments[]` | PDF | ✅ When filed | Satzung, Gesellschaftsvertrag, Gesellschafterliste, resolutions, etc. (AI-classified) |
| **Financial Statements** | `financialStatements[]` | PDF | ✅ Almost all companies | A listed issuer's ESEF-tagged consolidated statement is the one exception (see note). Deposited micro-company accounts are offered as a separate document |
| **Publications** | `otherDocuments[]` | PDF | ✅ When available | Register announcements |
| **Transparenzregister UBO extract** | `ultimateBeneficialOwnersCertificate` | PDF | ⚠️ Accounts with their own Transparenzregister access | See [Ultimate Beneficial Owners](#ultimate-beneficial-owners) |
### VR Companies (Associations)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Aktueller Abdruck** | `tradeRegisterExtract` | PDF | ✅ All associations | Trade register extract via Handelsregister |
| **Chronologischer Abdruck** | `tradeRegisterHistory` | PDF | ✅ All associations | Chronological register history via Handelsregister |
| **Transparenzregister UBO extract** | `ultimateBeneficialOwnersCertificate` | PDF | ⚠️ Accounts with their own Transparenzregister access | Same as for other entities; see [Ultimate Beneficial Owners](#ultimate-beneficial-owners) |
**VR companies have limited document availability.** Associations in the Vereinsregister (VR) have the Aktueller Abdruck, the Chronologischer Abdruck and the Transparenzregister UBO extract only. Dokumentenansicht documents (including a standalone Satzung), publications, and financial statements are **not available** for VR companies.
**Financial statements are moving to structured data.** Since the 2022 disclosure reform, companies file their published annual statements to the register as structured data rather than plain PDF. We retrieve these directly, so `financialStatements[]` still returns a statement for almost every company. The one exception is a listed issuer's ESEF-tagged consolidated statement (required under the EU Transparency Directive), which the register does not make available in any form. Deposited micro-company accounts (voluntary publication) remain available as a separate document.
## Data Source Priority & Routing
Requests are routed based on register type, detected from the company's registration number:
**Routing Logic by Register Type:**
1. **VR (Vereinsregister)** -- Always routed to **Handelsregister**:
* Search: Handelsregister VR search
* Company status: Handelsregister VR status check
* Aktueller Abdruck: Retrieved from the official register
* Documents: Aktueller Abdruck and Chronologischer Abdruck only
2. **HRB, HRA, GnR, PR, GsR** -- Routed to **Unternehmensregister** (with Handelsregister fallback):
* Search: Unternehmensregister search API
* Company status: Unternehmensregister search result
* Aktueller Abdruck: Retrieved from Unternehmensregister or Handelsregister
* Documents: Dokumentenansicht + Publications from Unternehmensregister
### Prefill mode (fast retrieval)
[`POST /v2/company`](/essentials/retrieve_company) with [`mode: "prefill"`](/essentials/modes) provides fast, cost-effective access to company profile data for Germany, optimized for prefill requests.
* **Coverage**: HRB, HRA, GnR, PR, and GsR registers
* **VR Register**: VR associations (e.V.) are not available in prefill mode. An prefill request for a VR company fails with `invalid_request`; request it in verification mode instead
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "DE", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "München HRB 228960",
"countryCode": "DE",
"identifiers": { "registerCourt": "München", "registerType": "HRB", "registerNumber": "228960" },
"legalName": "Beispiel Software GmbH",
"registrationDate": "2019-05-15",
"activityDescription": "Gegenstand des Unternehmens ist die Entwicklung und der Vertrieb von Software.",
"status": { "localName": "Aktiv", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Gesellschaft mit beschränkter Haftung (GmbH)", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "2HBR" },
"capital": { "amount": 25000, "currency": "EUR" },
"activities": {
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "6219", "description": "Other computer programming activities", "isAIInferred": true, "isMainActivity": true }],
"WZ_2008": [{ "code": "62.01.9", "description": "Sonstige Softwareentwicklung", "isAIInferred": true, "isMainActivity": true }],
"WZ_2025": [
{ "code": "62.10.2", "description": "Entwicklung und Programmierung von Computerspielen", "isAIInferred": true },
{ "code": "62.10.3", "description": "Entwicklung und Programmierung von Anwendungssoftware", "isAIInferred": true },
{ "code": "62.10.4", "description": "Entwicklung und Programmierung von künstlicher Intelligenz und maschinellem Lernen", "isAIInferred": true },
{ "code": "62.10.9", "description": "Programmierungstätigkeiten a. n. g.", "isAIInferred": true }
]
},
"legalAddress": { "addressLine1": "Maximilianstrasse 35", "city": "München", "postalCode": "80539", "countryCode": "DE" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Geschäftsführer", "standardized": "Managing Director" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Max SCHMIDT" } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Prokurist", "standardized": "Authorized Signatory" }, "representationMode": { "mode": "joint" }, "individual": { "name": { "fullName": "Anna WEBER" } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 60, "individual": { "name": { "fullName": "Max SCHMIDT" } } },
{ "entityId": "company_001", "type": "company", "sharePercentage": 40, "company": { "legalName": "Investment Holdings GmbH" } }
]
}
```
```json theme={null}
{
"company": {
"id": "Hamburg HRA 12345",
"countryCode": "DE",
"identifiers": { "registerCourt": "Hamburg", "registerType": "HRA", "registerNumber": "12345" },
"legalName": "Norddeutsche Handel GmbH & Co. KG",
"registrationDate": "2010-08-20",
"activityDescription": "Gegenstand des Unternehmens ist der Grosshandel mit Waren aller Art.",
"status": { "localName": "Aktiv", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Gesellschaft mit beschränkter Haftung & Co. Kommanditgesellschaft (GmbH & Co. KG)", "englishTranslation": "Limited Liability Company & Co. Limited Partnership", "standardized": "Partnership", "iso20275Code": "8Z6G" },
"activities": {
"NACE": [{ "code": "46.90", "description": "Non-specialised wholesale trade", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "4690", "description": "Non-specialised wholesale trade", "isAIInferred": true, "isMainActivity": true }],
"WZ_2008": [{ "code": "46.90.1", "description": "Großhandel mit Rohstoffen, Halb- und Fertigware, ohne ausgeprägten Schwerpunkt", "isAIInferred": true, "isMainActivity": true }],
"WZ_2025": [{ "code": "46.90.3", "description": "Großhandel mit Rohstoffen, Halb- und Fertigwaren, ohne ausgeprägten Schwerpunkt", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "Jungfernstieg 22", "city": "Hamburg", "postalCode": "20354", "countryCode": "DE" }
},
"legalRepresentatives": [
{ "entityId": "company_001", "type": "company", "role": { "localName": "Persönlich haftender Gesellschafter", "standardized": "General Partner" }, "representationMode": { "mode": "sole" }, "company": { "legalName": "Norddeutsche Verwaltungs GmbH" } }
],
"shareholders": [
{ "entityId": "company_002", "type": "company", "sharePercentage": 51, "company": { "legalName": "Holding Nord AG" }, "nominalCapitalHeld": { "amount": 510000, "currency": "EUR" } },
{ "entityId": "person_001", "type": "individual", "sharePercentage": 49, "individual": { "name": { "fullName": "Friedrich MEYER" } }, "nominalCapitalHeld": { "amount": 490000, "currency": "EUR" } }
]
}
```
**Note:** The Komplementar (Norddeutsche Verwaltungs GmbH) appears as a legal representative but is **excluded** from shareholders. Only Kommanditisten (limited partners) are included as shareholders with calculated ownership percentages.
```json theme={null}
{
"company": {
"id": "Köln HRB 98765",
"countryCode": "DE",
"identifiers": { "registerCourt": "Köln", "registerType": "HRB", "registerNumber": "98765" },
"legalName": "Alte Handels GmbH",
"registrationDate": "2005-03-01",
"activityDescription": "Gegenstand des Unternehmens war der Handel mit Konsumgutern.",
"status": { "localName": "Gelöscht", "active": false, "statusDetails": { "status": "CLOSED" } },
"legalForm": { "localName": "Gesellschaft mit beschränkter Haftung (GmbH)", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "2HBR" },
"capital": { "amount": 25000, "currency": "EUR" },
"activities": {
"NACE": [{ "code": "47.12", "description": "Other non-specialised retail sale", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "4719", "description": "Other non-specialized retail sale", "isAIInferred": true, "isMainActivity": true }],
"WZ_2008": [{ "code": "47.19.1", "description": "Einzelhandel mit Waren verschiedener Art (ohne Nahrungsmittel)", "isAIInferred": true, "isMainActivity": true }],
"WZ_2025": [
{ "code": "47.12.1", "description": "Einzelhandel mit Waren verschiedener Art, ohne Nahrungsmittel", "isAIInferred": true },
{ "code": "47.91.1", "description": "Versteigerungsgewerbe im Einzelhandel ohne ausgeprägten Schwerpunkt", "isAIInferred": true },
{ "code": "47.91.2", "description": "Sonstige Vermittlungstätigkeiten für den Einzelhandel ohne ausgeprägten Schwerpunkt", "isAIInferred": true }
]
},
"legalAddress": { "addressLine1": "Hohenzollernring 50", "city": "Köln", "postalCode": "50672", "countryCode": "DE" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Liquidator", "standardized": "Liquidator" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Hans WEBER" } } }
]
}
```
**Note:** Closed companies have `active: false` and local status `Gelöscht`, based on deletion information from the Unternehmensregister.
```json theme={null}
{
"company": {
"id": "Berlin (Charlottenburg) VR 38000",
"countryCode": "DE",
"identifiers": { "registerCourt": "Berlin (Charlottenburg)", "registerType": "VR", "registerNumber": "38000" },
"legalName": "Berliner Kulturverein e.V.",
"registrationDate": "2018-02-10",
"activityDescription": "Zweck des Vereins ist die Forderung von Kunst und Kultur.",
"status": { "localName": "Aktiv", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Eingetragener Verein (e.V.)", "englishTranslation": "Registered Association", "standardized": "Nonprofit Organization", "iso20275Code": "QZ3L" },
"activities": {
"NACE": [{ "code": "90.31", "description": "Operation of arts facilities and sites", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "9031", "description": "Operation of arts facilities and sites", "isAIInferred": true, "isMainActivity": true }],
"WZ_2008": [{ "code": "90.04.2", "description": "Opern- und Schauspielhäuser, Konzerthallen und ähnliche Einrichtungen", "isAIInferred": true, "isMainActivity": true }],
"WZ_2025": [
{ "code": "90.31.1", "description": "Spielstätten für Schauspiel und Musiktheater", "isAIInferred": true },
{ "code": "90.31.3", "description": "Live-Musikspielstätten, Musikclubs und ähnliche soziokulturelle Zentren", "isAIInferred": true },
{ "code": "90.31.9", "description": "Betrieb von Einrichtungen für kunstschaffende Tätigkeiten und darstellende Künste a. n. g.", "isAIInferred": true }
]
},
"legalAddress": { "addressLine1": "Unter den Linden 10", "city": "Berlin", "postalCode": "10117", "countryCode": "DE" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Vorstandsvorsitzender", "standardized": "Chairman of the Board" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Petra WAGNER" } } }
]
}
```
**Note:** VR companies (associations) are sourced from Handelsregister. No shareholder data is available for associations. Besides the Transparenzregister UBO extract, only the Aktueller Abdruck and the Chronologischer Abdruck documents are available. There is no standalone Satzung (`articlesOfAssociation`).
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
**Non-VR companies (HRB, HRA, GnR, PR, GsR):**
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Aktueller Abdruck (current register extract) PDF | All companies |
| `tradeRegisterHistory` | Chronologischer Abdruck (register history) PDF | All companies |
| `financialStatements[]` | Annual accounts PDF | When published. Deposited micro-company accounts are offered as a separate document |
| `articlesOfAssociation[]` | Satzung, Gesellschaftsvertrag | When filed (AI-classified) |
| `otherDocuments[]` | Gesellschafterliste, resolutions, register announcements | When available (AI-classified) |
**VR companies (Associations):**
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Aktueller Abdruck (current register extract) PDF | Available for all associations |
| `tradeRegisterHistory` | Chronologischer Abdruck (register history) PDF | Available for all associations |
| `ultimateBeneficialOwnersCertificate` | Transparenzregister UBO extract PDF | Same availability rules as for other entities; see [Ultimate Beneficial Owners](#ultimate-beneficial-owners) |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Composite registration number** | German company IDs consist of three parts: Register Court + Register Type + Number (e.g., "München HRB 228960"). All three together give an exact, unique match. Search also accepts partial inputs (court + number, register type + number, or just the number) in any order, and the abbreviated court code (e.g. "HRB 23591 KI"); partial inputs may return more than one candidate, so pass the full ID to `/v2/company`. |
| **129 register courts** | Companies can be registered at any of 129 Amtsgerichte across Germany. Fuzzy matching supports variations (e.g., "Munchen" for "München", "Berlin Charlottenburg" for "Berlin (Charlottenburg)"). |
| **VR companies use different source** | VR (Vereinsregister) companies are routed to Handelsregister. All other register types use Unternehmensregister. Never mix the sources. VR companies have the Aktueller Abdruck, the Chronologischer Abdruck and the Transparenzregister UBO extract, with no Dokumentenansicht documents (so no standalone Satzung), publications or financial statements. |
| **Variable register availability** | Both Unternehmensregister and Handelsregister have variable availability. Automatic retries are used to maximize reliability. For Aktueller Abdruck, non-VR companies query both sources. |
| **All activity codes are AI-inferred** | The Handelsregister provides only free-text business purpose (Gegenstand des Unternehmens). ISIC (Rev. 5) and WZ 2008 codes are AI-inferred from it, and NACE (Rev. 2.1) is mapped from the ISIC code, so all four classifications carry `isAIInferred: true`. WZ 2025 is up-converted from the WZ 2008 code and may contain several entries when a WZ 2008 code splits. |
| **Legal representatives follow the register wording** | Names, roles and signing authority are read straight from the Aktueller Abdruck text, so the same extract always returns the same representatives. The German role is returned as written and enriched with an English translation and a standardized role. |
| **Komplementare excluded from shareholders** | In KG/GmbH & Co. KG structures, general partners (Komplementare) are legal representatives, not shareholders. Only Kommanditisten (limited partners) are returned as shareholders. |
| **Legal form read from the extract** | Legal form is read deterministically from the Rechtsform section and resolved against the standardized list, including hybrid forms (GmbH & Co. KG, UG & Co. KG, etc.). AI is used only as a fallback for rare wordings. |
| **Prefill profile coverage** | Prefill data covers HRB/HRA/GnR/PR/GsR registers. VR associations are not available in prefill mode: the request fails with `invalid_request`, so request them in verification mode. |
| **Micro-company accounts are a separate document** | Regular companies publish their annual accounts. Micro-companies may deposit a balance sheet instead, which is listed as a separate document. See the pricing page for how each is billed. |
| **Aktueller Abdruck freshness** | Trade register extracts are kept up to date based on the register's latest update information. |
| **UBOs take days without your own Transparenzregister access** | Ultimate Beneficial Owners are not publicly accessible in Germany -- they're sourced from the Transparenzregister, which by law only grants access to obliged entities (Verpflichtete) making their own AML/KYC check. An account with its own credentials configured on its workspace (see [Register Credentials](/essentials/register-credentials)) gets them within the request, in seconds to minutes, in either request mode. An account without them is served through a local partner instead, so `ultimateBeneficialOwners` stays `in_progress` for 1 to 3 business days before settling. That partner path covers verification only: prefill mode and scheduled monitoring rechecks still return `account_configuration_required` without your own credentials. See [Ultimate Beneficial Owners](#ultimate-beneficial-owners) for the full behaviour, and contact [support@topograph.co](mailto:support@topograph.co) for help getting set up as an obliged entity. |
| **Shareholder extraction is multi-source** | Shareholders come from up to three sources (Gesellschafterliste, trade register extract, financial statements) with AI-driven legal form analysis determining the extraction path. |
# Greece
Source: https://docs.topograph.co/essentials/greece
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Greece reference is on the [Greece country page](https://www.topograph.co/countries/gr).
## Start here
This guide contains public integration notes for Greece. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Greece uses a single official registry operated by the Union of Hellenic Chambers of Commerce.
* **Γ.Ε.ΜΗ. (Γενικό Εμπορικό Μητρώο), General Commercial Registry (GEMI).** Maintained by the Union of Hellenic Chambers of Commerce since 2012, GEMI is the **sole data source** for all Greek commercial entities. It is reached through two surfaces:
* The **GEMI Open Data API** ([businessportal.gr](https://www.businessportal.gr)) — structured data powering the authoritative **verification** mode: company profiles, legal representatives, shareholders, activity codes, documents, and corporate announcements.
* The **GEMI Publicity Portal** ([publicity.businessportal.gr](https://publicity.businessportal.gr)) — powers company **search** and the fast **prefill** profile (company details, management, ownership, and activity codes), plus printable trade register extracts and financial statements.
**Retrieval modes.** Both modes return authoritative GEMI data for the same datapoints.
* **`mode: "prefill"`** (fast) — sourced from the GEMI Publicity Portal; returned in seconds.
* **`mode: "verification"`** (default) — sourced from the GEMI Open Data API, additionally geocoding the registered address and standardizing management roles. Slower but richer.
**Rate Limit:** The GEMI Open Data API enforces a rate limit of **8 requests per minute** (handled automatically). Search and the prefill profile use the Publicity Portal and are not subject to it.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All commercial entities** | GEMI | Up to 12 digits, no leading zeros (GEMI Number) | `31301000` | Primary identifier for company profile lookups. Leading zeros may be sent or omitted (`000031301000` is the same company) |
**GEMI Number Format:** the full GEMI number is 12 digits: a 7-digit serial number, a 2-digit code of the GEMI office that registered the entity, and a 3-digit branch number. It is returned without leading zeros, so it can be shorter (e.g., `301000`, `31301000`, `8271901000`, `101933403000`). In the records we have seen, a company ends in `000`. There is no check digit.
**GEMI Number only for company retrieval.** `/v2/company` only accepts the GEMI Number for Greek company-data requests. To look up a company by VAT number or name, use the search endpoint first to retrieve the GEMI Number, then use that for the company request.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `gemiNumber` | Up to 12 digits, no leading zeros | `31301000` | All companies |
| `vatNumber` | EL + 9 digits, leading zeros significant, last digit a check digit | `EL093808863` | VAT-registered companies |
| `taxNumber` | 9 digits (AFM), leading zeros significant, last digit a check digit | `093808863` | All companies with tax registration |
| `euid` | ELGEMI. + 12 digits | `ELGEMI.000031301000` | Supported domestic AE and IKE companies |
EUID is optional and returned in prefill and verification when the source confirms the company identity, supported legal form and non-branch status. The GEMI number is padded to 12 digits; the prefix is `ELGEMI`, not `GR`. It cannot be used as a search input. See [EUID coverage](/essentials/euid).
**VAT derived from AFM:** Greek VAT numbers are simply `EL` + AFM (Tax Number). For example, AFM `093808863` becomes VAT `EL093808863`. Note that Greece uses the prefix `EL` (not `GR`) for EU VAT purposes.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the GEMI number (`gemiNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By GEMI Number | Up to 12 digits, with or without leading zeros | `31301000` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | EL + 9 digits | `EL093808863` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT (plain AFM) | 9 digits | `093808863` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT (GR prefix) | GR + 9 digits | `GR093808863` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 2 chars) | `"CHEMCE"` | Fuzzy | Multiple results (about 10 per query) |
**Search Performance:** A single query is matched against name, GEMI Number, and AFM at once, and returns quickly for every input type, including broad name terms. Identifier searches return the exact match first (`matchType: id`); name searches are tokenized and return about 10 results per query, so refine a broad name or search by GEMI Number or VAT number instead. Search is free (no catalog item charge).
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Establishments
`establishments` returns registered branches listed by GEMI in both prefill and verification mode. Each entry includes its GEMI number, name, address, and incorporation date where published.
The list covers registered branches, rather than every shop or operating site. An empty list means GEMI lists no branches for the company. Branch activity status is not published, so `active` is omitted.
## Company Status
Company status is mapped **deterministically** from GEMI's official status catalog. All 12 GEMI status codes are mapped to standardized statuses.
### Active Statuses
| ID | Greek Status | English | Standardized Status | Notes |
| - | - | - | - | - |
| 3 | Ενεργή | Active | Active | Standard active status |
| 4 | Σε Αδράνεια | Dormant | Active | Legally active but not operating |
### Insolvency Statuses
| ID | Greek Status | English | Standardized Status | Closure Reason |
| - | - | - | - | - |
| 5 | Πτώχευση | Bankruptcy | Under Insolvency Proceeding | Bankruptcy |
| 15 | Διαδικασία Συνδιαλλαγής | Conciliation Procedure | Under Insolvency Proceeding | N/A |
| 19 | Αναγκαστική διαχείριση | Forced Administration | Under Insolvency Proceeding | N/A |
### Closed Statuses
| ID | Greek Status | English | Standardized Status | Closure Reason |
| - | - | - | - | - |
| 7 | Λύση - Εκκαθάριση | Dissolution - Liquidation | Closed | Liquidation |
| 17 | Διαγραφή | Deletion | Closed | Administrative Dissolution |
| 18 | Διαγραφή λόγω συγχώνευσης | Deletion due to Merger | Closed | Merger |
| 20 | Διαγραφή λόγω διάσπασης | Deletion due to Division | Closed | Other |
### Inactive (Not Closed) Statuses
| ID | Greek Status | English | Standardized Status | Notes |
| - | - | - | - | - |
| 21 | Αναστολή καταχώρησης | Registration Suspended | Inactive Not Closed | Registration is suspended; the company is not struck off |
### Other Statuses
| ID | Greek Status | English | Standardized Status | Notes |
| - | - | - | - | - |
| 2 | Προεγγραφή | Pre-registration | Unknown | Registration in progress |
| 0 | Άλλο | Other | Unknown | Catch-all status |
The local Greek status text is always preserved alongside the standardized status. Closure dates and insolvency start dates are derived from the `lastStatusChange` field when available.
**Registration suspension.** GEMI records a registration suspension (αναστολή καταχώρισης) separately from the company status, so a suspended company usually keeps the status Ενεργή (Active) in the register. In both modes, a company the register reports as suspended is returned with `active: false` and `statusDetails.status: "INACTIVE_NOT_CLOSED"`. It is not struck off, and the suspension lifts once the outstanding filings are made. `localName` keeps the register's formal status and adds the suspension wording (σε αναστολή καταχώρισης), and the statutory grounds and their dates are returned in `statusDetails.additionalInfo`.
## Legal Forms
Legal forms are mapped **deterministically** from GEMI's official legal type catalog. All mappings include the local Greek abbreviation, English translation, standardized form, and ISO 20275 (ELF) code.
### Corporations
| ID | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 1 | ΑΕ | Public Limited Company | Corporation | W2NK |
| 12 | Ευρωπαϊκή Εταιρία (SE) | European Company (SE) | Corporation | CQ5X |
### Limited Liability Companies
| ID | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 8 | ΕΠΕ | Limited Liability Company (LLC) | Limited Liability Company | H6OR |
| 19 | ΙΚΕ | Private Company (PC) | Limited Liability Company | QCA0 |
### Partnerships
| ID | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 2 | ΟΕ | General Partnership (GP) | Partnership | TIZ2 |
| 4 | ΕΕ | Limited Partnership (LP) | Partnership | 54AL |
| 68 | ΕΕ κατά μετοχές | Limited Partnership by Shares | Partnership | UCU5 |
| 14 | Κοινοπραξία | Consortium / Joint Venture | Partnership | MCWR |
| 10 | Ευρωπαϊκός Όμιλος Οικονομικού Σκοπού | European Economic Interest Grouping (EEIG) | Partnership | QNWW |
### Cooperatives
| ID | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 11 | Συνεταιρισμός | Cooperative | Cooperative | J3VJ |
| 13 | Ευρωπαϊκή Συνεταιριστική Εταιρία (SCE) | European Cooperative Society (SCE) | Cooperative | J3VJ |
| 20 | ΚΟΙ.Σ.Π.Ε | Limited Liability Social Cooperative (LLSCo) | Cooperative | J3VJ |
| 66 | Κοιν.Σ.Επ. | Social Cooperative Enterprise (SoCC) | Cooperative | J3VJ |
| 67 | Συνεταιρισμός Εργαζομένων | Workers' Cooperative | Cooperative | J3VJ |
| 65 | Ενεργειακή Κοινότητα | Energy Community | Cooperative | J3VJ |
| 3 | ΣυνΠΕ | Limited Liability Cooperative | Cooperative | J3VJ |
| 21 | Αγροτικός Συνεταιρισμός | Agricultural Cooperative | Cooperative | J3VJ |
| 69 | Κοινότητα Ανανεώσιμης Ενέργειας | Renewable Energy Community | Cooperative | J3VJ |
| 70 | Ενεργειακή Κοινότητα Πολιτών | Citizens Energy Community | Cooperative | J3VJ |
### Nonprofits & Civil Entities
| ID | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 17 | ΕΝΩΣΗ ΠΡΟΣΩΠΩΝ | Association of Persons | Nonprofit Organization | QSYQ |
| 18 | ΑΣΤΙΚΗ ΕΤΑΙΡΕΙΑ 784 Α.Κ. | Civil Company (Art. 784 Civil Code) | Nonprofit Organization | HKVP |
| 9 | ΚΟΙΝΩΝΙΑ | Society / Community | Nonprofit Organization | HKVP |
### Other
| ID | Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| 16 | ΑΤΟΜΙΚΗ | Sole Proprietorship | Sole Proprietorship | N/A |
| 15 | Υποκατάστημα Αλλοδαπής | Branch of Foreign Company | Other | N/A |
| 64 | ΛΟΙΠΩΝ ΥΠΟΧΡΕΩΝ | Other Liable Entities | Other | JYKN |
All legal form mappings are deterministic, not AI-enriched. The local Greek abbreviation is always preserved alongside the English translation, standardized form, and ISO 20275 code.
## Legal Representatives
Legal representatives are extracted from the GEMI registry, and the classification (legal representative vs. other key person) is **legal-form aware**. It follows Greek company law on who legally represents each form (e.g. the *managing director* of an ΑΕ, the *manager* / *διαχειριστής* of an ΙΚΕ/ΕΠΕ, or the *general partner* of an ΟΕ/ΕΕ; a limited partner is never a representative). For a **sole proprietorship (ΑΤΟΜΙΚΗ)**, which has no separate legal personality, the **proprietor** is returned as the legal representative (standardized role `Owner`).
* In **`mode: "prefill"`** (fast), roles are classified deterministically from the registry's role text and the company's legal form.
* In **`mode: "verification"`**, classification is additionally **AI-enriched** (analyzing each person's role text, category, and representation flags) and role titles are standardized.
### Representation Mode
For **Anonymes Etaireia (AE / SA)** companies with Board of Directors, GEMI provides structured boolean flags (`isRepresentativeAlone`, `isRepresentativeInCommon`) that indicate signing authority. These are enriched onto AI-parsed legal representatives via name matching:
* **`{ mode: "sole" }`**: Can sign alone (`isRepresentativeAlone: true`)
* **`{ mode: "joint" }`**: Must sign jointly (`isRepresentativeInCommon: true`)
* **`null`**: No signing authority flags set, or not applicable for this company type
`representationMode` is only populated for AE (SA) companies where GEMI provides the boolean flags. Other company types (IKE, EPE, OE, EE) do not have this data in GEMI.
### Person Categories from GEMI
| Greek Category | English | Contains |
| - | - | - |
| Διοικητικό συμβούλιο | Board of Directors | Board members for AE (SA) companies |
| Εταίροι | Partners | Partners for partnerships and LLCs |
| Λοιπές ιδιότητες διοίκησης | Other Management Roles | Liquidators, receivers, special administrators |
### Common Greek Roles
| Greek Role | English Translation | Typical Classification |
| - | - | - |
| Πρόεδρος | Chairman | Other Key Person on a joint-stock company unless separately authorized; source/form-specific on other entities |
| Διευθύνων Σύμβουλος | Managing Director / CEO | Legal Representative |
| Πρόεδρος & Διευθ. Σύμβουλ | Chairman & Managing Director | Legal Representative |
| Διαχειριστής | Manager | Legal Representative |
| Μέλος & Διαχειριστής | Partner & Manager | Legal Representative |
| Ατομικό Μέλος | Sole Proprietor | Legal Representative (`Owner`) for sole traders (ΑΤΟΜΙΚΗ) |
| Εκκαθαριστής | Liquidator | Legal Representative |
| Greek Role | English Translation | Typical Classification |
| - | - | - |
| Αντιπρόεδρος | Vice President | Other Key Person |
| Εκτελεστικό Μέλος | Executive Member | Other Key Person |
| Μη Εκτελεστικό Μέλος | Non-Executive Member | Other Key Person |
| Ανεξάρτητο μη Εκτελεστικό Μέλος | Independent Non-Executive Member | Other Key Person |
| Μέλος | Board Member (ΑΕ only) | Other Key Person on an ΑΕ; on an ΙΚΕ/ΕΠΕ/ΟΕ/ΕΕ a bare "Μέλος" is a company member (owner) and appears as a **shareholder**, not a key person |
| Greek Role | English Translation | Typical Classification |
| - | - | - |
| Ομόρρυθμο Μέλος | General Partner | Shareholder (not key person) |
| Ετερόρρυθμο Μέλος | Limited Partner | Shareholder (not key person) |
**Role classification:** GEMI titles are free Greek text. Known labels have deterministic standardized categories; representation classification remains tied to legal form and the source appointment. Explicit positive board representation flags control the representative context, and both explicitly false board flags mean a non-signing office. Null partner flags do not remove statutory general-partner or manager capacity. Partners who only hold shares but have no management role are filtered out of key persons and placed in the shareholders array instead.
**Representation Rights:** For board members (AE companies), the `representationMode` field indicates signing authority: `{ mode: "sole" }` for individual signing rights, `{ mode: "joint" }` for joint signing requirements.
## Shareholders
Shareholders are sourced from GEMI's **ownership records** (the register's member/partner data) for applicable company types, in **both** retrieval modes. This includes single-member (**μονοπρόσωπη**) companies, whose sole member is returned at **100%**, and both individual and **corporate** members (a company can be a partner). Only the current owners are returned; historical ownership entries are excluded.
### Legal Forms with Shareholders
| ID | Local Name | English | Notes |
| - | - | - | - |
| 19 | ΙΚΕ | Private Company | Members with share percentages |
| 8 | ΕΠΕ | Limited Liability Company | Members with share participation |
| 2 | ΟΕ | General Partnership | General partners with percentages |
| 4 | ΕΕ | Limited Partnership | General and limited partners |
| 68 | ΕΕ κατά μετοχές | Limited Partnership by Shares | Partners with percentages |
| 11 | Συνεταιρισμός | Cooperative | Members with percentages |
| 66 | Κοιν.Σ.Επ. | Social Cooperative Enterprise | Members with percentages |
| 65 | Ενεργειακή Κοινότητα | Energy Community | Members with percentages |
### Ownership Fields
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage (0-100) | GEMI ownership record. A sole member is `100`. |
| `nominalCapitalHeld` | Calculated capital held | `totalCapital * sharePercentage / 100` |
| `type` | `individual` or `company` | Whether the member is a natural person or a legal entity |
**Corporations (AE) do not expose shareholders** in the public GEMI registry. Shareholder information for corporations is typically only disclosed in annual reports. Only partnerships, private companies, LLCs, and cooperatives provide shareholder data via the API.
**Corporate members are supported.** A partner can be a legal entity (e.g. a holding company owning a single-member ΙΚΕ). Corporate members are returned with `type: "company"`, the member's legal name, and, when GEMI records it, the member's Greek tax number as `identifiers.taxNumber` (and `vatNumber` = `EL` + tax number). No country of domicile is asserted, as GEMI does not publish it (a foreign parent may carry a Greek tax registration).
**Single-member (μονοπρόσωπη) companies.** For a company with a single member, that member is returned at `sharePercentage: 100` holding the full nominal capital, whether the member is an individual or a company.
## Activity Code Mapping
Greece uses the **KAD\_2025** (Κωδικός Αριθμός Δραστηριότητας) classification, which extends the European NACE Rev. 2 standard with Greek-specific subdivisions. The system maps activity codes across three levels, all **deterministically** (no AI inference):
```
KAD_2025 XXYYZZZZ (Greek) → NACE Rev. 2.1 (European) → ISIC Rev. 5 (International, via correspondence table)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **KAD\_2025** | GEMI registry | `62010000` | No (official) |
| **NACE** | Derived from KAD\_2025 (first 4 digits → XX.YY), upconverted to Rev. 2.1 | `62.10` | No (deterministic) |
| **ISIC** | Derived from NACE (official correspondence table) | `621` | No (deterministic) |
**One code in, one code out.** You get one `NACE` and one `ISIC` code per declared KAD\_2025 code. Where a KAD\_2025 code has no single equivalent in the target revision, the shared parent class is returned rather than every candidate — see [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
**Main activity.** GEMI labels each activity as primary («Κύρια») or secondary («Δευτερεύουσα»). The primary activity is listed first and carries `isMainActivity: true` on its KAD\_2025 code, and the NACE and ISIC codes derived from it inherit the flag. Secondary activities carry no flag.
**All activity code mappings are deterministic for Greece.** Unlike some countries, ISIC codes are derived from NACE via the official NACE-to-ISIC correspondence table, not via AI. The `isAIInferred` flag is always `false`. KAD\_2025 descriptions are preserved in Greek from the GEMI registry.
Deterministic does not mean every KAD\_2025 code has a same-level equivalent: where the correspondence is ambiguous, the returned class is a group or division rather than a four-digit class. It is still derived, never inferred.
**KAD\_2025 Code Structure:** KAD\_2025 codes are 8 digits (`XXYYZZZZ`), where the first 4 digits correspond to NACE Rev. 2 (`XX.YY`) and the last 4 digits are Greek-specific subdivisions. For example, KAD\_2025 `62010000` maps to NACE `62.01` (Computer programming activities).
## Documents by Company Type
Greek documents come from GEMI: the trade register extract, plus financial statements, articles of association, and official publications filed with the register. Listing available documents is **free** (no catalog item charge). Each document is billed when you order it; see the [pricing page](https://topograph.co/pricing/gr) for prices.
### Always Available
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | All companies | Official extract from GEMI, mixed English/Greek, TTL: 1 day |
### GEMI API Documents (decisions)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Financial Statements** | `financialStatements[]` | PDF | When filed | Balance sheets, ELP/IFRS reports, fiscal year inferred |
| **Articles of Association** | `articlesOfAssociation[]` | PDF | When filed | Establishment notices, statute amendments, conversions |
| **Official Publications** | `officialPublications[]` | PDF | When available | Board changes, capital changes, mergers, bankruptcy filings, liquidation notices |
| **Other Documents** | `otherDocuments[]` | PDF | When available | Partner withdrawals, general filings, error corrections |
### GEMI API Documents (publications)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Formation Documents (YMS)** | `articlesOfAssociation[]` | PDF | When available | One-Stop Shop (YMS) formation documents |
GEMI classifies documents using 114 decision subject IDs from its official decision subject catalog. These are grouped into the following categories:
**Financial Statements** (IDs: 4, 7, 8, 9, 11, 17, 21, 42, 48, 72, 78, 79, 82, 95):
Balance sheet publications, financial statement approvals, bank balance sheets, consolidated statements, liquidation balance sheets.
**Articles of Association** (IDs: 18, 29, 30, 34, 35, 73, 74):
Establishment notices, statute amendments, registration of articles, IKE conversion documents.
**Board/Governance Changes** (IDs: 2, 10, 26, 43, 75, 80, 92, 118):
Board reconstitution, representation changes, first Board establishment, audit committee publicity, administrator designation.
**Capital Changes** (IDs: 3, 23, 24, 31, 45, 46, 54, 56, 66, 67, 68, 76, 77, 105):
Share capital increases/decreases, retrieval certifications, capital adjustments, pre-emption rights.
**Mergers/Splits/Transformations** (IDs: 27, 28, 70, 85, 104, 107, 114, 115):
Merger notices, division notices, draft agreements, conversions, deletion due to merger/division.
**Liquidation/Dissolution** (IDs: 5, 19, 20, 22, 36, 52, 96):
Dissolution announcements, liquidator appointments, end of liquidation, revival.
**Bankruptcy/Insolvency** (IDs: 12, 14, 15, 16, 37, 38, 39, 40, 41):
Bankruptcy petitions, bankruptcy declarations, conciliation proceedings, closure/recall of bankruptcy.
**Registration/Status Changes** (IDs: 55, 81, 94, 99, 100, 106):
Deletion, retroactive deletion, revocation/reversal of registration.
**Branches** (IDs: 101, 108, 116, 119):
Branch creation, branch changes, branch deletion, foreign company representative designation.
**Other** (IDs: 1, 6, 13, 25, 32, 33, 44, 49, 50, 51, 53, 57, 58, 59, 60, 61, 63, 64, 65, 69, 71, 83, 86, 87, 88, 89, 90, 91, 93, 103, 109, 110, 111, 112, 113, 120):
Address changes, stock options, auditor elections, valuation reports, remuneration reports, partner withdrawals, error corrections.
## Data Availability Matrix
| Data Type | All Companies | Notes |
| - | - | - |
| Company Profile | ✅ Async | Full data from GEMI in both modes |
| Legal Representatives | ✅ | Legal-form-aware; sole traders (ΑΤΟΜΙΚΗ) return the proprietor as `Owner`. Roles AI-standardized in verification mode |
| Other Key Persons | ✅ | Board members, auditors |
| Shareholders | ⚠️ Not for AE | Partnerships, private companies (ΙΚΕ), LLCs and cooperatives, including single-member (μονοπρόσωπη) companies (sole member at 100%) and corporate members. Not available for AE (Corporations) |
| Ultimate Beneficial Owners | ❌ | Separate register (Ministry of Finance), not publicly accessible |
| Establishments | ❌ | Branch data exists in GEMI but not exposed in current implementation |
| Activity Codes (KAD\_2025/NACE/ISIC) | ✅ | All deterministic, no AI inference |
| Trade Register Extract | ✅ | Official extract from GEMI |
| Financial Statements | ⚠️ When filed | From GEMI decisions |
| Articles of Association | ⚠️ When filed | From GEMI decisions/publications |
| Official Publications | ⚠️ When available | Board changes, capital changes, etc. |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
## Example API Responses
Identifiers and personal names below are **illustrative placeholders**, but the response shapes match real GEMI output. Query: `POST /v2/company` with `{ "id": "", "countryCode": "GR", "dataPoints": ["company", "legalRepresentatives", "shareholders", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "31301000",
"countryCode": "GR",
"identifiers": {
"gemiNumber": "31301000",
"vatNumber": "EL093808863",
"taxNumber": "093808863"
},
"legalName": "EXAMPLE INDUSTRIAL Ανώνυμος Εμπορική Εταιρεία",
"legalNameInEnglish": "EXAMPLE INDUSTRIAL SA",
"registrationDate": "2005-06-12",
"activityDescription": "Εμπορία χημικών προϊόντων και τυπογραφικών μελανιών.",
"status": {
"localName": "Ενεργή",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "ΑΕ",
"englishTranslation": "Public Limited Company",
"standardized": "Corporation",
"iso20275Code": "W2NK"
},
"capital": { "amount": 120000, "currency": "EUR" },
"activities": {
"KAD_2025": [{ "code": "46751262", "description": "ΧΟΝΔΡΙΚΟ ΕΜΠΟΡΙΟ ΤΥΠΟΓΡΑΦΙΚΗΣ ΜΕΛΑΝΗΣ", "isAIInferred": false }],
"NACE": [{ "code": "46.75", "isAIInferred": false }],
"ISIC": [{ "code": "4690", "description": "Non-specialized wholesale trade", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "ΚΗΦΙΣΙΑΣ 102",
"city": "ΑΘΗΝΑ",
"postalCode": "11526",
"region": "ΑΤΤΙΚΗΣ",
"countryCode": "GR"
},
"phones": ["2107010275"],
"website": "https://www.example.gr"
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Πρόεδρος & Διευθ. Σύμβουλ", "standardized": "Chief Executive Officer" },
"representationMode": { "mode": "sole" },
"individual": { "name": { "fullName": "ΙΩΑΝΝΗΣ ΠΑΠΑΔΟΠΟΥΛΟΣ", "firstName": "ΙΩΑΝΝΗΣ", "lastName": "ΠΑΠΑΔΟΠΟΥΛΟΣ" } },
"startDate": "2024-04-02",
"endDate": "2027-04-01"
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Αντιπρόεδρος", "standardized": "Vice Chairman of the Board" },
"individual": { "name": { "fullName": "ΜΑΡΙΑ ΓΕΩΡΓΙΟΥ" } },
"startDate": "2024-04-02",
"endDate": "2027-04-01"
},
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Μέλος", "standardized": "Board Member" },
"individual": { "name": { "fullName": "ΝΙΚΟΣ ΑΝΤΩΝΙΟΥ" } },
"startDate": "2024-04-02",
"endDate": "2027-04-01"
}
]
}
```
**Note:** AE (Corporation) companies have Board of Directors. No shareholders are available from the public GEMI registry for this legal form.
```json theme={null}
{
"company": {
"id": "13701000",
"countryCode": "GR",
"identifiers": {
"gemiNumber": "13701000",
"vatNumber": "EL082592010",
"taxNumber": "082592010"
},
"legalName": "DIGITAL SOLUTIONS ΙΚΕ",
"registrationDate": "2020-02-15",
"activityDescription": "Δραστηριότητες παροχής συμβουλών σε θέματα πληροφορικής.",
"status": {
"localName": "Ενεργή",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "ΙΚΕ",
"englishTranslation": "Private Company (PC)",
"standardized": "Limited Liability Company",
"iso20275Code": "QCA0"
},
"capital": { "amount": 1000, "currency": "EUR" },
"activities": {
"KAD_2025": [{ "code": "62020000", "description": "Δραστηριότητες παροχής συμβουλών σε θέματα πληροφορικής", "isAIInferred": false }],
"NACE": [{ "code": "62.02", "isAIInferred": false }],
"ISIC": [{ "code": "6202", "description": "Computer consultancy and computer facilities management activities", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "ΕΡΜΟΥ 25",
"city": "ΘΕΣΣΑΛΟΝΙΚΗ",
"postalCode": "54624",
"region": "ΘΕΣΣΑΛΟΝΙΚΗΣ",
"countryCode": "GR"
},
"phones": ["2109339090"],
"website": "https://www.example-ike.gr"
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Μέλος & Διαχειριστής", "standardized": "Managing Director" },
"individual": { "name": { "fullName": "ΔΗΜΗΤΡΙΟΣ ΚΩΝΣΤΑΝΤΙΝΟΥ", "firstName": "ΔΗΜΗΤΡΙΟΣ", "lastName": "ΚΩΝΣΤΑΝΤΙΝΟΥ" } },
"startDate": "2025-09-19"
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 91,
"nominalCapitalHeld": { "amount": 910, "currency": "EUR" },
"individual": { "name": { "fullName": "ΔΗΜΗΤΡΙΟΣ ΚΩΝΣΤΑΝΤΙΝΟΥ" } }
},
{
"entityId": "person_002",
"type": "individual",
"sharePercentage": 9,
"nominalCapitalHeld": { "amount": 90, "currency": "EUR" },
"individual": { "name": { "fullName": "ΕΛΕΝΗ ΣΤΑΜΑΤΙΟΥ" } }
}
]
}
```
**Note:** IKE (Private Company) shareholders include ownership percentages and calculated nominal capital held. The managing partner appears as both a legal representative and a shareholder.
```json theme={null}
{
"company": {
"id": "12345601000",
"countryCode": "GR",
"identifiers": {
"gemiNumber": "12345601000",
"vatNumber": "EL800000001",
"taxNumber": "800000001"
},
"legalName": "EXAMPLE HOSPITALITY ΜΟΝΟΠΡΟΣΩΠΗ ΙΚΕ",
"registrationDate": "2013-05-03",
"status": {
"localName": "Ενεργή",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "ΙΚΕ",
"englishTranslation": "Private Company (PC)",
"standardized": "Limited Liability Company",
"iso20275Code": "QCA0"
},
"capital": { "amount": 3000, "currency": "EUR" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Διαχειριστής", "standardized": "Manager" },
"individual": { "name": { "fullName": "ΑΝΤΩΝΙΟΣ ΡΩΤΑΣ" } },
"startDate": "2013-05-03"
}
],
"shareholders": [
{
"entityId": "company_001",
"type": "company",
"sharePercentage": 100,
"nominalCapitalHeld": { "amount": 3000, "currency": "EUR" },
"company": {
"id": "800000002",
"identifiers": { "taxNumber": "800000002", "vatNumber": "EL800000002" },
"legalName": "EXAMPLE HOLDINGS ΙΚΕ"
}
}
]
}
```
**Note:** A single-member company returns its sole member at `sharePercentage: 100` holding the full nominal capital. Here the member is another company (`type: "company"`), returned with its Greek tax number as identifiers and no `countryCode`. The manager is a separate individual returned as the legal representative.
```json theme={null}
{
"company": {
"id": "10203001000",
"countryCode": "GR",
"identifiers": {
"gemiNumber": "10203001000",
"vatNumber": "EL070000001",
"taxNumber": "070000001"
},
"legalName": "ΓΕΩΡΓΙΟΣ ΠΑΠΑΔΟΠΟΥΛΟΣ ΤΟΥ ΙΩΑΝΝΗ",
"status": {
"localName": "Ενεργή",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "ΑΤΟΜΙΚΗ",
"englishTranslation": "Sole Proprietorship",
"standardized": "Sole Proprietorship"
},
"activities": {
"KAD_2025": [{ "code": "47711203", "description": "ΛΙΑΝΙΚΟ ΕΜΠΟΡΙΟ ΕΝΔΥΜΑΤΩΝ", "isAIInferred": false }],
"NACE": [{ "code": "47.71", "isAIInferred": false }],
"ISIC": [{ "code": "4771", "description": "Retail sale of clothing, footwear and leather articles in specialized stores", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "ΠΕΛΟΠΙΔΑ 47",
"city": "ΠΕΡΙΣΤΕΡΙ",
"postalCode": "12135",
"region": "ΑΤΤΙΚΗΣ",
"countryCode": "GR"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Ατομικό Μέλος", "standardized": "Owner" },
"individual": { "name": { "fullName": "ΓΕΩΡΓΙΟΣ ΠΑΠΑΔΟΠΟΥΛΟΣ" } }
}
]
}
```
**Note:** A sole proprietorship (ΑΤΟΜΙΚΗ) has no separate legal personality, so the proprietor is returned as the legal representative with standardized role `Owner`. Sole traders have no shareholders. The legal name is the proprietor's own name as registered in GEMI.
```json theme={null}
{
"company": {
"id": "6101000",
"countryCode": "GR",
"identifiers": {
"gemiNumber": "6101000",
"vatNumber": "EL091016194",
"taxNumber": "091016194"
},
"legalName": "(ΥΠΟ ΕΚΚΑΘΑΡΙΣΗ) EXAMPLE ΕΜΠΟΡΙΚΗ Ο.Ε.",
"legalNameInEnglish": "(UNDER LIQUIDATION) EXAMPLE TRADING O.E.",
"commercialNames": ["ELPACO"],
"registrationDate": "1964-08-01",
"activityDescription": "Αντιπροσώπευση εμπορικών οίκων εξωτερικού και εσωτερικού.",
"status": {
"localName": "Λύση - Εκκαθάριση",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "LIQUIDATION",
"closureDate": "2021-09-27"
}
},
"legalForm": {
"localName": "ΟΕ",
"englishTranslation": "General Partnership (GP)",
"standardized": "Partnership",
"iso20275Code": "TIZ2"
},
"activities": {
"KAD_2025": [{ "code": "46141330", "description": "ΕΜΠΟΡΙΚΟΙ ΑΝΤΙΠΡΟΣΩΠΟΙ ΠΟΥ ΜΕΣΟΛΑΒΟΥΝ ΣΤΗΝ ΠΩΛΗΣΗ ΜΗΧΑΝΗΜΑΤΩΝ", "isAIInferred": false }],
"NACE": [{ "code": "46.14", "isAIInferred": false }],
"ISIC": [{ "code": "4610", "description": "Wholesale on a fee or contract basis", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "ΑΡΤΕΜΙΔΟΣ 3",
"city": "ΜΑΡΟΥΣΙ",
"postalCode": "15125",
"region": "ΑΤΤΙΚΗΣ",
"countryCode": "GR"
},
"phones": ["2106255000"]
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Εκκαθαριστής", "standardized": "Liquidator" },
"individual": { "name": { "fullName": "ΑΛΕΞΑΝΔΡΟΣ ΠΕΤΡΟΥ", "firstName": "ΑΛΕΞΑΝΔΡΟΣ", "lastName": "ΠΕΤΡΟΥ" } },
"startDate": "2021-09-27"
}
]
}
```
**Note:** Closed companies show `active: false` with closure details including the reason and date. Companies in liquidation typically have a Liquidator (Εκκαθαριστής) as a legal representative.
```json theme={null}
{
"company": {
"id": "9901000",
"countryCode": "GR",
"identifiers": {
"gemiNumber": "9901000",
"vatNumber": "EL091607191",
"taxNumber": "091607191"
},
"legalName": "(ΠΤΩΧΕΥΣΗ) EXAMPLE ΕΜΠΟΡΙΚΗ Ο.Ε.",
"commercialNames": ["(ΠΤΩΧΕΥΣΗ) EXAMPLE TRADE"],
"registrationDate": "1968-10-12",
"activityDescription": "Εμπορία ανταλλακτικών αυτοκινήτων.",
"status": {
"localName": "Πτώχευση",
"active": false,
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"closureReason": "BANKRUPTCY",
"insolvencyStartDate": "1968-10-12"
}
},
"legalForm": {
"localName": "ΟΕ",
"englishTranslation": "General Partnership (GP)",
"standardized": "Partnership",
"iso20275Code": "TIZ2"
},
"activities": {
"KAD_2025": [
{ "code": "45311217", "description": "ΧΟΝΔΡΙΚΟ ΕΜΠΟΡΙΟ ΚΑΙΝΟΥΡΓΙΩΝ ΑΝΤΑΛΛΑΚΤΙΚΩΝ ΚΑΙ ΕΞΑΡΤΗΜΑΤΩΝ ΑΥΤΟΚΙΝΗΤΩΝ", "isAIInferred": false },
{ "code": "45321212", "description": "ΛΙΑΝΙΚΟ ΕΜΠΟΡΙΟ ΚΑΙΝΟΥΡΓΙΩΝ ΑΝΤΑΛΛΑΚΤΙΚΩΝ ΚΑΙ ΕΞΑΡΤΗΜΑΤΩΝ ΑΥΤΟΚΙΝΗΤΩΝ", "isAIInferred": false }
],
"NACE": [
{ "code": "45.31", "isAIInferred": false },
{ "code": "45.32", "isAIInferred": false }
],
"ISIC": [{ "code": "4530", "description": "Sale of motor vehicle parts and accessories", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "ΘΕΡΜΟΠΥΛΩΝ 57",
"city": "ΑΘΗΝΑ",
"postalCode": "10435",
"region": "ΑΤΤΙΚΗΣ",
"countryCode": "GR"
},
"phones": ["2105249478"]
},
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 90,
"individual": { "name": { "fullName": "ΚΩΝΣΤΑΝΤΙΝΟΣ ΠΑΠΑΔΟΠΟΥΛΟΣ" } }
},
{
"entityId": "person_002",
"type": "individual",
"sharePercentage": 10,
"individual": { "name": { "fullName": "ΒΑΣΙΛΙΚΗ ΓΕΩΡΓΙΟΥ" } }
}
]
}
```
**Note:** Companies under insolvency proceeding show `active: false` with `status: "UNDER_INSOLVENCY_PROCEEDING"` and `closureReason: "Bankruptcy"`. Partnership shareholders with ownership percentages are still available.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | GEMI Trade Register Extract (PDF) | Always available |
| `financialStatements[]` | Financial Statements (PDF) | When filed (balance sheets, IFRS/ELP reports) |
| `articlesOfAssociation[]` | Articles of Association (PDF) | Establishment notices, amendments, YMS formation docs |
| `officialPublications[]` | Official Publications (PDF) | Board changes, capital changes, mergers, bankruptcy filings |
| `otherDocuments[]` | Other Documents (PDF) | Partner withdrawals, general filings, error corrections |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **GEMI Number only for company retrieval** | `/v2/company` only accepts the GEMI Number. VAT numbers and company names must use the search endpoint first to retrieve the GEMI Number. |
| **VAT uses EL prefix, not GR** | Greek VAT numbers use the EU prefix `EL` (not the ISO country code `GR`). For example, AFM `093808863` becomes `EL093808863`. Both `EL` and `GR` prefixes are accepted in search. |
| **KAD\_2025 codes extend NACE** | Greek KAD\_2025 codes are 8 digits (`XXYYZZZZ`), where the first 4 digits correspond to NACE Rev. 2 (`XX.YY`). The last 4 digits are Greek-specific subdivisions. |
| **ISIC is fully deterministic** | Unlike some countries, ISIC codes for Greece are derived deterministically from NACE via the official correspondence table, not via AI. The `isAIInferred` flag is always `false`. |
| **Shareholders limited to certain forms** | Shareholder data is available for partnerships (OE, EE), private companies (IKE), LLCs (EPE), and cooperatives, including single-member (μονοπρόσωπη) companies (sole member at 100%) and corporate members. Corporations (AE) do not expose shareholders in the public registry. |
| **Sole traders return the proprietor as legal rep** | A sole proprietorship (ΑΤΟΜΙΚΗ) has no separate legal personality, so the proprietor is returned as the legal representative with standardized role `Owner`. Sole traders have no shareholders. |
| **No UBO data** | Ultimate Beneficial Owner data is maintained in a separate register (Μητρώο Πραγματικών Δικαιούχων) managed by the Ministry of Finance and is **not publicly accessible**. |
| **12 possible GEMI statuses** | GEMI has 12 status codes including Active, Dormant, Pre-registration, Bankruptcy, Dissolution, Deletion (various reasons), Forced Administration, Conciliation, and Suspension. |
| **Dormant = legally active** | Companies with status "Σε Αδράνεια" (Dormant) are mapped as `active: true` because dormant companies are still legally registered entities, just not operating. A company under registration suspension is the exception: it is returned as `active: false` (`INACTIVE_NOT_CLOSED`) even when its register status reads Ενεργή. |
| **Greek text preserved** | Legal names, addresses, activity descriptions, and status names are preserved in Greek. English names are returned when available in the registry. In verification mode, the registered address is also geocoded. |
| **Rate limit: 8 req/min** | The GEMI Open Data API enforces a strict rate limit of 8 requests per minute. Rate limiting is handled automatically. |
| **AI-enriched role classification** | Legal representative vs. other key person classification is AI-enriched because GEMI stores roles as free-form Greek text without standardized codes. The AI also produces English translations and standardized role names. |
| **Percentage format inconsistency** | GEMI returns ownership percentages in inconsistent formats: `"91%"`, `"9%"`, `"0.994"` (meaning 99.4%), the bare fraction `"1"` (meaning 100%), or `"-"` (no percentage). The system normalizes all formats to a 0-100 scale, and a single member is always resolved to 100%. |
| **Trade Register Extract** | The Trade Register Extract is an official bilingual (English/Greek) PDF issued by GEMI. TTL is 1 day. |
# Guernsey
Source: https://docs.topograph.co/essentials/guernsey
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Guernsey reference is on the [Guernsey country page](https://www.topograph.co/countries/gg).
## Start here
This guide contains public integration notes for Guernsey. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Guernsey uses a single official registry for all entity types. Data comes from the **Guernsey Registry** -- there is no cross-registry merging.
### Commercial companies, partnerships & foundations
* **Guernsey Registry** -- Operated by the Guernsey Financial Services Commission (GFSC) under the Companies (Guernsey) Law, 2008. The Registry Portal at `portal.guernseyregistry.com` provides a public API covering companies (Non-Cellular, Protected Cell, Incorporated Cell), Limited Partnerships, Limited Liability Partnerships, and Foundations. This is the **sole source** for all structured entity data: company name, legal form, status, incorporation date, registered address, economic activity, directors, and other officials.
### Charities & non-profits
* **Guernsey Registry** -- Charities and Non-Profit Organisations are registered through the same Registry Portal under the Charities and Non Profit Organisations (Registration) (Guernsey) Law, 2008. The API exposes the same endpoints for these entity types, including officer data (Chairperson, Treasurer, Secretary) and available documents.
All Guernsey Registry data is publicly available without authentication. The API has a rate limit of **60 requests per minute**.
All data comes live from the Guernsey Registry. A company profile combines the entity's basic details (name, status, entity type, registration number), its registered address and registration date, its economic activity, its filing history (used to find the incorporation date) and its previous names. Key persons come from the entity's registered officials (Directors, Resident Agents, General Partners, Councillors, etc.).
Legal form is mapped deterministically from the Registry's entity type; status and activity codes are enriched using AI.
## Company Identifiers
### Query Identifiers
Guernsey entities are identified using a **registration number** prefixed by the entity type:
| Prefix | Entity Type | Format | Example | Notes |
| - | - | - | - | - |
| `CMP` | Company (Non-Cellular, PCC, ICC) | `CMP` + digits | `CMP10001` | Most common entity type |
| `FND` | Foundation | `FND` + digits | `FND167` | Guernsey Foundations Law, 2012 |
| `LLP` | Limited Liability Partnership | `LLP` + digits | `LLP149` | Guernsey LLP Law, 2013 |
| `LP` | Limited Partnership | `LP` + digits | `LP2515` | Includes variants with/without legal personality |
| `CH` | Charity | `CH` + digits | `CH12` | International and domestic charities |
| `NP` | Non-Profit Organisation | `NP` + digits | `NP2` | Domestic NPOs |
The prefix is uppercase and followed directly by the digits, with no space and no leading zeros. In the records we have seen, the number has 1 to 5 digits (`LP3`, `CMP27104`).
**Always use the full prefixed registration number, exactly as search returns it.** Each register numbers its entities separately, so the same digits can belong to different entities: `CMP321` is a company and `LP321` a limited partnership. The numeric part alone (e.g. `10001` instead of `CMP10001`) does not identify one entity.
Search can also return Guernsey trade mark records, numbered `GGGT` followed by digits (e.g. `GGGT8562`). These are not companies.
### Identifiers in API Response
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `registryNumber` | Uppercase prefix + digits, no space | `CMP10001` | All entity types |
The Guernsey register does not publish VAT numbers or SIREN equivalents. An optional LEI may be returned from GLEIF as described below.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Guernsey register number matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
The legal name must also agree with the LEI record because the same bare number can identify a company and a limited partnership.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Registration Number | Prefix + digits | `CMP10001` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Barron International"` | Fuzzy | Multiple results across all entity types |
| By Partial Name | Text string | `"Clay Target"` | Fuzzy | Multiple results |
**Search uses live Registry API lookups.** Both name and identifier searches query the Guernsey Registry's public-search endpoint in real time. Name searches accept free text with a minimum of 2 characters and a maximum of 100 characters.
Use registration number searches for exact matching and best performance. Name searches may return multiple results across different entity types (companies, charities, NPOs, foundations, partnerships).
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefixed registration numbers** | Registration numbers always include a prefix (`CMP`, `FND`, `LLP`, `LP`, `CH`, `NP`). Using just the numeric part will fail. |
| **No shareholders or UBO data** | Shareholder and Ultimate Beneficial Owner data is private in Guernsey and is not available through the public register. |
| **Corporate directors are common** | Many Guernsey companies use corporate directors (trust companies acting as directors). The system uses name pattern heuristics (suffixes like "Limited", "Ltd", "LLP") to distinguish corporate from individual directors. |
| **Compound surname handling** | Guernsey has significant French/Norman influence, so compound surnames (Le Gallez, De Carteret, Du Feu) are common and parsed with special prefix detection for `Le`, `De`, `Du`, `Van`, etc. |
| **Resident Agent on all entity types** | Almost all Guernsey entities have a Resident Agent (typically a licensed trust company), mapped as an Other Key Person. |
| **GFSC activity codes are non-standard** | Guernsey uses its own dotted-numeric classification (e.g., `10.5.7`), not SIC or NACE. NACE and ISIC are always AI-inferred from the description text. |
| **"NA" activity means no classification** | Some entities have `NA` as their economic activity, meaning no specific activity has been assigned. No activity codes are returned for these entities. |
| **Charity/NPO statements are priced separately** | Trade Register Extracts for charities (`CH`) and non-profits (`NP`) are a separate catalog item, priced lower than the extracts for commercial entity types (`CMP`, `LP`, `LLP`, `FND`). See [pricing](https://www.topograph.co/pricing). |
| **Uncertain relationship types need AI** | The "Other Managing Official" role is ambiguous and requires AI analysis to classify as legal representative or other key person. For charities/NPOs, these are typically trustees with collective signing authority. |
| **\~20 distinct entity statuses** | Guernsey has numerous status values including multiple dissolved variants (voluntary liquidation, registrar strike off, compulsory liquidation, voluntary strike off, wound up, etc.). All are AI-enriched to standardized statuses. |
| **Dissolved companies lack officials** | Dissolved companies often return empty arrays for the relationships/officials endpoint. |
| **Document delivery takes time** | Documents are ordered from the Guernsey Registry on request, so delivery can take up to 20 minutes. |
| **Rate limit: 60 requests/minute** | The Guernsey Registry API enforces a rate limit of 60 requests per minute. |
| **No financial statements** | Guernsey companies do not file financial statements publicly. "Annual Validation" and "Annual Return" documents are compliance filings, not financial statements. |
## Statutory Filings
Guernsey companies file an **annual validation**, the local equivalent of a confirmation statement, confirming the entity's particulars are current. The Registry publishes the date it next falls due, returned on the cross-country `statutoryFilings` field.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "dueDate": "2026-06-30" },
"source": "guernsey_registry"
}
}
}
```
The Registry exposes no "last filed" date, so only `next.dueDate` is populated. Guernsey companies file no public financial statements, so there is no `accounts` obligation to report.
See [Compliance Signals & Statutory Filings](/essentials/compliance-signals) for the full field reference.
## Mappings
### Company Status
Company status is extracted from the Guernsey Registry's `entityStatusDesc` field. The `active` flag is determined deterministically from a known list of active statuses. The standardized status (`statusDetails`) is **AI-enriched**.
#### Active Statuses
| Local Status | Standardized Status | Notes |
| - | - | - |
| Normal | Active | Standard operating status for companies, partnerships, foundations |
| Registered | Active | Standard status for charities and NPOs |
| Current | Active | Used for trademarks and patents |
#### At-Risk Statuses
| Local Status | Standardized Status | Notes |
| - | - | - |
| In Default | Under Insolvency Proceeding | Entity has failed to meet filing obligations or is in financial distress |
| Strike Off Listed | Under Insolvency Proceeding | Entity has been listed for strike-off by the Registrar |
| Voluntary strike off application | Under Insolvency Proceeding | Entity has applied for voluntary strike-off |
#### Winding Up Statuses
| Local Status | Standardized Status | Notes |
| - | - | - |
| Voluntary winding up Part 1 (liquidator appointed) | Under Insolvency Proceeding | Voluntary dissolution in progress, liquidator appointed |
| Voluntary winding up Part 2 (liquidator final meeting) | Under Insolvency Proceeding | Final stage of voluntary winding up |
| Compulsory winding up Part 1 (liquidator appointed) | Under Insolvency Proceeding | Court-ordered winding up, liquidator appointed |
| Compulsorily Wound Up | Closed | Company wound up by court order |
| Wound Up | Closed | Company has completed winding up process |
#### Inactive / Closed Statuses
| Local Status | Standardized Status | Notes |
| - | - | - |
| Ceased | Closed | Entity has ceased operations |
| Converted | Closed | Entity converted to another form |
| Amalgamated | Closed | Entity merged with another entity |
| Migrated | Closed | Entity migrated to another jurisdiction |
| Struck Off | Closed | Entity removed from the register |
| Expired | Closed | Used for trademarks/patents that have expired |
| Historic | Closed | Used for trademarks/patents no longer current |
#### Dissolved Statuses
| Local Status | Standardized Status | Notes |
| - | - | - |
| Dissolved | Closed | Generic dissolved status |
| Dissolved (voluntary liquidation) | Closed | Dissolved after voluntary liquidation |
| Dissolved (voluntary strike off) | Closed | Dissolved after voluntary strike off |
| Dissolved (registrar compulsory strike off) | Closed | Dissolved by Registrar compulsory action |
| Dissolved (compulsory liquidation) | Closed | Dissolved after compulsory (court-ordered) liquidation |
| Dissolved (wound up) | Closed | Dissolved after winding up process |
### Legal Forms
Guernsey uses entity type IDs from the Registry API. The entity type set is closed and statutory, so the local name, English name, standardized category and ISO 20275 (ELF) code are all mapped deterministically. No AI is involved in the legal form.
Guernsey's ISO 20275 vocabulary splits companies by liability (limited by
shares, limited by guarantee, mixed liability, unlimited), and each carries a
different ELF code. The Registry does not publish which of those a given
company is, so no ISO 20275 code is returned for the generic company types
rather than an inferred one.
#### Companies
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Non Cellular Company | Non Cellular Company | Limited Liability Company | not published |
| Protected Cell Company (PCC) | Protected Cell Company (PCC) | Limited Liability Company | 4C0J |
| Incorporated Cell Company (ICC) | Incorporated Cell Company (ICC) | Limited Liability Company | QJBA |
| Incorporated Cell | Incorporated Cell | Limited Liability Company | 2AUN |
#### Partnerships
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Limited Partnership | Limited Partnership | Partnership | UO3D |
| Limited Partnership (no separate legal personality) | Limited Partnership (no separate legal personality) | Partnership | 75XK |
| Incorporated Limited Partnership (with separate legal personality) | Incorporated Limited Partnership (with separate legal personality) | Partnership | MCQP |
| Limited Liability Partnership (LLP) | Limited Liability Partnership (LLP) | Partnership | Q49K |
#### Foundations & Non-Profits
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Foundation | Foundation | Nonprofit Organization | 9XFK |
| Non-Profit Organisation (Domestic - compulsorily registered) | Non-Profit Organisation (Domestic - compulsorily registered) | Nonprofit Organization | not published |
| Non-Profit Organisation (Domestic - voluntarily registered) | Non-Profit Organisation (Domestic - voluntarily registered) | Nonprofit Organization | not published |
#### Charities
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Charity (Domestic - compulsorily registered) | Charity (Domestic - compulsorily registered) | Nonprofit Organization | not published |
| Charity (Domestic - voluntarily registered) | Charity (Domestic - voluntarily registered) | Nonprofit Organization | not published |
| Charity (International - compulsorily registered) | Charity (International - compulsorily registered) | Nonprofit Organization | not published |
| Charity (Branch of British registered organisation) | Charity (Branch of British registered organisation) | Nonprofit Organization | not published |
#### Other Entity Types (not company profiles)
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Trademark (Word only) | Trademark (Word only) | -- | -- |
| Trademark (Stylised word) | Trademark (Stylised word) | -- | -- |
| Trademark (Device and word) | Trademark (Device and word) | -- | -- |
| Patent | Patent | -- | -- |
The local legal form name from the Registry is always preserved verbatim.
### Legal Representatives
Legal representatives are extracted from the Guernsey Registry's relationships endpoint. Classification is **deterministic** for known relationship types (no AI needed). Both individuals and corporate entities can hold legal representative roles.
| Local Role Name | English Translation | Standardized | Entity Types | Notes |
| - | - | - | - | - |
| Director | Director | Director | Companies, Charities | Can be individual or corporate (mixed) |
| General Partner | General Partner | General Partner | Limited Partnerships | Can be individual or corporate (mixed) |
| Chairperson | Chairperson | Chairman | NPOs, Charities | Always individual |
| Councillor | Councillor | Director | Foundations | Can be individual or corporate; equivalent to director |
| Member | Member | Managing Partner | LLPs | Can be individual or corporate (mixed) |
### Other Key Persons
A foundation guardian enforces its constitution and purpose for founders and beneficiaries. This supervisory office is returned under `otherKeyPersons`; it does not establish general authority to bind the foundation. See the [Foundations (Guernsey) Law](https://www.gfsc.gg/sites/default/files/Foundations-%28Guernsey%29-Law-2012-%28Consolidated-text%29.pdf).
| Local Role Name | English Translation | Standardized | Entity Types | Notes |
| - | - | - | - | - |
| Resident Agent | Resident Agent | Registered Agent | All entity types | Typically a licensed trust/fiduciary company; can be individual or corporate |
| Secretary | Secretary | Secretary | Companies | Always individual |
| Treasurer | Treasurer | Other | NPOs, Charities | Always individual |
| Guardian | Guardian | Supervisor | Foundations | Can be individual or corporate; enforces the constitution and purpose |
**Uncertain Roles (AI-parsed):** The "Other Managing Official" role (always individual) is ambiguous. For charities/NPOs, these are typically trustees with collective signing authority and are classified as Legal Representatives by AI. For companies, they are usually classified as Other Key Persons unless they have explicit signing authority.
#### Structural Relationships (excluded from key persons)
The following relationship types appear in the API but are **not** mapped to key persons:
| Local Role Name | English Translation | Notes |
| - | - | - |
| Incorporated Cell | Incorporated Cell | Cells within ICCs -- structural relationship |
| Related Guernsey Entity | Related Guernsey Entity | Cross-entity relationships -- structural |
### Shareholders
**No shareholder data available.** Shareholder and ownership information is private in Guernsey and is not disclosed through the public Registry. Neither ownership percentages nor beneficial ownership data is available.
### Activity Code Mapping
Guernsey uses its own **GFSC economic activity classification** with dotted numeric codes (e.g., `10.5.7`, `02.9.1`). These codes do not directly map to European or international standards. NACE and ISIC codes are **always AI-inferred** from the activity description text.
```
GFSC Activity Code (local) --> AI-inferred NACE (European) --> AI-inferred ISIC (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **GFSC** | Guernsey Registry extended details | `10.5.7` | No (official) |
| **NACE** | AI-inferred from GFSC description | `64.21` | Yes (always) |
| **ISIC** | AI-inferred from GFSC description | `6420` | Yes (always) |
Some entities have `NA` as their economic activity classification, indicating no specific activity has been assigned. In these cases, no activity codes are returned. Both NACE and ISIC codes are **always AI-inferred** for Guernsey entities -- check the `isAIInferred` flag.
## Data Availability
### Data Availability Matrix
| Data Type | Availability | Notes |
| - | - | - |
| Company Profile | ✅ Async | Name, status, legal form, incorporation date, registered address, previous names |
| Legal Representatives | ✅ Async | Directors, Councillors, Members, General Partners, Chairpersons |
| Other Key Persons | ✅ Async | Resident Agents, Secretaries, Treasurers, Guardians |
| Shareholders | ❌ | Private information -- not available through public register |
| Ultimate Beneficial Owners | ❌ | Private information -- not available through public register |
| Activity Codes | ✅ | GFSC codes (official); NACE/ISIC (AI-inferred) |
| Establishments | ❌ | Not applicable -- Guernsey entities register a single registered office |
| Documents | ✅ Async | Statements of Register, certificates, articles, filings |
**Legend:** ✅ Available | ❌ Not Available | Async = Asynchronous processing
### Documents by Company Type
| Entity Type | Trade Register Extract | Certificate of Good Standing | Certificate of Incorporation | Articles of Association | Other Filed Documents | Statement of Register |
| - | - | - | - | - | - | - |
| Company (`CMP`) | Company Statement of Register | ✅ | ✅ | ✅ | Annual Validations, Resolutions | Paid (see [pricing](https://www.topograph.co/pricing)) |
| Limited Partnership (`LP`) | LP Statement of Register | ✅ | ❌ | ❌ | Annual Validations | Paid (see [pricing](https://www.topograph.co/pricing)) |
| LLP (`LLP`) | LLP Statement of Register | ✅ | ✅ | ❌ | Governance, Resolutions | Paid (see [pricing](https://www.topograph.co/pricing)) |
| Foundation (`FND`) | Foundation Statement of Register | ✅ | ✅ | ❌ | Governance | Paid (see [pricing](https://www.topograph.co/pricing)) |
| Charity (`CH`) | Charity Statements | ❌ | ❌ | ❌ | Varies | Paid (see [pricing](https://www.topograph.co/pricing)) |
| Non-Profit (`NP`) | NPO Statements | ❌ | ❌ | ❌ | Varies | Paid (see [pricing](https://www.topograph.co/pricing)) |
**Certificate of Good Standing** is only available for entities with an active status (`Normal`, `Registered`). Dissolved, wound up, or struck off entities cannot obtain this certificate.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "GG", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "CMP10001",
"countryCode": "GG",
"identifiers": { "registryNumber": "CMP10001" },
"legalName": "EXAMPLE HOLDINGS LIMITED",
"incorporationDate": "2010-05-20",
"activityDescription": "Other holding company not directly engaged in trading or other active income generating activities",
"status": {
"localName": "Normal",
"active": true,
"statusDetails": { "status": "ACTIVE", "additionalInfo": "" }
},
"legalForm": {
"localName": "Non Cellular Company",
"englishTranslation": "Non Cellular Company",
"standardized": "Limited Liability Company"
},
"activities": {
"items": [{ "code": "10.5.7", "description": "Other holding company not directly engaged in trading or other active income generating activities" }],
"NACE": [{ "code": "64.21", "description": "Activities of holding companies", "isAIInferred": true }],
"ISIC": [{ "code": "6420", "description": "Activities of holding companies", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "PO Box 296, Regency Court", "addressLine2": "Glategny Esplanade", "city": "St Peter Port", "postalCode": "GY1 4NA", "countryCode": "GG" }
},
"legalRepresentatives": [
{
"entityId": "gg-rel-51767",
"type": "company",
"startDate": "2008-07-09",
"role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" },
"company": { "id": "CMP20002", "countryCode": "GG", "legalName": "CORPORATE DIRECTORS LIMITED", "identifiers": { "registryNumber": "CMP20002" }, "legalForm": { "localName": "Non Cellular Company" }, "status": { "localName": "Normal", "active": true } }
},
{
"entityId": "gg-rel-51768",
"type": "company",
"startDate": "2008-07-09",
"role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" },
"company": { "id": "CMP30003", "countryCode": "GG", "legalName": "TRUST SERVICES LIMITED", "identifiers": { "registryNumber": "CMP30003" } }
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"startDate": "2008-07-09",
"role": { "localName": "Resident Agent", "englishTranslation": "Resident Agent", "standardized": "Registered Agent" },
"company": { "id": "CMP40004", "countryCode": "GG", "legalName": "FIDUCIARY TRUST COMPANY LIMITED", "identifiers": { "registryNumber": "CMP40004" } }
}
]
}
```
**Note:** Corporate directors are enriched with additional company data (registration number, legal form, status, address) via a secondary entity lookup. This is a common pattern in Guernsey where trust companies act as directors.
```json theme={null}
{
"company": {
"id": "CMP5119",
"countryCode": "GG",
"identifiers": { "registryNumber": "CMP5119" },
"legalName": "EXAMPLE INSURANCE LIMITED",
"activityDescription": "Trusts, companies and other structures administered by fiduciaries",
"legacyLegalNames": ["FORMER INSURANCE LTD.", "OLD TRADING NAME LTD."],
"status": {
"localName": "Wound Up",
"active": false,
"statusDetails": { "status": "CLOSED", "closureReason": "VOLUNTARY_DISSOLUTION", "additionalInfo": "The term 'Wound Up' typically indicates that the company has been dissolved or liquidated voluntarily." }
},
"legalForm": {
"localName": "Non Cellular Company",
"englishTranslation": "Non Cellular Company",
"standardized": "Limited Liability Company"
},
"activities": {
"items": [{ "code": "10.2.1", "description": "Trusts, companies and other structures administered by fiduciaries" }],
"NACE": [{ "code": "64.21", "description": "Activities of holding companies", "isAIInferred": true }],
"ISIC": [{ "code": "6420", "description": "Activities of holding companies", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Le Bordage Rd", "city": "St Sampson", "postalCode": "GY2", "countryCode": "GG" }
}
}
```
**Note:** Dissolved companies include `legacyLegalNames` when previous names exist. Officials data is typically empty for dissolved entities.
```json theme={null}
{
"company": {
"id": "FND167",
"countryCode": "GG",
"identifiers": { "registryNumber": "FND167" },
"legalName": "THE EXAMPLE FAMILY FOUNDATION",
"activityDescription": "Trusts and other similar structures (that are not companies)",
"status": {
"localName": "Voluntary winding up Part 1 (liquidator appointed)",
"active": false,
"statusDetails": { "status": "UNDER_INSOLVENCY_PROCEEDING", "closureReason": "VOLUNTARY_DISSOLUTION", "additionalInfo": "Voluntary winding up with liquidator appointed indicates insolvency proceeding under voluntary dissolution." }
},
"legalForm": {
"localName": "Foundation",
"englishTranslation": "Foundation",
"standardized": "Nonprofit Organization",
"iso20275Code": "9XFK"
},
"activities": {
"items": [{ "code": "10.7.1", "description": "Trusts and other similar structures (that are not companies)" }],
"NACE": [{ "code": "64.3", "description": "Trusts, funds and similar financial entities", "isAIInferred": true }],
"ISIC": [{ "code": "6430", "description": "Trusts, funds and similar financial entities", "isAIInferred": true }]
},
"legalAddress": { "city": "St Pierre Du Bois", "countryCode": "GG" }
},
"legalRepresentatives": [
{
"entityId": "gg-rel-340353",
"type": "company",
"startDate": "2024-04-23",
"role": { "localName": "Councillor", "englishTranslation": "Councillor", "standardized": "Director" },
"company": { "id": "CMP50005", "countryCode": "GG", "legalName": "FAMILY OFFICE LIMITED", "identifiers": { "registryNumber": "CMP50005" } }
},
{
"entityId": "gg-rel-340354",
"type": "individual",
"startDate": "2024-04-23",
"role": { "localName": "Councillor", "englishTranslation": "Councillor", "standardized": "Director" },
"individual": { "name": { "fullName": "John Andrew Smith", "firstName": "John", "lastName": "Smith" } }
},
{
"entityId": "gg-rel-340355",
"type": "individual",
"startDate": "2024-04-23",
"role": { "localName": "Councillor", "englishTranslation": "Councillor", "standardized": "Director" },
"individual": { "name": { "fullName": "James Peter Brown", "firstName": "James", "lastName": "Brown" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"startDate": "2024-04-23",
"role": { "localName": "Guardian", "englishTranslation": "Guardian", "standardized": "Supervisor" },
"individual": { "name": { "fullName": "Robert David Wilson", "firstName": "Robert", "lastName": "Wilson" } }
},
{
"entityId": "company_001",
"type": "company",
"startDate": "2024-04-23",
"role": { "localName": "Resident Agent", "englishTranslation": "Resident Agent", "standardized": "Registered Agent" },
"company": { "id": "CMP50005", "countryCode": "GG", "legalName": "FAMILY OFFICE LIMITED", "identifiers": { "registryNumber": "CMP50005" } }
}
]
}
```
**Note:** Foundations use "Councillor" as the legal representative role (equivalent to directors for governance). The "Guardian" role is returned as an Other Key Person with supervisory duties. Resident Agent is always classified as Other Key Person.
```json theme={null}
{
"company": {
"id": "NP2",
"countryCode": "GG",
"identifiers": { "registryNumber": "NP2" },
"legalName": "THE EXAMPLE SPORTS CLUB LBG",
"status": {
"localName": "Normal",
"active": true,
"statusDetails": { "status": "ACTIVE", "additionalInfo": "" }
},
"legalForm": {
"localName": "Non-Profit Organisation (Domestic - compulsorily registered)",
"englishTranslation": "Non-Profit Organisation (Domestic - compulsorily registered)",
"standardized": "Nonprofit Organization"
},
"legalAddress": { "addressLine1": "63 Example Street", "city": "St Peter Port", "postalCode": "GY1", "countryCode": "GG" }
},
"legalRepresentatives": [
{
"entityId": "gg-rel-344311",
"type": "individual",
"startDate": "2024-07-25",
"role": { "localName": "Chairperson", "englishTranslation": "Chairperson", "standardized": "Chairman" },
"individual": { "name": { "fullName": "Michael James Green", "firstName": "Michael", "lastName": "Green" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"startDate": "2024-07-25",
"role": { "localName": "Treasurer", "englishTranslation": "Treasurer", "standardized": "Other" },
"individual": { "name": { "fullName": "Pierre Le Gallez", "firstName": "Pierre", "lastName": "Le Gallez" } }
},
{
"entityId": "person_002",
"type": "individual",
"startDate": "2024-07-25",
"role": { "localName": "Secretary", "englishTranslation": "Secretary", "standardized": "Secretary" },
"individual": { "name": { "fullName": "Thomas Robert Taylor", "firstName": "Thomas", "lastName": "Taylor" } }
}
]
}
```
**Note:** Non-profits have a Chairperson as the primary legal representative, with Treasurer and Secretary as other key persons. Note the compound surname "Le Gallez" -- common in Guernsey due to French/Norman heritage.
```json theme={null}
{
"company": {
"id": "CH12",
"countryCode": "GG",
"identifiers": { "registryNumber": "CH12" },
"legalName": "EXAMPLE CHARITY (CHANNEL ISLANDS) LBG",
"incorporationDate": "2023-01-05",
"activityDescription": "Other unregulated finance activities not elsewhere classified",
"status": {
"localName": "In Default",
"active": false,
"statusDetails": { "status": "UNDER_INSOLVENCY_PROCEEDING", "closureReason": "UNKNOWN", "additionalInfo": "Local status 'In Default' indicates financial distress, likely insolvency proceeding." }
},
"legalForm": {
"localName": "Charity (International - compulsorily registered)",
"englishTranslation": "Charity (International - compulsorily registered)",
"standardized": "Nonprofit Organization"
},
"activities": {
"items": [{ "code": "10.9.3", "description": "Other unregulated finance activities not elsewhere classified" }],
"NACE": [{ "code": "64.9", "description": "Other financial service activities, except insurance and pension funding activities, n.e.c.", "isAIInferred": true }],
"ISIC": [{ "code": "6499", "description": "Other financial service activities, except insurance and pension funding activities, n.e.c.", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Havilland Street", "city": "St Peter Port", "postalCode": "GY1 2QE", "countryCode": "GG" }
},
"legalRepresentatives": [
{
"entityId": "gg-rel-316943",
"type": "company",
"startDate": "2023-01-05",
"role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" },
"company": { "id": "CMP60006", "countryCode": "GG", "legalName": "CORPORATE DIRECTORS LIMITED", "identifiers": { "registryNumber": "CMP60006" } }
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"startDate": "2023-01-05",
"role": { "localName": "Resident Agent", "englishTranslation": "Resident Agent", "standardized": "Registered Agent" },
"company": { "id": "CMP70007", "countryCode": "GG", "legalName": "TRUST COMPANY LIMITED", "identifiers": { "registryNumber": "CMP70007" } }
}
]
}
```
**Note:** Charities can have corporate directors (Director role) even though they are non-profit entities. The "In Default" status indicates the entity has failed to meet filing obligations.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
**Commercial entities (CMP, LP, LLP, FND):**
| API Category | Document | Cost | Notes |
| - | - | - | - |
| `tradeRegisterExtract` | Statement of Register | Paid (see [pricing](https://www.topograph.co/pricing)) | Current company details, officers, address |
| `otherDocuments[]` | Certificate of Good Standing | Paid (see [pricing](https://www.topograph.co/pricing)) | Active entities only |
| `otherDocuments[]` | Incorporation Certificate | Paid (see [pricing](https://www.topograph.co/pricing)) | Historical document |
| `articlesOfAssociation[]` | Articles/Memorandum of Association | Paid (see [pricing](https://www.topograph.co/pricing)) | Constitutional documents |
| `otherDocuments[]` | Annual Validations, Resolutions, etc. | Paid (see [pricing](https://www.topograph.co/pricing)) | Historical filed documents |
**Charities and Non-Profits (CH, NP):**
| API Category | Document | Cost | Notes |
| - | - | - | - |
| `tradeRegisterExtract` | Charity/NPO Statement | Paid (see [pricing](https://www.topograph.co/pricing)) | Registration statement |
| `otherDocuments[]` | Filed documents | Paid (see [pricing](https://www.topograph.co/pricing)) | Varies by entity |
# Hong Kong
Source: https://docs.topograph.co/essentials/hong-kong
Country-specific identifiers, data sources, and data availability
This guide is outdated and will be removed on 1 November 2026. The up-to-date Hong Kong reference is on the [Hong Kong country page](https://www.topograph.co/countries/hk).
## Start here
This guide contains public integration notes for Hong Kong. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Hong Kong uses a single official registry for company data. For a given entity, **all data comes from one source**: the Companies Registry's online portal.
### All company types
* **ICRIS (Integrated Companies Registry Information System)**: Operated by the Hong Kong Companies Registry (a department of the Financial Services and the Treasury Bureau), ICRIS is the **sole data source** for all Hong Kong entities. The Companies Registry was established under the Companies Ordinance (Cap. 622), which came into effect on 3 March 2014, replacing the former Companies Ordinance (Cap. 32). ICRIS provides two access channels: **(1)** a structured **Open Data API** (`data.cr.gov.hk`) for company search by name or BRN, returning basic company particulars (name, type, address, incorporation date); **(2)** **Company Particulars pages** accessible via the e-Services Portal (`e-services.cr.gov.hk`), which provide comprehensive company information including directors, company secretary, share capital, and shareholder details.
Company profile data (legal representatives, shareholders, share capital, detailed company information) is **AI-extracted** from the ICRIS Company Particulars page, retrieved from the ICRIS e-Services Portal. Search results come from the structured ICRIS Open Data API.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | ICRIS | 8 digits, leading zeros significant (BRN); or a dummy BRN of a letter prefix and 7 digits | `77054426`, `C1300723` | Business Registration Number. Companies without one carry a dummy BRN (`C` for a local company) |
**BRN vs CR Number:** Always use the **Business Registration Number** (BRN) when querying the API, exactly as search returns it (8 digits, or a dummy BRN such as `C1300723`). The former Company Registration (CR) number printed on certificates of incorporation issued before 27 December 2023 (e.g. `3484775`) is a separate identifier and will **not** work with our endpoints.
### Identifiers in API Response
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `brn` | 8 digits, or a letter prefix and 7 digits | `77054426`, `C1300723` | All companies |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Business Registration Number (BRN) matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
Historical Company Registration (CR) numbers are excluded from LEI enrichment because they belong to a separate number space.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By BRN | 8 digits | `77054426` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Technology Advantage"` | Prefix | Multiple results (begins-with match) |
**Search Performance:** Use BRN-based searches for exact matching and best performance. Name searches use a `begins_with` match on the ICRIS Open Data API. Partial names must match from the beginning of the company name.
### Active companies only
Search only returns active companies, so [`activeOnly=true`](/essentials/search#active-companies-only) changes nothing here. Search covers live local companies only; dissolved or deregistered companies are not returned.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **BRN vs CR Number** | Always use the **Business Registration Number** (BRN, or the dummy BRN of a company without one), not the former Company Registration (CR) number. They are different identifiers. |
| **Bilingual names** | Hong Kong companies can have an English name, a Chinese name, or both. The ICRIS API returns both when available. The `legalName` field returns the English name if available, falling back to Chinese. |
| **Prefix-match name search** | Name searches use a `begins_with` match on the ICRIS Open Data API, not fuzzy search. Partial names must match from the beginning. |
| **Company Secretary is mandatory** | Every HK company must have a Company Secretary, which can be an individual or a corporate entity. An ordinary secretary appointment appears under other key persons; separately established signing capacity may appear under legal representatives. |
| **No UBO data** | Ultimate Beneficial Owner information is not publicly disclosed in Hong Kong. Companies must maintain a Significant Controllers Register (SCR) internally, but this is not accessible via the Companies Registry. |
| **All profile data is AI-extracted** | Company profile data (beyond basic search fields) is AI-extracted from the ICRIS Company Particulars HTML page. Data quality depends on parsing accuracy. |
| **Share capital in HKD** | Share capital is typically denominated in Hong Kong Dollars (HKD). Some companies may have share capital in other currencies. |
| **All activity codes are AI-inferred** | Hong Kong does not provide structured activity codes in ICRIS. NACE and ISIC codes are always AI-inferred from business descriptions when available. |
| **Retrieval time about a minute** | The Company Particulars page is retrieved from the ICRIS e-Services Portal. Requests typically complete in about a minute and can take longer when several purchases are queued. See the [pricing page](https://topograph.co/pricing/hk) for current response times. |
| **Address may be in Chinese only** | Registered office addresses on the Company Particulars page are sometimes in Chinese only, without English transliteration. |
| **Company profile charges a register extract** | A company profile request includes retrieval of the Company Particulars document from the official registry. This means `companyProfile` incurs the cost of the register extract catalog item. |
## Mappings
### Company Status
Company status is **AI-extracted** from the ICRIS Company Particulars page. The AI parser identifies status indicators in the HTML content.
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| Live | Live | Active | Company is currently active |
| Dissolved | Dissolved | Closed | Company has been dissolved |
| Winding Up | Winding Up | Under Insolvency Proceeding | Company is in liquidation |
| Struck Off | Struck Off | Closed | Company removed from register by the Registrar |
Status mapping is AI-inferred from the Company Particulars page content. The local status value is preserved verbatim as it appears on the ICRIS page.
### Legal Forms
Hong Kong company types are AI-extracted from the Company Particulars page, where the register's own company type label is preserved verbatim. The mapping to standardized forms and **ISO 20275 (ELF)** codes is **AI-enriched**.
Legal form standardization and ISO 20275 assignment are AI-enriched. The local company type from ICRIS is always preserved verbatim.
Under the Companies Ordinance (Cap. 622), Section 66, the following types of companies may be formed in Hong Kong:
#### Private Companies
| Local Name | Standardized | ISO 20275 | Notes |
| - | - | - | - |
| Private company limited by shares | Limited Liability Company | 254M | Most common company type in Hong Kong |
| Private unlimited company with share capital | AI-enriched | - | Members have unlimited liability. Not yet observed in register data |
| Private unlimited company without share capital | AI-enriched | - | Very rare. Not yet observed in register data |
#### Public Companies
| Local Name | Standardized | ISO 20275 | Notes |
| - | - | - | - |
| Public company limited by shares | Corporation | - | Listed or unlisted public companies |
| Company limited by guarantee | Corporation | - | Common for charities, clubs, and professional bodies; cannot have share capital under Cap. 622 |
#### Foreign Entities
| Local Name | Standardized | ISO 20275 | Notes |
| - | - | - | - |
| Registered non-Hong Kong company | Branch or Representative Office | - | Foreign companies registered under Part 16 of the Companies Ordinance. Not yet observed in register data |
### Legal Representatives
Legal representatives are **AI-extracted** from the ICRIS Company Particulars page. Names can be in **English**, **Chinese**, or both. Both individuals and corporate entities can hold the Director role.
| Local Role | English Translation | Classification |
| - | - | - |
| Director | Director | Legal Representative |
| Company Secretary with separately recorded signing capacity | Company Secretary | Legal Representative within the recorded scope |
| Liquidator / Provisional Liquidator | Liquidator | Legal Representative within the insolvency appointment |
| Receiver / Manager (insolvency section) | Receiver | Legal Representative within the recorded appointment |
### Other Key Persons
Offered from the same ICRIS Company Particulars report. Ordinary company secretaries use `Secretary`, reserve nominees use `Other`, and registered non-Hong Kong company representatives appointed to receive process/notices use `Registered Agent`. Preserve corporate identity where the office holder is a company.
In Hong Kong, a **Company Secretary** is a mandatory statutory position for all companies incorporated under the Companies Ordinance. The Company Secretary can be either an individual or a corporate entity. An ordinary report appointment appears under `otherKeyPersons` as "Secretary". Section 127(3) of the Companies Ordinance permits a director and company secretary to execute documents jointly for a multi-director company. The current parser does not certify a complete board count or articles; it preserves separately recorded signing capacity and does not infer sole or unrestricted authority from the secretary title.
### Shareholders
Shareholders are **AI-extracted** from the ICRIS Company Particulars page when shareholding information is disclosed.
#### Extraction Logic
| Source | When Used | Data Extracted |
| - | - | - |
| **Company Particulars (ICRIS)** | Always (when available) | Shareholder names, share classes, number of shares held |
#### Ownership Fields
| Field | Description | Source |
| - | - | - |
| `name` | Shareholder name (individual or corporate) | AI-extracted from Company Particulars |
| `type` | Individual or Company | AI-inferred from name format |
| `sharePercentage` | Ownership percentage | Calculated from shares held vs total issued shares (when available) |
Shareholder availability depends on the company type and what is disclosed on the Company Particulars page. The public extract only lists founding members, so current ownership may not reflect share transfers made after incorporation. A company limited by guarantee has no share capital: `shareholders` returns an explicit not-applicable response for it, at no charge.
### Activity Code Mapping
Hong Kong does not use a standardized national industry classification code in the ICRIS Company Particulars page. Activity information, when available, is extracted from the company's stated objects or business description and mapped via AI:
```
Business Description (free text) → AI → NACE Rev. 2 + ISIC Rev. 4
```
| Classification | Source | AI Inferred? |
| - | - | - |
| **Business Description** | Company Particulars (when stated) | No (official text) |
| **NACE** | AI-derived from business description | Yes |
| **ISIC** | AI-derived from business description | Yes |
Hong Kong uses the **HSIC** (Hong Kong Standard Industrial Classification) for statistical purposes, but this code is not present in Company Particulars data. Both NACE and ISIC codes are therefore **always AI-inferred** when activity data is available.
## Data Availability
### Data Availability Matrix
| Data Type | Availability | Notes |
| - | - | - |
| Company Profile | ✅ Async | Legal name (EN/CN), status, legal form, incorporation date, address, share capital |
| Legal Representatives | ✅ Async | Directors from ICRIS Company Particulars (AI-extracted) |
| Other Key Persons | ✅ Async | Secretaries, reserve nominees and process-service representatives from the same report |
| Shareholders | ⚠️ Async | When disclosed in Company Particulars (AI-extracted) |
| Ultimate Beneficial Owners | ❌ | Not publicly disclosed in Hong Kong (SCR is internal only) |
| Activity Codes | ⚠️ Async | AI-inferred from business description when available |
| Establishments | ❌ | Not available from ICRIS |
| Documents | ✅ Async | Company Particulars PDF |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing (typically about a minute)
### Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Company Particulars** | `tradeRegisterExtract` | PDF | ✅ All companies | Company Particulars PDF retrieved from the ICRIS e-Services Portal |
The Company Particulars PDF is retrieved from the ICRIS e-Services Portal. This is the same document used for AI-parsing the company profile data.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "HK", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "77054426",
"countryCode": "HK",
"identifiers": {
"brn": "77054426"
},
"legalName": "EXAMPLE TECHNOLOGY LIMITED",
"legalNameInEnglish": "EXAMPLE TECHNOLOGY LIMITED",
"incorporationDate": "2019-06-15",
"status": {
"localName": "Live",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Private company limited by shares",
"standardized": "Limited Liability Company",
"iso20275Code": "254M",
"englishTranslation": "Private company limited by shares"
},
"capital": {
"amount": 10000,
"currency": "HKD",
"formatted": "HK$10,000"
},
"legalAddress": {
"addressLine1": "Unit 1001, 10/F, Example Tower, 123 Des Voeux Road Central",
"countryCode": "HK"
}
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": {
"localName": "Director",
"standardized": "Director",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "CHAN Tai Man"
},
"birthDate": {},
"residenceAddress": {}
}
}
],
"otherKeyPersons": [
{
"type": "company",
"entityId": "company_001",
"role": {
"localName": "Company Secretary",
"standardized": "Secretary",
"englishTranslation": "Company Secretary"
},
"company": {
"id": "71580904",
"legalName": "EXAMPLE SECRETARIAL SERVICES LIMITED",
"countryCode": "HK"
},
"startDate": "2019-06-15"
}
]
}
```
```json theme={null}
{
"company": {
"id": "88123456",
"countryCode": "HK",
"identifiers": {
"brn": "88123456"
},
"legalName": "GOLDEN DRAGON TRADING LIMITED",
"legalNameInEnglish": "GOLDEN DRAGON TRADING LIMITED",
"incorporationDate": "2020-03-20",
"status": {
"localName": "Live",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Private company limited by shares",
"standardized": "Limited Liability Company",
"iso20275Code": "254M",
"englishTranslation": "Private company limited by shares"
},
"capital": {
"amount": 100000,
"currency": "HKD",
"formatted": "HK$10,000"
},
"legalAddress": {
"addressLine1": "Room 501, 5/F, Example Building, 456 Nathan Road, Kowloon",
"countryCode": "HK"
}
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": {
"localName": "Director",
"standardized": "Director",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "WONG Siu Ming"
},
"birthDate": {},
"residenceAddress": {}
}
},
{
"type": "individual",
"entityId": "person_002",
"role": {
"localName": "Director",
"standardized": "Director",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "LI Mei Ling"
},
"birthDate": {},
"residenceAddress": {}
}
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 60,
"individual": {
"name": {
"fullName": "WONG Siu Ming"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"sharePercentage": 40,
"individual": {
"name": {
"fullName": "LI Mei Ling"
}
}
}
],
"otherKeyPersons": [
{
"type": "individual",
"entityId": "person_003",
"role": {
"localName": "Company Secretary",
"standardized": "Secretary",
"englishTranslation": "Company Secretary"
},
"individual": {
"name": {
"fullName": "CHEUNG Ka Wai"
},
"birthDate": {},
"residenceAddress": {}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "71580904",
"countryCode": "HK",
"identifiers": {
"brn": "71580904"
},
"legalName": "OLD TRADING COMPANY LIMITED",
"legalNameInEnglish": "OLD TRADING COMPANY LIMITED",
"incorporationDate": "2015-01-10",
"status": {
"localName": "Dissolved",
"active": false,
"statusDetails": {
"status": "CLOSED"
}
},
"legalForm": {
"localName": "Private company limited by shares",
"standardized": "Limited Liability Company",
"iso20275Code": "254M",
"englishTranslation": "Private company limited by shares"
},
"legalAddress": {
"addressLine1": "Room 303, 3/F, Example Centre, 789 Queen's Road East",
"countryCode": "HK"
}
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": {
"localName": "Director",
"standardized": "Director",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "LEE Wing Kee"
},
"birthDate": {},
"residenceAddress": {}
}
}
],
"shareholders": []
}
```
**Note:** Dissolved companies have `active: false`. Shareholder and capital information may not be available for dissolved companies.
```json theme={null}
{
"company": {
"id": "66789012",
"countryCode": "HK",
"identifiers": {
"brn": "66789012"
},
"legalName": "Example Chinese Name Company",
"incorporationDate": "2018-07-22",
"status": {
"localName": "Live",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Private company limited by shares",
"standardized": "Limited Liability Company",
"iso20275Code": "254M",
"englishTranslation": "Private company limited by shares"
},
"capital": {
"amount": 10000,
"currency": "HKD",
"formatted": "HK$10,000"
},
"legalAddress": {
"addressLine1": "Example address in Chinese characters",
"countryCode": "HK"
}
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": {
"localName": "Director",
"standardized": "Director",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "Example Chinese Name"
},
"birthDate": {},
"residenceAddress": {}
}
}
],
"otherKeyPersons": [
{
"type": "individual",
"entityId": "person_002",
"role": {
"localName": "Company Secretary",
"standardized": "Secretary",
"englishTranslation": "Company Secretary"
},
"individual": {
"name": {
"fullName": "Example Secretary Name"
},
"birthDate": {},
"residenceAddress": {}
}
}
]
}
```
**Note:** Some companies register only a Chinese name and address. The `legalNameInEnglish` field is absent when no English name is registered.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Company Particulars PDF (from ICRIS) | Available for all companies |
## Data Source Priority & Routing
Hong Kong uses a **single-source model**: all data comes exclusively from the ICRIS (Companies Registry). There is no priority chain or cross-registry merging.
**Data Flow for Company Profile:**
1. **Search**: The ICRIS Open Data API (`data.cr.gov.hk`) is queried for basic company lookup by BRN or name
2. **Document Retrieval**: The Company Particulars page is retrieved from the ICRIS e-Services Portal
3. **AI Parsing**: The page content is parsed by AI models to extract: company information, legal representatives, and shareholders
4. **Result Assembly**: The AI-extracted data is assembled into the standardized API response
Requests typically complete in about a minute, with automatic retries on the document retrieval step.
### Attribute-Level Source Mapping
| Attribute | Source | AI-Parsed? | Notes |
| - | - | - | - |
| Company name (EN/CN) | ICRIS Company Particulars | Yes | English and/or Chinese name |
| Legal form | ICRIS Company Particulars | Yes | Register company type label kept verbatim; standardized value is AI-inferred |
| Status | ICRIS Company Particulars | Yes | AI-extracted from page content |
| Incorporation date | ICRIS Company Particulars | Yes | AI-extracted from page content |
| Registered address | ICRIS Company Particulars | No | Taken from the register's structured data; may be in Chinese only |
| Share capital | ICRIS Company Particulars | Yes | Amount and currency (typically HKD) |
| Directors | ICRIS Company Particulars | Yes | Individual and corporate directors |
| Company Secretary | ICRIS Company Particulars | Yes | Individual or corporate; mandatory position |
| Shareholders | ICRIS Company Particulars | Yes | Founding members; not applicable to companies limited by guarantee |
| Activity codes (NACE/ISIC) | AI-inferred from business description | Yes | Always AI-inferred; no official ICRIS codes |
# Hungary
Source: https://docs.topograph.co/essentials/hungary
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Hungary reference is on the [Hungary country page](https://www.topograph.co/countries/hu).
## Start here
This guide contains public integration notes for Hungary. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Hungary uses **two distinct registries** depending on the entity type, plus a ministry portal that backs prefill mode:
### Commercial Companies: OCCSZ
The **OCCSZ** (Országos Cégnyilvántartó és Céginformációs Szolgálat, National Company Register and Company Information Service) operates the official Hungarian company register (Cégjegyzék):
* **Company search**: Search by name, registration number, and tax number. Returns company name, registration number, address, tax number, and status.
* **Trade Register Extract (Cégkivonat)**: The official extract for each registered company. This is the **primary source for company profile data** in verification mode: legal name, legal form, registration date, share capital, tax number, registered address, legal representatives, auditors, supervisory board members, shareholders, activity codes (TEÁOR), establishments, and company status.
* **Trade Register History (Cégmásolat)**: The historical register copy. For a struck-off company the register no longer issues a current extract, so this document is issued instead.
**Company profile is derived from the Trade Register Extract.** Addresses, legal
form standardization (ISO 20275), people, shareholders and roles are enriched
with AI when the extract is read.
### Prefill Mode: Cégportál Stored Extract
`mode: "prefill"` reads the stored company extract (*Tárolt cégkivonat*) published on [Cégportál](https://cegportal.im.gov.hu) by the Ministry of Justice under decree 47/2007. (X. 20.) IRM § 5 (1) a). It returns the same five datapoints as verification mode: `company`, `legalRepresentatives`, `shareholders`, `otherKeyPersons` and `establishments`.
The register re-renders this extract periodically, not on every change, so prefill mode is **not authoritative**. A recent filing may not be reflected yet. It also issues no certified document. The Cégkivonat and Cégmásolat are available in verification mode only.
Use prefill mode for screening and enrichment at volume. Use verification mode, the default, when you need the current register position or a certified document.
**Ownership percentages are often absent.** Hungarian extracts state member participation in words rather than as a figure. *"A szavazati jog mértéke minősített többségű befolyást biztosít"* means the voting right confers qualified-majority influence, at least 75%. Where the register publishes no capital contribution per member, `sharePercentage` is omitted rather than derived from that wording, so treat it as optional. Shareholders are still returned with their identity. This applies to both modes.
### Sole Traders: NAV EVNY
The **NAV EVNY** (Egyéni Vállalkozók Nyilvántartása, Sole Traders Registry) is operated by the Hungarian Tax Authority (NAV). This is a separate registry from the Cégjegyzék.
* **EVNY lookup**: Search by registration number (Nyilvántartási szám, 8 digits) or tax number (Adószám, 8 digits). Returns the trader's name, address, activity codes, status, and registration dates.
* **EVNY Extract**: A PDF extract of the trader's EVNY record, available as a document for sole traders.
**Sole trader profiles are structured at the source.** The register returns
structured fields, so the data is mapped directly without AI enrichment
(except address geocoding).
### Financial Statements: e-beszámoló
The **e-beszámoló** (Electronic Financial Statements Portal, `https://e-beszamolo.im.gov.hu`) is the Ministry of Justice repository where every company keeping double-entry accounts publishes its annual accounts (beszámoló).
* **Financial Statements (Éves beszámoló)**: The published annual accounts for a company — balance sheet (mérleg) and income statement (eredménykimutatás), plus, where filed, the supplementary notes (kiegészítő melléklet), the profit-distribution resolution, and the independent auditor's report. One document is available per published fiscal year, retrieved live from the portal and billed per document. When the filed document is a PDF or XML, the balance sheet and income statement are also extracted into structured `extractedFinancialData`.
**Financial statements are company-only.** Sole traders (Egyéni Vállalkozó,
EVNY) keep simplified records and are not required to prepare or publish
annual accounts, so no financial statements are available for them.
## Company Identifiers
### Query Identifiers
| Identifier | Source | Format | Example | Notes |
| - | - | - | - | - |
| **Cégjegyzékszám** (Registration number) | OCCSZ | 10 digits (hyphens stripped) | `0109430929` | Primary company identifier: court code, company form code, 6-digit sequence number. Hyphens accepted but removed (e.g., `01-09-430929` becomes `0109430929`) |
| **Nyilvántartási szám** (Sole trader reg. number) | EVNY | 8 digits | `56109748` | Primary sole trader identifier. Automatically routes to EVNY |
| **Adószám** (Tax number) | Both | 8-11 digits (hyphens stripped) | `32565144241` | Full format: `XXXXXXXX-X-XX`. First 8 digits used for registry search. Searches both OCCSZ and EVNY |
| **VAT** | VIES | HU + 8 digits | `HU32565144` | Automatically stripped to 8-digit VAT value for VIES validation |
**Tax Number Format Breakdown:** `32565144-2-41` = `32565144` (base number,
the last digit a check digit) + `2` (VAT status: 1=VAT free, 2=normal VAT,
4/5=group taxpayers) + `41` (tax office code)
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| `companyNumber` | 10 digits | `0109430929` | Companies. Hyphens stripped |
| `evnyRegistrationNumber` | 8 digits | `56109748` | Sole traders (Nyilvántartási szám) |
| `taxNumber` | `XXXXXXXX-X-XX`, sometimes without hyphens | `32565144-2-41` | As published by the register, when available |
| `VAT` | 8 digits | `32565144` | First 8 digits of tax number, present when tax number is available |
| `statisticalCode` | 17 digits, `XXXXXXXX-XXXX-XXX-XX` | `32565144-4740-113-01` | KSH statistical code, when available |
| `euid` | `HUOCCSZ.CC-TT-NNNNNN` | `HUOCCSZ.01-09-430929` | European Unique Identifier, when available in the extract (§60) |
| `vatGroupNumber` | `XXXXXXXX-X-XX` | `17783666-5-41` | Group VAT number (Csoportos adószám), present when the company is part of a Hungarian VAT group. Sourced from NAV. |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the company registration number (`companyNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Cégjegyzékszám | 10 digits | `0109430929` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Nyilvántartási szám | 8 digits | `56109748` | Exact | Exact match returned first (matchType: id, from EVNY); other results may follow |
| By Adószám (8 digits) | 8 digits | `32565144` | Exact | Company and/or sole trader (searches both OCCSZ and EVNY in parallel) |
| By Adószám (11 digits) | 11 digits | `32565144241` | Exact | Exact match returned first (matchType: id, first 8 digits used); other results may follow |
| By Adószám (with hyphens) | `XXXXXXXX-X-XX` | `32565144-2-41` | Exact | Exact match returned first (matchType: id, hyphens stripped, first 8 digits used); other results may follow |
| By VAT number | HU + 8 digits | `HU32565144` | Exact | Exact match returned first (matchType: id, HU prefix stripped, 8 digits extracted); other results may follow |
| By company name | Text string | `"bolttech Services"` | Contains | Multiple results (OCCSZ only; EVNY does not support name search) |
**8-digit queries search both registries.** A pure 8-digit input is ambiguous
(could be a sole trader registration number or a tax number), so it is searched
in both OCCSZ (by tax number) and EVNY (by both registration number and tax
number) in parallel. Results are deduplicated.
### Company Profile
For `/v2/company` company-data requests, use the **10-digit Cégjegyzékszám** for companies or the **8-digit Nyilvántartási szám** for sole traders:
* Company: `0109430929`, `0106216884`, `01-09-430929`
* Sole trader: `57478665`, `59173988`
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies being registered or in the course of deletion are kept, as their status is transitional.
## Company Status
Company status is determined **deterministically** from the Trade Register Extract. AI is used only to refine the closure reason of a deleted company when the register's deletion method matches no known pattern.
### Status Logic
Status is determined in priority order from the Trade Register Extract:
| Priority | Condition | Local Status | Standardized Status | Notes |
| - | - | - | - | - |
| 1 | §1 has "Törlés hatálya" (deletion date) | Törölve (reason) | Closed | Checked first. Company was deleted from registry |
| 2 | Name contains "végelszámolás" in quotes | végelszámolás alatt | Closed | Voluntary dissolution in progress |
| 3 | Name contains "felszámolás" in quotes | felszámolás alatt | Under Insolvency Proceeding | Bankruptcy/insolvency proceedings |
| 4 | Name contains "kényszertörlés" in quotes | kényszertörlés alatt | Closed | Administrative dissolution in progress |
| 5 | Name contains "szerkezetátalakítás" in quotes | szerkezetátalakítás alatt | Active | Structural transformation (company remains active) |
| 6 | No closure markers | Hatályos | Active | Default. Company is active |
### Closure Reasons
When status is Closed, the closure reason is derived from the "Megjegyzés" (remark) field in §1 or from the quoted status in the company name:
| Hungarian Deletion Method | Standardized Closure Reason |
| - | - |
| Contains "átalakulás" (transformation) | Merger |
| Contains "illetékességváltás" (change of court) | Merger |
| Contains "felszámolás" (liquidation) | Bankruptcy |
| Contains "kényszertörlés" (forced deletion) | Administrative Dissolution |
| Contains "végelszámolás" (voluntary winding) | Voluntary Dissolution |
| Any other method | Classified with AI, `Other` when no better reason is found |
**Struck-off companies.** When the register no longer issues a current extract
for a company, the profile returns the legal name, identifiers and a `Törölve`
closed status, without a closure reason or date. See [Documents by Entity
Type](#documents-by-entity-type).
### Sole Trader Status (EVNY)
Sole trader status is determined from the EVNY API's structured fields:
| Condition | Local Status | `active` | Standardized Status | Notes |
| - | - | - | - | - |
| `vallalkozasAllapot` = "Működő" | Működő | `true` | Active | Normal operating trader |
| `szuneteltetes` present | Szünetelő | `false` | Active (dormant) | Voluntary dormancy (up to 2 years). Entity still legally exists but is not trading. `additionalInfo` contains dormancy start date |
| `felfuggesztes` present | Felfüggesztett | `false` | Under Insolvency Proceeding | Suspended by NAV (tax authority). `additionalInfo` contains reason and dates |
| In `vallalkozasMegszunt` array | Megszűnt | `false` | Closed | Terminated. Closure reason and date when available |
## Legal Forms
The local legal form (**Cégforma**) is extracted deterministically from the TRE and then enriched with AI for ISO 20275 code and standardized company type.
### Key Business Forms
| Abbr. | Hungarian Name | English Translation | Standardized |
| - | - | - | - |
| KFT | Korlátolt Felelősségű Társaság | Limited Liability Company | Limited Liability Company |
| BT | Betéti Társaság | Limited Partnership | Partnership |
| ZRT | Zártkörűen Működő Részvénytársaság | Private Limited Company | Corporation |
| NYRT | Nyilvánosan Működő Részvénytársaság | Public Limited Company | Corporation |
| KKT | Közkereseti Társaság | General Partnership | Partnership |
| EC | Egyéni Cég | Individual Company | Sole Proprietorship |
### Sole Entrepreneurs
| Abbr. | Hungarian Name | Standardized |
| - | - | - |
| EV | Egyéni Vállalkozó | Sole Proprietorship |
### Foreign Entities
| Abbr. | Hungarian Name | Standardized |
| - | - | - |
| FIL | Külföldi Vállalkozás Magyarországi Fióktelepe | Branch or Representative Office |
| - | Külföldi Székhelyű Vállalkozás Fióktelepe | Branch or Representative Office |
### Other Forms
| Abbr. | Hungarian Name | Standardized |
| - | - | - |
| SZÖV | Szövetkezet | Cooperative |
| EGY | Egyesülés | Other |
| ALA | Alapítvány | Nonprofit Organization |
| KHT | Közhasznú Társaság | Nonprofit Organization |
Legal form standardization and ISO 20275 assignment are AI-enriched; the local
Hungarian legal form name is always preserved verbatim from the TRE.
## Legal Representatives
Legal representatives are extracted from **Section 13** (§13) of the Trade Register Extract: "A vezető tisztségviselő(k), a képviseletre jogosult(ak) adatai" (Data of executive officers and those authorized to represent).
### Extraction Details
* **Individual representatives**: Name, birth date, residence address (Hungarian or foreign), role, start date, tax ID
* **Company representatives**: Legal name, registered address, role, start date
* **Representation mode**: Extracted deterministically from Hungarian signing authority terms in §13. Each legal representative includes a `representationMode` field indicating how they can sign for the company:
* **`{ mode: "sole" }`**: Can sign alone ("önálló" or "egyedüli")
* **`{ mode: "joint" }`**: Must sign jointly with others ("együttes")
* **`null`**: No signing authority explicitly stated
**Legal representatives are only available for active companies.** Closed
companies use a minimal TRE format that may not include Section 13. This is a
register limitation.
### Legal Representative Roles
Common Hungarian register roles and their usual classification:
| Hungarian Role | English Translation | Standardized Role |
| - | - | - |
| **ügyvezető** | Managing Director | Managing Director |
| **ügyvezető (vezető tisztségviselő)** | Managing Director (Executive Officer) | Managing Director |
| **vezérigazgató** | Chief Executive Officer | Chief Executive Officer |
| **igazgatóság elnöke** | Chairman of the Board | Chairman of the Board |
| **igazgatósági tag** | Board Member | Board Member |
| **üzletvezetésre jogosult tag** | Managing Partner | Managing Partner |
| **elnök** | President | President |
| **alelnök** | Vice President | Vice President |
| **igazgatótanácsi tag** | Board of Directors Member | Board Member |
| **cégvezető** | Company Manager | Manager |
| **felszámoló** | Liquidator | Liquidator |
| **végelszámoló** | Voluntary Liquidator | Liquidator |
Known register titles have fixed English translations and standardized roles.
Unlisted exact titles retain the AI enrichment fallback. Signing authority uses the register section and recorded powers; it is not inferred from a title.
The original Hungarian role name is always preserved as `localName`.
## Other Key Persons
The TRE contains additional personnel data beyond legal representatives:
* **Auditors** (§14): Both audit firms and individually responsible auditors, with name, address, and registration number
* **Supervisory Board Members** (§15): Name, birth date, address, start date
* **Other employees with registered signing rights** (`más munkavállaló`, §13): returned as other key persons. This person category does not expose their registered signing mode.
A source entry explicitly stating that representation is not exercised is also a key person. `cégvezető` means Company Manager, rather than Managing Director; any representation grant and signing mode are separate register facts.
## Shareholders
Shareholder data is extracted from **Part II** of the Trade Register Extract when available. The TRE contains structured ownership information including:
* **Individual shareholders**: Name, birth date, address, share amount/percentage, voting rights
* **Company shareholders**: Legal name, registration number, address, share amount/percentage
Shareholder data availability depends on the company type and the TRE content.
Not all company types include Part II (ownership section) in their TRE.
## Activity Code Mapping
Hungary uses the **TEÁOR** (Tevékenységek Egységes Ágazati Osztályozási Rendszere) classification, the Hungarian adaptation of NACE. The extract marks each code as TEÁOR'08 (NACE Rev. 2) or TEÁOR'25 (NACE Rev. 2.1). TEÁOR'08 codes are converted to NACE Rev. 2.1; TEÁOR'25 codes are already Rev. 2.1 and pass through unchanged. Stamped codes are returned under the revision-explicit `TEAOR_2008` or `TEAOR_2025` key. Only unstamped codes use `TEAOR`. Activity codes are mapped across three levels:
```
TEÁOR (Hungarian) → NACE Rev. 2.1 (European) → ISIC Rev. 5 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **TEÁOR** | TRE (§902) | `6201` | No (official) |
| **NACE** | Derived from TEÁOR | `62.10` | No (deterministic conversion) |
| **ISIC** | Derived from NACE via mapping table | `621` | No (deterministic) |
**One code in, one code out.** You get one `NACE` and one `ISIC` code per declared TEÁOR code. Where a TEÁOR code has no single equivalent in the target revision, the shared parent class is returned rather than every candidate — see [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
TEÁOR codes are extracted directly from the TRE and are **never** AI-inferred.
The main activity is identified when the TRE marks it as "Főtevékenység" (main
activity). For sole traders, the EVNY register declares the main activity the
same way (fő tevékenység).
**Main activity.** The register-declared main activity ("Főtevékenység") is
flagged with `isMainActivity: true` on the TEÁOR classification and listed
first. The NACE and ISIC codes derived from it inherit the flag. Codes without
the flag are not necessarily secondary: absence means the register did not
mark them.
## Data Availability Matrix
| Data Type | Commercial Companies (OCCSZ) | Sole Traders (EVNY) | Non-Profits / Foundations | Notes |
| - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ⚠️ Limited | Companies: variable pricing. Sole traders: fixed price only |
| Legal Representatives | ✅ (active only) | ✅ (owner as legal rep) | ⚠️ Limited | OCCSZ: §13 of TRE. EVNY: owner mapped as Sole Proprietor |
| Other Key Persons | ✅ | ❌ | ⚠️ Limited | Auditors (§14), Supervisory Board (§15) from TRE |
| Shareholders | ⚠️ | ❌ (not applicable) | ❌ | OCCSZ: Part II of TRE. EVNY: no share capital, returns `datapoint_not_applicable` |
| Ultimate Beneficial Owners | ❌ | ❌ | ❌ | Not available from registry |
| Activity Codes | ✅ | ✅ | ❌ | TEÁOR from TRE/EVNY, converted to NACE + ISIC |
| Documents | ✅ | ✅ | ❌ | OCCSZ: TRE PDF, variable price. EVNY: extract PDF |
| Financial Statements | ✅ | ❌ | ❌ | Annual accounts from e-beszámoló. Companies only, sole traders do not file |
| Establishments | ✅ | ✅ | ❌ | OCCSZ: §6/§7 from TRE. EVNY: telephely addresses |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
**Egyéni Cég (EC)** (Individual Company) is a different entity type from
Egyéni Vállalkozó (EV). EC is registered in the Cégjegyzék and falls under the
Commercial Companies column.
## Documents by Entity Type
### Commercial Companies (Cégjegyzékszám)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Cégkivonat (Trade Register Extract)** | `tradeRegisterExtract` | PDF | ✅ Registered companies | Variable price, shown before purchase |
| **Cégmásolat (Trade Register History)** | `tradeRegisterHistory` | PDF | ✅ Struck-off companies | Issued instead of the Cégkivonat when the register holds no current extract. Variable price, shown before purchase |
| **Éves beszámoló (Financial Statements)** | `financialStatements` | PDF / XML / ZIP | ✅ Companies, per fiscal year | From e-beszámoló, billed per document |
**The Cégmásolat is a historical record.** It lists past register entries
with their validity periods. For a struck-off company, the profile does not
return its historical officers or owners as current data.
### Sole Traders (Nyilvántartási szám)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **EVNY Extract** | `tradeRegisterExtract` | PDF | ✅ All sole traders | Billed per document, separately from the profile |
**No financial statements for sole traders.** Sole traders keep simplified
records and do not file annual accounts, so `financialStatements` is never
returned for an EVNY entity.
**TRE price is variable.** Unlike flat-rate documents, the Trade Register
Extract price depends on the register's quote for that company. Larger
companies with more register history have higher prices. The price is always
shown in the `price` field before purchase.
## Pricing
Pricing differs by entity type:
* **Commercial companies (OCCSZ)**: **Variable** pricing, based on the register's quote for the Trade Register Extract of that company.
* **Sole traders (EVNY)**: **Fixed** pricing.
See the [pricing page](https://topograph.co/pricing/hu) for current prices. Financial statements and the EVNY extract are billed per document.
**Budget control.** For commercial companies, because pricing is variable, the
`profileMaxBudget` parameter lets you set a maximum spend. The value is
denominated in the same units as the `price` field returned by the
available-documents call. Set the cap based on the quoted price you accept. If
the estimated cost exceeds your budget, the request fails immediately with a
`budget_exceeded` error that includes the quoted price, so you can retry with a
higher cap. For sole traders, budget control is not supported.
## Data Source Priority & Routing
For a given entity, data follows a deterministic retrieval path:
**Company Profile Resolution Flow:**
1. **Price quote**: The Trade Register Extract price for the company is quoted by the register
2. **Budget check**: If `profileMaxBudget` is set, the resulting profile price is compared against the budget. The request is rejected with `budget_exceeded` if over budget
3. **Extract**: The Trade Register Extract is retrieved and read into structured data (name, address, legal form, capital, representatives, shareholders, activities, establishments, status), with the group VAT number added from NAV
4. **VIES VAT validation**: A qualified VIES check validates the VAT number (HU + first 8 digits of tax number) and obtains a consultation number
The same extract used for the company profile is delivered as the `tradeRegisterExtract` document.
### Attribute-Level Source Mapping
| Attribute | Source | AI Enriched? | Notes |
| - | - | - | - |
| Legal name | **TRE** (§2) | No | Extracted deterministically from markdown |
| Registration number | **TRE** (§1 header) | No | Hyphens stripped |
| Tax number | **OCCSZ search** + **TRE** (§21) | No | From search result `internalIdentifiers` or TRE |
| Registered address | **TRE** (§5) | Yes | Parsed from Hungarian format, AI-enriched for structuring |
| Legal form | **TRE** (Cégforma field) | Yes | Deterministic extraction, AI-enriched for ISO 20275 |
| Registration date | **TRE** (§8) | No | Founding date |
| Status | **TRE** (§1 + name) | Partial | Deterministic: §1 deletion date/reason checked first, then quoted status in name, then default active. AI refines an unrecognized closure reason |
| Share capital | **TRE** (§11) | Partial | Amount and known currencies (HUF, EUR, USD, GBP, CHF) deterministic; AI fallback only for unrecognized currencies |
| Legal representatives | **TRE** (§13) | Yes | AI extraction with deterministic fallback; known role meanings fixed, unlisted titles AI-enriched |
| Auditors | **TRE** (§14) | Yes | AI extraction with deterministic fallback |
| Supervisory board | **TRE** (§15) | Yes | AI extraction with deterministic fallback |
| Shareholders | **TRE** (Part II) | Yes | AI extraction with deterministic fallback, when available |
| Activity codes (TEÁOR/NACE) | **TRE** (§902) | No | Deterministic extraction and conversion |
| Activity codes (ISIC) | **TRE** (§902) | No | Deterministic: NACE → ISIC via official UN correspondence table |
| Establishments | **TRE** (§6, §7) | Yes | Deterministic extraction, address AI-enriched |
| Group VAT number | **NAV** (csoportos\_afaalanyok) | No | Sourced from the NAV Group VAT registry when the company is part of a Hungarian VAT group. Present in `identifiers.vatGroupNumber` |
| VAT verification | **VIES** | No | Qualified check with consultation number |
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "HU", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "0109430929",
"countryCode": "HU",
"identifiers": { "companyNumber": "0109430929", "taxNumber": "32565144-2-41", "VAT": "32565144", "euid": "HUOCCSZ.01-09-430929" },
"taxId": {
"type": "eu_vat",
"value": "32565144",
"country": "HU",
"verification": {
"status": "verified",
"verifiedName": "PELDA TECHNOLOGIA KFT",
"consultationNumber": "WAPIXXXXXXXXXXXX"
}
},
"legalName": "Példa Technológia Korlátolt Felelősségű Társaság",
"registrationDate": "2024-05-28",
"status": { "localName": "Hatályos", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Korlátolt Felelősségű Társaság", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "P9F2" },
"capital": { "amount": 3100000, "currency": "HUF" },
"activities": {
"TEÁOR": [{ "code": "6201", "description": "Számítógépes programozás", "isAIInferred": false }],
"TEAOR_2008": [{ "code": "6201", "description": "Számítógépes programozás", "isAIInferred": false }],
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "621", "description": "Computer programming activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "2 Ferenciek tere", "city": "Budapest", "postalCode": "1053", "countryCode": "HU" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "ügyvezető", "englishTranslation": "Managing Director", "standardized": "Managing Director" },
"representationMode": { "mode": "sole" },
"individual": {
"name": { "fullName": "Nagy István", "firstName": "Nagy", "lastName": "István" },
"birthDate": { "year": 1985, "month": 6, "day": 15 },
"residenceAddress": { "addressLine1": "10 Andrássy út", "city": "Budapest", "postalCode": "1061", "countryCode": "HU" }
},
"startDate": "2024-05-28"
}
]
}
```
```json theme={null}
{
"company": {
"id": "0106216884",
"countryCode": "HU",
"identifiers": { "companyNumber": "0106216884", "taxNumber": "28383040-2-42" },
"legalName": "Példa Kereskedelmi Betéti Társaság \"végelszámolás alatt\"",
"status": {
"localName": "Törölve",
"active": false,
"statusDetails": { "status": "CLOSED" }
}
},
"legalRepresentatives": []
}
```
**Note:** When the register no longer issues a current extract for a struck-off company, the profile returns only the legal name, identifiers and a closed status. Person datapoints are empty, and the historical register copy (Cégmásolat) is delivered as the `tradeRegisterHistory` document. Companies that were in liquidation ("végelszámolás alatt") before deletion retain that marker in their legal name.
```json theme={null}
{
"company": {
"id": "57478665",
"countryCode": "HU",
"identifiers": { "evnyRegistrationNumber": "57478665", "taxNumber": "59443494129", "VAT": "59443494" },
"taxId": {
"type": "eu_vat",
"value": "59443494",
"country": "HU",
"verification": { "status": "verified", "verifiedName": "KOVÁCS ÁDÁM" }
},
"legalName": "KOVÁCS ÁDÁM e.v.",
"registrationDate": "2022-09-01",
"activityDescription": "Reklámfelület ügynöki értékesítése",
"status": { "localName": "Működő", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Egyéni vállalkozó", "englishTranslation": "Sole Proprietorship", "standardized": "Sole Proprietorship" },
"activities": {
"TEÁOR": [{ "code": "731201", "description": "Reklámfelület ügynöki értékesítése" }],
"NACE": [{ "code": "73.12", "description": "Media representation" }],
"ISIC": [{ "code": "7310", "description": "Media representation" }]
},
"legalAddress": { "addressLine1": "VINCELLÉR UTCA 2 10 em. 87 ajtó", "city": "DEBRECEN", "postalCode": "4031", "countryCode": "HU" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Egyéni vállalkozó", "englishTranslation": "Sole Proprietor", "standardized": "Owner" },
"individual": { "name": { "fullName": "KOVÁCS ÁDÁM", "firstName": "ÁDÁM", "lastName": "KOVÁCS" } }
}
]
}
```
**Note:** Sole traders always have exactly one legal representative (the owner, role "Sole Proprietor"). A sole trader has no share capital, so a `shareholders` request returns `datapoint_not_applicable`. Activity codes use 6-digit TEÁOR codes from EVNY (vs 4-digit from OCCSZ TRE). Legal name includes the "e.v." suffix (egyéni vállalkozó).
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Cégkivonat (Trade Register Extract) PDF | Variable price. Registered companies. For sole traders, the EVNY extract |
| `tradeRegisterHistory` | Cégmásolat (Trade Register History) PDF | Variable price. Struck-off companies, instead of the Cégkivonat |
| `financialStatements` | Éves beszámoló (Financial Statements), one entry per published fiscal year | Retrieved from e-beszámoló, billed per document. Companies only |
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_abc123",
"name": "Trade Register Extract",
"description": "Trade register extract from the Hungarian Trade Register (Ministry of Justice)",
"format": "pdf"
}
},
"request": {
"companyId": "0109430929",
"countryCode": "HU",
"dataStatus": {
"dataPoints": {
"availableDocuments": { "status": "succeeded" }
}
}
}
}
```
**Note:** Each document carries a `price` field, in credits, shown before purchase. The Trade Register Extract price varies per company.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Hyphens in identifiers** | Both Cégjegyzékszám and Adószám may contain hyphens (e.g., `01-09-430929`, `28383040-2-42`). These are stripped internally before processing. |
| **Leading zeros in registration numbers** | Registration numbers always have 10 digits. Numbers with leading zeros (e.g., `0109430929`, Budapest court code `01`) are preserved correctly. |
| **Liquidation detected from company name** | Companies in liquidation are identified by the presence of "végelszámolás alatt" or "v.a." in the legal name, not from a dedicated status field. |
| **TRE price is variable** | The Trade Register Extract price depends on the register's quote for that company. Larger companies (more history, more sections) cost more. Prices are always shown before purchase. |
| **Company profile = TRE** | In verification mode, the company profile is derived from the Trade Register Extract. For a struck-off company, the historical Cégmásolat is issued instead and the profile returns only the name, identifiers and closed status. |
| **No shareholders for all company types** | Part II (ownership section) is not present in all TRE documents. Availability depends on the company type and registry content. |
| **No legal reps for closed companies** | Section 13 (legal representatives) may be absent in TRE documents for closed companies. |
| **Group VAT number not in the Trade Register** | The Csoportos adószám is not published in the Cégkivonat. It is sourced separately from NAV and may not be present for all companies. Both the regular tax number and the group tax number must appear on invoices when a company is part of a VAT group. |
| **Closure reason defaults to OTHER** | When a company is closed ("Törölve") and the deletion method doesn't match a known pattern, the closure reason is classified with AI and defaults to `OTHER` when no better reason is found. Known patterns: átalakulás and illetékességváltás (Merger), felszámolás (Bankruptcy), kényszertörlés (Administrative Dissolution), végelszámolás (Voluntary Dissolution). |
| **TEÁOR = NACE** | TEÁOR'08 codes are NACE Rev. 2 classes, upconverted to our NACE Rev. 2.1 output revision (so TEÁOR'08 `6201` is returned as NACE `62.10`, not `62.01`). TEÁOR'25 codes are already NACE Rev. 2.1 and pass through unchanged. |
| **8-digit IDs are ambiguous** | A pure 8-digit input could be a sole trader registration number or a tax number. Both OCCSZ and EVNY are searched in parallel, with deduplication. |
| **Sole traders use 6-digit TEÁOR codes** | EVNY provides 6-digit TEÁOR codes (e.g., `731201`) vs. 4-digit from OCCSZ TRE (e.g., `7312`). The first 4 digits are identical and map to the same NACE/ISIC codes. |
| **EVNY name search not supported** | The EVNY API does not support name-based search. Only registration number and tax number queries are available for sole traders. |
# Iceland
Source: https://docs.topograph.co/essentials/iceland
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Iceland reference is on the [Iceland country page](https://www.topograph.co/countries/is).
## Start here
This guide contains public integration notes for Iceland. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Iceland uses a single official government registry. All company data comes from the Skatturinn Company Register. There are no fallback registries or secondary data sources.
* **Skatturinn (RSK Fyrirtækjaskrá).** The Icelandic Directorate of Internal Revenue (Ríkisskattstjóri) maintains the Company Register (Fyrirtækjaskrá). The register provides company profiles, legal representatives, UBO data, ÍSAT activity codes, VAT numbers, and documents. Accessible at [skatturinn.is/fyrirtaekjaskra/](https://www.skatturinn.is/fyrirtaekjaskra/).
**Single-source model.** All entity data comes from Skatturinn: company profiles, legal representatives, UBOs, available documents and search results are all read from the Company Register.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entity types** | RSK Fyrirtækjaskrá | 10 digits (Kennitala) | `5602151420` | Kennitala, the national identification number, also used for individuals |
**Kennitala Format:** Icelandic kennitala is a 10-digit number (DDMMYY-RRCX). The first 6 digits encode a date. For legal entities the first two digits are the day plus 40 (41 to 71); individuals keep the calendar day (01 to 31). The century is determined by the 10th digit: `9` = 1900s, `0` = 2000s. Example: `5602151420` → 16 February 2015. A kennitala starting 01 to 31 in the company register belongs to a sole entrepreneur trading under their own national ID. The 9th digit is a check digit. Responses carry the kennitala without the hyphen; send it the same way.
### Identifiers in API Response
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `kennitala` | 10 digits | `5602151420` | All entities |
| `VAT` | 5 or 6 digits, no prefix | `119978` | VAT-registered entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the kennitala (`kennitala`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Kennitala | 10 digits | `5602151420` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"AD Company"` | Partial/Contains | Multiple results |
**Search Performance:** Use kennitala searches for exact matching. Name searches run live against the register and may be slower.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Supported Entity Families
| Entity Family | Legal Forms | Notes |
| - | - | - |
| **Private Limited Companies** | ehf. (Einkahlutafélag) | Most common company type in Iceland |
| **Public Limited Companies** | hf. (Hlutafélag) | Includes listed companies, which are exempt from UBO disclosure |
| **Partnerships** | sf. (Sameignarfélag) | General partnerships |
| **Cooperatives** | svf. (Samvinnufélag) | Cooperative associations |
| **Self-employed** | Einstaklingsfyrirtæki | Sole proprietorships |
| **Non-profits** | félag (Association) | Non-profit organizations |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Listed hf. companies have no UBOs** | Public limited companies (hf.) listed on the Icelandic stock exchange are exempt from UBO disclosure under Act 82/2019. The UBO section is absent from their registry page. |
| **UBO data is public** | Unlike many EU countries, Icelandic UBO data is publicly accessible directly on the company registry page, without authentication or special access. |
| **All data is live** | Every request reads the register in real time. This means slightly higher latency but always-fresh data. |
| **Supported documents** | The Trade Register Extract (Gjaldfrjálst yfirlit) and annual accounts (Ársreikningur) are available. Certified certificates and notarized documents are not supported. |
| **Board and key persons come from the Trade Register Extract** | The register's company page only lists one "Forráðamaður" (authorized person). Full board members, auditors, CEOs, and proxy holders are extracted from the Trade Register Extract (Gjaldfrjálst yfirlit) PDF. |
| **ÍSAT codes and NACE** | ÍSAT2008, the Icelandic extension of NACE Rev. 2, is returned verbatim under the revision-explicit `ISAT_2008`. The `NACE` key carries the corresponding NACE Rev. 2.1 classes, with NACE descriptions. |
| **Shareholders via AI reconstruction** | Shareholder data is extracted via AI reconstruction from documents (annual accounts, Trade Register Extract), not from structured register data. |
## Company Status
Iceland returns the local status and the `active` flag. No standardized `statusDetails` is set.
| Local Status | `active` | Notes |
| - | - | - |
| Virk | `true` | Standard active status |
| Afskráð | `false` | Deregistered from the company register |
## Legal Forms
| Icelandic Name | Abbreviation | Code | English Translation |
| - | - | - | - |
| Einkahlutafélag | ehf. | E1 | Private Limited Company |
| Hlutafélag, almennt | hf. | H2 | Public Limited Company |
| Sameignarfélag | sf. | S1 | General Partnership |
| Samvinnufélag | svf. | S3 | Cooperative |
| Einstaklingsfyrirtæki | - | E3 | Sole Proprietorship |
**AI-enriched legal forms.** Legal form codes (e.g., `E1`) and Icelandic names are extracted from the registry. The standardized English translation and ISO 20275 mapping are provided by the AI legal form enrichment parser.
## Legal Representatives
The register's company page lists a single "Forráðamaður" (authorized person/director), but the company profile datapoint enriches this with the Trade Register Extract (Gjaldfrjálst yfirlit) PDF to extract the full board plus other key persons when available. Known office meanings have fixed translations and standardized values; unfamiliar labels may remain unstandardized. The PDF distinguishes representing appointments from other key persons: a board seat or reserve appointment alone does not confer an individual signing grant. Managing directors represent within their ordinary-management duties. Recorded personal or category signing rules determine additional authority; no sole or joint mode is inferred from a title.
| Icelandic Role | English Translation | Standardized Role |
| - | - | - |
| Stjórnarformaður | Chairman of the Board | Chairman of the Board |
| Framkvæmdastjóri | Managing Director | Managing Director |
| Stjórnarmaður | Board Member | Board Member |
| Prókúruhafi | Procuration Holder | Authorized Signatory |
## Ultimate Beneficial Owners (UBOs)
UBO data is extracted from the "Raunverulegir eigendur" section of the company registry page. This data is mandated by Act 82/2019 on measures against money laundering and terrorist financing.
| Field | Description |
| - | - |
| `name.fullName` | UBO's full name |
| `birthDate` | Birth year and month (e.g., 1984-07) |
| `nationality` | Country of nationality (AI-resolved from Icelandic name) |
| `residenceAddress.countryCode` | Country of residence (AI-resolved) |
| `control.types` | Ownership type (see mapping below) |
| `control.details` | Ownership percentage when available |
### Ownership Type Mapping
| Icelandic Type | English | Control Type |
| - | - | - |
| Beint eignarhald | Direct ownership | `ownership-of-shares` |
| Óbeint eignarhald | Indirect ownership | `ownership-of-shares` |
| Bein stjórnun | Direct management | `significant-influence-or-control` |
| Stjórn skráð sem eigandi | Management registered as owner | `significant-influence-or-control` |
**Management-as-owner pattern.** For companies where no individual holds a qualifying ownership stake, the board may be registered as UBOs with the type "Stjórn skráð sem eigandi" (management registered as owner) and ownership share marked as `-`. This is common for larger ehf. companies.
## Shareholders
Shareholders are extracted via **AI reconstruction** from documents (annual accounts and Trade Register Extract PDFs). This uses the same pattern as France and Belgium.
**AI-reconstructed data.** Shareholder data is not available as structured data from the registry. It is extracted from PDF documents using AI, which means accuracy depends on document quality. Results should be verified.
## Data Availability Matrix
| Data Type | ehf. | hf. | sf. / svf. | Notes |
| - | - | - | - | - |
| Company Profile | ✅ Live | ✅ Live | ✅ Live | Read from the register in real time |
| Legal Representatives | ✅ | ✅ | ✅ | Full board and key persons extracted from the Trade Register Extract |
| Other Key Persons | ✅ | ✅ | ✅ | Auditors and chartered auditors (Skoðunarmaður, Endurskoðandi) from the Trade Register Extract |
| UBOs | ✅ | ✅ (listed hf. exempt) | ✅ | Act 82/2019 |
| Shareholders | ✅ AI | ✅ AI | ✅ AI | AI reconstruction from documents |
| Trade Register Extract | ✅ | ✅ | ✅ | PDF used as source for structured company data |
| Annual Accounts | ✅ | ✅ | ✅ | All available fiscal years |
| Company Data | ✅ Live | ✅ Live | ✅ Live | Structured company data built from the live register page and the Trade Register Extract |
| Activity Codes (ÍSAT/NACE) | ✅ | ✅ | ✅ | ÍSAT from the register page, NACE Rev. 2.1 derived from it |
**Legend:** ✅ Available | ❌ Not Available | Live = Read from the register in real time | AI = AI reconstruction
## Documents
| Document Type | API Category | Format | Notes |
| - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | Gjaldfrjálst yfirlit, registration overview PDF included with company data |
| **Annual Accounts** | `financialStatements` | PDF | Ársreikningur, all available fiscal years |
**Only annual accounts are ordered separately.** The Trade Register Extract is included with company data because it is used to build structured company data. The certified certificate (Staðfest vottorð) is not supported.
## Pricing
See the [Iceland pricing page](https://topograph.co/pricing/is) for current prices and delivery times. The Trade Register Extract is included with company data rather than billed separately.
## Example API Responses
All examples use **real data from the Icelandic Company Register**.
Query: `GET /v2/search?country=IS&query=Marel`
```json theme={null}
{
"results": [
{
"id": "6407070540",
"countryCode": "IS",
"legalName": "Marel Iceland ehf.",
"address": { "addressLine1": "Austurhrauni 9, 210 Garðabær", "countryCode": "IS" }
},
{
"id": "5005022310",
"countryCode": "IS",
"legalName": "Marel Edvaldsson ehf.",
"address": { "addressLine1": "Fornubúðum 12, 220 Hafnarfjörður", "countryCode": "IS" }
}
]
}
```
Query: `POST /v2/company` with `{ "id": "5602151420", "countryCode": "IS", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "5602151420",
"countryCode": "IS",
"identifiers": { "kennitala": "5602151420", "VAT": "119978" },
"legalName": "AD Company ehf.",
"registrationDate": "2015-01-05",
"status": { "localName": "Virk", "active": true },
"legalForm": { "localName": "Einkahlutafélag (ehf)", "englishTranslation": "Private Limited Company", "standardized": "Limited Liability Company" },
"legalAddress": { "addressLine1": "Hafnargötu 50 230 Reykjanesbær", "countryCode": "IS" },
"activities": {
"ISAT_2008": [
{ "code": "74.90.0", "description": "Önnur ótalin sérfræðileg, vísindaleg og tæknileg starfsemi" },
{ "code": "74.30.0", "description": "Þýðingar- og túlkunarþjónusta" }
],
"NACE": [
{ "code": "74.9", "description": "Other professional, scientific and technical activities n.e.c." },
{ "code": "74.30", "description": "Translation and interpretation activities" }
]
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "stjórnarmaður", "englishTranslation": "Board Member", "standardized": "Board Member" },
"individual": { "name": { "fullName": "Dominika Anna Madajczak" } }
}
]
}
```
Query: `POST /v2/company` with `{ "id": "5602151420", "countryCode": "IS", "dataPoints": ["ultimateBeneficialOwners"] }`
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "Dominika Anna Madajczak" },
"birthDate": { "year": 1984, "month": 7 },
"nationality": "IS",
"residenceAddress": { "countryCode": "IS" },
"control": {
"types": ["ownership-of-shares"],
"details": [{ "type": "shares", "percentageValue": 100, "nature": "direct" }]
}
}
]
}
```
Query: `POST /v2/company` with `{ "id": "6407070540", "countryCode": "IS", "dataPoints": ["ultimateBeneficialOwners"] }`
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "Viðar Erlingsson" },
"birthDate": { "year": 1975, "month": 10 },
"nationality": "IS",
"control": { "types": ["significant-influence-or-control"], "details": [] }
},
{
"entityId": "person_002",
"name": { "fullName": "Elín Granz" },
"birthDate": { "year": 1974, "month": 5 },
"nationality": "IS",
"control": { "types": ["significant-influence-or-control"], "details": [] }
}
]
}
```
**Note:** When no individual holds a qualifying ownership stake, board members are registered as UBOs with "Stjórn skráð sem eigandi" (management registered as owner).
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Trade Register Extract (Gjaldfrjálst yfirlit) | PDF overview included with company data |
| `financialStatements` | Annual Accounts (Ársreikningur) | All available fiscal years |
# Ireland
Source: https://docs.topograph.co/essentials/ireland
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Ireland reference is on the [Ireland country page](https://www.topograph.co/countries/ie).
## Start here
This guide contains public integration notes for Ireland. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Fast search data](#fast-search-data)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
All company data is sourced from the **Companies Registration Office (CRO)**, Ireland's central registry for companies, business names, and limited partnerships. The CRO was formally re-established under the Companies Act 2014, which consolidated Ireland's 17 prior Companies Acts (1963-2013) into a single statute that took effect on 1 June 2015.
Three CRO sources are used:
* **CRO Public API** -- The official web services API providing basic company profile data (name, status, legal form, registered address, registration date) and company search. Used as the **primary source** for structured company data.
* **CRO Open Data** -- The company dataset supplies declared NACE Rev. 2 classifications when available.
* **CRO Core Portal** -- The CRO's online filing and enquiry platform. Used for **document listing and retrieval** (historical filings, certificates, reports, and generated extracts).
The CRO Public API provides only basic company profile data (name, status, legal form, address). It does **not** provide structured data for legal representatives, shareholders, or activity codes. Legal representatives and shareholders are instead extracted from CRO documents using AI parsing (see sections below).
### Data Source Priority & Routing
Ireland uses a single register (CRO) with several access interfaces. Unlike France or Germany, there is no multi-source priority chain -- **all data comes from the CRO**:
1. **Company Profile** -- Live query to the CRO Public API, supplemented with declared activity codes from CRO Open Data
2. **Legal Representatives & Other Key Persons** -- AI-extracted from the Company Printout document (or the Business Name Profile for registered business names), retrieved from CRO Core
3. **Shareholders** -- AI-extracted from the most recent annual return (B1C preferred, then B1, then B1C3), retrieved from CRO Core
4. **Documents** -- Listed and retrieved from CRO Core
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Supported domestic private and public companies limited by shares, including DACs limited by shares. Business names are excluded. Example: `IECRO.368047`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Identifier | Format | Example | Notes |
| - | - | - | - |
| **Company Number** | 1 to 6 digits | `368047` | Primary CRO registration number. No zero-padding. |
| **Business Name Number** | CRO number + `-B` suffix | `131910-B` | Registered business names (sole traders and trading names) on the CRO Business Names register |
| **VAT Number** | `IE` + 7 digits + 1 or 2 letters (the `IE` prefix is optional) | `IE6388047V` | Search only. Validated in VIES, then resolved to the company through the name VIES returns. Older numbers with a letter in second position (such as `IE1Z23456A`) are not recognised |
Irish company numbers are numeric with no fixed length. Both `12965` and `308943` are valid formats. There is no check digit or prefix.
The same CRO number can belong to both a company and a registered business name (for example, `131910` is a company and `131910-B` is an unrelated business name). Use the `-B` suffix to address the business name; the bare number always addresses the company.
### Identifiers in API Response
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| `companyNumber` | Numeric string | `"368047"` | CRO registration number. For a business name this is the bare number: the `-B` suffix appears only in `company.id` and in the search result `id` |
| `euid` | `IECRO.` + CRO number | `"IECRO.368047"` | Supported domestic companies only; never on a business name |
**VAT is searchable but not returned.** You can search with an Irish VAT number, but the CRO does not publish VAT numbers or Revenue registration numbers, so no VAT or tax identifier is returned under `identifiers`. The CRO company number, an eligible EUID, and an optional matched LEI may be returned.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the CRO company number matches a registration or validation reference in GLEIF and identifies a single LEI.
Registered business names with a `-B` identifier are excluded because their numbers overlap with unrelated companies.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Company Number | Numeric string | `12965` | Exact | Exact match returned first (matchType: id); a business name sharing the number is returned as a separate result with its `-B` id |
| By Business Name Number | Number + `-B` | `131910-B` | Exact | The registered business name only |
| By VAT Number | `IE` + 7 digits + 1 or 2 letters | `IE6388047V` | Name from VIES | The number is validated in VIES, then the CRO is searched by the name VIES returns |
| By Company Name | Text string | `"CRH Public Limited"` | Contains | Multiple results, across companies, business names, and external companies |
**Companies and business names are distinct results.** Name and number searches cover the Companies, Business Names, and External Companies registers. A business name always carries the `-B` suffix in its `id`, so it never collides with a company that has the same CRO number.
Use company number searches for exact matching. Name searches use a "contains" match type and may return many results for common terms.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Fast search data
Ireland company data is **periodically synchronized** from the CRO Open Data CSV into a fast search index.
### Search
Search queries hit the **fast search index first** for instant results, with automatic fallback to the live CRO API if the fast search index misses.
### Companies in fast search data
The fast search index contains **only active Irish entities** from the CRO dataset. Companies are filtered by CRO status code:
| Included Status | Code | Description |
| - | - | - |
| Normal | `1151` | Active company |
| ReInstated HCO | `1160` | Reinstated by High Court order |
| ReInstated | `1161` | Reinstated |
All other status codes (Liquidation, Strike Off Listed, Struck Off, Dissolved, Ceased, etc.) are **excluded** from the fast search dataset.
### Prefill Mode
In prefill mode, requests for the `company` datapoint use the fast search dataset rather than a live CRO lookup. This provides faster responses with lighter enrichment. Data freshness depends on the source refresh schedule. The dataset covers the Companies register only, so registered business names (`-B` ids) are read live from the CRO in prefill mode.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Activity coverage varies** | CRO Open Data provides a NACE Rev. 2 class for some companies. Companies without a valid declared class and registered business names have no activity codes. |
| **Legal reps from AI parsing** | Directors and secretaries are extracted from the Company Printout PDF using AI, not from a structured API endpoint. The CRO Public API does not expose officer data. |
| **Shareholders from the latest annual return** | Shareholders are AI-extracted from the most recent annual return. The B1C (Annual Return with Accounts) is preferred, then a plain B1, then a B1C3, all within the same age limit. Shareholders are empty when none of these forms is recent enough. |
| **Annual return age limit** | The annual return must cover at most the current year minus 2. In 2026, only returns covering 2024 or later are accepted. Older filings are rejected to avoid stale data. |
| **Shareholders require active status** | Shareholder extraction only runs for companies with Active, Under Insolvency Proceeding, or Unknown status. Closed companies return no shareholders. |
| **Business names have no shareholders** | A registered business name (`-B` id) issues no shares. Requesting `shareholders` returns a `datapoint_not_applicable` error; the registered owner(s) are returned under `legalRepresentatives`. |
| **Company number format varies** | Irish company numbers are 1 to 6 digits, with no fixed length or zero-padding. Values like `12965`, `104547`, and `308943` are all valid. |
| **PDF multi-column parsing** | CRO Company Printout PDFs use multi-column layouts where sections may be interleaved. Page footers containing dates and "Company:" text must be distinguished from actual addresses. |
| **Document retrieval is asynchronous** | Document retrieve and download involves a multi-step process (retrieval, download, save) that typically takes 1-2 minutes per document. |
| **Letter of Status is delivered later** | The CRO produces the Letter of Status after the order, and it arrives about one business day later. Consume it through the webhook or by polling the request. |
| **Documents are priced per type** | Check `availableDocuments` and the [pricing page](https://topograph.co/pricing/ie) for the price of each document type before retrieval. |
| **CRO status text has trailing spaces** | The `company_status_desc` from the CRO API may include trailing whitespace (e.g., `"Normal "` instead of `"Normal"`). The `localName` preserves this verbatim. |
## Statutory Filings
Every Irish company has a **Next Annual Return Date (NARD)**, the date its annual return (Form B1) falls due. The CRO publishes it alongside the date of the last return filed, and both are returned on the cross-country `statutoryFilings` field.
The Irish annual return is the same obligation as the UK confirmation statement: a periodic confirmation that the company's particulars are current. It is **not** a financial filing, so it maps to `annualFiling`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"lastFiled": { "periodEnd": "2025-05-23" },
"next": { "periodEnd": "2026-05-23" },
"source": "cro"
}
}
}
```
**The NARD is not the filing deadline.** The CRO defines the Annual Return Date as the latest date to which a return must be *made up*, and the return is then due within 56 days of it. Both dates are therefore reported as `periodEnd`, and no `dueDate` is published: treating the NARD as a deadline would mark every Irish company overdue about eight weeks early.
The deadline is not derived either, because it is not a plain 56 days. It extends to the next working day when it falls on a weekend or public holiday, and where financial statements must be annexed it is the earlier of ARD + 56 days and financial-year-end + 9 months + 56 days.
The `accounts` obligation is **not** returned for Ireland: the CRO company endpoint carries no accounts date. **Business names** (the `-B` register, sole traders) file no annual return at all, so `statutoryFilings` is absent for them.
See [Compliance Signals & Statutory Filings](/essentials/compliance-signals) for the full field reference.
## Mappings
### Company Status
Company status is determined **deterministically** from CRO numeric status codes -- no AI inference is involved.
| Code | CRO Status | Standardized Status | Closure Reason | Active? |
| - | - | - | - | - |
| 1151 | Normal | Active | - | Yes |
| 1153 | Normal (Receivership) | Active | - | Yes |
| 1160 | ReInstated HCO | Active | - | Yes |
| 1161 | ReInstated | Active | - | Yes |
| 1162 | Interim | Active | - | Yes |
| 1154 | Examinership | Under Insolvency Proceeding | - | Yes |
| 1152 | Liquidation | Under Insolvency Proceeding | Liquidation | No |
| 1155 | Liquidation (Receivership) | Under Insolvency Proceeding | Liquidation | No |
| 1156 | Strike Off Listed | Under Insolvency Proceeding | Administrative Dissolution | No |
| 1157 | Struck Off | Closed | Administrative Dissolution | No |
| 1158 | Dissolved | Closed | Voluntary Dissolution | No |
| 1159 | Dissolved-20 years | Closed | Voluntary Dissolution | No |
| 1163 | Ceased | Closed | Other | No |
| 1173 | Dissolved PostMerger | Closed | Merger | No |
**Examinership** is an Irish insolvency process (similar to US Chapter 11) where the company remains active while under court protection. The company is mapped as `active: true` but with status `UNDER_INSOLVENCY_PROCEEDING` because it can still trade.
**Normal (Receivership)** means the company is in receivership but not in liquidation -- it remains active. A receiver manages specific assets while the company continues to operate.
### Legal Forms
Ireland's company types are defined by the Companies Act 2014 and earlier legislation. The CRO assigns a numeric `company_type_code` to each entity. The mapping to standardized forms is **deterministic** (hardcoded lookup table, not AI-inferred). ISO 20275 (ELF) codes are returned where one exists for the form, as shown in the tables below.
Legal forms are classified from official registry data. For known codes, standardized classification is applied directly; for unrecognized codes, AI-based classification is used as fallback.
#### Business Names
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Business name - Individual | Business Name (Sole Trader) | Sole Proprietorship | - |
| Business name - Partnership | Business Name (Partnership) | Partnership | - |
| Business name - Body Corporate | Business Name (Body Corporate) | Other | - |
#### Limited Companies
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Private limited by shares | Private Company Limited by Shares | Limited Liability Company | MNQ7 |
| LTD - Private Company Limited by Shares | Private Company Limited by Shares | Limited Liability Company | MNQ7 |
| Public limited company | Public Limited Company | Corporation | VYAX |
| PLC - Public Limited Company | Public Limited Company | Corporation | VYAX |
| Public limited company (closed ended) | Closed-Ended Public Limited Company | Corporation | VYAX |
| Single member private company limited by shares | Single Member Private Company Limited by Shares | Limited Liability Company | MNQ7 |
| Private, limited by shares, licence to omit ltd | Private Company Limited by Shares (Licence to Omit Ltd) | Limited Liability Company | MNQ7 |
#### Designated Activity Companies
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| DAC - Designated Activity Company (limited by shares) | Designated Activity Company (Limited by Shares) | Limited Liability Company | 5AX8 |
| DAC - Designated Activity Company (limited by shares) (Licenced Company) | Designated Activity Company (Limited by Shares, Licenced) | Limited Liability Company | 5AX8 |
| DAC - Designated Activity Company (limited by guarantee) | Designated Activity Company (Limited by Guarantee) | Limited Liability Company | 5AX8 |
| DAC - Designated Activity Company (limited by guarantee) (licenced company) | Designated Activity Company (Limited by Guarantee, Licenced) | Limited Liability Company | 5AX8 |
#### Unlimited Companies
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Private unlimited with share capital | Private Unlimited Company with Share Capital | Limited Liability Company | KMFX |
| ULC - Private Unlimited Company | Private Unlimited Company | Limited Liability Company | KMFX |
| ULC - Private Unlimited Company (licenced company) | Private Unlimited Company (Licenced) | Limited Liability Company | KMFX |
| Public unlimited company with a share capital | Public Unlimited Company with Share Capital | Corporation | KMFX |
| PUC - Public Unlimited Company | Public Unlimited Company | Corporation | KMFX |
| Public unlimited company without share capital | Public Unlimited Company without Share Capital | Corporation | KMFX |
| PULC - Public Unlimited Company without share capital | Public Unlimited Company without Share Capital | Corporation | KMFX |
| PUC - Public Unlimited Company (licenced company) | Public Unlimited Company (Licenced) | Corporation | KMFX |
| PULC - Public Unlimited Company without share capital (licenced company) | Public Unlimited Company without Share Capital (Licenced) | Corporation | KMFX |
#### Guarantee Companies
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Guarantee company without a share capital (public) | Public Guarantee Company without Share Capital | Limited Liability Company | C58S |
| Private guarantee with share capital | Private Company Limited by Guarantee with Share Capital | Limited Liability Company | C58S |
| CLG - Company Limited by Guarantee | Company Limited by Guarantee | Limited Liability Company | C58S |
| Guarantee licence company w/o sh/capital (public) | Public Guarantee Company (Licenced) | Limited Liability Company | C58S |
| Single member company ltd by g/tee with sh/cap | Single Member Company Limited by Guarantee with Share Capital | Limited Liability Company | LMIM |
| Private guarantee with shares, licence to omit ltd | Private Company Limited by Guarantee (Licence to Omit Ltd) | Limited Liability Company | C58S |
| CLG - Company Limited by Guarantee (licenced company) | Company Limited by Guarantee (Licenced) | Limited Liability Company | C58S |
#### Partnerships
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Limited Partnership | Limited Partnership | Partnership | HNJK |
#### Investment Companies
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Public limited company with variable capital | Investment Company with Variable Capital (Public) | Corporation | VYAX |
| Private company with variable capital | Investment Company with Variable Capital (Private) | Limited Liability Company | MNQ7 |
| Part XII Pub/Priv Investment Company | Investment Company (Part XII) | Corporation | MNQ7 |
| IC - Investment company - Part 24 Companies Act 2014 | Investment Company (Part 24, Companies Act 2014) | Corporation | 2GV9 |
| U.C.I.T | Undertaking for Collective Investment in Transferable Securities | Trust | - |
| UCITS - Undertaking for Collective Investment in Transferable Securities | Undertaking for Collective Investment in Transferable Securities | Trust | 2GV9 |
#### European Companies (Societas Europaea)
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Societas Europaea - New Incorporation | Societas Europaea (New Incorporation) | Corporation | JXDX |
| Societas Europaea - Transfer into State | Societas Europaea (Transfer into State) | Corporation | JXDX |
| Societas Europaea - Formation of Subsidiary | Societas Europaea (Formation of Subsidiary) | Corporation | JXDX |
| Societas Europaea - PLC conversion | Societas Europaea (PLC Conversion) | Corporation | JXDX |
| PLC - Societas Europaea conversion | Societas Europaea (from PLC Conversion) | Corporation | JXDX |
#### Foreign / Branch / Other
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| External company | External Company | Branch or Representative Office | - |
| Foreign Body Corporate making a local offer (B18a) | Foreign Branch (Local Offer) | Branch or Representative Office | - |
| Inward Migrating Company | Inward Migrating Company | Branch or Representative Office | - |
| Unknown | Unknown | Other | - |
**Standardization rationale:** Unlimited companies (ULC, PUC, PULC) are mapped to `Limited Liability Company` or `Corporation` based on their private/public nature, despite having unlimited member liability. This prioritizes corporate structure over liability model for consistent classification. Guarantee companies (CLG, DAC guarantee) are similarly mapped to `Limited Liability Company` as they are corporate bodies with separate legal personality.
### Legal Representatives
Legal representatives are **AI-extracted** from the CRO Company Printout document (trade register extract). The CRO Public API does not provide structured officer data.
| Role | Classification | Authority |
| - | - | - |
| **Director** | Other Key Person (`Board Member`) unless individual authority is recorded | The board acts as a body; the title alone does not establish personal signing powers |
| **Registered Person / Authorized Representative** | Legal Representative (`Authorized Signatory`) | Recorded authority to bind or represent the company |
| **Company Secretary** | Other Key Person | Statutory officer but no legal representation authority |
| **Electronic Filing Agent** | Other Key Person | Authority for CRO filings; this appointment alone does not establish general signing powers |
| **Business Name Owner** | Legal Representative | Registered owner of a business name (`-B` id), individual or company |
Known source titles have fixed English meanings and standardized roles. The Company Printout is extracted using AI, and unlisted titles retain that fallback. Classification also uses the source context: under Companies Act 2014 sections 39–40, authority of the board as a body does not establish individual authority for every director. A director with a recorded individual grant is returned as a legal representative; an office-only director is a key person. Source signing restrictions are retained when present; absent powers do not imply sole or joint representation.
Both individuals and companies can hold roles. Electronic Filing Agents are typically companies (e.g., accountancy firms), while directors and secretaries are typically individuals.
**Registered business names (`-B` ids)** have no directors or secretary. Their registered owner(s), individual or company, are read from the CRO Business Name Profile and returned under `legalRepresentatives` with the standardized role `Owner`. `otherKeyPersons` is empty for business names.
### Other Key Persons
| Role | English Translation | Notes |
| - | - | - |
| Company Secretary | Secretary | Statutory officer required by Irish law |
| Electronic Filing Agent | Electronic Filing Agent | Authorized agent for electronic CRO submissions |
| Persons authorised to accept service of process | Agent for Service of Process | Service function, not general signing authority |
| Persons responsible for ensuring compliance details | Person Responsible for Compliance | Compliance function, not general signing authority |
### Shareholders
Shareholders are **AI-extracted** from the most recent **annual return** filed with the CRO. The **Form B1C** (Annual Return with Accounts) is preferred, then a plain **Form B1**, then a **Form B1C3**. This is conceptually similar to the German approach of extracting shareholders from filed documents rather than structured registry data.
**Extraction process:**
1. Fetch available documents and keep the annual returns that cover a recent period (within 2 years of the current year)
2. Pick the newest B1C; if there is none, the newest B1; if there is none, the newest B1C3
3. Retrieve and download the annual return from CRO Core
4. Extract the text from the filing
5. Parse shareholders using AI
**Data extracted per shareholder:**
| Field | Description | Example |
| - | - | - |
| `type` | Individual or company | `"company"` |
| `sharePercentage` | Ownership percentage, computed from the share counts (share held ÷ total issued shares) | `99` |
| `numberOfShares` | Number of shares held | `2` |
| `nominalCapitalHeld` | Capital value with currency | `{ "amount": 2.54, "currency": "EUR" }` |
| `company.legalName` or `individual.name` | Shareholder name | `"Analysys Mason Limited"` |
| `company.legalAddress` or `individual.residenceAddress` | Parsed from B1C | Structured address object |
| `company.countryCode` or address `countryCode` | Derived from address | `"GB"` |
Shareholder names, share counts, and addresses are read from the B1C members and share tables; `sharePercentage` and `nominalCapitalHeld` are then computed from the printed share counts and issued share capital (not free-form estimates), so the same filing always yields the same figures.
**Example response** — the `shareholders` array for LinkedIn Technology Unlimited Company (CRO 477442), whose B1C lists two members:
```json theme={null}
[
{
"entityId": "company_001",
"type": "company",
"company": {
"legalName": "LinkedIn International",
"countryCode": "IM",
"legalAddress": {
"addressLine1": "34 North Quay",
"city": "Douglas",
"postalCode": "IM2 4EY",
"countryCode": "IM"
}
},
"sharePercentage": 1,
"numberOfShares": 1,
"nominalCapitalHeld": { "amount": 1, "currency": "EUR" },
"source": "Extracted from B1C Annual Return (Form B1C - Annual Return General)"
},
{
"entityId": "company_002",
"type": "company",
"company": {
"legalName": "Microsoft Ireland Research Unlimited Company",
"countryCode": "IE",
"legalAddress": {
"addressLine1": "70 Sir John Rogerson's Quay",
"city": "Dublin",
"countryCode": "IE"
}
},
"sharePercentage": 99,
"numberOfShares": 99,
"nominalCapitalHeld": { "amount": 99, "currency": "EUR" },
"source": "Extracted from B1C Annual Return (Form B1C - Annual Return General)"
}
]
```
**Limitations:**
| Limitation | Details |
| - | - |
| Single document source | Only the most recent eligible annual return is used; historical ownership changes are not tracked |
| Annual return age limit | Must cover at most current year minus 2 (e.g., 2024+ in 2026). When no B1C, B1, or B1C3 is recent enough, shareholders are empty |
| Active companies only | Only companies with Active, Under Insolvency Proceeding, or Unknown status |
| Business names | Not applicable: requesting `shareholders` for a `-B` id returns `datapoint_not_applicable` |
| AI extraction quality | Best-effort reconstruction from document text; complex multi-column layouts may affect accuracy |
| Document retrieval | The annual return is retrieved automatically; you do not need to order it first |
### Activity Code Mapping
CRO Open Data supplies a declared **NACE Rev. 2** class where one is recorded. It is returned under `company.activities.NACE_REV2`, with its official English description in `company.activityDescription`. The original classification is preserved; the code is also converted to NACE Rev. 2.1 under `NACE` and to ISIC Rev. 5 under `ISIC` using official correspondence tables. These codes carry `isAIInferred: false`.
When a Rev. 2 class splits into several Rev. 2.1 classes, the response uses the common parent supported by the declared code. It does not report every possible successor as a separate registered activity.
```json theme={null}
{
"activityDescription": "Computer programming activities",
"activities": {
"NACE_REV2": [{ "code": "62.01", "description": "Computer programming activities", "isMainActivity": true, "isAIInferred": false }],
"NACE": [{ "code": "62.10", "isMainActivity": true, "isAIInferred": false }],
"ISIC": [{ "code": "621", "isMainActivity": true, "isAIInferred": false }]
}
}
```
The declared classification comes from a periodically refreshed dataset in both prefill and verification modes. It may be absent or older than the live company profile. Registered business names (`-B` ids) are excluded from this dataset and do not inherit the activity of a company with the same number.
## Data Availability
### Data Availability Matrix
| Data Type | Availability | Processing | Notes |
| - | - | - | - |
| Company Profile | Yes | Sync | Name, status, legal form, address, registration date from CRO Public API |
| Legal Representatives | Yes | Async | AI-extracted from Company Printout (trade register extract); owners of business names from the Business Name Profile |
| Other Key Persons | Yes | Async | Secretaries and filing agents from Company Printout |
| Shareholders | Yes | Async | AI-extracted from the latest annual return (B1C, B1, or B1C3). Not applicable to business names |
| Establishments | No | - | CRO does not provide branch/establishment data |
| Activity Codes | When recorded | Sync | Declared NACE Rev. 2 from CRO Open Data, with formal NACE Rev. 2.1 and ISIC Rev. 5 conversions |
| Documents | Yes | Async | Extensive historical filings from CRO Core |
**Legend:** Sync = synchronous (seconds) | Async = asynchronous processing (1-2 minutes)
### Documents by Company Type
Documents are sourced from **CRO Core** and organized into three categories: documents (filings), certificates, and reports.
| Document Type | API Category | Format | Description |
| - | - | - | - |
| **Company Printout** | `tradeRegisterExtract` | PDF | Current company details from registry (no financial accounts) |
| **Business Name Profile** | `tradeRegisterExtract` | PDF | Registration details of a business name (`-B` id), including the registered owner(s) |
| **Financial Statements** | `financialStatements[]` | PDF | Annual accounts, auditor reports, account details |
| **Company Constitution** | `articlesOfAssociation[]` | PDF | Constitutional documents defining governance rules |
| **B1C Annual Return** | `otherDocuments[]` | PDF | Annual return with accounts (preferred shareholder data source) |
| **B1 Annual Return** | `otherDocuments[]` | PDF | Annual return without accounts (shareholder data source when no recent B1C exists) |
| **B10 Director/Secretary Changes** | `otherDocuments[]` | PDF | Director or secretary appointment/resignation filings |
| **Charge Documents (C1, C2, C6, C17)** | `otherDocuments[]` | PDF | Mortgage/charge creation, satisfaction, and updates |
| **Share Capital (B5, B7)** | `otherDocuments[]` | PDF | Share allotments and capital structure changes |
| **Resolutions (G1, G2)** | `otherDocuments[]` | PDF | Special and ordinary shareholder resolutions |
| **A1 Incorporation** | `otherDocuments[]` | PDF | Original application to register as a new company |
| **Letter of Status** | `otherDocuments[]` | PDF | Official letter confirming company current status. Delivered about one business day after the order |
| **Certificates** | `otherDocuments[]` | PDF | Charge certificates, name change certificates, etc. |
**Document pricing varies by document type.** See the [pricing page](https://topograph.co/pricing/ie) for current prices. Requesting `legalRepresentatives` or `otherKeyPersons` includes the Company Printout (or the Business Name Profile for a business name) at no extra charge, and requesting `shareholders` includes the B1C annual return when that is the filing the shareholders were read from.
**B1C priority sorting.** When listing available documents, B1C (Annual Return with Accounts) forms are prioritized at the top of the document list, followed by other documents sorted by date descending. This ensures the most useful documents for due diligence appear first.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "IE", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "654321",
"countryCode": "IE",
"identifiers": {
"companyNumber": "654321"
},
"legalName": "EXAMPLE SOLUTIONS LIMITED",
"registrationDate": "2019-04-10",
"status": {
"localName": "Normal",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "LTD - Private Company Limited by Shares",
"englishTranslation": "Private Company Limited by Shares",
"standardized": "Limited Liability Company",
"iso20275Code": "MNQ7"
},
"legalAddress": {
"addressLine1": "15 Fitzwilliam Square",
"city": "Dublin",
"postalCode": "D02 XY12",
"countryCode": "IE"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Director",
"standardized": "Board Member",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "John Murphy",
"firstName": "John",
"lastName": "Murphy"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Director",
"standardized": "Board Member",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "Mary O'Brien",
"firstName": "Mary",
"lastName": "O'Brien"
}
}
},
{
"entityId": "person_003",
"type": "individual",
"role": {
"localName": "Secretary",
"standardized": "Secretary"
},
"individual": {
"name": {
"fullName": "Patrick Kelly",
"firstName": "Patrick",
"lastName": "Kelly"
}
}
},
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Electronic Filing Agent",
"standardized": "Other"
},
"company": {
"legalName": "Dublin Accountancy Services Ltd"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "112233",
"countryCode": "IE",
"identifiers": {
"companyNumber": "112233"
},
"legalName": "EMERALD HOLDINGS PUBLIC LIMITED COMPANY",
"registrationDate": "1985-03-20",
"status": {
"localName": "Normal",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "PLC - Public Limited Company",
"englishTranslation": "Public Limited Company",
"standardized": "Corporation",
"iso20275Code": "VYAX"
},
"legalAddress": {
"addressLine1": "42 Fitzwilliam Square",
"city": "Dublin 2",
"postalCode": "D02 R279",
"countryCode": "IE"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Director",
"standardized": "Board Member",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "Sean Fitzgerald",
"firstName": "Sean",
"lastName": "Fitzgerald"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Director",
"standardized": "Board Member",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "Aoife Byrne",
"firstName": "Aoife",
"lastName": "Byrne"
}
}
},
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Secretary",
"standardized": "Secretary"
},
"company": {
"legalName": "Corporate Services Ireland Ltd"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "445566",
"countryCode": "IE",
"identifiers": {
"companyNumber": "445566"
},
"legalName": "OLD TRADING COMPANY LIMITED",
"registrationDate": "2005-01-15",
"status": {
"localName": "Struck Off",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "ADMINISTRATIVE_DISSOLUTION",
"closureDate": "2020-09-15T00:00:00Z"
}
},
"legalForm": {
"localName": "LTD - Private Company Limited by Shares",
"englishTranslation": "Private Company Limited by Shares",
"standardized": "Limited Liability Company",
"iso20275Code": "MNQ7"
},
"legalAddress": {
"addressLine1": "10 Patrick Street",
"city": "Cork",
"countryCode": "IE"
}
},
"legalRepresentatives": []
}
```
**Note:** Closed companies may have no active legal representatives extracted. The `closureDate` is populated from the CRO status date when the company's status is CLOSED.
```json theme={null}
{
"company": {
"id": "778899",
"countryCode": "IE",
"identifiers": {
"companyNumber": "778899"
},
"legalName": "INSOLVENT MANUFACTURING LIMITED",
"registrationDate": "1995-08-10",
"status": {
"localName": "Liquidation(Receivership)",
"active": false,
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"closureReason": "LIQUIDATION"
}
},
"legalForm": {
"localName": "CLG - Company Limited by Guarantee",
"englishTranslation": "Company Limited by Guarantee",
"standardized": "Limited Liability Company",
"iso20275Code": "C58S"
},
"legalAddress": {
"addressLine1": "13 City Quay",
"city": "Dublin 2",
"postalCode": "D02 ED70",
"countryCode": "IE"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Director",
"standardized": "Board Member",
"englishTranslation": "Director"
},
"individual": {
"name": {
"fullName": "Ciaran Walsh"
}
}
}
]
}
```
Query with `"dataPoints": ["shareholders"]`:
```json theme={null}
{
"shareholders": [
{
"entityId": "company_001",
"type": "company",
"sharePercentage": 100,
"numberOfShares": 2,
"nominalCapitalHeld": { "amount": 2.54, "currency": "EUR" },
"company": {
"legalName": "Parent Holdings Limited",
"countryCode": "GB",
"legalAddress": {
"addressLine1": "North West Wing, Bush House, Aldwych",
"city": "London",
"postalCode": "WC2B 4PJ",
"countryCode": "GB"
}
}
}
]
}
```
**Note:** Shareholders include a `source` field indicating which B1C document they were extracted from. Both individual and company shareholders are supported. The `countryCode` is derived from the shareholder's address, not the filing country.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "f61acfca-9b34-52a7-b4f2-41c652f91394",
"name": "Company Printout",
"description": "Current company details from registry - does not include financial accounts",
"format": "pdf"
},
"financialStatements": [
{
"id": "8d376fa9-4adb-57a5-94d7-b7a1131778ac",
"name": "FINANCIAL STATEMENT (SR371822)",
"description": "Company financial statements and accounts - Filed on 2025-04-14, effective 2020-03-31",
"format": "pdf",
"date": "2025-04-14"
}
],
"articlesOfAssociation": [
{
"id": "7b570df7-b0f5-5655-9593-65b2a2a4309b",
"name": "AMENDED CONSTITUTION (3528381)",
"description": "Company constitutional document defining governance rules - Filed on 2004-02-06",
"format": "pdf",
"date": "2004-02-05"
}
],
"otherDocuments": [
{
"id": "d3af92b7-1e22-5dad-84ec-1e9f3c5926ab",
"name": "Form B1C - Annual Return General (SR371822)",
"description": "Yearly company filing including financial accounts - Filed on 2025-04-14, effective 2020-03-31",
"format": "pdf",
"date": "2025-04-14"
},
{
"id": "c9ed0cc7-aa0a-5831-b50b-b5797e2af8d7",
"name": "Letter of status - Companies",
"description": "Official letter confirming company current status",
"format": "pdf"
}
]
}
}
```
**Note:** Document names include the CRO submission reference in parentheses (e.g., `SR371822`). Descriptions include filing and effective dates when available. Each document also carries a `price` in credits; see the [pricing page](https://topograph.co/pricing/ie) for current document prices.
```json theme={null}
{
"company": {
"id": "12965",
"countryCode": "IE",
"identifiers": { "companyNumber": "12965" },
"legalName": "CRH PUBLIC LIMITED COMPANY",
"registrationDate": "1949-06-19",
"status": { "localName": "Normal ", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "PLC - Public Limited Company", "englishTranslation": "Public Limited Company", "standardized": "Corporation", "iso20275Code": "VYAX" },
"legalAddress": { "addressLine1": "42 FITZWILLIAM SQUARE", "postalCode": "D02R279", "countryCode": "IE" }
}
}
```
**Note:** Prefill profiles are served from the fast search source (business names are read live from the CRO). For known CRO type codes, the legal form carries the same `englishTranslation`, `standardized`, and `iso20275Code` as in verification mode. No shareholders. Declared activity codes are included where recorded in CRO Open Data.
# Isle of Man
Source: https://docs.topograph.co/essentials/isle-of-man
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Isle of Man reference is on the [Isle of Man country page](https://www.topograph.co/countries/im).
## Start here
This guide contains public integration notes for the Isle of Man. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
The Isle of Man uses a single official register for every entity type. All data comes live from the **Isle of Man Companies Registry**, and there is no cross-register merging.
### Companies, foundations, business names and foreign companies
* **Isle of Man Companies Registry**: maintained by the Isle of Man Government. It holds the register of companies incorporated under the Companies Act 1931 and the Companies Act 2006, limited liability companies, foundations, registered business names, and foreign companies. It is the **sole source** for the company profile (name, registration number, legal form, status, incorporation date, registered office address), for search, and for documents.
**Same answer in both modes.** Prefill (`mode: "prefill"`) and verification (`mode: "verification"`) requests read the same live register page and return the same `company` data.
## Company Identifiers
### Query Identifiers
Isle of Man entities are identified by their **company number**: exactly 6 digits, zero-padded, followed by one uppercase letter, with no space. The letter tells you which register the entity belongs to.
| Suffix | Registry Type | Format | Example |
| - | - | - | - |
| `C` | 1931 Act Company | 6 digits + `C` | `099176C` |
| `V` | 2006 Act Company | 6 digits + `V` | `002092V` |
| `B` | Business Name | 6 digits + `B` | `025021B` |
| `F` | Foreign Company | 6 digits + `F` | `003444F` |
| `L` | Limited Liability Company | 6 digits + `L` | `000594L` |
| `M` | Foundation | 6 digits + `M` | `000361M` |
| Other letters | The Registry's other registers (industrial societies, limited partnerships, credit unions) | 6 digits + letter | `000006I` |
**Send the full company number, leading zeros and suffix included** (for example `002092V`, not `2092` or `2092V`). The suffix is part of the official identifier, and the register looks the entity up by the full number.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `registrationNumber` | 6 digits + letter suffix | `099176C` | All entity types |
The register publishes the company number and does not publish VAT numbers or other secondary identifiers. An optional LEI may be returned from GLEIF as described below.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the full company number (including its suffix) matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Company Number | 6 digits + suffix letter (`C`, `V`, `B`, `F`, `L`, `M`) | `099176C` | Exact (`matchType: id`) | The matching entity, or none |
| By Name | 2 to 100 characters | `"Example Holdings"` | Name match | Multiple results across all registry types |
**Search uses live register lookups.** Both name and number searches query the Isle of Man Companies Registry in real time. Results carry the company number (`id`), the current legal name and the country code.
Name search matches **current names only**. A company that is known only by a former name does not appear when you search for that former name. Search by company number when you already have it.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Suffix identifies the register** | The trailing letter of the company number (`C`, `V`, `B`, `F`, `L`, `M`) is part of the identifier and tells you whether the entity is a 1931 Act company, a 2006 Act company, a business name, a foreign company, an LLC or a foundation. |
| **No officers, shareholders or beneficial owners** | The public company summary does not list directors, secretaries, shareholders or beneficial owners. Only the `company` datapoint is offered. Officer details appear in filings such as annual returns and changes in directors, which you can order as documents. |
| **Fields vary by registry type** | 1931 Act and 2006 Act companies carry the most data. Business names, foundations, foreign companies and LLCs have no company type, so their legal form is the registry type. Foundations, business names and foreign companies usually have no registered office address. |
| **Incorporation date can be missing** | The register leaves the date empty for foundations and for some very old or LLC entries. `incorporationDate` is omitted in that case. |
| **Address returned as one line** | The registered office address is returned as a single `addressLine1` string, as the register publishes it. It is not split into city or postal code. |
| **Status is the register's own wording** | `status.localName` is the register's status verbatim. `active` is `true` only for `Live`. No standardized status is returned. |
| **No activity codes** | The register does not publish an activity classification, so no SIC, NACE or ISIC codes are returned. |
| **Registry filings are ordered on request** | The Trade Register Extract is generated from the live register page. Registry filings are ordered from the register when you request them, so they take longer to deliver. |
| **One entry per filing type** | The document list returns one entry for each filing type and description, not every historical copy of that filing. |
## Mappings
### Company Status
Status comes from the register's summary page and is returned verbatim in `status.localName`. The `active` flag is derived deterministically. No AI is involved and no `statusDetails` object is returned.
| Local Status | English Translation | `active` | Notes |
| - | - | - | - |
| Live | Live | `true` | Entity is on the register and current |
| Dissolved | Dissolved | `false` | Used across all registry types |
| Struck Off | Struck Off | `false` | Seen on foreign companies |
| Ceased | Ceased | `false` | Seen on business names |
Any other status the register publishes is passed through as-is with `active: false`.
### Legal Forms
The legal form is returned verbatim in `legalForm.localName`. For 1931 Act and 2006 Act companies it is the register's **company type**. For every other registry type, where the register publishes no company type, it is the **registry type**. No standardized legal form or ISO 20275 code is returned.
#### Company types (1931 Act and 2006 Act companies)
| Local Name | English Translation | Registry Type |
| - | - | - |
| Private Ltd by Shares | Private company limited by shares | 1931 Act Company |
| Public Ltd by Shares | Public company limited by shares | 1931 Act Company |
| Limited by shares | Company limited by shares | 2006 Act Company |
#### Registry types (entities without a company type)
| Local Name | English Translation | Company Number Suffix |
| - | - | - |
| Business Name | Registered business name | `B` |
| Foreign Company | Foreign company registered in the Isle of Man | `F` |
| Limited Liability Company | Limited liability company | `L` |
| Foundation | Foundation | `M` |
The company types above are the values observed on the register. A company type not listed here is still returned verbatim in `legalForm.localName`.
## Data Availability
### Data Availability Matrix
| Data Type | Availability | Notes |
| - | - | - |
| Company Profile (`company`) | ✅ | Legal name, company number, legal form, status, incorporation date, registered office address |
| Legal Representatives | ❌ | Directors are not published in the public company summary |
| Other Key Persons | ❌ | Secretaries and registered agents are not returned |
| Shareholders | ❌ | Not published by the register |
| Ultimate Beneficial Owners | ❌ | Not publicly available |
| Activity Codes | ❌ | Not published by the register |
| Establishments | ❌ | Not applicable |
| Documents | ✅ | Trade Register Extract and registry filings |
**Legend:** ✅ Available | ❌ Not Available
### Documents by Company Type
| Entity Type | Trade Register Extract | Registry Filings |
| - | - | - |
| 1931 Act Company (`C`) | ✅ Company Summary | ✅ When the register holds filed documents |
| 2006 Act Company (`V`) | ✅ Company Summary | ✅ When the register holds filed documents |
| Business Name (`B`) | ✅ Company Summary | ✅ When the register holds filed documents |
| Foreign Company (`F`) | ✅ Company Summary | ✅ When the register holds filed documents |
| Limited Liability Company (`L`) | ✅ Company Summary | ✅ When the register holds filed documents |
| Foundation (`M`) | ✅ Company Summary | ✅ When the register holds filed documents |
* **Trade Register Extract** (`tradeRegisterExtract`): a PDF of the entity's Company Summary page on the Isle of Man Companies Registry, stamped with the time it was generated. Available for every entity.
* **Registry filings** (`otherDocuments`): documents filed with the register, such as annual returns, changes in directors or secretaries, registers of directors, and particulars of charges. Filings identified as a memorandum or articles of association are listed under `articlesOfAssociation` instead. The list depends on what the entity has filed, and some entities have none.
All documents are **PDF** format in **English**.
## Example API Responses
All examples use **placeholder data**.
### Search by Company Number
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=IM&query=012345C" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "012345C",
"legalName": "EXAMPLE HOLDINGS LIMITED",
"countryCode": "IM",
"matchReason": { "matchType": "id", "identifier": { "registrationNumber": "012345C" } }
}
]
```
### Company Profile
Query: `POST /v2/company` with `{ "id": "", "countryCode": "IM", "dataPoints": ["company"] }`
```json theme={null}
{
"company": {
"id": "012345C",
"countryCode": "IM",
"identifiers": { "registrationNumber": "012345C" },
"legalName": "EXAMPLE HOLDINGS LIMITED",
"incorporationDate": "2000-03-15",
"status": { "localName": "Live", "active": true },
"legalForm": { "localName": "Private Ltd by Shares" },
"legalAddress": { "addressLine1": "1st Floor, Example House, Example Street, Douglas, Isle of Man, IM1 1AA", "countryCode": "IM" }
}
}
```
```json theme={null}
{
"company": {
"id": "001234V",
"countryCode": "IM",
"identifiers": { "registrationNumber": "001234V" },
"legalName": "EXAMPLE SERVICES LTD",
"incorporationDate": "2012-06-04",
"status": { "localName": "Dissolved", "active": false },
"legalForm": { "localName": "Limited by shares" },
"legalAddress": { "addressLine1": "2 Example Road, Ramsey, Isle of Man, IM8 1AA", "countryCode": "IM" }
}
}
```
```json theme={null}
{
"company": {
"id": "000345M",
"countryCode": "IM",
"identifiers": { "registrationNumber": "000345M" },
"legalName": "Example Family Foundation",
"status": { "localName": "Live", "active": true },
"legalForm": { "localName": "Foundation" }
}
}
```
**Note:** Foundations have no company type, so the legal form is the registry type. The register publishes no registered office address or incorporation date for them.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Company Summary | Available for every entity |
| `otherDocuments[]` | Registry filings (for example Annual Return, Register Of Directors) | Depends on what the entity has filed |
| `articlesOfAssociation[]` | Memorandum or articles of association filings | Only when the entity has filed one |
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "3f2b8c1e-5d4a-5b6f-9e7d-1a2b3c4d5e6f",
"name": "Company Summary",
"format": "pdf",
"description": "Trade register extract from the Isle of Man Companies Registry"
},
"otherDocuments": [
{
"id": "8a7b6c5d-4e3f-5a2b-8c1d-0e9f8a7b6c5d",
"name": "Annual Return",
"format": "pdf"
},
{
"id": "c1d2e3f4-a5b6-5c7d-8e9f-0a1b2c3d4e5f",
"name": "Register Of Directors",
"format": "pdf"
}
]
}
}
```
# Italy
Source: https://docs.topograph.co/essentials/italy
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Italy reference is on the [Italy country page](https://www.topograph.co/countries/it).
## Start here
This guide contains public integration notes for Italy. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Italy uses two data sources that both access the **Registro Imprese** (Italian Business Register), the official economic registry managed by the Italian Chambers of Commerce. For a given entity, **data comes from a single primary source** -- the system does not merge attributes across sources. It follows a deterministic priority chain and returns data from the first source that provides complete information.
### Commercial companies
* **Registro Imprese** -- The official economic register managed by the Italian Chambers of Commerce. This is the primary source for comprehensive company data: company name, legal form, status, identifiers, registered address, share capital, ATECO activity codes, legal representatives, other key persons, shareholders, subsidiaries, establishments, and financial statements when available.
* **Fast profile source** -- Used for search operations and prefill profiles when a faster response is required. See [Verification vs prefill mode](/essentials/modes) for how to decide whether the fast response is sufficient for your use case.
### Sole entrepreneurs
* **Sole proprietor records** -- For sole proprietorships (*Impresa Individuale*), query using the owner's personal Codice Fiscale. The response contains business name, address, ATECO codes, and owner information when available.
Verification and prefill may use different source paths. Use the `authoritative` flag in `dataStatus` to decide whether to trigger a verification follow-up after prefill.
### Data Source Priority & Routing
For a given company query, data comes from **one source only** (all-or-nothing model):
1. Official register data is used for verification-mode company, legal representative, other key person, shareholder, establishment, and subsidiary datapoints.
2. Fast-source data is used for prefill where available.
3. Sole proprietors must be queried with their personal Codice Fiscale.
Use [Italy coverage, pricing, and sources](https://topograph.co/pricing/it) for the live mode and data block catalog.
## Company Identifiers
### Query Identifiers
| Identifier | Format | Example | Notes |
| - | - | - | - |
| **Codice Fiscale (company)** | 11 digits, last is a control digit | `00484960588` | Universal fiscal identifier; for companies, typically identical to Partita IVA |
| **Partita IVA (VAT number)** | 11 digits, last is a control digit | `00905811006` | Required for commercial activities; usually identical to Codice Fiscale for companies, but not always (ENI: Codice Fiscale `00484960588`, Partita IVA `00905811006`) |
| **Codice Fiscale (individual)** | 16 alphanumeric, uppercase, ends in a check letter | `BRNLSN75H27B564E` | Personal tax code for sole proprietors; encodes name, birth date, and place |
| **CCIAA + REA Code** | 2 letters + 1-7 digits | `TO1239673` | Provincial register identifier (CCIAA = Chamber province, REA = register number). Accepted by `/v2/search` only |
**Primary Identifier**: The system uses **Codice Fiscale** as the company ID for all Italian entities. For companies (SRL, SPA, etc.), the 11-digit Codice Fiscale is typically identical to their Partita IVA. For sole proprietors, the 16-character personal Codice Fiscale must be used -- they cannot be queried by their 11-digit VAT number.
**`/v2/company` accepts the Codice Fiscale only.** The `id` must be either an
11-digit Codice Fiscale with a valid control digit (`00484960588`, optionally
written `IT00484960588`), or a 16-character personal Codice Fiscale for a sole
proprietor. Whitespace, dots and hyphens around an 11-digit number are accepted
and stripped, and the value is stored and echoed back in its bare, uppercase
form.
Anything else is rejected immediately with `400 invalid_request`, before any
register lookup, and is not billed. That includes a REA or CCIAA + REA code
(`RM-1734032`), a sole proprietor's Partita IVA, and an 11-digit number whose
control digit does not check out. Pass these to
[`/v2/search`](/essentials/search) instead: it resolves them to the Codice
Fiscale to use here.
### Identifiers in API Response
| Identifier | Key | Always Present | Example |
| - | - | - | - |
| **Partita IVA** | `VAT` | When available | `00905811006` |
| **Codice Fiscale** | `codiceFiscale` | Yes | `00484960588` or `BRNLSN75H27B564E` |
| **CCIAA** | `cciaa` | When available | `RM` |
| **REA Code** | `rea` | When available | `756453` |
| **European Unique Identifier** | `euid` | Supported domestic limited companies | `ITRI.00484960588` |
The EUID is derived from the company's Registro Imprese number (Codice Fiscale), preserving leading zeros. It is included for supported domestic limited-company forms, including SRL, SpA and SRLS. It is omitted for sole traders, partnerships, cooperatives, foreign-law entities and unknown legal forms. EUID search is not supported.
The same keys are used for the identifiers of legal representatives, shareholders and subsidiaries. The capitalised spellings `Codice Fiscale`, `CCIAA` and `REA Code` were retired on 2026-09-01.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Codice Fiscale (`codiceFiscale`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## VAT (Partita IVA) Validation
For verification-mode company lookups, the response includes a `taxId` block: the Partita IVA plus a `verification` object that records how the number was checked and by which authority.
The Partita IVA is taken from the official register (for sole proprietors, whose Partita IVA differs from their Codice Fiscale, it is resolved automatically), then validated in two steps:
1. **VIES (EU).** The number is checked against the EU VAT Information Exchange System. If it is registered for intra-EU trade, VIES returns a consultation number that is legal proof of the check, and `verification.source` is `vies`.
2. **Agenzia delle Entrate (domestic).** Most Italian VAT numbers are not enabled for intra-EU trade, so VIES reports them as not valid even when they are perfectly active in Italy. When VIES does not confirm a number, it is checked against the Italian Revenue Agency (Agenzia delle Entrate), the authoritative source for domestic VAT status. A number confirmed there has `verification.source` set to `agenzia_entrate`.
If neither source confirms the number, `verification.status` is `unverified`. A company being active in the business register is never treated as a substitute for validating its VAT number.
| Field | Description |
| - | - |
| `taxId.value` | The 11-digit Partita IVA (without the `IT` prefix) |
| `taxId.verification.status` | `verified` or `unverified` |
| `taxId.verification.source` | `vies` or `agenzia_entrate`: which authority confirmed the number |
| `taxId.verification.consultationNumber` | VIES legal-proof reference, present only when `source` is `vies` |
| `taxId.verification.verifiedName` | Name held by the validating authority for that number |
A `vies` result is the strongest proof for intra-EU transactions because it carries a consultation number. An `agenzia_entrate` result confirms the number is active for domestic purposes but has no intra-EU consultation number.
## Search Capabilities
Search automatically detects the identifier type and routes to the appropriate endpoint:
| Search Pattern | Format | Examples | Match Type | Results |
| - | - | - | - | - |
| **Company Name** | Text string | `Barilla`, `Zona Web` | Fuzzy match | Up to 10 results |
| **CCIAA + REA** | 2 letters + 1-7 digits | `TO1239673`, `TO 1239673` | Exact match by province | Exact match returned first (matchType: id); other results may follow |
| **REA Only** | 1-7 digits (not 11) | `1239673`, `12345` | Cross-province + name search | Multiple results |
| **Partita IVA** | 11 digits | `00905811006`, `IT00905811006` | Exact ID match | Exact match returned first (matchType: id); other results may follow |
| **Codice Fiscale (company)** | 11 digits | `03943150270` | Exact ID match | Exact match returned first (matchType: id); other results may follow |
| **Codice Fiscale (individual)** | 16 alphanumeric | `BRNLSN75H27B564E` | Exact ID match | Exact match returned first (matchType: id); other results may follow |
REA numbers are unique within a province but can exist in multiple provinces. Searching by REA only (without CCIAA) performs **both** a cross-province REA search and a company name search simultaneously, then combines and deduplicates the results.
Search is powered by a fast third-party profile source. Name searches use fuzzy matching with up to 10 results. ID searches (Codice Fiscale, Partita IVA) return exact matches. The `IT` prefix on identifiers is automatically stripped.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile. Search results do not carry the company status, so ceased companies can appear; check the status on the company profile.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Codice Fiscale = Partita IVA for companies** | For companies (SRL, SPA, etc.), the 11-digit Codice Fiscale is usually identical to the Partita IVA. For sole proprietors, they are always different. |
| **Sole proprietors need personal Codice Fiscale** | Sole proprietorships (*Impresa Individuale*) must be queried using their 16-character personal Codice Fiscale, not their 11-digit Partita IVA. Querying with Partita IVA returns a not-found error with a hint to use the correct identifier. |
| **IT prefix is optional** | The `IT` prefix on Partita IVA / Codice Fiscale is automatically stripped. Both `IT00484960588` and `00484960588` work, and both are stored under the same bare id. The prefix is only removed when what remains is an 11-digit number, so a personal Codice Fiscale that happens to start `IT` is left intact. |
| **A REA code is not a company id** | `/v2/company` rejects a REA or CCIAA + REA code with `400 invalid_request` rather than searching for it. Resolve it through `/v2/search` first. |
| **REA is province-scoped** | REA numbers are unique within a province but can exist in multiple provinces. Always pair with CCIAA code for exact identification. |
| **Legal rep roles are AI-enriched** | The local Italian role name is always preserved verbatim. The standardized role mapping and English translation use AI enrichment. |
| **NACE comes from the register in verification mode** | In verification mode the register publishes the NACE code next to the ATECO code, and ISIC is mapped from it through the official correspondence (`isAIInferred: false`). AI inference is used only when no NACE code is available, as on the prefill path. Check the `isAIInferred` flag. |
| **ATECO code lengths vary** | ATECO codes range from 2 to 6 digits depending on the granularity of the registered activity. There is no universal logic for code length. |
| **Share capital ships with the shareholder list** | In verification mode `company.capital` is returned only when the shareholder filing has been retrieved for the same company. See [Share capital in verification mode](#share-capital-in-verification-mode). |
| **Shareholder birth data cross-reference** | The register's shareholder filing does not include birth date/place for shareholders. The system cross-references by fiscal code with legal representative data to enrich shareholders with birth information where available. |
| **Shareholder filing may be missing or too large** | When the register has no shareholder filing for the company (for example, some cooperatives), `shareholders` is an empty list. When the filing is too large to be issued online, the datapoint fails with a no-document response. Both outcomes are refunded. |
| **Document delivery is asynchronous** | Visura and bilancio documents are ordered from the register and delivered asynchronously. Estimated delivery time is 5 minutes (300 seconds). |
| **Bilancio documents are historical** | Financial statement documents never change once filed. They are deduplicated permanently since they never change. |
## Mappings
### Company Status
Company status is determined **deterministically** from Italian registry status codes. No AI inference is involved.
| Code | Local Status | English Translation | Standardized Status |
| - | - | - | - |
| `A` | Attiva | Active | `ACTIVE` |
| `C` | Cessata | Ceased | `CLOSED` |
| `CF` | Out of business | Out of Business | `CLOSED` |
| `CS` | Out of business | Out of Business | `CLOSED` |
| `I` | Inactive | Inactive | `UNKNOWN` |
| `IF` | In closure | In Closure | `UNDER_INSOLVENCY_PROCEEDING` |
| `IS` | In closure | In Closure | `UNDER_INSOLVENCY_PROCEEDING` |
| `S` | Dormant | Dormant | `UNKNOWN` |
The prefill path reports only active (`A`) or ceased (`C`). Unknown codes default to `UNKNOWN` status.
### Legal Forms
Italy has 70+ official legal form classifications managed by the Chambers of Commerce. Legal form mapping uses a deterministic code-to-description lookup for Italian names and a static dictionary for English translations. When no deterministic match is found, **AI enrichment** is used to translate and standardize the legal form, and to assign the ISO 20275 (ELF) code.
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `SR` | Societa' a Responsabilita' Limitata | Limited Liability Company | OV32 |
| `SP` | Societa' per Azioni | Joint Stock Company | P418 |
| `AS` | Societa' in Accomandita Semplice | Limited Partnership | CGSO |
| `SN` | Societa' in Nome Collettivo | General Partnership | T2X1 |
| `AA` | Societa' in Accomandita per Azioni | Limited Partnership by Shares | DLS4 |
| `SE` | Societa' Semplice | Simple Partnership | 2XXH |
| `SA` | Societa' Anonima | Anonymous Company | - |
| `SV` | Societa' tra Professionisti | Professional Partnership | ZZOG |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `SU` | Societa' a Responsabilita' Limitata con Unico Socio | Single-Member Limited Liability Company | B5TO |
| `AU` | Societa' per Azioni con Socio Unico | Single-Member Joint Stock Company | X32V |
| `RS` | Societa' a Responsabilita' Limitata Semplificata | Simplified Limited Liability Company | 8GU1 |
| `RR` | Societa' a Responsabilita' Limitata a Capitale Ridotto | Reduced Capital Limited Liability Company | - |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `DI` | Impresa Individuale | Sole Proprietorship | LHBB |
| `PF` | Persona Fisica | Natural Person | - |
| `IF` | Impresa Familiare | Family Business | - |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `SC` | Societa' Cooperativa | Cooperative Company | QRZJ |
| `OO` | Cooperativa Sociale | Social Cooperative | PHMS |
| `CL` | Societa' Cooperativa a Responsabilita Limitata | Limited Liability Cooperative | CTNS |
| `CI` | Societa' Cooperativa a Responsabilita Illimitata | Unlimited Liability Cooperative | - |
| `PC` | Piccola Societa' Cooperativa | Small Cooperative Company | - |
| `PS` | Piccola Societa' Cooperativa a Responsabilita' Limitata | Small Limited Liability Cooperative | ZU9S |
| `OC` | Societa' Cooperativa Consortile | Consortium Cooperative Company | C1IC |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `CO` | Consorzio | Consortium | HN75 |
| `CC` | Consorzio con Attivita' Esterna | Consortium with External Activity | 2J7Z |
| `CS` | Consorzio senza Attivita' Esterna | Consortium without External Activity | SBQN |
| `CF` | Consorzio Fidi | Credit Guarantee Consortium | DCRK |
| `CR` | Consorzio Intercomunale | Inter-Municipal Consortium | - |
| `CM` | Consorzio Municipale | Municipal Consortium | VDRB |
| `CZ` | Consorzio di cui al DLgs 267/2000 | Consortium under DLgs 267/2000 | X62Z |
| `CN` | Societa' Consortile | Consortium Company | - |
| `SL` | Societa' Consortile a Responsabilita' Limitata | Consortium Limited Liability Company | BL52 |
| `SO` | Societa' Consortile per Azioni | Consortium Joint Stock Company | LZZD |
| `OS` | Societa' Consortile Cooperativa a Responsabilita' Limitata | Consortium Cooperative Limited Liability Company | 8AXV |
| `AN` | Societa' Consortile in Nome Collettivo | Consortium General Partnership | - |
| `AE` | Societa' Consortile in Accomandita Semplice | Consortium Limited Partnership | WRU2 |
| `GE` | Gruppo Europeo di Interesse Economico | European Economic Interest Grouping | 634M |
| `RC` | Contratto di Rete dotato di Soggettivita' Giuridica | Network Contract with Legal Personality | K021 |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `AC` | Associazione | Association | 1TON |
| `AI` | Associazione Impresa | Business Association | WPED |
| `PA` | Associazione in Partecipazione | Joint Venture Association | - |
| `FO` | Fondazione | Foundation | 75WC |
| `FI` | Fondazione Impresa | Business Foundation | 70X0 |
| `SM` | Societa' di Mutuo Soccorso | Mutual Aid Society | VA1V |
| `MA` | Mutua Assicurazione | Mutual Insurance | W9SC |
| `EM` | Ente Morale | Moral Entity | ARJF |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `EP` | Ente Pubblico Economico | Public Economic Entity | ZG6S |
| `ED` | Ente Diritto Pubblico | Public Law Entity | 5ODO |
| `EC` | Ente Pubblico Commerciale | Public Commercial Entity | - |
| `EN` | Ente | Entity | K26L |
| `EI` | Ente Impresa | Business Entity | KCSG |
| `EL` | Ente Sociale | Social Entity | 2SZI |
| `EE` | Ente Ecclesiastico | Ecclesiastical Entity | IMHA |
| `ER` | Ente Ecclesiastico Civilmente Riconosciuto | Civilly Recognized Ecclesiastical Entity | 1RI9 |
| `IR` | Istituto Religioso | Religious Institute | ADAZ |
| `ES` | Ente di cui alla L.R. 21-12-93 N88 | Entity under Regional Law 88/1993 | - |
| `AL` | Azienda Speciale | Special Agency | KXZT |
| `LL` | Azienda Speciale di cui al DLgs 267/2000 | Special Agency under DLgs 267/2000 | KCHO |
| `AZ` | Azienda Speciale REA | Special Agency REA | SSP9 |
| `AM` | Azienda Municipale | Municipal Company | L1ZJ |
| `AP` | Azienda Provinciale | Provincial Company | - |
| `AR` | Azienda Regionale | Regional Company | - |
| `AT` | Azienda Autonoma Statale | Autonomous State Company | DSSD |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `IC` | Istituto di Credito | Credit Institution | - |
| `ID` | Istituto di Credito di Diritto Pubblico | Public Law Credit Institution | - |
| `ST` | Soggetto Estero | Foreign Entity | H7D4 |
| `SS` | Societa' Costituita in Base a Leggi di Altro Stato | Company Incorporated under Foreign Law | 135L |
| `SZ` | Societa' non Prevista dalla Legislazione Italiana | Company Not Provided for under Italian Law | W2PE |
| `SD` | Societa' Europea | European Company (SE) | VUPE |
| `SG` | Societa' Cooperativa Europea | European Cooperative Society (SCE) | 9KGS |
| Code | Italian Name | English Translation | ISO 20275 |
| - | - | - | - |
| `AF` | Altre Forme | Other Forms | RWZD |
| `SF` | Societa' di Fatto | De Facto Partnership | - |
| `SI` | Societa' Irregolare | Irregular Company | - |
| `CE` | Comunione Ereditaria | Hereditary Community | - |
| `XX` | Non Precisata | Unspecified | - |
ISO 20275 (ELF) codes are matched against GLEIF's ELF code list for Italy (for example SRL = OV32, SPA = P418). Forms marked `-` have no dedicated Italian entry in that list.
### Legal Representatives
When the register publishes signing powers for a returned representative's appointment, `signingPowers.localText` preserves the original Italian text. Simple unconditional declarations populate `representationMode.mode` with `sole` or `joint`. For an explicit two-signature declaration, `minimumSignatories` is `2`, including the representative.
Powers that depend on transaction type, amount, named co-signers or other conditions remain in `signingPowers.localText` without a single representation mode. An absent mode means the signing arrangement has not been classified; it does not mean the person has no authority. For those texts, `signingPowers.englishTranslation` carries an English translation and `signingAuthority` a model-derived reading: a `verdict` (`sole`, `sole_within_limits`, `joint` or `unclear`) and one `rules[]` entry per power with its English `scope`, `mode`, optional `amountLimit` and `coSigners`, and the verbatim `sourceExcerpt` it was read from. Treat `signingAuthority` as an analyst's summary to be checked against the excerpts, not as a register statement: `derivedFrom` is always `ai`, `confidence` drops to `low` when an excerpt could not be matched to the text, and `unclear` is returned rather than a guess when the text only refers to another instrument. Missing text means no powers text was retrieved for that appointment. A role title alone does not establish signing authority. These fields enrich the returned representatives and do not guarantee a complete list of all authorized signatories.
Legal representatives are extracted from the Registro Imprese and are available in verification mode only. Known office codes use the published role catalogue for fixed English translations and standardized values; unfamiliar labels may require enrichment. The local Italian role name is preserved verbatim. Both individuals and corporate entities can hold legal representative roles.
| Italian Role | English Translation |
| - | - |
| Amministratore unico | Sole Director |
| Amministratore delegato | Managing Director / CEO |
| Amministratore | Director |
| Presidente del consiglio di amministrazione | Chairman of the Board |
| Consigliere delegato | Executive Board Member |
| Consigliere | Board Member |
| Socio amministratore | Managing Partner |
| Presidente | President / Chairman |
| Vice presidente | Vice President |
| Direttore generale | General Manager |
| Titolare | Owner |
| Italian Role | English Translation |
| - | - |
| Rappresentante legale | Legal Representative |
| Procuratore | Attorney / Proxy |
| Procuratore speciale | Special Attorney |
| Institore | Business Manager (Institor) |
| Liquidatore | Liquidator |
| Italian Role | English Translation |
| - | - |
| Socio accomandatario | General Partner (unlimited liability) |
| Socio accomandante | Limited Partner |
| Socio unico | Sole Shareholder |
The register publishes official office codes, alongside Italian labels that can vary by grammatical gender. Known codes use fixed translations and standardized values. The original label remains in `localName`. Office names identify appointments; the register's representation information and the powers filed for that appointment establish authority.
### Other Key Persons
`otherKeyPersons` is available in verification mode for filed office holders whose appointment has no established representation grant, including non-signing board members and auditors present in the register response. Registered representatives, and appointments with supported signing powers, appear under `legalRepresentatives`. Ownership alone does not create either an officer appointment or signing authority.
A person may hold several distinct appointments, with different roles and powers. An office title does not imply sole or joint signing authority. Prefill returns company data only.
### Shareholders
Shareholders are extracted from the register's shareholder filing in the Registro Imprese, in verification mode only. Both individual and corporate shareholders are supported.
**Extraction Logic:**
| Company type | Result |
| - | - |
| **Companies with a shareholder filing** | Shareholders with ownership percentages, nominal capital held, paid-in amounts, fiscal codes, addresses, country codes |
| **Sole proprietorships** | Not applicable: an explicit not-applicable response, with no charge. The owner is returned under `legalRepresentatives` |
**Ownership Fields:**
| Field | Description |
| - | - |
| `sharePercentage` | Ownership percentage |
| `nominalCapitalHeld` | Nominal capital amount held (EUR) |
| `paidInAmount` | Amount of capital paid in (EUR) |
| `type` | `INDIVIDUAL` or `COMPANY` |
| `individual.identifiers` | Codice Fiscale of shareholder |
| `company.countryCode` | Country code for foreign corporate shareholders |
The register's shareholder filing does not include birth date/place for shareholders. When a shareholder is also a legal representative (common in small Italian companies), the system cross-references by fiscal code and copies birth information from the legal representative record to enrich the shareholder data.
When the register has no shareholder filing for the company (for example, some cooperatives), `shareholders` is an empty list. When the filing is too large to be issued online, the datapoint fails with a no-document response. Both outcomes are refunded.
### Subsidiaries
Subsidiaries are the inverse of shareholders: companies in which the queried company holds equity. For Italy they are extracted from the register's filing of current participations in other companies ("Partecipazioni in altre societa'").
**Fields populated:**
| Field | Description |
| - | - |
| `company.legalName` | Subsidiary's legal name |
| `company.id` | Subsidiary's Codice Fiscale |
| `sharePercentage` | Direct equity stake (0–100) |
| `numberOfShares` | Share or quota count held |
| `nominalCapitalHeld` | Total nominal value held (EUR) |
| `acquisitionDate` | Earliest date the participation was recorded |
Only current participations in companies that have not been cancelled are returned. Historical participations and transfers are not surfaced, and `endDate` is not set. Sole proprietorships return an empty list.
See [Subsidiaries](/essentials/subsidiaries-extraction) for the universal contract.
### Activity Code Mapping
Italy uses the **ATECO** (Attivita Economiche) classification system, maintained by ISTAT (Italian National Institute of Statistics). The ATECO 2025 classification, effective from April 1, 2025, aligns with the EU's NACE Rev. 2.1 system and has 6 levels of classification depth.
**Classification pipeline:**
```
Verification: ATECO_2025 + NACE (register) → ISIC (official NACE-to-ISIC correspondence)
Prefill: ATECO → ISIC and NACE (AI-inferred)
```
**Available classifications in API responses:**
| Classification | Source | AI-Inferred | Notes |
| - | - | - | - |
| **ATECO\_2025** | Registro Imprese | No | Verification mode; the company's prevailing activity |
| **ATECO** | Fast profile source | No | Prefill mode |
| **NACE** | Registro Imprese (verification) or AI-enriched (prefill) | No in verification, Yes in prefill | European standard (NACE Rev. 2.1). In verification mode it is published by the register next to the ATECO code |
| **ISIC** | Mapped from NACE (verification) or AI-enriched (prefill) | Inherits the flag of the NACE code in verification, Yes in prefill | International standard, mapped from NACE through the official correspondence |
**Main activity:** the Registro Imprese declares each company's prevailing activity (attivita prevalente) and publishes a single ATECO code for it. That ATECO code carries `isMainActivity: true`, and the NACE and ISIC codes derived from it inherit the flag.
ATECO code lengths vary from 2 to 6 digits depending on the granularity of the registered activity. There is no universal logic for code length. AI inference is used only when no NACE code is available, which is the case on the prefill path.
## Data Availability
### Data Availability Matrix
| Data Point | Registro Imprese (Verification) | Fast profile source (Verification fallback) | Fast profile source (Prefill) |
| - | - | - | - |
| Company name | Yes | Yes | Yes |
| Legal form | Yes | Yes | Yes |
| Status | Yes | Yes (A/C) | Yes (A/C) |
| Identifiers (VAT, CF, CCIAA, REA) | Yes | Yes | Yes |
| Registered address | Yes | Yes | Yes |
| Share capital | Only alongside `shareholders` ([see below](#share-capital-in-verification-mode)) | No | No |
| Incorporation date | Yes | Yes | Yes |
| Registration date | Yes | Yes | Yes |
| ATECO activity codes | Yes (ATECO\_2025 + NACE) | Yes (ATECO) | Yes (ATECO) |
| Activity description | Yes | Yes | Yes |
| Legal representatives | Yes (with birth data) | No | No |
| Other key persons | Yes, when recorded | No | Yes, when recorded |
| Shareholders | Yes (with nominal/paid-in) | No | No |
| Subsidiaries | Yes (current participations only) | No | No |
| Establishments | Yes (secondary registered seats and active operational branches) | No | No |
| Employee count | No | No | No |
| Phone / website | No | No | No |
| PEC (certified email) | No | No | No |
### Share capital in verification mode
The Italian register does not publish share capital on the company record itself. It
files it with the **shareholder list**, which is a separate, separately priced record.
That has one visible consequence in `mode: "verification"`:
| You request | `company.capital` |
| - | - |
| `company` (and/or `legalRepresentatives`) alone | Omitted |
| `company` **and** `shareholders` together | Returned |
| `company` alone, within 24h of a `shareholders` request for the same company | Returned |
| `mode: "prefill"` | Omitted |
**Why we do not simply fetch it.** Share capital is filed with the shareholder list, which
is a separately priced record, so we do not buy that record just to populate one field.
We do not substitute a
non-authoritative source for it either: in verification mode every field we return
comes from the register itself, and share capital is no exception. When the shareholder
record has been retrieved, capital comes along with it at no extra charge.
**If you always need capital**, request `shareholders` alongside `company`. You get the
ownership breakdown and the capital figure together, for the price of the two blocks.
In `mode: "prefill"` share capital is not returned. Prefill returns only the
`company` datapoint (name, legal form, status, identifiers, registered address, main
ATECO code, incorporation and registration dates).
### Documents by Company Type
| Document | Type | Format | Delivery | Companies | Sole proprietorships | Notes |
| - | - | - | - | - | - | - |
| **Visura Camerale** | Certified Trade Register Extract | PDF | \~5 min | Yes | Yes | Official Italian-language extract from the Registro Imprese. Includes the corporate object (oggetto sociale), board powers (poteri di firma), ATECO classification, per-branch activity matrix, employee distribution, statutory clauses, and the list of historical filings available for the company. |
| **Visura Storica** | Trade Register History | PDF | \~5 min | Yes | Yes | Historical company report listing every amendment to the entity since its registration. |
| **Fascicolo Storico** | Historical Company File (`otherDocuments`, subType `fascicolo_storico`) | PDF | \~5 min | Yes | No | Complete historical company file. Richer than the Visura Storica: it adds the share and quota transfer history. |
| **Statuto** | Articles of Association | PDF | \~5 min | Yes | No | The company's constitutional document as filed at the chamber of commerce, including any amending protocols. |
| **Bilancio d'Esercizio** | Financial Statement | ZIP | \~5 min | When filed | When filed | Annual accounts per fiscal year; ZIP contains XBRL/PDF |
| **Bilancio Consolidato** | Consolidated Financial Statement | ZIP | \~5 min | When filed | When filed | Consolidated group accounts per fiscal year |
Chamber of commerce documents (Visura Camerale, Visura Storica, Fascicolo Storico, Statuto) are listed only for entities registered in the Registro Imprese. An entity with no REA registration, or whose registration is still pending, has none listed.
Documents are ordered from the register and generated asynchronously. The Visura Camerale is deduplicated for 24 hours; subsequent requests within this period return the deduplicated version. Financial statements are historical documents and are deduplicated permanently since historical filings never change. Bilancio documents are listed per company from the register, showing all available fiscal years.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "IT", "dataPoints": ["company", "legalRepresentatives"] }`
Note that this request returns no `company.capital`, because the register files share
capital with the shareholder list. Add `"shareholders"` to `dataPoints` to get it. See
[Share capital in verification mode](#share-capital-in-verification-mode).
```json theme={null}
{
"company": {
"id": "01234567890",
"countryCode": "IT",
"identifiers": {
"VAT": "01234567890",
"codiceFiscale": "01234567890",
"cciaa": "MI",
"rea": "2098765"
},
"legalName": "EXAMPLE TECH SRL",
"incorporationDate": "2015-03-10",
"registrationDate": "2015-03-15",
"status": {
"localName": "attiva",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "SOCIETA' A RESPONSABILITA' LIMITATA",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "OV32"
},
"activities": {
"ATECO_2025": [
{ "code": "620100", "description": "Computer programming activities", "isAIInferred": false, "isMainActivity": true }
],
"NACE": [
{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false, "isMainActivity": true }
],
"ISIC": [
{ "code": "6201", "description": "Computer programming activities", "isAIInferred": false, "isMainActivity": true }
]
},
"legalAddress": {
"addressLine1": "Via Roma 42",
"city": "Milano",
"postalCode": "20121",
"region": "MI",
"countryCode": "IT"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Amministratore unico",
"englishTranslation": "Sole Director",
"standardized": "Director"
},
"individual": {
"name": { "fullName": "Marco Rossi", "firstName": "Marco", "lastName": "Rossi" },
"gender": "Male",
"birthDate": { "year": 1980, "month": 5, "day": 15 },
"birthAddress": { "city": "Milano", "region": "MI", "countryCode": "IT" },
"residenceAddress": {
"addressLine1": "Via Giuseppe Verdi 8",
"city": "Milano",
"postalCode": "20121",
"region": "MI",
"countryCode": "IT"
},
"identifiers": { "codiceFiscale": "RSSMRC80E15F205X" }
}
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 60,
"nominalCapitalHeld": { "amount": 30000, "currency": "EUR", "formatted": "30000 EUR" },
"paidInAmount": { "amount": 30000, "currency": "EUR", "formatted": "30000 EUR" },
"individual": {
"name": { "fullName": "Marco Rossi" },
"identifiers": { "codiceFiscale": "RSSMRC80E15F205X" },
"birthDate": { "year": 1980, "month": 5, "day": 15 },
"birthAddress": { "city": "Milano", "region": "MI", "countryCode": "IT" }
}
},
{
"entityId": "person_002",
"type": "individual",
"sharePercentage": 40,
"nominalCapitalHeld": { "amount": 20000, "currency": "EUR", "formatted": "20000 EUR" },
"paidInAmount": { "amount": 20000, "currency": "EUR", "formatted": "20000 EUR" },
"individual": {
"name": { "fullName": "Giulia Bianchi" },
"identifiers": { "codiceFiscale": "BNCGLI85A41H501Y" }
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "09876543210",
"countryCode": "IT",
"identifiers": {
"VAT": "09876543210",
"codiceFiscale": "09876543210",
"cciaa": "RM",
"rea": "1503238"
},
"legalName": "GRANDE INDUSTRIA SPA",
"incorporationDate": "2000-01-20",
"registrationDate": "2000-02-01",
"status": {
"localName": "attiva",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "SOCIETA' PER AZIONI",
"englishTranslation": "Joint Stock Company",
"standardized": "Corporation",
"iso20275Code": "P418"
},
"activities": {
"ATECO": [
{ "code": "461900", "description": "Agents involved in the sale of a variety of goods", "isAIInferred": false, "isMainActivity": true }
],
"ISIC": [
{ "code": "4610", "description": "Wholesale on a fee or contract basis", "isAIInferred": true, "isMainActivity": true }
],
"NACE": [
{ "code": "46.19", "description": "Agents involved in the sale of a variety of goods", "isAIInferred": true, "isMainActivity": true }
]
},
"legalAddress": {
"addressLine1": "Via del Corso 10",
"city": "Roma",
"postalCode": "00186",
"region": "RM",
"countryCode": "IT"
}
},
"legalRepresentatives": []
}
```
When the register cannot return the company and the fast profile source is used as a fallback, legal representatives are **not available** and the activity code is returned under `ATECO`.
```json theme={null}
{
"company": {
"id": "05678901234",
"countryCode": "IT",
"identifiers": {
"VAT": "05678901234",
"codiceFiscale": "05678901234",
"cciaa": "TO",
"rea": "876543"
},
"legalName": "VECCHIA DITTA SNC DI BIANCHI E VERDI",
"incorporationDate": "1995-06-15",
"registrationDate": "1995-07-01",
"status": {
"localName": "cessata",
"active": false,
"statusDetails": { "status": "CLOSED" }
},
"legalForm": {
"localName": "SOCIETA' IN NOME COLLETTIVO",
"englishTranslation": "General Partnership",
"standardized": "Partnership"
},
"activities": {
"ATECO_2025": [
{ "code": "471100", "description": "Retail sale in non-specialised stores", "isAIInferred": false, "isMainActivity": true }
]
},
"legalAddress": {
"addressLine1": "Corso Vittorio Emanuele 88",
"city": "Torino",
"postalCode": "10121",
"region": "TO",
"countryCode": "IT"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Socio amministratore",
"englishTranslation": "Managing Partner",
"standardized": "Partner"
},
"individual": {
"name": { "fullName": "Luigi Bianchi", "firstName": "Luigi", "lastName": "Bianchi" },
"identifiers": { "codiceFiscale": "BNCLGU70A01L219K" }
}
}
],
"shareholders": []
}
```
```json theme={null}
{
"company": {
"id": "RSSMRA85M01H501Z",
"countryCode": "IT",
"identifiers": {
"codiceFiscale": "RSSMRA85M01H501Z",
"VAT": "04567890123",
"cciaa": "RM",
"rea": "1234567"
},
"legalName": "ROSSI MARIO CONSULENZE",
"incorporationDate": "2010-09-01",
"registrationDate": "2010-09-05",
"status": {
"localName": "attiva",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "IMPRESA INDIVIDUALE",
"englishTranslation": "Sole Proprietorship",
"standardized": "Sole Proprietorship"
},
"activities": {
"ATECO_2025": [
{ "code": "702200", "description": "Business and other management consultancy activities", "isAIInferred": false, "isMainActivity": true }
],
"NACE": [
{ "code": "70.22", "description": "Business and other management consultancy activities", "isAIInferred": true, "isMainActivity": true }
]
},
"legalAddress": {
"addressLine1": "Via Appia Nuova 200",
"city": "Roma",
"postalCode": "00183",
"region": "RM",
"countryCode": "IT"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "TITOLARE",
"englishTranslation": "Owner",
"standardized": "Owner"
},
"individual": {
"name": { "fullName": "Mario Rossi", "firstName": "Mario", "lastName": "Rossi" },
"identifiers": { "codiceFiscale": "RSSMRA85M01H501Z" }
}
}
]
}
```
The owner is returned under `legalRepresentatives`. Requesting `shareholders` for a sole proprietorship returns an explicit not-applicable response, with no charge.
Query: `POST /v2/company` with `{ "id": "", "countryCode": "IT", "mode": "prefill", "dataPoints": ["company"] }`. Prefill returns only `company`: no share capital, officers, shareholders, employees, phones or website.
```json theme={null}
{
"company": {
"id": "01234567890",
"countryCode": "IT",
"identifiers": {
"VAT": "01234567890",
"codiceFiscale": "01234567890",
"cciaa": "MI",
"rea": "2098765"
},
"legalName": "EXAMPLE TECH SRL",
"incorporationDate": "2015-03-10",
"registrationDate": "2015-03-15",
"status": {
"localName": "ATTIVA",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "SOCIETA' A RESPONSABILITA' LIMITATA",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "OV32"
},
"activities": {
"ATECO": [
{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false, "isMainActivity": true }
],
"ISIC": [
{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }
],
"NACE": [
{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": true }
]
},
"legalAddress": {
"addressLine1": "Via Roma 42",
"city": "Milano",
"postalCode": "20121",
"region": "MI",
"countryCode": "IT"
}
}
}
```
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
```json theme={null}
{
"documents": {
"certifiedTradeRegisterExtract": {
"name": "Visura Camerale",
"description": "Certified trade register extract from Italian Chamber of Commerce",
"format": "pdf",
"estimatedDeliverySeconds": 300
},
"tradeRegisterHistory": {
"name": "Visura Storica",
"description": "Historical company report listing every amendment to the entity since its registration.",
"format": "pdf",
"estimatedDeliverySeconds": 300
},
"financialStatements": [
{
"name": "Bilancio d'Esercizio 2023",
"description": "Financial Statement for the year ending December 31, 2023",
"format": "zip",
"estimatedDeliverySeconds": 300,
"date": "2023-12-31",
"period": {
"startDate": { "year": 2023, "month": 1, "day": 1 },
"endDate": { "year": 2023, "month": 12, "day": 31 }
}
},
{
"name": "Bilancio Consolidato 2023",
"description": "Consolidated Financial Statement for the year ending December 31, 2023",
"format": "zip",
"estimatedDeliverySeconds": 300,
"date": "2023-12-31",
"period": {
"startDate": { "year": 2023, "month": 1, "day": 1 },
"endDate": { "year": 2023, "month": 12, "day": 31 }
}
},
{
"name": "Bilancio d'Esercizio 2022",
"description": "Financial Statement for the year ending December 31, 2022",
"format": "zip",
"estimatedDeliverySeconds": 300,
"date": "2022-12-31",
"period": {
"startDate": { "year": 2022, "month": 1, "day": 1 },
"endDate": { "year": 2022, "month": 12, "day": 31 }
}
}
]
}
}
```
In verification mode the register publishes the ATECO 2025 code of the prevailing activity together with its NACE code, and ISIC is mapped from NACE:
```json theme={null}
{
"activities": {
"ATECO_2025": [
{ "code": "107300", "description": "Manufacture of macaroni, noodles, couscous and similar farinaceous products", "isAIInferred": false, "isMainActivity": true }
],
"NACE": [
{ "code": "10.73", "description": "Manufacture of macaroni, noodles, couscous and similar farinaceous products", "isAIInferred": false, "isMainActivity": true }
],
"ISIC": [
{ "code": "1074", "description": "Manufacture of macaroni, noodles, couscous and similar farinaceous products", "isAIInferred": false, "isMainActivity": true }
]
}
}
```
In this example:
* **Main activity**: `107300` from ATECO\_2025, as declared to the register
* **NACE**: published by the register (NACE Rev. 2.1), not inferred
* **ISIC**: mapped from the NACE code through the official correspondence, so `isAIInferred` is `false`
# Jersey
Source: https://docs.topograph.co/essentials/jersey
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Jersey reference is on the [Jersey country page](https://www.topograph.co/countries/je).
## Start here
This guide contains public integration notes for Jersey. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
All Jersey company data and documents come from the **Jersey Financial Services Commission (JFSC)**.
* **JFSC public register**: Basic identity information, including legal name, registration number, status, legal form, and registration date.
* **Entity Profile Report**: The official trade register extract. Where offered, it supplies detailed company information and any directors, capital, or shareholders disclosed in the report.
* **Certificate of Business Name Registration**: Confirms the registration of a trading name. It is available as a separate document and does not replace the Entity Profile Report for detailed company data.
Document availability depends on what JFSC offers for the individual entity. An active or registered status does not guarantee that an Entity Profile Report exists. Request `availableDocuments` to see the supported documents available for that entity.
## Company Identifiers
### Query Identifiers
The JFSC assigns registration numbers **per entity type**, each starting its own series from 1. That means a bare registration number is not unique: it can identify several entities at once. For example, registration number `3499` is both LORDSWOOD LIMITED (a Registered Company, dissolved in 1968) and QUADRIGA CAPITAL PRIVATE EQUITY VI B L.P. (an active Limited Partnership). Both pages on the JFSC register print `Registration Number: 3499`, with nothing to tell them apart.
To address a single entity, Topograph identifiers combine the registration number with the JFSC entity id, joined by a hyphen: `3499-3005057`. A bare registration number remains a valid **search** query, and `/v2/search` returns every entity that carries it, but `/v2/company` requires the full identifier.
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **Companies and other entities** | JFSC Registry | `-`, digits on both sides | `3499-3005057`, `41-319968`, `159454-3289543` | Registration number and JFSC entity id, hyphen-joined. In the records we have seen, the registration number has 2 to 6 digits and the entity id 6 or 7 |
| **Registered business names** | JFSC Registry | `-`, the registration number prefixed with `RBN` or `BNT` | `RBN14929-158455`, `BNT12894-168806` | Preserve the identifier exactly as returned by search |
Reserved names (`RN`-prefixed registrations) are name reservations rather than entities: they carry no company data and are not returned by search, so they cannot be queried.
**Preserve prefixes:** registration numbers `RBN14929` and `14929` belong to different registrations. Use the complete identifier returned by search.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `companyNumber` | Registration number and JFSC entity id, hyphen-joined | `3499-3005057` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the JFSC entity identifier matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
A bare JFSC registration number is insufficient because numbers overlap across entity types. The match must identify the same entity as the composite identifier.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Registration Number | Digits, optionally prefixed | `3499` | Exact | One result per entity carrying that number, often more than one |
| By Name | Text string (2-100 chars) | `"EXAMPLE HOLDINGS"` | Fuzzy | Multiple results (up to 100 per page) |
**Search Performance:** Use registration number searches for best performance and the most precise results; keep the full identifier, including any `RBN` prefix. Name searches include previous names by default and may return many results across all entity types.
**Search uses the JFSC API directly.** Both name and ID searches query the JFSC Registry Search API in real time. Name searches include previous/historical names to help find renamed entities.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Company Status
The JFSC status is a closed list of values. Topograph maps each one **deterministically** to a standardized status and, where the register's wording names the cause, a closure reason. For active entities whose data comes from the Entity Profile Report, status is AI-parsed from the report.
| Local Status | Standardized Status | Closure Reason | Notes |
| - | - | - | - |
| Active | Active | -- | Entity is currently operating |
| Registered | Active | -- | Live status of a registered business name |
| Active (Continued In) | Active | -- | Continued into Jersey from another jurisdiction |
| Active (Merged) | Active | -- | Surviving entity of a merger |
| In Liquidation | Under Insolvency Proceeding | Liquidation | Entity is being liquidated |
| Cancelled | Closed | Other | Registration cancelled (partnerships, funds) |
| Inactive (Cancelled) | Closed | Other | |
| Ceased | Closed | Other | Business name that has stopped trading |
| Dissolved | Closed | Other | |
| Inactive (Dissolved) | Closed | Other | |
| Inactive (Dissolved/Ceased) | Closed | Other | |
| Inactive (Struck Off) | Closed | Administrative Dissolution | Removed from the register |
| Inactive (Merged/Demerged) | Closed | Merger | |
| Inactive (Merged Out) | Closed | Merger | Absorbed by a merger |
| Inactive (Continued Overseas) | Closed | Other | Migrated out of Jersey |
| Inactive (Continued Out) | Closed | Other | Migrated out of Jersey |
| Used | Unknown | -- | Name reservation consumed by an incorporation, not a company |
| Rejected | Unknown | -- | Name reservation refused by the JFSC, not a company |
For **inactive** entities (for example Dissolved, Inactive (Struck Off), Cancelled, Ceased), the Entity Profile Report is **not available** from the JFSC. This means legal representatives, shareholders, capital, and registered address cannot be extracted for inactive companies -- only basic data (name, status, legal form, registration date) is returned from the public register.
## Legal Forms
Jersey entities are classified by type from the JFSC Registry. The JFSC type is a closed list of values, mapped **deterministically** to an English translation, standardized company type, and ISO 20275 (ELF) code. The local JFSC entity type is always preserved verbatim in the `localName` field. For active entities whose data comes from the Entity Profile Report, the legal form is AI-parsed from the report.
### Companies
| Local Name | Standardized | ISO 20275 | Notes |
| - | - | - | - |
| Registered Company Private | Limited Liability Company | SQXV | Most common company type (private limited) |
| Registered Company Public | Corporation | JOX1 | Public limited company |
| Limited Liability Company - Body Corporate | Limited Liability Company | -- | Jersey LLC |
| Limited Liability Company - Unincorporated Body | Limited Liability Company | -- | Jersey LLC |
### Cell Companies
| Local Name | Standardized | ISO 20275 | Notes |
| - | - | - | - |
| Incorporated Cell Company Private | Limited Liability Company | -- | Company with segregated cells |
| Incorporated Cell Company Public | Corporation | -- | Company with segregated cells |
| Incorporated Cell Private | Limited Liability Company | -- | Cell of an incorporated cell company |
| Incorporated Cell Public | Corporation | -- | Cell of an incorporated cell company |
| Protected Cell Company Private | Limited Liability Company | -- | Company with protected cells |
| Protected Cell Company Public | Corporation | -- | Company with protected cells |
| Protected Cell Private | Limited Liability Company | -- | Cell of a protected cell company |
| Protected Cell Public | Corporation | -- | Cell of a protected cell company |
### Partnerships
| Local Name | Standardized | ISO 20275 | Notes |
| - | - | - | - |
| Limited Partnership | Partnership | UBWU | LP structure |
| Limited Liability Partnership | Partnership | 7RZH | LLP structure |
| Separate Limited Partnership | Partnership | 21F4 | SLP with separate legal personality |
| Incorporated Limited Partnership | Partnership | 33IP | ILP with separate legal personality |
### Other Entities
| Local Name | Standardized | ISO 20275 | Notes |
| - | - | - | - |
| Foundation | Nonprofit Organization | 40A7 | Jersey foundation |
| Business Name | Sole Proprietorship | -- | Trading name registration |
| Registered Business Name | Sole Proprietorship | -- | Trading name registration |
| Unregulated Fund | Other | -- | |
## Legal Representatives
Disclosed current appointments come from the **Entity Profile Report**. The role catalogue distinguishes company directors, foundation council members, general partners, LLP partners and LLC management appointments. A title identifies a capacity; it does not establish sole or joint signing or unrestricted transaction powers.
| Role | Classification | Standardized | Notes |
| - | - | - | - |
| Director, Nominee Director, Alternate Director | Legal Representative | Director | Current director appointment |
| Council Member, Member of the council | Legal Representative | Board Member | Foundation council appointment |
| Qualified Person | Depends on appointment | Board Member or Other | Board Member only when a current qualified council appointment is confirmed |
| General Partner | Legal Representative | General Partner | General-partner appointment |
| Partner | Depends on appointment | Partner or Other | LLP agency or a separately disclosed representative mandate |
| Manager, Member | Depends on appointment | Manager or Other | LLC management and authority depend on the management arrangement and LLC agreement; ownership alone is insufficient |
**Corporate role holders** retain type `company` and their disclosed registered identity. Individual details are included only when disclosed. An unfamiliar appointment title is preserved with standardized role `Other`.
## Other Key Persons
Disclosed administrative or other appointments are returned separately from representative capacities.
| Role | Classification | Standardized | Notes |
| - | - | - | - |
| Secretary | Other Key Person | Secretary | Unless a separate representative mandate is explicitly disclosed |
| Unqualified member, partner or qualified-person capacity | Other Key Person | Other | Ownership, formation or service-provider status alone does not establish authority |
Person records require an available Entity Profile Report and are limited to its disclosures. JFSC generally keeps secretary information private unless the person is also a director or member. Directors of share-transfer companies may appear publicly only as members; a member entry alone is not treated as a director appointment. People are not supplied by the fast search-only mode.
## Shareholders
Shareholders are extracted from the **Entity Profile Report** PDF using AI parsing when shareholder information is disclosed in the document.
### Extraction Logic
| Source | When Used | Data Extracted |
| - | - | - |
| **Entity Profile Report** (Members/Shareholders section) | Active entities only | Shareholder name, number of shares, share class, ownership percentage |
### Ownership Fields
| Field | Description | Source |
| - | - | - |
| `type` | Individual or Company | AI-inferred from name format (e.g., "Ltd" suffix = company) |
| `sharePercentage` | Ownership percentage | AI-calculated from shares held vs. total issued shares |
| `numberOfShares` | Number of shares held | AI-extracted from document |
### Share Types
| Share Class | Description |
| - | - |
| Ordinary shares | Standard voting shares |
| Preference shares | Preferential dividend rights |
| Management shares | Often held by directors |
**Private Jersey companies are not required to publicly disclose shareholders.** When a company's shareholder data is not in the Entity Profile Report, an empty array is returned. Shareholder data is **never** available for inactive entities.
Business name registrations and Jersey foundations have no share capital. For these, the `shareholders` datapoint is not applicable and returns an explicit not-applicable response at no charge.
**Wholly-Owned Subsidiary Pattern:** Many Jersey companies have only 1 share issued despite higher authorized capital. A single shareholder holding 1 share is correctly interpreted as 100% ownership.
## Activity Code Mapping
Jersey does **not** provide activity codes or industry classification through the JFSC Registry. There are no SIC, NACE, or ISIC codes available for Jersey companies.
The JFSC Registry does not include industry classification data in its company records. As a result, no activity codes (NACE, ISIC, SIC, or local classification) are returned for Jersey entities.
## Data Availability Matrix
| Data Type | Active Entities | Inactive Entities | Notes |
| - | - | - | - |
| Company Profile (basic) | ✅ Sync | ✅ Sync | Name, status, legal form, registration date from search API |
| Company Profile (full) | ✅ Async (\~2 min) | ❌ | Requires Entity Profile Report (not available for inactive) |
| Registered Address | ✅ | ❌ | From the JFSC register |
| Share Capital | ✅ | ❌ | From Entity Profile Report (AI-parsed) |
| Legal Representatives | ✅ | ❌ | AI-extracted from Entity Profile Report |
| Other Key Persons | ✅ | ❌ | Secretary, AI-extracted from Entity Profile Report |
| Shareholders | ⚠️ When disclosed | ❌ | Private companies not required to disclose. Not applicable to business names and foundations (explicit not-applicable response, no charge) |
| Ultimate Beneficial Owners | ❌ | ❌ | Not available through JFSC |
| Establishments | ❌ | ❌ | Not provided by JFSC |
| Activity Codes | ❌ | ❌ | JFSC does not provide industry classification |
| Documents (Entity Profile Report) | ⚠️ Where offered | ❌ | Check `availableDocuments`; active status alone is insufficient |
| Documents (Business Name Registration Certificate) | ⚠️ Where offered | ⚠️ Where offered | Confirms registration of a trading name |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Sync = Synchronous | Async = Asynchronous
## Documents by Company Type
| Document | API Category | Format | Availability |
| - | - | - | - |
| **Entity Profile Report (Uncertified)** | `tradeRegisterExtract` | PDF | Entities for which JFSC offers the report |
| **Certificate of Business Name Registration** | `otherDocuments[]` | PDF | Business names for which JFSC offers the certificate |
The certificate carries `subType: "business_name_registration_certificate"`. A business name is a trading name registered by an individual or a company; its registration does not establish which legal form the holder has.
Some active business names have a registration certificate but no Entity Profile Report. The document list reflects the supported products currently offered by JFSC for the requested entity. Inactive entities generally have no Entity Profile Report; basic company information remains available from the public register.
Retrieved documents are reused for 24 hours.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "JE", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "3499-3005057",
"countryCode": "JE",
"identifiers": {
"companyNumber": "3499-3005057"
},
"legalName": "EXAMPLE HOLDINGS (JERSEY) LIMITED",
"legalNameInEnglish": "EXAMPLE HOLDINGS (JERSEY) LIMITED",
"registrationDate": "2018-03-15",
"status": {
"localName": "Active",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Registered Company Private",
"englishTranslation": "Private Limited Company",
"standardized": "Limited Liability Company",
"iso20275Code": "SQXV"
},
"capital": {
"amount": 10000,
"currency": "GBP",
"formatted": "\u00a310,000"
},
"legalAddress": {
"addressLine1": "47 Esplanade",
"city": "St. Helier",
"postalCode": "JE1 0BD",
"countryCode": "JE"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Director",
"englishTranslation": "Director",
"standardized": "Director"
},
"individual": {
"name": {
"fullName": "Jane Elizabeth Smith",
"firstName": "Jane Elizabeth",
"lastName": "Smith"
},
"birthDate": {
"month": 6,
"year": 1980
},
"nationality": "GB",
"residenceAddress": {
"addressLine1": "47 Esplanade",
"city": "St. Helier",
"region": "Jersey",
"postalCode": "JE1 0BD",
"countryCode": "JE"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Director",
"englishTranslation": "Director",
"standardized": "Director"
},
"individual": {
"name": {
"fullName": "John Robert Doe",
"firstName": "John Robert",
"lastName": "Doe"
},
"birthDate": {
"month": 10,
"year": 1975
},
"nationality": "GB",
"residenceAddress": {
"addressLine1": "47 Esplanade",
"city": "St. Helier",
"region": "Jersey",
"postalCode": "JE1 0BD",
"countryCode": "JE"
}
}
}
],
"shareholders": [
{
"entityId": "company_001",
"type": "company",
"sharePercentage": 100,
"numberOfShares": 1,
"company": {
"legalName": "PARENT GROUP LIMITED",
"countryCode": "JE",
"legalAddress": {
"addressLine1": "47 Esplanade",
"city": "St. Helier",
"postalCode": "JE1 0BD",
"countryCode": "JE"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "495-318592",
"countryCode": "JE",
"identifiers": {
"companyNumber": "495-318592"
},
"legalName": "EXAMPLE PARTNERS L.P.",
"registrationDate": "2004-03-31",
"status": {
"localName": "Cancelled",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "OTHER"
}
},
"legalForm": {
"localName": "Limited Partnership",
"englishTranslation": "Limited Partnership",
"standardized": "Partnership",
"iso20275Code": "UBWU"
}
}
}
```
**Note:** Inactive companies return only basic data (name, status, legal form, registration date). No legal representatives, shareholders, address, or capital -- the Entity Profile Report is not available for inactive entities.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Entity Profile Report (Uncertified) | Where offered by JFSC |
| `otherDocuments[]` | Certificate of Business Name Registration | Where offered; `subType: "business_name_registration_certificate"` |
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "b903c3b8-e0a6-5880-923f-306c10722b15",
"name": "Entity Profile Report - Uncertified Online",
"format": "pdf",
"description": "Jersey FSC Entity Profile Report (uncertified)",
"estimatedDeliverySeconds": 60
}
}
}
```
All documents are **PDF** format in **English**.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No data for inactive entities** | The Entity Profile Report is only available for active companies. Dissolved, Inactive (Struck Off), Cancelled, Ceased, and other inactive entities return only basic data (name, status, legal form, registration date) with no directors, shareholders, address, or capital. |
| **Shareholders often undisclosed** | Private Jersey companies are not required to publicly disclose shareholders. When a company's shareholder data is not in the Entity Profile Report, an empty array is returned. For business names and foundations, `shareholders` returns a not-applicable response at no charge. |
| **Wholly-owned subsidiary pattern** | Many Jersey companies have only 1 share issued despite higher authorized capital. A single shareholder with 1 share is correctly interpreted as 100% ownership. |
| **Document delivery time** | Entity Profile Reports usually arrive in about a minute, and can take longer in edge cases. A full company profile built from the report takes about 2 minutes. |
| **No activity codes** | The JFSC does not provide industry classification (SIC, NACE, ISIC) for Jersey companies. Activity codes are not returned. |
| **AI-parsed legal representatives** | Directors and secretaries are extracted from the Entity Profile Report PDF using AI parsing, not from a structured API endpoint. |
| **Registration numbers are not unique on their own** | The JFSC numbers each entity type in its own series, so a bare registration number can belong to several entities. Topograph identifiers combine the registration number with the JFSC entity id (e.g., `3499-3005057`); some also carry a prefix (`RBN`, `BNT`). |
| **Documents deduplicated 24 hours** | Entity Profile Reports are deduplicated for 24 hours after retrieval to avoid redundant retrieves. |
| **Capital in GBP** | Jersey companies report share capital in British Pounds Sterling (GBP), not Euros. |
| **No UBOs** | Ultimate Beneficial Owner data is not available through the JFSC Registry. |
| **No establishments** | The JFSC does not provide establishment/branch data. |
# Latvia
Source: https://docs.topograph.co/essentials/latvia
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Latvia reference is on the [Latvia country page](https://www.topograph.co/countries/lv).
## Start here
This guide contains public integration notes for Latvia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Latvia uses two complementary data sources: the **real-time UR API** for full company profiles and documents, and **open data** for fast batch-deduplicated search and onboarding.
* **Uzņēmumu reģistrs (UR) API.** The Enterprise Register of the Republic of Latvia, maintained by the Register of Enterprises. This is the source for **full company profiles** with AI enrichment: activity codes (NACE/ISIC), legal representatives with standardized roles, supervisory board, shareholders with ownership details, UBOs with control types, and document access. Accessible at [ur.gov.lv](https://www.ur.gov.lv).
* **Latvia Open Data (data.gov.lv).** CC0-licensed datasets from the Enterprise Register, updated daily. Covers \~480K entities across 7 CSV files: company register, officers, members (SIA shareholders), stockholders (AS shareholders), beneficial owners, equity capitals, and areas of activity. Used for **fast search** and the **prefill profile** datapoint.
**Dual-source model.** Search queries hit the fast search index first for
fast results from batch data, then fall back to the UR API for supplementary
results. Prefill mode serves data from the register's daily open-data
export, while verification mode queries the UR API live for AI-enriched data.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entity types** | UR | 11 digits, or 9 digits with leading zeros for some older entries (Registration Number) | `40103217882` | Universal identifier for all Latvian entities |
**Registration Number Format:** Most Latvian registration numbers are 11 digits (`40103217882`). Some older entries have 9 digits, and their leading zeros are part of the number (`000307795`). Pass the number exactly as a search result returns it, with no separators.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `registrationNumber` | 11 digits, or 9 digits with leading zeros | `40103217882` | All entities |
| `euid` | `LVUR.` + 11 digits | `LVUR.50003090101` | SIA and AS companies |
| `foreignRegistrationNumber` | Home-country registration number, in that register's own format | `930097705` | Foreign entities in the register |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Latvian registration number (`registrationNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Source | Speed |
| - | - | - | - | - | - |
| By Registration Number | 9-11 digits | `40103217882` | Exact | Fast index + UR API | fast initial results |
| By Name | Text string (2-100 chars) | `"Bolt"` | Fuzzy/Contains | Fast index + UR API | fast initial results |
| By VAT Number | `LV` + 11 digits | `LV40103217882` | Exact | VIES + UR API | \~1-5s |
**Search Performance:** Fast-index results arrive first from
batch-deduplicated data covering \~480K entities. UR API results supplement later via
progressive streaming. Use registration number searches for exact matching and
best performance.
**Search architecture:** Search queries run all sources in parallel. Fast-index sources return first from synchronized open data. The UR API sources (by ID, by VAT, by name) provide supplementary results. Results are merged with matchType priority (ID > exact name > partial match).
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. A registered company in liquidation remains active until removal and can appear in both name and identifier searches.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefill mode uses open data** | Prefill mode is served from the Enterprise Register's daily open-data export (about a 24-hour lag), so it keeps answering when the live register is unavailable. It does not include birth dates, supervisory board members, procurists, or activity codes. Use verification mode for those. UBOs are available in verification mode only. |
| **NACE revision conversion** | Latvia may provide NACE Rev. 1 or 1.1 codes (pre-2008 classification) for older companies. These are converted to NACE Rev. 2 via AI, then transitioned to Rev. 2.1 under `NACE` and flagged `isAIInferred`. The register's own codes stay under `NACE_REV1` / `NACE_REV11`. Division codes have different meanings across revisions (e.g., Division 15 = Food products in Rev. 1 vs. Leather in Rev. 2). |
| **Status uses finite enum** | Company status is deterministic from a finite API enum: `REGISTERED`, `REMOVED`, `ANNULLED`. No AI inference needed. Reorganization and liquidation details refine the standardized status. |
| **Hyphen vs. underscore in status** | The UR API returns status details with both hyphens (`IN-LIQUIDATION`) and underscores (`IN_LIQUIDATION`). Both formats are handled automatically. |
| **Closure causes need evidence** | An explicit liquidation record can establish Liquidation. Reorganization, removal or annulment alone do not establish merger, administrative dissolution or court order; their closure cause is Unknown. |
| **Hybrid role mapping** | Legal representative and other key person roles use a hybrid approach: known roles are mapped deterministically, unknown free-text roles are enriched by AI. The recorded position and governing body are considered alongside the role title. |
| **Historical currency (LVL)** | Older records may show share capital in Latvian Lats (LVL) instead of EUR. Latvia adopted the Euro on January 1, 2014. |
| **Document format conversion** | EDOC and ASICE containers are delivered as PDF. HTML and similar formats are delivered as the original file plus a PDF rendering. Other formats are delivered as-is. |
| **ISIC derived from NACE** | ISIC codes are derived from the `NACE` codes through the formal correspondence and copy the `isAIInferred` flag of the NACE code they come from. They are AI-inferred only when that NACE code is. |
| **Shareholder nominal value** | Shareholder data includes `shareNominalValue` (value per share) which is multiplied by `numberOfShares` to compute total nominal capital held. |
| **Legacy person-as-entity records** | Some older records (especially individual undertakings) list natural persons as legal entities. These are returned as individuals. |
| **No employee count** | The UR API does not provide employee count data for any entity type. |
| **No website/email/phone** | Contact information (website, email, phone numbers) is not available from the Enterprise Register. |
## Company Status
Company status is determined **deterministically** from the UR API schema. No AI inference is involved. The API returns a finite enum of statuses with optional status details and liquidation records.
| Local Name | Standardized Status | Active | Closure Reason |
| - | - | - | - |
| Reģistrēts | Active | true | - |
| Likvidācijas procesā | Pending Dissolution | true | - |
| Izslēgts (reorganizācija) | Closed | false | Unknown |
| Izslēgts (likvidācija) | Closed | false | Liquidation |
| Izslēgts no reģistra | Closed | false | Unknown |
| Anulēts | Closed | false | Unknown |
| Unrecognized source status | Unknown | false | - |
Liquidation alone does not establish insolvency, so no `insolvencyStartDate` is inferred from a liquidation date. `statusDetails.additionalInfo` retains recorded liquidation grounds where available.
For a removed company, `closureDate` is the register's removal date. A cancelled liquidation does not establish the cause of a later removal.
## Legal Forms
The **18 known verification forms** below have deterministic native names, English translations and broad standardized categories. An ISO 20275 reference is included where the native form has an exact match. Prefill covers all **54 form codes observed in the register's public data**, including historical forms. See the pricing page for the complete catalogue.
The standardized category is a broad grouping. Native legal form and ISO 20275 reference preserve more specific distinctions; an additional-liability company is classified as Other.
The **Legal basis** column links the act that creates or defines each form, at its official publication. The pricing-page catalogue carries the same links for every verified form and role in a `legalBasisBeta` list, one entry per act. This field is in beta: its name and shape may change before it becomes `legalBasis`. A form whose register label does not identify a single act has no link.
### Commercial Companies
| API Type Code | Latvian Name | Abbr. | English Translation | Standardized | Legal basis |
| - | - | - | - | - | - |
| `LIMITED_LIABILITY_COMPANY_SIA` | Sabiedrība ar ierobežotu atbildību | SIA | Limited Liability Company | Limited Liability Company | [Commercial Law s.134](https://likumi.lv/ta/id/5490-komerclikums#p134) |
| `PUBLIC_LIMITED_COMPANY_AS` | Akciju sabiedrība | AS | Public Limited Company | Corporation | [Commercial Law s.134](https://likumi.lv/ta/id/5490-komerclikums#p134) |
| `GENERAL_PARTNERSHIP_PS` | Pilnsabiedrība | PS | General Partnership | Partnership | [Commercial Law s.77](https://likumi.lv/ta/id/5490-komerclikums#p77) |
| `LIMITED_PARTNERSHIP_KS` | Komandītsabiedrība | KS | Limited Partnership | Partnership | [Commercial Law s.118](https://likumi.lv/ta/id/5490-komerclikums#p118) |
| `COOPERATIVE_SOCIETY_KB` | Kooperatīvā sabiedrība | - | Cooperative Society | Cooperative | [Cooperative Societies Law s.1, s.3](https://likumi.lv/ta/id/298656-kooperativo-sabiedribu-likums#p1) |
### Sole Entrepreneurs & Individual Entities
| API Type Code | Latvian Name | Abbr. | English Translation | Standardized | Legal basis |
| - | - | - | - | - | - |
| `SOLE_TRADER_IK` | Individuālais komersants | IK | Sole Trader | Sole Proprietorship | [Commercial Law s.74](https://likumi.lv/ta/id/5490-komerclikums#p74) |
| `INDIVIDUAL_UNDERTAKING_IND` | Individuālais uzņēmums | - | Individual Undertaking | Sole Proprietorship | [Commercial Law transition act s.17](https://likumi.lv/ta/id/56945-komerclikuma-speka-stasanas-kartibas-likums#p17) |
| `FARM_ZEM` | Zemnieku saimniecība | Z/S | Farm | Sole Proprietorship | [Commercial Law transition act s.17](https://likumi.lv/ta/id/56945-komerclikuma-speka-stasanas-kartibas-likums#p17) |
### Non-Profits & Civil Society
| API Type Code | Latvian Name | English Translation | Standardized | Legal basis |
| - | - | - | - | - |
| `ASSOCIATION_BDR` | Biedrība | Association | Nonprofit Organization | [Associations and Foundations Law s.2](https://likumi.lv/ta/id/81050-biedribu-un-nodibinajumu-likums#p2) |
| `FOUNDATION_NOD` | Nodibinājums | Foundation | Nonprofit Organization | [Associations and Foundations Law s.2](https://likumi.lv/ta/id/81050-biedribu-un-nodibinajumu-likums#p2) |
| `RELIGIOUS_ORGANIZATION_REL` | Reliģiskā organizācija | Religious Organization | Nonprofit Organization | [Law on Religious Organisations s.3](https://likumi.lv/ta/id/36874-religisko-organizaciju-likums#p3) |
| `POLITICAL_PARTY_PP` | Politiskā partija | Political Party | Nonprofit Organization | [Political Parties Law s.2](https://likumi.lv/ta/id/139367-politisko-partiju-likums#p2) |
### European & International Entities
| API Type Code | Latvian Name | Abbr. | English Translation | Standardized | Legal basis |
| - | - | - | - | - | - |
| `EUROPEAN_COMPANY_SE` | Eiropas komercsabiedrība | SE | European Company (SE) | Corporation | [European Company Law s.2](https://likumi.lv/ta/id/104374-eiropas-komercsabiedribu-likums#p2), [Regulation (EC) 2157/2001](https://eur-lex.europa.eu/eli/reg/2001/2157/oj) |
| `EUROPEAN_COOPERATIVE_SOCIETY_SCE` | Eiropas kooperatīvā sabiedrība | SCE | European Cooperative Society (SCE) | Cooperative | [European Cooperative Society Law s.1–2](https://likumi.lv/ta/id/147524-eiropas-kooperativo-sabiedribu-likums#p1), [Regulation (EC) 1435/2003](https://eur-lex.europa.eu/eli/reg/2003/1435/oj) |
| `EUROPEAN_ECONOMIC_INTEREST_GROUPING_EEIG` | Eiropas ekonomisko interešu grupējums | EEIG | European Economic Interest Grouping (EEIG) | Partnership | [EEIG Law s.2](https://likumi.lv/ta/id/90817-eiropas-ekonomisko-interesu-grupu-likums#p2), [Regulation (EEC) 2137/85](https://eur-lex.europa.eu/eli/reg/1985/2137/oj) |
### Other Entity Types
| API Type Code | Latvian Name | English Translation | Standardized | Legal basis |
| - | - | - | - | - |
| `BRANCH_FIL` | Filiāle | Branch | Branch or Representative Office | [Commercial Law s.22](https://likumi.lv/ta/id/5490-komerclikums#p22) |
| `PUBLIC_BODY` | Publiska persona vai iestāde | Public Body | Government-Owned Entity | - |
| `MIL` | Masu informācijas līdzeklis | Mass Media | Other | [Law on the Press and Other Mass Media s.9](https://likumi.lv/ta/id/64879-par-presi-un-citiem-masu-informacijas-lidzekliem#p9) |
Unrecognized forms retain the register's wording. Verification may enrich their translation and category. A missing ISO 20275 reference does not imply that the native form is unknown.
## Legal Representatives
Legal representatives come from actual registered representation rights, executive-body appointments and known authorised offices. Structured position and governing-body fields take precedence over free-text titles. A supervisory-body record is an other key person unless the register separately records representation rights. The supervisory board's specific statutory capacity in disputes with executive-board members does not itself establish ordinary commercial signing authority.
### Representation Mode
Both modes retain structured source conditions in `signingPowers.localText`. Pure `INDIVIDUALLY` means sole signing. `WITH_AT_LEAST`, `WITH_ALL`, `WITH_CHAIR`, `WITH_DEPUTY_CHAIR` and joint-only combinations mean joint signing. Conditions mixing individual and joint operation remain unspecified rather than being reduced to one mode. Missing rights remain unspecified.
A recorded `withAtLeast` quantity is preserved in the source condition. Its basis as co-signers or total signers has not been verified, so it is not presented as `minimumSignatories`.
### Legal Representative Roles (Deterministic Mapping)
| Role Key | Latvian Name | English Translation | Standardized Role |
| - | - | - | - |
| `valdes_loceklis` | Valdes loceklis | Board Member | Board Member |
| `valdes_priekssedetajs` | Valdes priekšsēdētājs | Chairman of the Board | Chairman of the Board |
| `direktors` | Direktors | Director | Director |
| `izpilddirektors` | Izpilddirektors | Executive Director | Executive Director |
| `likvidators` | Likvidators | Liquidator | Liquidator |
| `administrators` | Administrators | Administrator | Administrator |
| `prokurists` | Prokūrists | Procurist | Authorized Signatory |
| Position Value | Latvian Name | English Translation | Standardized Role | Legal basis |
| - | - | - | - | - |
| `CHAIR_OF_BOARD` | Valdes priekšsēdētājs | Chairman of the Board | Chairman of the Board | [Commercial Law s.221–223, s.301–303](https://likumi.lv/ta/id/5490-komerclikums#p221) |
| `BOARD_MEMBER` | Valdes loceklis | Board Member | Board Member | [Commercial Law s.221–223, s.301–303](https://likumi.lv/ta/id/5490-komerclikums#p221) |
| `DIRECTOR` | Direktors | Director | Director | - |
| `EXECUTIVE_DIRECTOR` | Izpilddirektors | Executive Director | Executive Director | - |
| `LIQUIDATOR` | Likvidators | Liquidator | Liquidator | [Commercial Law s.322](https://likumi.lv/ta/id/5490-komerclikums#p322) |
| `ADMINISTRATOR` | Administrators | Administrator | Administrator | [Insolvency Law s.65–67](https://likumi.lv/ta/id/214590-maksatnespejas-likums#p65) |
| Governing Body | Classification |
| - | - |
| `EXECUTIVE_BOARD` | Legal Representative |
| `SUPERVISORY_BOARD` | Other Key Person |
The public officer feed currently contains 15 nonblank position codes and 10 governing-body codes. Titles are preserved from the source. Unknown titles do not establish representation through substring matching. Standalone `MANAGER`, `MEMBER`, `ESTATE_TRUSTEE` and other context-dependent appointments need actual registered rights or an executive-body context. Otherwise the named officer is retained as an other key person. Oversight coverage in the open-data feed is sparse; verification has the richer register record.
**Procurists** ([Commercial Law s.34–35](https://likumi.lv/ta/id/5490-komerclikums#p34)) are available in verification mode and returned as individuals. Recorded representation and immovable-property conditions are retained in `signingPowers.localText`. `representationMode` is provided only when the recorded terms establish sole or joint operation. Both individual and corporate legal representatives are supported.
## Other Key Persons
Other key persons (supervisory board members, auditors) are drawn from the same register officers, classified by role, position or governing body.
### Other Key Person Roles (Deterministic Mapping)
| Role Key / Position | Latvian Name | English Translation | Standardized Role | Legal basis |
| - | - | - | - | - |
| `padomes_loceklis` / `SUPERVISORY_BOARD_MEMBER` | Padomes loceklis | Supervisory Board Member | Supervisory Board Member | [Commercial Law s.292–297](https://likumi.lv/ta/id/5490-komerclikums#p292) |
| `padomes_priekssedetajs` / `CHAIR_OF_SUPERVISORY_BOARD` | Padomes priekšsēdētājs | Chairman of Supervisory Board | Supervisory Board Member | [Commercial Law s.292–297](https://likumi.lv/ta/id/5490-komerclikums#p292) |
| `revidents` / `AUDITOR` / `REVISOR` | Revidents | Auditor | Auditor | - |
A supervisory-body appointment without a specific title is classified as Supervisory Board Member while retaining its source label. A known chair title remains visible. Both individual and corporate other key persons are supported.
## Shareholders
Shareholders are drawn from the Enterprise Register's recorded members for **capital companies and partnerships** (SIA, AS, PS, KS, cooperatives). Sole entrepreneurs (IK, individual undertakings, farms) and non-profits (associations, foundations, religious organizations, political parties) have no share capital: a `shareholders` request for them returns an explicit not-applicable response and is not billed. In prefill mode, shareholders come from the register's open data, which covers SIA and AS members only.
### Extraction Logic
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | `shareHolderDetails.inPercent` |
| `numberOfShares` | Number of shares held | `shareHolderDetails.numberOfShares` |
| `nominalCapitalHeld` | Total nominal capital (value per share x number of shares) | `shareHolderDetails.shareNominalValue` x `numberOfShares` |
| `type` | Individual or Company | Determined from `naturalPerson` or `legalEntity` presence |
The register also records voting rights, joint ownership, ownership start dates, representatives of minors or legal entities, and paid-up amounts. These are not returned.
Both individual and corporate shareholders are supported. Corporate
shareholders include registration number and country when available. Foreign
corporate shareholders are identified with their home country registration
details.
## Activity Code Mapping
Latvia uses **NACE** (Nomenclature of Economic Activities) codes from the Enterprise Register. The system maps activity codes across two levels, with special handling for older NACE revisions:
```
NACE Rev. 2 (register) → NACE Rev. 2.1 (European standard) → ISIC Rev. 5 (International)
```
| Key | Source | Example | AI Inferred? |
| - | - | - | - |
| `NACE` | Rev. 2.1 transition of the register's code | `62.10` | No, unless the register's code was Rev. 1/1.1 |
| `NACE_REV2` | UR API (`naceTypes` stamped `2`), as declared | `62.01` | No |
| `NACE_REV1` / `NACE_REV11` | UR API (`naceTypes` stamped `1` / `1.1`), as declared | `15.31` | No |
| `ISIC` | Derived from `NACE` | `621` | No, unless the NACE code it came from is AI-inferred |
### NACE Revision Handling
| Scenario | Processing |
| - | - |
| **NACE Rev. 2 codes** | Published as declared under `NACE_REV2`; transitioned to Rev. 2.1 for `NACE`, ISIC derived formally |
| **NACE Rev. 1 or 1.1 codes** | Published as declared under `NACE_REV1` / `NACE_REV11`; converted to Rev. 2 via AI where possible, then transitioned to `NACE` (marked `isAIInferred`) and ISIC derived. A code the model cannot place stays under its own key only |
| **No NACE codes (text only)** | Registered activity and purpose descriptions used for AI enrichment to derive both NACE and ISIC |
| **Placeholder codes (00.00)** | Filtered out automatically |
**NACE Revision Mismatch:** Older Latvian companies may have NACE Rev. 1 or
1.1 codes that look similar to Rev. 2 codes but represent entirely different
economic activities. For example, Division 15 in Rev. 1.1 = "Food products and
beverages" but in Rev. 2 = "Leather and related products." The system detects
the revision and converts automatically.
Non-profit entities (associations, foundations) may have activity area codes
(`areasOfActivityOfAssociationsFoundations`) instead of NACE codes. These use
a separate classification (e.g., `HEALTH_AND_DISEASE_PREVENTION`, `EDUCATION`,
`CULTURE`, `SPORT`) and are processed via AI enrichment to derive NACE/ISIC
equivalents.
## Data Availability Matrix
| Data Type | Commercial Companies (SIA, AS) | Sole Entrepreneurs (IK) | Partnerships (PS, KS) | Non-Profits (Biedrība) | Foundations (Nodibinājums) | Notes |
| - | - | - | - | - | - | - |
| Prefill Profile | ✅ Fast | ✅ Fast | ✅ Fast | ✅ Fast | ✅ Fast | From batch open data (\~1s). Includes legal reps, shareholders, capital |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | ✅ Async | ✅ Async | Full data from Enterprise Register |
| Legal Representatives | ✅ | ✅ | ✅ | ✅ | ✅ | Board members, directors, liquidators, procurists (procurists in verification mode only) |
| Other Key Persons | ✅ | ⚠️ Limited | ⚠️ Limited | ⚠️ Limited | ⚠️ Limited | Available nonrepresentative officers are retained in both modes; oversight coverage is sparse in prefill |
| Shareholders | ✅ | ❌ | ✅ | ❌ | ❌ | Not applicable to sole entrepreneurs and non-profits (explicit not-applicable response, not billed). Prefill mode covers SIA and AS only |
| Ultimate Beneficial Owners | ✅ | ⚠️ Limited | ⚠️ Limited | ⚠️ Limited | ⚠️ Limited | Directly from register, no retrieve required. Verification mode only |
| Activity Codes | ✅ | ✅ | ✅ | ✅ | ✅ | NACE (may need revision conversion) + ISIC. Verification mode only |
| Documents | ✅ | ✅ | ✅ | ✅ | ✅ | CTRE, annual reports, articles, registry docs |
| Share Capital | ✅ | ❌ | ❌ | ❌ | ❌ | SIA and AS only |
| Employee Count | ❌ | ❌ | ❌ | ❌ | ❌ | Not available from Enterprise Register |
| Previous Names | ❌ | ❌ | ❌ | ❌ | ❌ | Not returned |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
Prefill mode is served from the register's daily open data, with about a
24-hour lag. It does not include birth dates, supervisory board members,
procurists, or activity codes. UBOs are available in verification mode only.
## Documents by Company Type
Latvia provides comprehensive document access through the Enterprise Register (Uzņēmumu reģistrs). Documents are sourced from two channels: the UR website (for CTRE) and the UR API (for all other documents).
### Always Available
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Certified Trade Register Extract** | `certifiedTradeRegisterExtract` | PDF | ✅ All registered companies | Official e-sealed extract with complete registration data. Priced with the company data product (see the pricing page) |
### From UR API (Public Documents)
| Document Type | UR Type Code | API Category | Notes |
| - | - | - | - |
| Articles of Association | `AOA` | `articlesOfAssociation[]` | Company bylaws (Statūti) |
| Amendments to Articles of Association | `AMENDMENTS_TO_AOA` | `articlesOfAssociation[]` | Changes to bylaws |
| Document Type | UR Type Code | API Category | Notes |
| - | - | - | - |
| Annual Report | `ANNUAL_REPORT` | `financialStatements[]` | Balance sheet, income statement, cash flow |
| Sample Report | `SAMPLE_REPORT` | `financialStatements[]` | Simplified financial report |
| Document Type | UR Type Code | Internal Type | Notes |
| - | - | - | - |
| Registration Certificate | `REGISTRATION_CERTIFICATE` | Certificate of Incorporation | Original registration document |
| Memorandum | `MEMORANDUM` | Other | Founding documentation |
| Document Type | UR Type Code | Internal Type | Notes |
| - | - | - | - |
| Statement Regarding Beneficial Owners | `STATEMENT_REGARDING_BENEFICIAL_OWNERS` | UBO Extract | Declared beneficial owners |
| Beneficial Owner Justification | `BO_JUSTIFICATION` | UBO Extract | Justification for UBO declarations |
| Document Type | UR Type Code | Notes |
| - | - | - |
| Shareholders Register | `SHAREHOLDERS_REGISTER` | List of company shareholders |
| Application for Share Acquisition | `APPLICATION_FOR_SHARE_ACQUISITION` | Share retrieve applications |
| Share Transfer Attestation | `ATTESTATION_SHARE_TRANSFER` | Share transfer certificates |
| Regulations on Equity | `REGULATIONS_ON_EQUITY` | Rules governing share capital |
| Bank Statement - Equity Retrieval | `BANK_STATEMENT_REGARDING_PAYMENT_OF_EQUITY` | Proof of equity retrieval |
| Appraisal Report | `APPRAISAL_REPORT` | Asset valuation reports |
| Board Statement Regarding Equity | `BOARD_STATEMENT_REGARDING_EQUITY` | Board declarations on equity |
| Document Type | UR Type Code | Notes |
| - | - | - |
| Company Protocol | `PROTOCOL_OF_COMPANY_OR_ORGANISATION` | Meeting minutes and decisions |
| List of Board Members | `LIST_OF_BOARD_MEMBERS` | Board composition |
| Consent of Supervisory Board | `CONSENT_OF_SUPERVISORY_BOARD` | Supervisory board approvals |
| Consent of Auditor | `CONSENT_OF_AUDITOR` | Auditor consent documents |
| Document Type | UR Type Code | Notes |
| - | - | - |
| Notarial Decision | `NOTARIAL_DECISION` | Notarized decisions and certificates |
| Power of Attorney | `POWER_OF_ATTORNEY` | Authorization documents |
| Confirmation of Legal Address | `CONFIRMATION_OF_LEGAL_ADDRESS` | Address proof |
| Legal Address Announcement | `ANNOUNCEMENT_REGARDING_LEGAL_ADDRESS` | Address change notices |
| Reorganisation Agreement | `REORGANISATION_AGREEMENT` | Merger/restructuring docs |
| Reorganisation Announcement | `ANNOUNCEMENT_REGARDING_REORGANISATION` | Reorganisation notices |
| Document Type | UR Type Code | Notes |
| - | - | - |
| Foreign Company Registration Documents | `DOCUMENTS_CONFIRMING_REGISTRATION_OF_FOREIGN_COMPANY` | For foreign parent companies |
| Foreign Organisation Registration Documents | `DOCUMENTS_CONFIRMING_REGISTRATION_OF_FOREIGN_ORGANISATION` | For foreign parent organisations |
| Commercial Pledge | `PLEDGOR` | Commercial pledge documents |
| Application | `APPLICATION` | Various applications |
| Submission | `SUBMISSION` | Regulatory submissions |
| Other Document | `OTHER` | Miscellaneous documents |
Insolvency proceeding documents are retrieved from a separate API endpoint and enriched via AI parsing to extract the proceeding type, status, and descriptive English names.
| Source | Format | Notes |
| - | - | - |
| UR Insolvency API | PDF | AI-enriched names and descriptions |
**Document Format Conversion:** Documents from the Enterprise Register may
arrive in TIF, HTML, EDOC, or ASICE format. EDOC and ASICE containers are
listed with `format` PDF and delivered as PDF. HTML and similar formats keep
their original `format` and are delivered as the original file plus a PDF
rendering. Other formats are delivered as-is.
**Annual Report Deduplication:** The UR API may return multiple versions of
the same annual report (including DUF structured data files). The system
automatically filters out DUF files and deduplicates by year+format, keeping
only the most recent version.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "LV", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "40103217882",
"countryCode": "LV",
"identifiers": { "registrationNumber": "40103217882" },
"legalName": "Piemērs Tehnoloģijas SIA",
"incorporationDate": "2010-05-20",
"status": { "localName": "Reģistrēts", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Sabiedrība ar ierobežotu atbildību (SIA)", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "ES2D" },
"capital": { "amount": 2800, "currency": "EUR" },
"activities": {
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false }],
"NACE_REV2": [{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "621", "description": "Computer programming activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Brīvības iela 100", "city": "Rīga", "postalCode": "LV-1001", "countryCode": "LV" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Valdes priekšsēdētājs", "englishTranslation": "Chairman of the Board", "standardized": "Chairman of the Board" }, "startDate": "2010-05-20", "individual": { "name": { "fullName": "Jānis BĒRZIŅŠ", "firstName": "Jānis", "lastName": "BĒRZIŅŠ" }, "birthDate": { "year": 1985, "month": 3, "day": 15 }, "nationality": "LV" } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Valdes loceklis", "englishTranslation": "Board Member", "standardized": "Board Member" }, "startDate": "2012-08-10", "individual": { "name": { "fullName": "Anna KALNIŅA", "firstName": "Anna", "lastName": "KALNIŅA" }, "birthDate": { "year": 1990, "month": 7, "day": 22 }, "nationality": "LV" } }
],
"otherKeyPersons": [
{ "entityId": "person_003", "type": "individual", "role": { "localName": "Padomes priekšsēdētājs", "englishTranslation": "Chairman of Supervisory Board", "standardized": "Supervisory Board Member" }, "startDate": "2010-05-20", "individual": { "name": { "fullName": "Pēteris OZOLS" }, "nationality": "LV" } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 60, "numberOfShares": 168, "individual": { "name": { "fullName": "Jānis BĒRZIŅŠ" } }, "nominalCapitalHeld": { "amount": 1680, "currency": "EUR" } },
{ "entityId": "company_001", "type": "company", "sharePercentage": 40, "numberOfShares": 112, "company": { "id": "40003000771", "countryCode": "LV", "legalName": "Nordic Holdings AS", "identifiers": { "registrationNumber": "40003000771" } }, "nominalCapitalHeld": { "amount": 1120, "currency": "EUR" } }
],
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "Jānis BĒRZIŅŠ", "firstName": "Jānis", "lastName": "BĒRZIŅŠ" },
"birthDate": { "year": 1985, "month": 3, "day": 15 },
"nationality": "LV",
"residenceAddress": { "countryCode": "LV" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"description": "As shareholder with 60% shares and 60% voting rights",
"details": [
{ "type": "shares", "percentageValue": 60 },
{ "type": "voting-rights", "percentageValue": 60 }
]
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "50003090101",
"countryCode": "LV",
"identifiers": { "registrationNumber": "50003090101" },
"legalName": "Vecais Uzņēmums SIA",
"incorporationDate": "2003-01-15",
"status": { "localName": "Izslēgts no reģistra", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "UNKNOWN", "closureDate": "2022-06-30" } },
"legalForm": { "localName": "Sabiedrība ar ierobežotu atbildību (SIA)", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company" },
"capital": { "amount": 2000, "currency": "EUR" },
"legalAddress": { "addressLine1": "Elizabetes iela 50", "city": "Rīga", "postalCode": "LV-1050", "countryCode": "LV" }
}
}
```
**Note:** Closed companies have `active: false`. The removal date is retained when available. A coarse removal or reorganization status has closure cause Unknown; an explicit liquidation record can establish Liquidation.
```json theme={null}
{
"company": {
"id": "40003555777",
"countryCode": "LV",
"identifiers": { "registrationNumber": "40003555777" },
"legalName": "Likvidējamais Uzņēmums SIA",
"incorporationDate": "2008-11-20",
"status": { "localName": "Likvidācijas procesā", "active": true, "statusDetails": { "status": "PENDING_DISSOLUTION" } },
"legalForm": { "localName": "Sabiedrība ar ierobežotu atbildību (SIA)", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company" },
"capital": { "amount": 5000, "currency": "EUR" },
"legalAddress": { "addressLine1": "Krišjāņa Barona iela 30", "city": "Rīga", "postalCode": "LV-1011", "countryCode": "LV" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Likvidators", "englishTranslation": "Liquidator", "standardized": "Liquidator" }, "startDate": "2024-03-15", "individual": { "name": { "fullName": "Ivars LIEPA" }, "nationality": "LV" } }
]
}
```
**Note:** A registered company in liquidation has status `Likvidācijas procesā` (Pending Dissolution) and remains active until removal. Liquidation does not itself establish insolvency. Registered liquidators are returned as legal representatives with their recorded signing conditions.
```json theme={null}
{
"company": {
"id": "40008123456",
"countryCode": "LV",
"identifiers": { "registrationNumber": "40008123456" },
"legalName": "Latvijas Sporta Biedrība",
"incorporationDate": "2015-09-01",
"status": { "localName": "Reģistrēts", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Biedrība", "englishTranslation": "Association", "standardized": "Nonprofit Organization" },
"activities": {
"NACE": [{ "code": "93.12", "description": "Activities of sports clubs", "isAIInferred": false }],
"NACE_REV2": [{ "code": "93.12", "description": "Activities of sports clubs", "isAIInferred": false }],
"ISIC": [{ "code": "9312", "description": "Activities of sports clubs", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Stadionu iela 5", "city": "Rīga", "postalCode": "LV-1013", "countryCode": "LV" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Valdes priekšsēdētājs", "englishTranslation": "Chairman of the Board", "standardized": "Chairman of the Board" }, "individual": { "name": { "fullName": "Mārtiņš LIEPIŅŠ" } } }
]
}
```
**Note:** Non-profit associations do not have shareholders or share capital. Legal representatives (board members) are available. Activity codes may use the non-profit activity area classification instead of NACE.
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": {
"fullName": "Jānis BĒRZIŅŠ",
"firstName": "Jānis",
"lastName": "BĒRZIŅŠ"
},
"birthDate": { "year": 1985, "month": 3, "day": 15 },
"nationality": "LV",
"residenceAddress": { "countryCode": "LV" },
"identifiers": { "personalCode": "150385-12345" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"description": "As shareholder with 75% shares and 75% voting rights",
"details": [
{ "type": "shares", "percentageValue": 75 },
{ "type": "voting-rights", "percentageValue": 75 }
]
}
},
{
"entityId": "person_002",
"name": {
"fullName": "Anna KALNIŅA",
"firstName": "Anna",
"lastName": "KALNIŅA"
},
"birthDate": { "year": 1990, "month": 7, "day": 22 },
"nationality": "LV",
"residenceAddress": { "countryCode": "LV" },
"control": {
"types": ["ownership-of-shares"],
"description": "As member with 25% shares",
"details": [{ "type": "shares", "percentageValue": 25 }]
}
}
]
}
```
**Note:** UBOs are available directly from the Enterprise Register, no separate retrieve required. The `natureOfControl` field uses known enum values: `AS_MEMBER`, `AS_FOUNDATION_FOUNDER`, `AS_OWNER`, `ON_GROUNDS_OF_PROPERTY_RIGHT`, `AS_SHAREHOLDER`. Includes share and voting rights percentages when declared.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
**All entity types:**
| API Category | Document | Notes |
| - | - | - |
| `certifiedTradeRegisterExtract` | Certified Trade Register Extract (e-sealed PDF) | Always available for registered companies |
| `financialStatements[]` | Annual Reports | When filed, deduplicated by year |
| `articlesOfAssociation[]` | Articles of Association / Amendments | When filed |
| Various (see Documents section) | Registration cert., shareholder register, protocols, etc. | Based on what company has filed |
# Liechtenstein
Source: https://docs.topograph.co/essentials/liechtenstein
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Liechtenstein reference is on the [Liechtenstein country page](https://www.topograph.co/countries/li).
## Start here
This guide contains public integration notes for Liechtenstein. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
All company data is sourced from the official **Liechtenstein Handelsregister** (Trade Register), operated by the Amt fuer Justiz (Office of Justice). Verification and prefill expose different levels of detail depending on the requested datapoint.
### Prefill Profile (lightweight)
* **Handelsregister Company Details Page** ([handelsregister.li](https://www.handelsregister.li)). The public company details page of the official trade register. Provides basic company information: legal name, legal form, status, address (street and postal code when the register publishes a service address, otherwise the registered city), and activity codes inferred from the company purpose (Zweck). No legal representatives or shareholders.
### Company Profile (comprehensive)
* **Handelsregister Trade Register Extract (Handelsregisterauszug).** The official trade register extract is the primary source for comprehensive verification data: legal name, legal form, status, capital, registered address, legal representatives, shareholders, and company purpose.
Comprehensive verification can take longer than lightweight prefill because the official extract must be retrieved and converted into structured data. Use webhooks or polling for this country.
## Company Identifiers
Prefill profiles for Aktiengesellschaft companies can return `company.identifiers.euid`, for example `LIFL.FL-0001.548.501-4`, when the company identity is confirmed. EUID is not currently provided in verification profiles or for other legal forms. It is not a search key.
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | Handelsregister | `FL-XXXX.XXX.XXX-X` | `FL-0002.658.754-1` | FL-Nummer with checksum digit |
**FL-Nummer Format Breakdown:** `FL-0002.658.754-1` = `FL-` (prefix) + `0002` (block 1) + `.` + `658` (block 2) + `.` + `754` (block 3) + `-` + `1` (checksum digit). The regex pattern is: `^FL-\d{4}\.\d{3}\.\d{3}-\d$`
In the records we have seen, block 1 is `0001` (for example `FL-0001.548.501-4`) or `0002`. The checksum digit follows the modulo 10 recursive scheme in every FL-Nummer we have seen.
**Always include the full FL-Nummer format** including the `FL-` prefix and the checksum digit after the hyphen. The system validates this format strictly and rejects identifiers that do not match.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `flNumber` | `FL-XXXX.XXX.XXX-X` | `FL-0002.658.754-1` | All companies (FL-Nummer, primary identifier) |
| `euid` | `LIFL.` + FL-Nummer | `LIFL.FL-0001.548.501-4` | Prefill profiles of Aktiengesellschaft companies with a confirmed register identity |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the FL-Nummer (`flNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By FL-Nummer | `FL-XXXX.XXX.XXX-X` | `FL-0002.658.754-1` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (2-100 chars) | `"Fürstentum Automobile"` | Fuzzy | Multiple results |
**Search includes deleted companies.** Name searches include deleted (geloescht) companies in results by default.
**Search by FL-Nummer** provides direct lookup and returns the exact match first (`matchReason.matchType = "id"`); other results may follow. **Search by name** can be slower and may return multiple results.
### Active companies only
The register itself excludes companies that are no longer active when you search with [`activeOnly=true`](/essentials/search#active-companies-only). Name searches exclude deleted companies at the register itself. A lookup by FL number only ever returns companies still on the register.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Official extract required for full profile** | Comprehensive verification data comes from the trade register extract. |
| **Processing time is longer than most countries** | Company profile retrieval can take several minutes. Use asynchronous handling. |
| **All activity codes are AI-inferred** | The Handelsregister provides only a free-text purpose (Zweck). NACE and ISIC codes are always AI-inferred. `isAIInferred` is always `true`. |
| **Legal representatives are AI-parsed** | Extracted from the trade register extract PDF via AI. Only available in full company retrieval, not in prefill mode requests for `company`. |
| **Shareholders depend on legal form** | Shareholders are extracted for forms with share capital (GmbH Gesellschafter, AG Aktionäre) when the register lists them. Einzelfirma and Verein return a not-applicable response for `shareholders`. Anstalt, Stiftung, and Trust entities typically have no shareholder section. |
| **Currency is CHF** | Liechtenstein uses the Swiss Franc (CHF). Capital amounts are denominated in CHF. |
| **German-only documents** | All official trade register documents are in German. Company names and legal form names are in German. |
| **No UBO data** | Liechtenstein has a UBO register, but it is not publicly accessible. |
| **Deleted companies have limited documents** | Available documents can be empty for deleted (Geloescht) companies. |
| **Long-running retrieval is possible** | Verification requests can remain in progress while the official extract is retrieved and processed. |
## Company Status
Company status is determined **differently** depending on the data point requested.
### Prefill Profile (from company details page)
Status is derived from keyword matching on the Handelsregister company details page:
| Local Status | English | Standardized Status | Detection Logic |
| - | - | - | - |
| Aktiv | Active | Active | Register indicates active status |
| Gelöscht | Deleted | Closed | Register indicates company has been deleted |
### Company Profile (AI-parsed from trade register extract)
Status is extracted from the trade register extract PDF using AI parsing. The AI analyzes the document text and produces a standardized status.
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| Active | Active | Active | AI-parsed from document text |
| Aktiv | Active | Active | German variant from document |
| Geloescht | Deleted | Closed | Company has been deleted from register |
| In Liquidation | In Liquidation | Closed | Company is being liquidated |
For the prefill profile, status classification is deterministic (keyword matching). For the company profile, status is AI-parsed from the trade register extract document, which may use either German or English terminology.
## Legal Forms
Liechtenstein has a distinctive set of legal forms, including entity types unique to the principality (Anstalt, Trust). Legal form names come from the Handelsregister and are enriched with AI for standardized names, and ISO 20275 codes are matched against the GLEIF list of Liechtenstein legal forms.
### Key Business Forms
| German Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Aktiengesellschaft | AG | Stock Corporation | Corporation | 7RRP |
| Gesellschaft mit beschraenkter Haftung | GmbH | Limited Liability Company | Limited Liability Company | Y8LH |
| Kommanditgesellschaft | KG | Limited Partnership | Partnership | ANSR |
| Kollektivgesellschaft | -- | General Partnership | Partnership | NDID |
### Unique Liechtenstein Entity Types
| German Name | English Translation | Standardized | ISO 20275 | Notes |
| - | - | - | - | - |
| Anstalt | Establishment | Other | TMU1 | Unique to Liechtenstein; hybrid between company and foundation |
| Stiftung | Foundation | Nonprofit Organization or Other | BSZ8 | Private or public purpose foundation |
| Trust | Trust | Trust | -- | Anglo-Saxon trust structure recognized under Liechtenstein law |
| Treuhänderschaft | Trusteeship | Trust | 53QF | Alternative German term for trust |
### Sole Entrepreneurs & Cooperatives
| German Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Einzelfirma | Sole Proprietorship | Sole Proprietorship | EV7F |
| Einzelunternehmen | Sole Proprietorship | Sole Proprietorship | -- |
| Genossenschaft | Cooperative | Cooperative | IF49 |
### Non-Profits
| German Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Verein | Association | Nonprofit Organization | 32HC |
Legal form standardization and ISO 20275 assignment are AI-enriched. The local German legal form name from the Handelsregister is always preserved verbatim.
## Legal Representatives
Legal representatives are extracted from the **trade register extract** (Handelsregisterauszug) PDF in verification mode. Registered signing rights and statutory appointment capacity control classification; the office title alone does not establish sole or unrestricted representation. Non-signing offices and audit appointments are returned under `otherKeyPersons` from the same extract. Neither person list is available in prefill mode.
### Extraction Details
| Aspect | Details |
| - | - |
| **Source** | Trade register extract (Handelsregisterauszug) PDF |
| **Method** | AI parsing of document text |
| **Availability** | Full company retrieval only (not prefill mode `company`) |
| **AI-inferred** | Yes -- extraction and role classification from PDF is AI-based |
| **Role enrichment** | Roles are standardized with AI, using the company's legal form as context |
### Complete Role Nomenclature
| German Role | English Translation | Typical Legal Forms |
| - | - | - |
| Geschaeftsfuehrer | Managing Director | GmbH |
| Direktor | Director | AG, Anstalt |
| Praesident | President | AG, Stiftung |
| Vizepraesident | Vice President | AG |
| German Role | English Translation | Typical Legal Forms |
| - | - | - |
| Verwaltungsrat | Board Member | AG, Anstalt |
| Verwaltungsratspraesident | Chairman of the Board | AG |
| Stiftungsrat | Foundation Board Member | Stiftung |
| Stiftungsratspraesident | Chairman of the Foundation Board | Stiftung |
| German Role | English Translation | Typical Legal Forms |
| - | - | - |
| Zeichnungsberechtigter | Authorized Signatory | All |
| Prokurist | Authorized Officer (Prokura) | All |
| Bevollmaechtigter | Authorized Representative | All |
| German Role | English Translation | Typical Legal Forms |
| - | - | - |
| Liquidator | Liquidator | All (during liquidation) |
| Treuhänder | Trustee | Trust |
Role standardization is AI-determined and depends on the company's legal form context. Signing authority details (Einzelzeichnung, Kollektivzeichnung zu zweien) are captured when available in the trade register extract.
## Other Key Persons
Non-signing board or management offices, and Revisor / Revisionsstelle audit appointments, are returned in verification mode when the extract records them. Exact filed titles, individual or corporate identities, and appointment dates are preserved where supplied. A board chair without representation capacity uses Chairman of the Board in `otherKeyPersons`; a management office without such capacity uses C-Level Executive. Trustee appointments remain source-qualified rather than acquiring powers from their title.
The extract's signing column distinguishes Einzelunterschrift, Kollektivunterschrift zu zweien or dreien, and a bare collective signing right. The [Office of Justice](https://www.llv.li/serviceportal2/amtsstellen/amt-fuer-justiz/newsletter/2025/pdf-llv-aju-newsletter_2025_05.pdf) explains that a bare collective right requires all other authorized signers; it must not be assumed to require only two. Source wording and restrictions are preserved when available.
## Shareholders
Shareholders are extracted from the **trade register extract** (Handelsregisterauszug) PDF using AI parsing. This data is **only available in verification mode**.
### Extraction Logic
| Aspect | Details |
| - | - |
| **Source** | Trade register extract (Handelsregisterauszug) PDF |
| **Method** | AI parsing of document text |
| **AI-inferred** | Yes -- extraction from PDF is AI-based |
### Availability by Legal Form
| Legal Form | Shareholders Available | Notes |
| - | - | - |
| **GmbH** | Yes | Gesellschafter (partners) extracted with capital contributions (Stammkapital) when the register lists them |
| **AG** | Yes, when listed | Aktionäre extracted when the register lists them |
| **Anstalt** | No | Typically no shareholder section in the register |
| **Stiftung** | No | Foundation structure does not have shareholders |
| **Trust** | No | Typically no shareholder section in the register |
| **KG** | Partial | Komplementaer (general partner) is listed; Kommanditisten may be listed |
| **Einzelfirma** | Not applicable | `shareholders` returns a not-applicable response; the owner is returned under `legalRepresentatives` |
| **Verein** | Not applicable | `shareholders` returns a not-applicable response; the board is returned under `legalRepresentatives` |
| **Genossenschaft** | No | Cooperative members are not listed individually |
### Ownership Fields
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | Calculated from capital contributions (AI-parsed) |
| `numberOfShares` | Number of shares held | Extracted from document when available |
| `type` | Individual or Company | Determined from document context |
| `nominalCapitalHeld` | Capital contribution amount and currency | Extracted from Stammkapital/Aktienkapital data |
### Key Terminology
| German Term | English | Description |
| - | - | - |
| Gesellschafter | Shareholder/Partner | GmbH shareholders |
| Aktionaer | Shareholder | AG shareholders |
| Stammkapital | Share capital | GmbH share capital (in CHF) |
| Aktienkapital | Share capital | AG share capital (in CHF) |
| Anteil | Share/Stake | Ownership share |
| Stammeinlage | Capital contribution | Individual partner's contribution to GmbH |
Shareholder data availability depends on the legal form. Shareholder records exist only for legal forms with share capital (GmbH Gesellschafter, AG Aktionäre) and are returned when the register lists them. Einzelfirma and Verein have no share capital, so `shareholders` returns an explicit not-applicable response instead of an empty array. Anstalt, Stiftung, and Trust entities typically have no shareholder section in the register.
## Activity Code Mapping
Liechtenstein does not use a national activity code classification in the Handelsregister. Activity codes are **always AI-inferred** from the company's `Zweck` (purpose) field, which is a free-text description extracted from the trade register extract or the company details page.
```
Zweck / Company Purpose (free text) --> ISIC Rev. 5 (AI-inferred) --> NACE Rev. 2.1 (derived from ISIC)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **ISIC Rev. 5** (`ISIC`) | Inferred from company purpose via AI | `4781` | Yes (always) |
| **NACE Rev. 2.1** (`NACE`) | Derived from the ISIC code | `47.81` | Yes (always) |
Both NACE and ISIC codes are **always AI-inferred** for Liechtenstein companies because the trade register provides only a free-text purpose description (Zweck), not structured activity codes. The `isAIInferred` flag is always `true`. For the prefill profile, activity codes are inferred from the company purpose, and the single code inferred from the Zweck is flagged with `isMainActivity: true`. Because it is always AI-inferred, it stays distinguishable from a main activity a register itself declares, and an absent flag means the source did not designate one.
## Data Availability Matrix
| Data Type | Prefill Profile | Company Profile | Notes |
| - | - | - | - |
| Company Profile | Yes (fast) | Yes (async, \~2-5 min) | Prefill: basic data from details page. Company: AI-parsed from trade register extract |
| Legal Representatives | No | Yes (AI-parsed) | Registered representative capacity from the trade register extract |
| Other Key Persons | No | Yes (AI-parsed) | Non-signing office and audit appointments from the same extract |
| Other Key Persons | No | No | Not available for Liechtenstein |
| Shareholders | No | Conditional | GmbH/AG: when listed in the register; Einzelfirma/Verein: not applicable; Anstalt/Stiftung/Trust: typically none |
| Ultimate Beneficial Owners | No | No | Not publicly accessible in Liechtenstein |
| Establishments | No | No | Not available from Handelsregister |
| Activity Codes | Yes (AI-inferred) | Yes (AI-inferred) | Always AI-inferred from Zweck (company purpose) |
| Documents | -- | Yes | Trade register extract |
**Legend:** Yes = Available | No = Not Available | Conditional = Depends on legal form | Async = Asynchronous processing
## Documents by Company Type
### All companies (active only)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract (uncertified)** | `tradeRegisterExtract` | PDF | Yes (active companies only) | Official uncertified Handelsregisterauszug with current information. |
**Documents are only available for active companies.** The available documents request validates that the company exists and is not deleted (Geloescht) before listing any documents. Deleted companies return an empty document list.
## Data Source Priority & Routing
Liechtenstein uses a **single data source** (the Handelsregister) with two access methods depending on the requested data point:
| Data Point | Source | Method | Notes |
| - | - | - | - |
| **Search** | Handelsregister | Direct lookup (FL-Nummer) / Automated retrieval (name) | -- |
| **Prefill Profile** | Handelsregister company details page | Automated retrieval from register | Lightweight, no document retrieval |
| **Company Profile** | Trade register extract (Handelsregisterauszug) | Official document retrieval + AI parsing | Company, legal representatives, other key persons, and shareholders come from one extract |
| **Available Documents** | Handelsregister | Automated retrieval (validates company exists & is active) | -- |
| **Document (Register Extract)** | Handelsregister | Official document retrieval | Uncertified PDF |
**One extract serves the whole verification profile.** In verification mode, `company`, `legalRepresentatives`, and `shareholders` are all built from a single trade register extract, and ordering the extract document too does not add a second charge. See the [pricing page](https://topograph.co/pricing/li) for current prices.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "LI", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "FL-0002.658.754-1",
"countryCode": "LI",
"identifiers": {
"flNumber": "FL-0002.658.754-1"
},
"legalName": "Fuerstentum Automobile GmbH",
"registrationDate": "2021-05-21",
"activityDescription": "Zweck der Gesellschaft ist der Kauf und Verkauf sowie die Vermittlung von Neuwagen und Gebrauchtwagen aller Marken.",
"status": {
"localName": "Active",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Gesellschaft mit beschraenkter Haftung",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "Y8LH"
},
"capital": {
"amount": 50000,
"currency": "CHF",
"formatted": "CHF 50,000"
},
"activities": {
"NACE": [
{
"code": "47.81",
"description": "Retail sale of motor vehicles",
"isAIInferred": true
}
],
"ISIC": [
{
"code": "4781",
"description": "Retail sale of motor vehicles",
"isAIInferred": true
}
]
},
"legalAddress": {
"addressLine1": "Wirtschaftspark 23",
"city": "Eschen",
"postalCode": "9492",
"countryCode": "LI"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"startDate": "2021-05-21",
"role": {
"localName": "Geschaeftsfuehrer",
"englishTranslation": "Managing Director",
"standardized": "Managing Director"
},
"individual": {
"name": {
"fullName": "Hans Mueller",
"firstName": "Hans",
"lastName": "Mueller"
},
"residenceAddress": {
"city": "Bad Ragaz",
"postalCode": "7310",
"countryCode": "CH"
}
}
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 100,
"numberOfShares": 1,
"individual": {
"nationality": "CH",
"name": {
"fullName": "Hans Mueller",
"firstName": "Hans",
"lastName": "Mueller"
},
"residenceAddress": {
"city": "Bad Ragaz",
"postalCode": "7310",
"countryCode": "CH"
}
},
"nominalCapitalHeld": {
"amount": 50000,
"currency": "CHF",
"formatted": "CHF 50,000.00"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "FL-0001.122.356-7",
"countryCode": "LI",
"identifiers": {
"flNumber": "FL-0001.122.356-7"
},
"legalName": "Alpenbank Aktiengesellschaft",
"registrationDate": "2005-08-12",
"activityDescription": "Die Gesellschaft bezweckt den Betrieb einer Bank gemaess dem Bankengesetz.",
"status": {
"localName": "Active",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Aktiengesellschaft",
"englishTranslation": "Stock Corporation",
"standardized": "Corporation",
"iso20275Code": "7RRP"
},
"capital": {
"amount": 20000000,
"currency": "CHF",
"formatted": "CHF 20,000,000"
},
"activities": {
"NACE": [
{
"code": "64.19",
"description": "Other monetary intermediation",
"isAIInferred": true
}
],
"ISIC": [
{
"code": "6419",
"description": "Other monetary intermediation",
"isAIInferred": true
}
]
},
"legalAddress": {
"addressLine1": "Staedtle 28",
"city": "Vaduz",
"postalCode": "9490",
"countryCode": "LI"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Verwaltungsratspraesident",
"englishTranslation": "Chairman of the Board",
"standardized": "Chairman of the Board"
},
"individual": {
"name": {
"fullName": "Peter Frick",
"firstName": "Peter",
"lastName": "Frick"
},
"residenceAddress": {
"city": "Balzers",
"postalCode": "9496",
"countryCode": "LI"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Geschaeftsfuehrer",
"englishTranslation": "Managing Director",
"standardized": "Managing Director"
},
"individual": {
"name": {
"fullName": "Maria Wanger",
"firstName": "Maria",
"lastName": "Wanger"
},
"residenceAddress": {
"city": "Vaduz",
"postalCode": "9490",
"countryCode": "LI"
}
}
}
]
}
```
**Note:** AG (Aktiengesellschaft) shareholders (Aktionäre) are returned only when the trade register extract lists them. This example requests only `company` and `legalRepresentatives`.
```json theme={null}
{
"company": {
"id": "FL-0003.456.789-0",
"countryCode": "LI",
"identifiers": {
"flNumber": "FL-0003.456.789-0"
},
"legalName": "Alte Handelsgesellschaft GmbH",
"status": {
"localName": "Gelöscht",
"active": false
},
"legalForm": {
"localName": "Gesellschaft mit beschraenkter Haftung",
"standardized": "Limited Liability Company",
"iso20275Code": "Y8LH"
},
"legalAddress": {
"city": "Schaan",
"countryCode": "LI"
}
}
}
```
**Note:** Deleted companies have `active: false` and status `Gelöscht`. Full company profile (with legal representatives and shareholders) is **not available** for deleted companies because the trade register extract cannot be retrieved.
```json theme={null}
{
"company": {
"id": "FL-0001.987.654-3",
"countryCode": "LI",
"identifiers": {
"flNumber": "FL-0001.987.654-3"
},
"legalName": "Vermoegensverwaltung Anstalt",
"registrationDate": "2010-03-15",
"activityDescription": "Die Anstalt bezweckt die Verwaltung eigenen Vermoegens.",
"status": {
"localName": "Active",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Anstalt",
"englishTranslation": "Establishment",
"standardized": "Other"
},
"capital": {
"amount": 30000,
"currency": "CHF"
},
"activities": {
"NACE": [
{
"code": "64.99",
"description": "Other financial service activities, except insurance and pension funding n.e.c.",
"isAIInferred": true
}
],
"ISIC": [
{
"code": "6499",
"description": "Other financial service activities n.e.c., except insurance and pension funding activities",
"isAIInferred": true
}
]
},
"legalAddress": {
"addressLine1": "Landstrasse 11",
"city": "Vaduz",
"postalCode": "9490",
"countryCode": "LI"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Verwaltungsrat",
"englishTranslation": "Board Member",
"standardized": "Board Member"
},
"individual": {
"name": {
"fullName": "Thomas Buechel",
"firstName": "Thomas",
"lastName": "Buechel"
},
"residenceAddress": {
"city": "Triesen",
"postalCode": "9495",
"countryCode": "LI"
}
}
}
]
}
```
**Note:** Anstalt (Establishment) is a legal form unique to Liechtenstein. It does not have shareholders in the traditional sense -- the founder or beneficiary information is not publicly disclosed.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Official Handelsregisterauszug PDF | Active companies only |
**Note:** Only the uncertified register extract is currently available. Certified register extracts (`certifiedTradeRegisterExtract`) are defined as a document type but not yet implemented.
# Lithuania
Source: https://docs.topograph.co/essentials/lithuania
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Lithuania reference is on the [Lithuania country page](https://www.topograph.co/countries/lt).
## Start here
This guide contains public integration notes for Lithuania. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
Lithuania is in beta. Check the live pricing page or contact support before relying on it in production. `LT` is accepted by the API but is not yet listed in the public `countryCode` enum of the OpenAPI spec.
**Lithuania is prefill-only.** Every request must pass `"mode": "prefill"`. The whole country is served from a daily bulk extract of the register, so there is no authoritative live lane for `verification` — which is what `/v2/company` uses when you omit `mode`. A request without it comes back with the datapoint failed and the error code `authoritative_source_unavailable`. See [Modes](/essentials/modes).
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Supported Entity Types](#supported-entity-types)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Lithuania has one data source: the **Register of Legal Entities (Juridinių asmenų registras, JAR)** open data, published by Registrų centras at [registrucentras.lt](https://www.registrucentras.lt/jar/).
Three extracts feed the integration, all regenerated daily:
* **Registered entities**: every entity currently on the register, with its legal form, legal status and status date.
* **Deregistered entities**: entities removed from the register, with the removal date.
* **Share capital**: registered share capital for the legal forms that must declare one.
Data reflects the latest daily extract, so a change filed with the register can take up to 24 hours to appear. There is no live query to the register.
## Company Identifiers
### Query Identifiers
| Identifier | Format | Example | Notes |
| - | - | - | - |
| **Juridinio asmens kodas** | 9 digits | `123033512` | The legal-entity code. Assigned by Registrų centras at registration and used for every entity type. |
The legal-entity code is **not** the VAT number. The Lithuanian PVM code is issued separately by the tax authority and cannot be derived from it. MAXIMA LT, for instance, is entity `123033512` but VAT `LT230335113`. Pass the 9-digit legal-entity code; VAT numbers are not accepted, and are not published in this register's open data.
### Identifiers in API Response
| Identifier | Format | Example |
| - | - | - |
| `jaKodas` | 9 digits | `123033512` |
| `euid` | `LTJAR.` + 9 digits | `LTJAR.123033512` |
EUID is returned for UAB and AB companies with a confirmed legal-entity code and legal form.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the legal-entity code (`jaKodas`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Example | Match type | Notes |
| - | - | - | - |
| By legal-entity code (exact) | `123033512` | `id` | Exact match only. |
| By name (partial) | `MAXIMA LT` | `name` | Full-text search. |
Search is free. Only company profile retrieval is charged.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Companies | Yes | UAB, AB, MB, ŽŪB, cooperatives, credit unions, and every other registered form |
| Sole traders and partnerships | Yes | IĮ, TŪB, KŪB, but the register anonymises their names (see below) |
| Non-profits | Yes | Associations, charity and sponsorship funds, public institutions, religious communities, trade unions, political parties |
| Public bodies | Yes | State and municipal enterprises, budget institutions |
| Branches and representative offices | Yes | Including branches of foreign legal entities |
| Deregistered entities | Yes | Reported as closed, with the removal date |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Use prefill mode** | Lithuania has a single non-authoritative mode. Pass `"mode": "prefill"` on `/v2/company`; the default verification path has no source to resolve. |
| **No live register access** | All data comes from daily bulk extracts. Real-time queries are not available. |
| **Anonymised names for IĮ / TŪB / KŪB** | The register redacts the names of individual enterprises and partnerships in its open data, because those names contain the owner's or partners' personal names. Around 13,500 entities are affected. They return the bare legal-form label as their `legalName` (for example `Individuali įmonė`), and are findable by legal-entity code but not by name. |
| **No officers, shareholders or beneficial owners** | The register's open data publishes only *counts*: how many governing bodies an entity has and how many participants, split by resident/foreign and natural/legal person. No names or percentages are published anywhere in the open data. |
| **Status "no legal proceedings" means healthy** | `Teisinis statusas neįregistruotas` is the normal state of a sound company (98% of the register). It means no restructuring, insolvency or dissolution proceeding is registered, and maps to `ACTIVE`. |
| **Pre-euro share capital** | Capital last declared before Lithuania adopted the euro in 2015 is still recorded in litas. It is returned with currency `LTL` and is not converted. |
| **Municipality-only addresses** | A small number of entities register an address that names only a municipality (for example `Vilniaus m. sav.`). These return `region` and no `city`. |
## Mappings
### Company Status
Lithuania publishes an official legal-status classifier. An entity carries at most one status at a time.
| Local status | English | Standardized status | Active |
| - | - | - | - |
| Teisinis statusas neįregistruotas | No legal proceedings | `ACTIVE` | Yes |
| Reorganizuojamas | Under reorganization | `ACTIVE` | Yes |
| Pertvarkomas | Under reformation | `ACTIVE` | Yes |
| Restruktūrizuojamas | Under restructuring | `UNDER_INSOLVENCY_PROCEEDING` | Yes |
| Bankrutuojantis | Going bankrupt | `UNDER_INSOLVENCY_PROCEEDING` | Yes |
| Bankrutavęs | Bankrupt | `UNDER_INSOLVENCY_PROCEEDING` | No |
| Likviduojamas | Under liquidation | `PENDING_DISSOLUTION` | Yes |
| Inicijuojamas likvidavimas | Liquidation being initiated | `PENDING_DISSOLUTION` | Yes |
| Likviduojamas dėl bankroto | Liquidation due to bankruptcy | `UNDER_INSOLVENCY_PROCEEDING` | Yes |
| Nepersiregistravęs | Not reregistered | `INACTIVE_NOT_CLOSED` | No |
| Išregistruotas | Removed from the register | `CLOSED` | No |
| Likviduotas | Liquidated | `CLOSED` | No |
An entity under liquidation is still on the register and still reported as active until the proceeding completes. See the pricing page for the complete list of 30 status labels.
### Legal Forms
Registrų centras publishes an official legal-form classifier of 168 codes, each with its own English translation. The most common:
| Local name | English | Standardized | Legal basis |
| - | - | - | - |
| Uždaroji akcinė bendrovė (UAB) | Private Limited Liability Company | Limited Liability Company | [Law on Companies art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.106080/asr) |
| Mažoji bendrija (MB) | Small Partnership | Limited Liability Company | [Law on Small Partnerships art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.429530/asr) |
| Akcinė bendrovė (AB) | Public Limited Liability Company | Corporation | [Law on Companies art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.106080/asr) |
| Asociacija | Association | Nonprofit Organization | [Law on Associations art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.226938/asr) |
| Individuali įmonė (IĮ) | Individual Enterprise | Sole Proprietorship | [Law on Individual Enterprises art. 2–3](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.222038/asr) |
| Viešoji įstaiga (VšĮ) | Public Institution | Nonprofit Organization | [Law on Public Establishments art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.29578/asr) |
| Bendrija | Community | Nonprofit Organization | - |
| Biudžetinė įstaiga | Budget Institution | Government-Owned Entity | [Law on Budgetary Institutions art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.23064/asr) |
| Labdaros ir paramos fondas | Charity and Sponsorship Fund | Nonprofit Organization | [Law on Charity and Sponsorship Funds art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.26243/asr) |
| Tikroji ūkinė bendrija (TŪB) | General Partnership | Partnership | [Law on Partnerships art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.222036/asr) |
| Komanditinė ūkinė bendrija (KŪB) | Limited Partnership | Partnership | [Law on Partnerships art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.222036/asr) |
| Žemės ūkio bendrovė (ŽŪB) | Agricultural Company | Limited Liability Company | [Law on Agricultural Companies art. 3](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.1213/asr) |
| Kooperatinė bendrovė | Cooperative Society | Cooperative | [Law on Cooperative Companies art. 1–2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.5474/asr) |
| Kredito unija | Credit Union | Cooperative | [Law on Credit Unions art. 3(2)](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.15228/asr) |
| Valstybės įmonė (VĮ) | State Enterprise | Government-Owned Entity | [Law on State and Municipal Enterprises art. 2](https://e-seimas.lrs.lt/portal/legalAct/lt/TAD/TAIS.15154/asr) |
| Užsienio juridinio asmens filialas | Branch of a Foreign Enterprise | Branch or Representative Office | - |
Branches and representative offices carry their own codes and are standardized as `Branch or Representative Office`, separately from the entity type they belong to. See the pricing page for the complete list.
The **Legal basis** column links the act that creates or defines each form, at its current consolidated text. The pricing-page catalogue carries the same links for every verified base form in a `legalBasisBeta` list, one entry per act. This field is in beta: its name and shape may change before it becomes `legalBasis`. European forms (SE, SCE, EEIG, EGTC, European political parties) link to their EU regulation. Branches, representative offices and historical forms with no current act have no link.
Mažoji bendrija is translated by the register as "Small Partnership", but its members have limited liability and it is standardized as a Limited Liability Company rather than a Partnership.
Agricultural Company uses the same broad limited-liability category while retaining its distinct native form and ISO 20275 reference. Individual Enterprise has separate legal personality and unlimited owner liability; its Sole Proprietorship category is a broad ownership grouping.
## Data Availability
| Data type | Available | Notes |
| - | - | - |
| Company profile | Yes | Name, legal form, legal status, registration date, registered office address |
| Share capital | Partial | Returned for the legal forms that must declare one |
| Deregistered entities | Yes | Reported as closed, with the removal date |
| Legal representatives | No | Not published in the register's open data |
| Shareholders | No | Not published in the register's open data |
| Ultimate beneficial owners | No | Not published as open data |
| Activity codes | No | Not recorded against an entity in this register |
| Documents | No | Open-data-only integration |
| Financial statements | No | Not part of this integration |
## Example API Responses
Query: `POST /v2/company` with `{ "id": "123033512", "countryCode": "LT", "dataPoints": ["company"], "mode": "prefill" }`
```json theme={null}
{
"company": {
"id": "123033512",
"countryCode": "LT",
"identifiers": { "jaKodas": "123033512" },
"legalName": "MAXIMA LT, UAB",
"registrationDate": "1995-03-17",
"status": {
"localName": "Teisinis statusas neįregistruotas",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Uždaroji akcinė bendrovė",
"englishTranslation": "Private Limited Liability Company",
"standardized": "Limited Liability Company"
},
"capital": {
"amount": 107590000,
"currency": "EUR",
"formatted": "€107,590,000"
},
"legalAddress": {
"addressLine1": "Vilnius, Naugarduko g. 84, LT-03160",
"city": "Vilnius",
"postalCode": "LT-03160",
"countryCode": "LT"
}
}
}
```
Query: `POST /v2/company` with `{ "id": "110000334", "countryCode": "LT", "dataPoints": ["company"], "mode": "prefill" }`
```json theme={null}
{
"company": {
"id": "110000334",
"countryCode": "LT",
"identifiers": { "jaKodas": "110000334" },
"legalName": "Bendra Lietuvos - Vokietijos - Lenkijos įmonė uždaroji akcinė bendrovė \"RUDOMEX\"",
"registrationDate": "1991-03-14",
"status": {
"localName": "Išregistruotas",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "UNKNOWN",
"closureDate": "2003-11-12"
}
},
"legalForm": {
"localName": "Uždaroji akcinė bendrovė",
"englishTranslation": "Private Limited Liability Company",
"standardized": "Limited Liability Company"
}
}
}
```
The register redacts the registered name of individual enterprises and partnerships, publishing the bare legal-form label instead. Topograph relays exactly what the register publishes and never substitutes a name.
```json theme={null}
{
"company": {
"id": "111485050",
"countryCode": "LT",
"identifiers": { "jaKodas": "111485050" },
"legalName": "Individuali įmonė",
"legalForm": {
"localName": "Individuali įmonė",
"englishTranslation": "Individual Enterprise",
"standardized": "Sole Proprietorship"
},
"legalAddress": {
"addressLine1": "Kaunas, Aukštaičių g. 90, LT-50283",
"city": "Kaunas",
"postalCode": "LT-50283",
"countryCode": "LT"
}
}
}
```
# Luxembourg
Source: https://docs.topograph.co/essentials/luxembourg
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Luxembourg reference is on the [Luxembourg country page](https://www.topograph.co/countries/lu).
## Start here
This guide contains public integration notes for Luxembourg. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Luxembourg uses a single official register, the RCS, as its data source. What you get depends on the mode:
* **Prefill mode** (`company` only): read live from the register's public data. Returns the RCS number, company name, legal form, registration date, NACE code and registered seat. Status is derived from enforcement measures published by the register.
* **Verification mode** (`company`, `legalRepresentatives`, `otherKeyPersons`, `shareholders`): extracted with AI parsing from the certified trade register extract ("Extrait du RCS"). All four datapoints come from the same extract and are billed as one block (see [pricing](https://topograph.co/pricing/lu)).
### All company types
* **RCS (Registre de Commerce et des Societes)** -- Operated by Luxembourg Business Registers (LBR), an economic interest grouping comprising the State, the Chamber of Commerce, and the Chamber of Skilled Trades, under the authority of the Ministry of Justice since 2003. The RCS is the central commercial register for the Grand Duchy of Luxembourg, containing registration data for virtually all legal entities: commercial companies, partnerships, sole traders, civil companies, non-profit associations (ASBLs), foundations, investment funds, and branches of foreign entities. In verification mode, company name, legal form, status, registration date, registered address, share capital, activities, legal representatives, and shareholders are AI-parsed from the certified extract.
* **VIES (VAT Information Exchange System)** -- The EU-wide VAT validation service is used during **VAT number searches** to resolve a Luxembourg VAT number to a company name, which is then used to search the RCS. In verification mode, VIES also validates the VAT number found on the extract, and the result is returned as `taxId` with its verification status.
**Document-based data extraction:** Officers and shareholders are only published on the certified extract ("Extrait du RCS"), so verification mode extracts them from that document using AI parsing. Data quality depends on the document content and parsing accuracy. Prefill mode does not use the extract and returns only the base fields the register publishes.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All registered entities** | RCS | Section letter (A to O) + digits, no space | `B246607` | Standard RCS registration number; other sections look like `F6` or `K1206` |
| **By VAT number** | VIES | LU + 8 digits | `LU32326416` | EU VAT number lookup via VIES |
**RCS Number Format:** The Luxembourg RCS number consists of an uppercase section letter followed by digits, with no space (e.g., `B246607`). The letter is the register section: `B` for commercial companies is the most common. In the records we have seen the number has 1 to 6 digits and no leading zeros. The regex validation pattern is `^[A-Z]\d+$`. Send the number without the space some documents print (`B 246607`).
### RCS Number Prefixes
| Prefix | Entity Type |
| - | - |
| `A` | Sole traders (commercants personnes physiques) |
| `B` | Commercial companies (SA, SARL, SAS, SCA, etc.) and mutual insurance associations |
| `C` | Groupements d'interet economique (GIE) |
| `D` | Groupements europeens d'interet economique (GEIE) |
| `E` | Civil companies (societes civiles) |
| `F` | Non-profit associations (ASBL) |
| `G` | Foundations (fondations) |
| `H` | Agricultural associations |
| `I` | Pension savings associations |
| `J` | Public establishments |
| `K` | Mutual funds (fonds communs de placement, FCP) |
| `L` | Reserved alternative investment funds (RAIF) not registered under another section |
| `M` | Mutual societies (mutuelles) |
| `N` | Branches (succursales) |
| `O` | Securitisation funds |
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `rcs` | Section letter + digits, no space | `B246607` | All registered entities |
| `VAT` | 8 digits (no `LU` prefix) | `32326416` | Verification mode, companies with a VAT number on the extract |
| `euid` | `LURCSL.` + RCS number | `LURCSL.B781` | When available |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the RCS number (`rcs`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By RCS Number | Section letter + digits, no space | `B246607` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | LU + 8 digits | `LU32326416` | Exact via VIES | Exact match returned first (matchType: id); other results may follow |
| By VAT (no prefix) | 8 digits | `32326416` | Exact via VIES | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 3 chars) | `"VREF Germany"` | Fuzzy | Multiple results |
**Search Performance:** Identifier-based searches (RCS number, VAT) provide exact matching and faster results. Name searches query the RCS directly and may return multiple results across the register.
**VAT Search Flow:** VAT searches follow a two-step process: (1) validate the number via VIES to retrieve the official company name, then (2) search the RCS by that company name. The matched company is flagged as an `id` match and promoted to the top of results. Both formats are accepted: with country prefix (`LU32326416`) and without (`32326416`).
**Search reliability:** All search operations include built-in retry handling for reliability against the RCS API.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Companies the register flags as struck off are removed. Other results carry no status, including some from very broad name searches, and are returned unfiltered.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Verification data is AI-parsed from the extract** | In verification mode, company data, legal representatives, and shareholders are extracted from the certified trade register extract (PDF) via AI parsing. Prefill mode returns only the base fields the register publishes. |
| **Asynchronous document delivery** | The certified extract is delivered asynchronously, usually within about an hour. |
| **Asynchronous company data in verification mode** | Because verification-mode `company` depends on the certified extract, it stays `processing` until the document is received and parsed. Prefill-mode `company` does not wait for the extract. |
| **Status detection is heuristic + AI** | In verification mode, status is first detected by keyword search in the document text for closure terms ("radiee", "dissous", "dissolution"), then AI-enriched for standardization. Edge cases may exist for unusual status descriptions. In prefill mode, a company under a published enforcement measure is returned as inactive. |
| **One NACE code per company** | The register publishes a single NACE code per company. Returned NACE and ISIC codes are standardized with AI: from the extract in verification mode, and from the register's NACE label in prefill mode. |
| **RCS number prefix indicates entity type** | The letter prefix is the RCS section (e.g., `A` for sole traders, `B` for commercial companies, `F` for ASBLs, `G` for foundations). See the prefix table above. |
| **VAT format is 8 digits** | Luxembourg VAT numbers are `LU` + 8 digits (e.g., `LU32326416`), shorter than most EU countries. The API returns them without the `LU` prefix (`32326416`). Search accepts both forms. |
| **Several document types** | Besides the certified Extrait du RCS, RESA publications and RCS filings (including annual accounts) are listed in `availableDocuments`. UBO certificates are not available. |
| **No UBO data** | Luxembourg maintains a Register of Beneficial Owners (RBE), also managed by LBR, but this register is not currently integrated. UBO data is not available from the RCS extract. |
| **Document is also the data source** | The Extrait du RCS serves a dual purpose: it is both the official company document delivered to the user and the source from which verification-mode data is AI-parsed. Company, legal representatives, and shareholders from the extract are billed as one block. |
| **SCSp has no legal personality** | The Societe en commandite speciale (SCSp) is a legal form without legal personality, used primarily as an investment vehicle. It is registered in the RCS but may have limited data in the extract. |
## Mappings
### Company Status
Company status is determined from the trade register extract document using a two-step process: (1) a keyword-based heuristic checks for closure indicators in the document text, then (2) the status is **AI-enriched** for standardization.
| Local Status | English Translation | Standardized Status | Detection Method |
| - | - | - | - |
| Active | Active | `ACTIVE` | No closure indicators in document |
| Radiee | Struck Off | `CLOSED` | Document contains "radiee" |
| Dissous | Dissolved | `CLOSED` | Document contains "dissous" |
| Dissolution | Dissolution | `CLOSED` | Document contains "dissolution" |
| En liquidation | In Liquidation | `UNDER_INSOLVENCY_PROCEEDING` | AI-inferred from document context |
If no closure indicators are found in the document text, the company is considered **Active** by default. The AI enrichment step maps the detected status to a standardized `CompanyStatus` enum value (`ACTIVE`, `CLOSED`, `UNDER_INSOLVENCY_PROCEEDING`, or `UNKNOWN`).
### Legal Forms
Luxembourg legal forms are extracted from the RCS trade register extract via **AI parsing**. The `legalFormCode` field from search results provides an initial abbreviation, while the full legal form name is parsed from the certified extract document and **AI-enriched** to add English translations, standardized types, and ISO 20275 codes.
Because legal form standardization and ISO 20275 assignment are AI-enriched, exact mappings may evolve. The local Luxembourg legal form name from the RCS document is always preserved verbatim.
#### Key Business Forms
| French Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Societe a responsabilite limitee | S.a r.l. / SARL | Private Limited Liability Company | Limited Liability Company | `DVXS` |
| Societe a responsabilite limitee simplifiee | S.a r.l.-S | Simplified Private Limited Liability Company | Limited Liability Company | `EUT4` |
| Societe anonyme | SA | Public Limited Company | Corporation | `5GGB` |
| Societe par actions simplifiee | SAS | Simplified Joint-Stock Company | Corporation | `HHR4` |
| Societe en commandite par actions | SCA / SECA | Partnership Limited by Shares | Corporation | `81G5` |
#### Partnerships
| French Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Societe en commandite simple | SCS / SECS | Limited Partnership | Partnership | `63P9` |
| Societe en nom collectif | SNC / SENC | General Partnership | Partnership | `ATQY` |
| Societe en commandite speciale | SCSp | Special Limited Partnership | Partnership | `U8KA` |
#### Sole Proprietorships
| French Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Entreprise individuelle | EI | Sole Proprietorship | Sole Proprietorship | `2IGL` |
#### Cooperatives & European Forms
| French Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Societe cooperative | SC | Cooperative Society | Cooperative | `V5OS` |
| Societas Cooperativa Europaea | SCE | European Cooperative Society | Cooperative | `FG84` |
| Societe europeenne | SE | European Company | Corporation | `WCEP` |
| Groupement d'interet economique | GIE | Economic Interest Grouping | Other | `LCR0` |
#### Non-Profits & Foundations
| French Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Association sans but lucratif | ASBL | Non-Profit Association | Nonprofit Organization | `2JEI` |
| Fondation | - | Foundation | Nonprofit Organization | `V19Y` |
| Association agricole | AA | Agricultural Association | Nonprofit Organization | `68J6` |
#### Investment Vehicles
| French Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Societe d'investissement a capital variable | SICAV | Open-Ended Investment Company | Other | `UDY2` |
| Societe d'investissement a capital fixe | SICAF | Closed-Ended Investment Company | Other | `BEAN` |
| Fond commun de placement | FCP | Common Investment Fund | Other | `AIR5` |
| Societe d'epargne-pension a capital variable | SEPCAV | Variable Capital Pension Savings Company | Other | `9C91` |
#### Insurance & Mutual Associations
| French Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Association d'assurances mutuelles | AAM | Mutual Insurance Association | Other | `BKAB` |
| Mutuelle | - | Mutual Society | Other | `7SIZ` |
| Association d'epargne pension | ASSEP | Pension Savings Association | Other | `2S2U` |
#### Foreign Entities
| French Name | Description | Standardized | ISO 20275 |
| - | - | - | - |
| Succursale d'une societe etrangere | Branch of a foreign company | Branch or Representative Office | - |
### Legal Representatives
Legal representatives and other key persons are read from the certified RCS extract. Known French and German office labels use published translations and standardized values. The extract's representation powers and the company's legal form determine who can bind the company.
Managers of a SARL represent the company subject to its signing rule. An SA board title alone does not establish a personal signature power. Supervisory members and auditors appear under `otherKeyPersons`; officers with recorded sole or joint powers appear under `legalRepresentatives`.
| French Role | English Translation | Standardized | Typical Entity Type |
| - | - | - | - |
| Gerant | Manager | Manager | SARL, SCS |
| Gerant unique | Sole Manager | Manager | SARL (single manager) |
| Administrateur | Director | Director | SA |
| Administrateur-delegue | Managing Director | Managing Director | SA |
| Directeur | Director | Director | Various |
| Directeur général | General Manager | Managing Director | SA |
| President | President | President | SAS |
| President du conseil d'administration | Chairman of the Board | Chairman of the Board | SA |
| Vice-president | Vice President | Vice President | SA, SAS |
| Associe-gerant | Managing Partner | Managing Partner | SCS, SCSp |
| Associe commandite | General Partner | General Partner | SCA, SCS |
| Liquidateur | Liquidator | Liquidator | Companies in liquidation |
| French Role | English Translation | Standardized | Typical Entity Type |
| - | - | - | - |
| Commissaire aux comptes | Statutory Auditor | Auditor | SA, SARL (above threshold) |
| Reviseur d'entreprises | Certified Auditor | Auditor | Various |
| Reviseur d'entreprises agree | Approved Statutory Auditor | Auditor | SA (large companies) |
| Membre du conseil de surveillance | Supervisory Board Member | Supervisory Board Member | SA (dual board structure) |
| President du conseil de surveillance | Chairman of the Supervisory Board | Supervisor | SA (dual board structure) |
| Secretaire | Secretary | Secretary | Various |
Both individuals and corporate entities can hold legal representative and other key person roles in Luxembourg companies. The split follows the published representation powers, not the title alone. Extraction and ISO 5009 matching may use AI; known role translations and standardized values come from the published role list.
### Shareholders
Shareholders are extracted from the RCS trade register extract via **AI parsing**. The AI looks for Luxembourg-specific shareholder terminology in the document text.
#### Extraction Logic
The AI parser identifies shareholders from specific sections of the trade register extract:
| Source Section | Terms Searched | Data Extracted |
| - | - | - |
| **Associe(s)** | Associes, Actionnaires, Associe unique | Shareholder name, registration number, legal form, address |
| **Parts sociales** | Parts detenues, Nombre, Type(s) de parts | Share count, share type |
| **Capital social** | Apport, Participation au capital | Total capital for percentage calculation |
#### Ownership Fields
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | Calculated from shares held / total shares |
| `type` | `individual` or `company` | Determined by AI from shareholder details |
| `numberOfShares` | Number of shares held | From "Parts detenues" section |
| `company.id` | RCS number of corporate shareholder | From "N d'immatriculation au RCS" |
| `company.legalName` | Name of corporate shareholder | From "Denomination" section |
| `company.countryCode` | Country of corporate shareholder | Inferred from registration details |
Shareholder extraction quality depends on the structure and completeness of the trade register extract document. Both individual and corporate shareholders are supported. Percentage calculation is derived from the ratio of shares held to total shares when available. Not all legal forms publish shareholder information in the RCS extract -- SAs (public limited companies) typically do not list individual shareholders in their extracts.
### Activity Code Mapping
Luxembourg uses the **NACE Rev. 2** classification. The register publishes one NACE code per company. Returned NACE and ISIC codes are standardized with AI: in verification mode from the activity found on the extract, and in prefill mode from the register's NACE label.
The system maps activity codes across two levels:
```
NACE Rev. 2 (European) --> ISIC Rev. 4 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NACE** | Register NACE code or activity on the extract, standardized with AI | `7022` | Yes |
| **ISIC** | Derived from NACE via mapping tables or AI | `7020` | Yes |
When company data is AI-parsed from the trade register extract, activity descriptions may also be extracted from "Objet social" or "Activite principale" sections and used for the activity classification.
## Data Availability
### Data Availability Matrix
| Data Type | Commercial Companies | Sole Proprietors | ASBLs / Foundations | Notes |
| - | - | - | - | - |
| Company Profile | ✅ | ✅ | ✅ | Prefill: base register fields. Verification: async, AI-parsed from Extrait du RCS |
| Legal Representatives | ✅ | ✅ | ✅ | Verification mode, AI-parsed from document |
| Other Key Persons | ✅ | When recorded | ✅ | Verification: non-signing office holders, supervisory members and auditors on the certified extract |
| Shareholders | ✅ | N/A | N/A | Verification mode, AI-parsed; mainly for SARL/SCS |
| Ultimate Beneficial Owners | ❌ | ❌ | ❌ | RBE register not integrated |
| Establishments | ❌ | ❌ | ❌ | Not available from RCS extract |
| Activity Codes (NACE) | ✅ | ✅ | ✅ | Standardized with AI |
| Capital | ✅ | N/A | N/A | AI-parsed, formatted in EUR |
| Documents | ✅ | ✅ | ✅ | Extrait du RCS, RESA publications, RCS filings |
**Legend:** ✅ Available | ❌ Not Available | N/A Not Applicable | Async = Asynchronous processing (document delivery typically \~1 hour)
### Documents by Company Type
| Document Type | API Category | Format | Availability | Estimated Delivery |
| - | - | - | - | - |
| **Extrait du RCS** | `certifiedTradeRegisterExtract` | PDF | All registered entities | \~1 hour |
| **RESA publications** | `officialPublications[]` | PDF | When published in the RESA gazette | Minutes |
| **RCS filings** | `officialPublications[]` | PDF | When filed with the RCS | Minutes |
| **Annual accounts** | `financialStatements[]` | PDF | When filed with the RCS | Minutes |
**Document Delivery Time:** Luxembourg certified trade register extracts are delivered asynchronously. Typical delivery time is approximately 1 hour, and can occasionally take longer.
The certified Extrait du RCS serves as both the official company document and the source from which verification-mode data (company, legal representatives, other key persons, shareholders) is AI-parsed. RESA publications and RCS filings (including annual accounts) are listed alongside it in `availableDocuments`.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "LU", "dataPoints": ["company", "legalRepresentatives", "availableDocuments"] }`
```json theme={null}
{
"company": {
"id": "B246607",
"countryCode": "LU",
"identifiers": { "rcs": "B246607", "VAT": "32326416" },
"legalName": "Example Holdings S.a r.l.",
"registrationDate": "2017-05-11",
"incorporationDate": "2017-04-26",
"activityDescription": "La prise de participations dans d'autres societes.",
"status": {
"localName": "Active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Societe a responsabilite limitee",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "DVXS"
},
"capital": {
"amount": 27000,
"currency": "EUR",
"formatted": "27,000.00 EUR"
},
"activities": {
"NACE": [{ "code": "6420", "description": "Activities of holding companies", "isAIInferred": true }],
"ISIC": [{ "code": "6420", "description": "Activities of holding companies", "isAIInferred": true }]
},
"legalAddress": {
"addressLine1": "9 Rue de Bitbourg",
"city": "Luxembourg",
"postalCode": "1273",
"countryCode": "LU"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Gerant",
"standardized": "Manager",
"iso5009Code": "ZULBC6"
},
"individual": {
"name": { "firstName": "Jean", "lastName": "MUELLER", "fullName": "Jean MUELLER" }
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Gerant",
"standardized": "Manager",
"iso5009Code": "ZULBC6"
},
"individual": {
"name": { "firstName": "Marie", "lastName": "SCHMIT", "fullName": "Marie SCHMIT" }
}
}
],
"shareholders": [
{
"entityId": "company_001",
"type": "company",
"sharePercentage": 100,
"numberOfShares": 27000,
"company": {
"id": "B214572",
"legalName": "Parent Holding Company S.a r.l.",
"countryCode": "LU"
}
}
],
"documents": {
"certifiedTradeRegisterExtract": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Extrait du RCS",
"description": "Certified Luxembourg trade register extract",
"format": "pdf"
}
}
}
```
```json theme={null}
{
"company": {
"id": "B100000",
"countryCode": "LU",
"identifiers": { "rcs": "B100000" },
"legalName": "Ancienne Societe SA",
"registrationDate": "2010-01-20",
"status": {
"localName": "Radiee",
"active": false,
"statusDetails": { "status": "CLOSED" }
},
"legalForm": {
"localName": "Societe anonyme",
"englishTranslation": "Public Limited Company",
"standardized": "Corporation",
"iso20275Code": "5GGB"
},
"capital": {
"amount": 31000,
"currency": "EUR",
"formatted": "31,000.00 EUR"
},
"legalAddress": {
"addressLine1": "15 Boulevard Royal",
"city": "Luxembourg",
"postalCode": "2449",
"countryCode": "LU"
}
},
"legalRepresentatives": [],
"shareholders": []
}
```
Closed companies have `active: false` and status "Radiee" (struck off). Document data may be more limited compared to active companies, and legal representatives and shareholders may not always be present in the extract.
```json theme={null}
{
"results": [
{
"id": "B246607",
"legalName": "Example Holdings S.a r.l.",
"countryCode": "LU",
"address": {
"addressLine1": "9 Rue de Bitbourg",
"city": "Luxembourg",
"postalCode": "1273",
"countryCode": "LU"
}
},
{
"id": "B179987",
"legalName": "Another Example SARL",
"countryCode": "LU",
"address": {
"addressLine1": "7A Rue Robert Stumper",
"city": "Luxembourg",
"postalCode": "2557",
"countryCode": "LU"
}
}
]
}
```
```json theme={null}
{
"results": [
{
"id": "B246607",
"legalName": "Example Holdings S.a r.l.",
"countryCode": "LU",
"address": {
"addressLine1": "9 Rue de Bitbourg",
"city": "Luxembourg",
"postalCode": "1273",
"countryCode": "LU"
},
"matchReason": {
"matchType": "id",
"identifier": { "VAT": "LU32326416" }
}
}
]
}
```
VAT searches return results with a `matchReason` object indicating the match type (`id`) and the identifier used. The matched company is promoted to the top of results.
```json theme={null}
{
"documents": {
"certifiedTradeRegisterExtract": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Extrait du RCS",
"description": "Certified Luxembourg trade register extract",
"format": "pdf"
}
}
}
```
| API Category | Document | Format | Notes |
| - | - | - | - |
| `certifiedTradeRegisterExtract` | Extrait du RCS | PDF | All registered entities, asynchronous delivery (\~1 hour) |
| `officialPublications[]` | RESA publications and RCS filings | PDF | When published or filed |
| `financialStatements[]` | Annual accounts | PDF | When filed |
# Malta
Source: https://docs.topograph.co/essentials/malta
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Malta reference is on the [Malta country page](https://www.topograph.co/countries/mt).
## Start here
This guide contains public integration notes for Malta. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
**Verification mode only.** Every Malta datapoint is served from the live register in verification mode. A request with `"mode": "prefill"` fails each Malta datapoint with `fast_source_unavailable`. Omit `mode` or pass `"verification"`. See [Modes](/essentials/modes).
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Malta uses a single official register for all company data. For a given entity, **data comes from one source**, with no cross-register merging.
* **Malta Business Registry (MBR)**, queried live through its online system, BAROS (Business Automation Registry Online System). The MBR keeps the register of companies and partnerships under the Companies Act (Cap. 386), and of foundations and associations under the Second Schedule to the Civil Code. It returns the company profile (name, registration number, legal form, status, registration date, registered office, issued share capital, area of activity), the persons recorded on the entity (directors, secretary, legal and judicial representatives, partners, liquidators, auditors, subscribers and other involvements), the share register used for `shareholders`, and the list of filed documents, which are sold per document.
A VAT number search is first resolved to the company's registered name through the EU VAT validation service (VIES), then searched by that name in the MBR.
**Authenticated source:** The Maltese register requires authenticated access. Topograph handles this as part of the standard API flow.
## Company Identifiers
Domestic private and public limited liability companies also return `company.identifiers.euid`, for example `MTROC.C2833`. The EUID omits the space in the national registration number. It is not a search key.
### Query Identifiers
| Entity Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **Companies** | MBR | C + space + digits | `C 2833` | Standard Malta company number issued by MBR |
| **Partnerships en nom collectif** | MBR | P + space + digits | `P 2241` | General partnerships |
| **Partnerships en commandite** | MBR | P COMM + space + digits | `P COMM 203` | Limited partnerships |
| **Overseas companies** | MBR | OC + space + digits | `OC 1299` | Maltese branches of foreign companies |
| **SICAVs** | MBR | SV + space + digits | `SV 88` | Investment companies with variable share capital |
| **Foundations** | MBR | LPF + space + digits | `LPF 455` | Foundations registered with MBR |
| **Former offshore companies** | MBR | OS/ + digits + /T or /NT | `OS/1116/NT` | Companies registered under the former offshore regime. Slashes, no space. `T` = trading, `NT` = non-trading |
**Malta Registration Number Format:** Malta registration numbers consist of an entity-type prefix (`C`, `P`, `P COMM`, `OC`, `SV`, or `LPF`) followed by a space and digits (e.g., `C 2833`). The space between the prefix and the number is part of the official format. The one exception is the former offshore series, written with slashes and no space (e.g., `OS/1116/NT`).
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `registrationNumber` | Prefix + space + digits, or `OS//T` / `OS//NT` | `C 2833`, `SV 88`, `OS/1116/NT` | All registered entities |
| `euid` | `MTROC.` + registration number without the space | `MTROC.C2833` | Domestic private and public limited liability companies |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Maltese registration number (`registrationNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Registration Number | Prefix (`C`, `P`, `P COMM`, `OC`, `SV`, `LPF`) + space + digits, or `OS//T` / `OS//NT` | `C 2833`, `LPF 455`, `OS/1116/NT` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 3 chars) | `"Valletta Holdings"` | Partial | Multiple results |
| By VAT Number | `MT` + 8 digits, or 8 digits | `MT12345678` | Via registered name | Companies matching the name registered for that VAT number |
**Search Performance:** Identifier-based searches use exact matching and return the exact match first (`matchReason.matchType = "id"`); other results may follow. Name searches use partial matching and may return many results. A VAT number is resolved to its registered name through the EU VAT validation service, then searched by that name. All search types query the Malta Business Registry live.
### Active companies only
Search can return companies that are no longer active, but search results carry no company status, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Verification mode only** | There is no prefill source for Malta. In `"mode": "prefill"`, every Malta datapoint fails with `fast_source_unavailable`. |
| **Fee-based documents** | Malta documents are paid (see [pricing](https://www.topograph.co/pricing)). The document listing itself is free. |
| **Registration number format includes space** | Malta registration numbers include a space after the entity-type prefix (e.g., `C 2833`, `P COMM 203`). The space is normalized during search (whitespace-insensitive matching). |
| **Judicial representatives are not legal representatives** | The register records the persons vested with the *legal* representation of a company (who can bind it) separately from its *judicial* representatives (who represent it in court proceedings only, Companies Act art. 141). The first are returned under `legalRepresentatives`, the second under `otherKeyPersons`. |
| **No signing rule** | The register does not record whether representatives sign alone or jointly; that rule is in the memorandum and articles or the deed of partnership. `representationMode` and `signingPowers` are never returned. |
| **Founding subscribers are not shareholders** | Subscribers to the memorandum at incorporation are returned under `otherKeyPersons` with the role `Subscribers`. Current shareholders come from the separate `shareholders` datapoint. |
| **Area of activity is not always recorded** | The register records one primary area of activity per entity, a NACE Rev. 2 code. Many entities, older ones especially, have none, and their response then carries no `activities` and no `activityDescription`. |
| **Some partnerships record no people** | For some partnerships the register lists no partners or representatives at all; they appear only in the deed of partnership, which is available as an `articlesOfAssociation` document. |
| **No UBO data** | Beneficial owners are not available for Malta. |
| **Document names and categories are generated** | The register lists each filing with a short filing name. The document `name`, `description` and category are generated from that metadata by AI; the filing `date` and `format` come from the register. |
## Mappings
### Company Status
`status.localName` preserves the register's wording. Known statuses are mapped deterministically, without AI. `status.active` is `true` only for `Active`. The mapping covers observed profile statuses and the register's explicit struck-off variants:
| `status.localName` | `status.active` | `statusDetails.status` |
| - | - | - |
| Active | `true` | `ACTIVE` |
| In Dissolution | `false` | `PENDING_DISSOLUTION` |
| In Process of Merging | `false` | `INACTIVE_NOT_CLOSED` |
| Struck Off | `false` | `CLOSED` |
| Struck Off as Defunct | `false` | `CLOSED` |
| Struck Off Following Merger | `false` | `CLOSED` |
| Struck Off Following Division | `false` | `CLOSED` |
| Struck Off Following Insolvency | `false` | `CLOSED` |
| Struck Off Following Cross-Border Merger | `false` | `CLOSED` |
| Struck Off Following Cross-Border Conversion | `false` | `CLOSED` |
| Struck Off Following Cross-Border Division | `false` | `CLOSED` |
A status outside this mapping keeps its register wording, returns `statusDetails.status: "UNKNOWN"`, and omits `active`. If the register supplies no status, `company.status` is absent.
### Legal Forms
`legalForm.localName` is the company type exactly as the register words it. The register records a limited liability company together with its category (private or public, exempt or non-exempt, single member), which is written in parentheses.
So one legal form can appear under several local names: `Limited Liability Company (Private Exempt)` and `Limited Liability Company (Private Non-Exempt)` are both private limited liability companies. Compare companies on `legalForm.standardized` and `legalForm.iso20275Code`, not on `localName`.
`englishTranslation`, `standardized` and `iso20275Code` come from a closed list of the 57 forms the Malta Business Registry registers; the full list is on the [pricing page](https://topograph.co/pricing/mt). A legacy form outside that list is translated and standardized at request time, and carries `isAIEnriched: true`.
#### Companies
| `localName` | `englishTranslation` | `standardized` | `iso20275Code` |
| - | - | - | - |
| Limited Liability Company (Private Exempt) | Private Exempt Limited Liability Company | Limited Liability Company | `V89C` |
| Limited Liability Company (Private Exempt Single Member) | Private Exempt Single-Member Limited Liability Company | Limited Liability Company | `V89C` |
| Limited Liability Company (Private Non-Exempt) | Private Limited Liability Company | Limited Liability Company | `V89C` |
| Limited Liability Company (Public Non-Exempt) | Public Limited Liability Company | Corporation | `C061` |
| Continued (Private Non-Exempt), and the other `Continued (…)` categories | Continued … Limited Liability Company (companies re-domiciled to Malta) | Limited Liability Company, or Corporation for a public company | `V89C`, or `C061` for a public company |
| SICAV (Private), SICAV (Public) | Investment Company with Variable Share Capital | Corporation | - |
| Societas Europea | European Company (SE) | Corporation | `CR7N` |
| International Trading Company (…), International Holding Company (…) | International Trading / Holding Company | Limited Liability Company | - |
| Offshore Company (Trading), Offshore Company (Non-Trading) | Offshore Company | Limited Liability Company | - |
**Private vs Public:** A private company may have a maximum of 50 shareholders, may not invite the public to subscribe for shares, and restricts share transfer rights. A public company has no such restrictions. **Exempt vs Non-Exempt:** An exempt company has fewer regulatory obligations (e.g., audit exemption eligibility under S.L. 386.20). Private and public companies have different minimum authorised share capital requirements under Maltese company law.
#### Partnerships, branches and other entities
| `localName` | `englishTranslation` | `standardized` | `iso20275Code` |
| - | - | - | - |
| Partnership (En Nom Collectif) | General Partnership (en nom collectif) | Partnership | `JOZN` |
| Partnership (En Commandite / Limited Partnership) | Limited Partnership (en commandite) | Partnership | `BVJ0` |
| Partnership (En Commandite / Limited Partnership by Shares) | Limited Partnership by Shares (en commandite) | Partnership | `BVJ0` |
| Overseas (Overseas Company) | Overseas Company (branch of a foreign company) | Branch or Representative Office | - |
| European Economic Interest Grouping | European Economic Interest Grouping (EEIG) | Partnership | `YB0U` |
| Purpose Foundation, Private Beneficiary Foundation | Purpose Foundation, Private Beneficiary Foundation | Nonprofit Organization | `3U3Y` |
| Association, Legal Entities (Sports Association), Legal Entities (Non-Profit Voluntary Association) | Association, Sports Association, Non-Profit Voluntary Association | Nonprofit Organization | `J4S1` |
| Cooperatives | Cooperative | Cooperative | `F5X7` |
A **partnership en nom collectif** (general partnership) has partners who are jointly and severally liable. A **partnership en commandite** (limited partnership) has at least one general partner (unlimited liability) and one limited partner (liability limited to contribution). Both are governed by the Companies Act 1995.
`iso20275Code` is returned where GLEIF publishes an ISO 20275 code for the form in Malta. Cells, SICAVs, overseas companies, international trading and holding companies, and the legacy offshore forms have none.
### Roles
Roles are mapped from a closed list of the roles the Malta Business Registry records, published on the [pricing page](https://topograph.co/pricing/mt). `role.localName` is the register's own wording; `englishTranslation` and `standardized` are fixed per role.
A role is returned under `legalRepresentatives` when Maltese law gives it the representation of the entity, and under `otherKeyPersons` otherwise. A role can be held by an individual (`type: "individual"`) or a company (`type: "company"`).
#### Legal Representatives
| `role.localName` | `role.englishTranslation` | `role.standardized` | Found on |
| - | - | - | - |
| Director | Director | Director | Companies |
| Legal Representative | Legal Representative | Authorized Signatory | The persons vested with the legal representation of the entity |
| General Partner | General Partner | General Partner | Partnerships en commandite |
| General Partner vested with Administration | General Partner vested with Administration | Managing Partner | Partnerships en commandite |
| Persons vested with Administration of the Partnership | Partner vested with Administration of the Partnership | Managing Partner | Partnerships en nom collectif |
| Liquidator | Liquidator | Liquidator | Companies being wound up |
| Administrators | Administrator | Administrator | Foundations |
| Local Representative of an Overseas Company | Local Representative of an Overseas Company | Authorized Signatory | Overseas companies |
| Joint Representative of an Overseas Company | Joint Representative of an Overseas Company | Authorized Signatory | Overseas companies |
| Manager (EEIG) | Manager of a European Economic Interest Grouping | Manager | European Economic Interest Groupings |
Individuals carry the `nationality` the register records for them, as an ISO 3166-1 alpha-2 code. A legal representative may also carry an ISO 5009 `role.iso5009Code` when the role has an equivalent for the company's legal form.
#### Other Key Persons
`role.standardized` on an other key person takes its values from a separate, shorter list: `Secretary` and `Auditor` have their own value, every other role is `Other`.
| `role.localName` | `role.englishTranslation` | `role.standardized` | Notes |
| - | - | - | - |
| Judicial Representative | Judicial Representative | Other | Represents the entity in court proceedings only |
| Secretary | Secretary | Secretary | Company secretary, required for every Maltese company |
| Auditor | Auditor | Auditor | Statutory auditor |
| Subscribers | Subscriber to the Memorandum | Other | Signatories of the memorandum at incorporation, not current shareholders |
| Limited Partner | Limited Partner | Other | Partner whose liability is limited to their contribution; cannot manage or represent the partnership |
| Special Attorney | Special Attorney | Other | |
| Pledgor | Pledgor | Other | Party that pledged shares |
| Pledgee | Pledgee | Other | Party holding a pledge over shares |
| Member (EEIG) | Member of a European Economic Interest Grouping | Other | |
A role the register adds later, outside this list, is returned with the register's wording in `localName` and translated at request time.
### Shareholders
Structured shareholders are available as a separate `shareholders` datapoint, read from the Malta Business Registry's share register data. No document purchase or AI parsing is involved.
| Field | Description |
| - | - |
| `type` | `individual` or `company` |
| `individual` / `company` | Shareholder identity: name and address; for individuals, the nationality; for companies, the registration number and country when provided |
| `numberOfShares` | Total number of shares held, across share classes |
| `nominalCapitalHeld` | Nominal value of the shares held (number of shares times value per share) |
| `sharePercentage` | Shareholder's nominal capital as a percentage of the total nominal capital held by all shareholders |
Founding subscribers (the signatories of the memorandum at incorporation) are returned under `otherKeyPersons` and are not treated as current shareholders. Partnerships have no share register, so their `shareholders` list is empty.
### Activity Codes
The Malta Business Registry records one **area of activity** per entity: the primary activity declared by the company, chosen from the register's own NACE Rev. 2 list. It is a register statement, not an inference.
| Field | Content |
| - | - |
| `activityDescription` | The register's area of activity, as its NACE Rev. 2 label (e.g. `Business and other management consultancy activities`) |
| `activities.NACE_REV2` | The register's code exactly as declared, with `isMainActivity: true` and `isAIInferred: false` |
| `activities.NACE` | The same activity standardized to NACE Rev. 2.1, with `isMainActivity: true` |
| `activities.ISIC` | The ISIC Rev. 5 equivalent |
When the register records no area of activity for the entity, `activities` and `activityDescription` are both absent.
Most Rev. 2 classes have one Rev. 2.1 successor, and `NACE` then carries `isAIInferred: false`. Where Rev. 2.1 split or deleted the class, the Rev. 2.1 code is chosen from the activity description, or the group that contains the candidates, and carries `isAIInferred: true` (for example `64.20` becomes `64.21`). `NACE_REV2` always holds the register's own code.
## Data Availability
### Data Availability Matrix
| Data Type | Commercial Companies | Partnerships | Notes |
| - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | Live from the MBR |
| Legal Representatives | ✅ | ⚠️ | Directors, legal representatives, partners vested with representation, liquidators. Some partnerships record none (see quirks) |
| Other Key Persons | ✅ | ✅ | Secretary, judicial representatives, auditors, subscribers, limited partners |
| Shareholders | ✅ | ❌ | Separate datapoint: identity, number of shares, nominal capital held, ownership percentage. Partnerships have no share register |
| Ultimate Beneficial Owners | ❌ | ❌ | Not available |
| Establishments | ❌ | ❌ | Not available |
| Activity Codes | ⚠️ | ⚠️ | The register's area of activity, when it records one |
| Documents | ✅ | ✅ | Fee-based retrieval; see [pricing](https://www.topograph.co/pricing) |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Documents by Company Type
Malta documents are fee-based and retrieved from the Maltese register. Document types and prices come from the register's filing list and are surfaced through `availableDocuments`.
| Typical Document Types | Returned under |
| - | - |
| Memorandum and Articles of Association, alterations to them, deeds of partnership | `articlesOfAssociation` |
| Annual accounts | `financialStatements` |
| Annual returns | `annualReturns` |
| Prospectus | `otherDocuments` |
| Notices, forms, resolutions, share transfers and other filings | `otherDocuments` |
**Paid Documents:** Malta documents can incur a register fee. Check the [pricing page](https://www.topograph.co/pricing) or `availableDocuments` before purchase. The document listing itself is free.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "MT", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "C 12345",
"countryCode": "MT",
"identifiers": { "registrationNumber": "C 12345", "euid": "MTROC.C12345" },
"legalName": "Example Malta Holdings Limited",
"registrationDate": "2010-04-15",
"activityDescription": "Business and other management consultancy activities",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Limited Liability Company (Private Exempt)", "englishTranslation": "Private Exempt Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "V89C", "isAIEnriched": false },
"capital": { "amount": 1200, "currency": "EUR", "formatted": "€1,200" },
"activities": {
"NACE_REV2": [{ "code": "70.22", "description": "Business and other management consultancy activities", "isAIInferred": false, "isMainActivity": true }],
"NACE": [{ "code": "70.20", "description": "Business and other management consultancy activities", "isAIInferred": false, "isMainActivity": true }],
"ISIC": [{ "code": "7020", "description": "Business and other management consultancy activities", "isAIInferred": false, "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "42, Republic Street", "city": "Valletta", "postalCode": "VLT 1234", "countryCode": "MT" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" }, "individual": { "name": { "fullName": "Mr John BORG", "firstName": "John", "lastName": "BORG" }, "nationality": "MT" } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Legal Representative", "englishTranslation": "Legal Representative", "standardized": "Authorized Signatory" }, "individual": { "name": { "fullName": "Ms Maria CAMILLERI", "firstName": "Maria", "lastName": "CAMILLERI" }, "nationality": "MT" } }
],
"otherKeyPersons": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Judicial Representative", "englishTranslation": "Judicial Representative", "standardized": "Other" }, "individual": { "name": { "fullName": "Mr John BORG", "firstName": "John", "lastName": "BORG" }, "nationality": "MT" } },
{ "entityId": "person_003", "type": "individual", "role": { "localName": "Secretary", "englishTranslation": "Secretary", "standardized": "Secretary" }, "individual": { "name": { "fullName": "Mr Paul ZAMMIT", "firstName": "Paul", "lastName": "ZAMMIT" }, "nationality": "MT" } },
{ "entityId": "company_001", "type": "company", "role": { "localName": "Auditor", "englishTranslation": "Auditor", "standardized": "Auditor" }, "company": { "legalName": "ABC Audit Services Limited", "id": "C 99999", "countryCode": "MT" } }
]
}
```
```json theme={null}
{
"company": {
"id": "C 22222",
"countryCode": "MT",
"identifiers": { "registrationNumber": "C 22222", "euid": "MTROC.C22222" },
"legalName": "Example International Holdings p.l.c.",
"registrationDate": "2000-03-10",
"activityDescription": "Other monetary intermediation",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Limited Liability Company (Public Non-Exempt)", "englishTranslation": "Public Limited Liability Company", "standardized": "Corporation", "iso20275Code": "C061", "isAIEnriched": false },
"capital": { "amount": 500000, "currency": "EUR", "formatted": "€500,000" },
"activities": {
"NACE_REV2": [{ "code": "64.19", "description": "Other monetary intermediation", "isAIInferred": false, "isMainActivity": true }],
"NACE": [{ "code": "64.19", "description": "Other monetary intermediation", "isAIInferred": false, "isMainActivity": true }],
"ISIC": [{ "code": "6419", "description": "Other monetary intermediation", "isAIInferred": false, "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "Tower Business Centre, Level 5", "city": "Swatar", "postalCode": "BKR 4012", "countryCode": "MT" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" }, "individual": { "name": { "fullName": "Mr Joseph VELLA", "firstName": "Joseph", "lastName": "VELLA" }, "nationality": "MT" } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" }, "individual": { "name": { "fullName": "Ms Anna FARRUGIA", "firstName": "Anna", "lastName": "FARRUGIA" }, "nationality": "IT" } }
],
"otherKeyPersons": [
{ "entityId": "person_003", "type": "individual", "role": { "localName": "Secretary", "englishTranslation": "Secretary", "standardized": "Secretary" }, "individual": { "name": { "fullName": "Dr Mark GRECH", "firstName": "Mark", "lastName": "GRECH" }, "nationality": "MT" } }
]
}
```
```json theme={null}
{
"company": {
"id": "C 33333",
"countryCode": "MT",
"identifiers": { "registrationNumber": "C 33333", "euid": "MTROC.C33333" },
"legalName": "Old Trading Company Limited",
"registrationDate": "1998-07-22",
"status": { "localName": "In Dissolution", "active": false, "statusDetails": { "status": "PENDING_DISSOLUTION" } },
"legalForm": { "localName": "Limited Liability Company (Private Non-Exempt)", "englishTranslation": "Private Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "V89C", "isAIEnriched": false },
"capital": { "amount": 5000, "currency": "EUR", "formatted": "€5,000" },
"legalAddress": { "addressLine1": "15, Triq il-Kbira", "city": "Mosta", "postalCode": "MST 1011", "countryCode": "MT" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Liquidator", "englishTranslation": "Liquidator", "standardized": "Liquidator" }, "individual": { "name": { "fullName": "Mr Toni GALEA", "firstName": "Toni", "lastName": "GALEA" }, "nationality": "MT" } }
]
}
```
**Note:** This company recorded no area of activity, so `activities` and `activityDescription` are absent. Once a company is being wound up, its liquidator represents it and is returned under `legalRepresentatives`.
```json theme={null}
{
"company": {
"id": "P 44444",
"countryCode": "MT",
"identifiers": { "registrationNumber": "P 44444" },
"legalName": "Borg & Sons Trading",
"registrationDate": "2015-01-08",
"status": { "localName": "Active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Partnership (En Nom Collectif)", "englishTranslation": "General Partnership (en nom collectif)", "standardized": "Partnership", "iso20275Code": "JOZN", "isAIEnriched": false },
"legalAddress": { "addressLine1": "78, Triq San Pawl", "city": "Rabat", "postalCode": "RBT 1234", "countryCode": "MT" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Persons vested with Administration of the Partnership", "englishTranslation": "Partner vested with Administration of the Partnership", "standardized": "Managing Partner" }, "individual": { "name": { "fullName": "Mr Noel BORG", "firstName": "Noel", "lastName": "BORG" }, "nationality": "MT" } }
]
}
```
**Note:** Partnerships carry no share capital and no `euid`. Some partnerships record no people at the register; their partners are only in the deed of partnership.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested, grouped by category. Pass a document `id` in `documents` to buy it.
```json theme={null}
{
"documents": {
"articlesOfAssociation": [
{
"id": "5f1c2a9e-0b7d-5c3e-9a41-2d6e8b7f0a11",
"name": "Memorandum and Articles of Association - 2010-04-15",
"description": "Memorandum and Articles of Association dated 2010-04-15",
"format": "PDF",
"date": "2010-04-15"
},
{
"id": "c2e4f6a8-3b5d-5f7a-9c1e-4d6f8a0b2c4e",
"name": "Alterations to the Memorandum and Articles",
"format": "PDF",
"date": "2024-03-18"
}
],
"annualReturns": [
{
"id": "8a3d4b6c-1e2f-5a7b-8c9d-0e1f2a3b4c5d",
"name": "Annual Return 2025",
"description": "Annual return for the year 2025",
"format": "PDF",
"date": "2025-11-10"
}
]
}
}
```
**Document pricing summary:** Malta document pricing varies by filing type. Use `availableDocuments` or the [pricing page](https://www.topograph.co/pricing) before purchase.
# Manual Delivery
Source: https://docs.topograph.co/essentials/manual-delivery
Some datapoints and documents take a few business days because they are fulfilled through a manual process
Most Topograph datapoints resolve in seconds or minutes. A small number are fulfilled through a manual process and take longer: from **1–2 business days** in most countries up to **14–20 business days** in a few, depending on the country. The request stays `in_progress` during that time and delivers through the same response shape, webhooks, and polling as any other datapoint.
## What is affected
Manual delivery currently applies to beneficial ownership data (`ultimateBeneficialOwners`) in several countries, and to shareholder data (`shareholders`) in China. Some document types in these countries are also manually fulfilled.
The [live pricing page](https://topograph.co/pricing) marks every affected datapoint and document with a **Manual** badge. Use it to check the current list before building a country-specific flow.
## Detect it at runtime
The public catalog, `GET /v2/catalog`, exposes `manual` and `manualDescription` on each data block mode and on each document type. Where the delivery window is known, `manualDeliveryEstimate` gives it in business days as `minBusinessDays` and `maxBusinessDays`.
Use these fields to branch in your integration logic, set user expectations, or skip a datapoint when you need instant results.
The catalog needs no API key and returns every country's manifest, keyed by country code:
```bash theme={null}
curl --request GET \
--url 'https://api.topograph.co/v2/catalog'
```
In the response, a manually delivered data block mode looks like this (Slovenia, trimmed to the relevant fields):
```json theme={null}
{
"SI": {
"dataBlocks": [
{
"datapoints": ["ultimateBeneficialOwners"],
"modes": [
{
"fast": false,
"authoritative": true,
"manual": true,
"manualDescription": "Sourced through our SI partner — typically 1–2 business days.",
"manualDeliveryEstimate": { "minBusinessDays": 1, "maxBusinessDays": 2 }
}
]
}
],
"countryDocuments": [
{
"type": "ubo_extract",
"displayName": "Beneficial Ownership Extract",
"manual": true,
"manualDescription": "Sourced through our SI partner — typically 1–2 business days.",
"manualDeliveryEstimate": { "minBusinessDays": 1, "maxBusinessDays": 2 }
}
]
}
}
```
`manualDeliveryEstimate` is an estimate, not a measured time, and is separate from the indicative response times published for automated datapoints. A mode or document without `manual: true` is delivered automatically. `GET /v2/pricing` returns prices per mode and does not carry these fields.
`GET /v2/catalog` is the programmatic source of truth. Avoid hardcoding which datapoints are manual: the set can change as countries add automated sources.
## How it works in a request
Manual datapoints follow the same lifecycle as any other datapoint:
1. **Create a request** with `POST /v2/company` as usual. The response returns `in_progress` for the manual datapoint.
2. **The datapoint stays `in_progress`** while the manual work is underway. This is expected, not an error.
3. **A `company.updated` webhook fires** when the datapoint finishes, with the same payload shape as an instant datapoint. If you poll instead, the status moves to `succeeded` or `failed`.
4. **The result** is available through `GET /v2/company/{requestId}` in the same response shape as any other data.
You do not need separate code paths to consume manually delivered data. The only difference is time.
### Concurrency
A request whose only remaining work is manually delivered does not hold a slot against your account's [concurrency limit](/guides/concurrency-and-backfills). The slot is released once the automated portion of the request finishes. Manual items never block your capacity for other requests.
### Timeouts and retries
The standard retry windows described in [Reliability and errors](/guides/reliability-and-errors) apply to automated register retrieval (up to 1 hour in verification mode). Manual items have their own turnaround and are not covered by those windows.
If a manual item is not delivered within **14 days** (7 days for shareholder data in China), it fails with the error code [`manual_document_timeout`](/guides/reliability-and-errors). This failure is final and is not retried automatically. Contact [support@topograph.co](mailto:support@topograph.co) with the request id if you still need the data, rather than sending the request again.
While a manual item is still in progress, sending the same request again does not restart or speed up the manual process.
If the document turns out not to exist for the company, the item fails as soon as that is confirmed, with `no_document_available`, instead of waiting out the full window.
## Integration recommendations
* **Set user expectations.** If your flow includes a manually delivered datapoint, tell your users the result will arrive later. The `manual` flag from `GET /v2/catalog` lets you detect this at build time or at runtime.
* **Use webhooks.** Polling every few seconds for a result that takes days wastes bandwidth. Set up [webhooks](/guides/webhooks) and process the result when it arrives.
* **Consider splitting your request.** Request instant datapoints first, then request manual ones in a follow-up call if your UX benefits from showing partial data immediately. Both requests are billed independently through the normal [deduplication window](/essentials/pricing-and-caching).
# Marshall Islands
Source: https://docs.topograph.co/essentials/marshall-islands
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Marshall Islands reference is on the [Marshall Islands country page](https://www.topograph.co/countries/mh).
## Start here
This guide contains public integration notes for Marshall Islands. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Marshall Islands data comes from a single official source, the **Republic of the Marshall Islands Corporate Register**, maintained by International Registries, Inc. It covers non-resident and resident entities: corporations, limited liability companies, partnerships, limited partnerships, foreign maritime entities and resident entities.
* **Marshall Islands Corporate Register** (`resources.register-iri.com`). The **sole source** for search, the company profile, the registered agent, and the Non-Resident Entity Report. Every request reads the register live; there is no bulk extract of this register.
The register publishes the entity number, legal name, entity type, status, existence (formation) date, and the registered agent's name and address. Officers, directors, members and shareholders are not publicly available.
**Modes.** Both `mode: "prefill"` and `mode: "verification"` (the default) read the same live register and return the same fields. Prefill results are flagged `authoritative: false`; verification results are authoritative. See [Modes](/essentials/modes).
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Entity Number** | Digits only, no leading zeros; 4 to 6 digits in the records we have seen | `127599`, `35087`, `9519` | Primary identifier assigned by the Marshall Islands Corporate Register. Appears on the register's entity detail and on the Non-Resident Entity Report. |
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | Digits only, 4 to 6 digits in the records we have seen | `127599` | All entities |
The Marshall Islands register publishes the entity number and does not issue tax identification or VAT numbers for non-resident entities. An optional LEI may be returned from GLEIF as described below.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the entity number matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Entity Number | 3 to 8 digits | `127599` | Exact (`matchType: id`) | Single result or none |
| By Name | 4 to 200 characters | `"PACIFIC OCEAN"` | Begins with | Multiple results across all entity types |
**Name search** returns entities whose legal name starts with your query, so start from the first word of the name. The query must be at least 4 characters. Results cover all six entity types and are de-duplicated by entity number. A result whose legal name matches the query exactly is returned with `matchType: exactLegalName`.
**Numeric queries** are treated as entity numbers only. A query made entirely of digits is not run as a name search.
Both searches query the register live. Search results carry the entity number (`id`) and legal name; status, entity type and address come from the `company` datapoint.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Annulled, dissolved, transferred and converted entities are removed.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No officers, directors or shareholders** | The register does not disclose directors, officers, managers, members or shareholders. Only the registered agent is public, so `legalRepresentatives` and `shareholders` are not available. |
| **Registered agent returned as an other key person** | The registered agent is returned under `otherKeyPersons` with the role `Registered Agent`, as a company. It is not an officer of the entity. |
| **Legal address is the registered agent's office** | Non-resident entities have no separate registered office. `legalAddress` is the registered agent's address in Majuro, so many entities share the same address. |
| **No UBO register** | The Marshall Islands does not maintain a public beneficial ownership register. |
| **No activity codes** | The register does not collect industry classification codes, so no NACE or ISIC codes are returned. |
| **Name search is prefix-based** | Name search matches the beginning of the legal name, not words in the middle of it. Search by entity number when you have it. |
| **Status is not good standing** | The register's public record shows existence and status only, and the register marks its entity record as not a statement of good standing. A Certificate of Good Standing is not offered. |
| **Registration date** | `registrationDate` is the register's existence (formation) date. |
## Mappings
### Company Status
Status is mapped deterministically from the register's status value.
| Local Status | English Translation | `active` |
| - | - | - |
| Active | Active | `true` |
| Annulled | Annulled | `false` |
| Dissolved | Dissolved | `false` |
| Transferred | Transferred | `false` |
| Conversion | Conversion | `false` |
A status value outside this list is returned with its `localName` and no `active` flag.
### Legal Forms
Legal form is mapped deterministically from the register's entity type, a closed list of six values. The register does not publish ISO 20275 (ELF) codes, so `iso20275Code` is not returned.
| Local Name | English Translation | Standardized |
| - | - | - |
| Corporation | Corporation | `Corporation` |
| Limited Liability Company | Limited Liability Company | `Limited Liability Company` |
| Partnership | Partnership | `Partnership` |
| Limited Partnership | Limited Partnership | `Partnership` |
| Foreign Maritime | Foreign Maritime Entity | `Other` |
| Resident Entity | Resident Entity | `Other` |
### Legal Representatives
Not available. The register does not publish directors, officers or managers.
### Other Key Persons
| Local Role Name | Standardized | Holder |
| - | - | - |
| Registered Agent | `Registered Agent` | Company |
The registered agent is returned with its legal name and address.
### Shareholders
Not available. Shareholder and member registers are held privately by the entity and are not published by the register.
### Activity Code Mapping
Not available. The register does not collect industry classification codes.
## Data Availability
### Data Availability Matrix
The same fields are returned in prefill and verification mode.
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Entity number | Yes | `identifiers.entityNumber` |
| Company status | Yes | See [Company Status](#company-status) |
| Legal form | Yes | Closed list of six entity types |
| Registration date | Yes | Existence (formation) date |
| Legal address | Yes | The registered agent's office |
| Registered agent | Yes | Under `otherKeyPersons`, with name and address |
| Legal representatives | No | Not published by the register |
| Shareholders | No | Not published by the register |
| UBOs | No | No public beneficial ownership register |
| Activity codes | No | Not collected by the register |
| Tax IDs | No | Not issued for non-resident entities |
### Documents by Company Type
| Response Key | Document | Entity Types | Contents |
| - | - | - | - |
| `tradeRegisterExtract` | Non-Resident Entity Report (PDF) | All | Entity number, legal name, entity type, status, existence (formation) date, registered agent name and address |
The Trade Register Extract is included with the company data. It is listed for every entity through the `availableDocuments` datapoint. See the [pricing page](https://topograph.co/pricing/mh) for current pricing.
## Example API Responses
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=MH&query=PACIFIC%20EXAMPLE" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "123456",
"countryCode": "MH",
"legalName": "PACIFIC EXAMPLE SHIPPING LTD",
"matchReason": { "matchType": "default" }
},
{
"id": "123789",
"countryCode": "MH",
"legalName": "PACIFIC EXAMPLE HOLDINGS LLC",
"matchReason": { "matchType": "default" }
}
]
```
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=MH&query=123456" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "123456",
"countryCode": "MH",
"legalName": "PACIFIC EXAMPLE SHIPPING LTD",
"matchReason": { "matchType": "id", "identifier": { "entityNumber": "123456" } }
}
]
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "MH", "id": "123456", "dataPoints": ["company", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "123456",
"countryCode": "MH",
"identifiers": { "entityNumber": "123456" },
"legalName": "PACIFIC EXAMPLE SHIPPING LTD",
"registrationDate": "2024-08-21",
"status": { "localName": "Active", "active": true },
"legalForm": {
"localName": "Corporation",
"englishTranslation": "Corporation",
"standardized": "Corporation"
},
"legalAddress": { "addressLine1": "Example Complex, Example Road", "city": "Majuro", "postalCode": "96960", "countryCode": "MH" }
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"company": {
"legalName": "EXAMPLE REGISTERED AGENT, INC.",
"countryCode": "MH",
"legalAddress": { "addressLine1": "Example Complex, Example Road", "city": "Majuro", "postalCode": "96960", "countryCode": "MH" }
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "123789",
"countryCode": "MH",
"identifiers": { "entityNumber": "123789" },
"legalName": "PACIFIC EXAMPLE HOLDINGS LLC",
"registrationDate": "2015-03-02",
"status": { "localName": "Dissolved", "active": false },
"legalForm": {
"localName": "Limited Liability Company",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": { "addressLine1": "Example Complex, Example Road", "city": "Majuro", "postalCode": "96960", "countryCode": "MH" }
}
}
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "MH", "id": "123456", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_123",
"name": "Trade Register Extract",
"format": "pdf"
}
}
}
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "MH", "id": "123456", "documents": ["doc_tre_123"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_123",
"name": "Trade Register Extract",
"format": "pdf",
"url": "https://files.example.com/documents/doc_tre_123.pdf?sig=..."
}
}
}
```
# Mauritius
Source: https://docs.topograph.co/essentials/mauritius
Country-specific identifiers, data sources, and data availability
This guide is outdated and will be removed on 1 November 2026. The up-to-date Mauritius reference is on the [Mauritius country page](https://www.topograph.co/countries/mu).
## Start here
This guide contains public integration notes for Mauritius. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Mauritius uses a single official registry as its data source. There is no multi-source priority chain -- all data comes from the CBRD.
* **CBRD (Corporate and Business Registration Department)** -- Operated under the Ministry of Finance, Economic Planning and Development, the CBRD is the central company register for Mauritius. The online search portal provides company search, detailed company profiles, and printable extracts. The system retrieves structured data including company name, legal form, status, registration date, registered address, stated capital, business activity, office bearers, and shareholders.
**Performance expectations:** Mauritius is slower than most countries. Searches take several seconds, and full company profiles and document generation take about 30 to 60 seconds. The Speed section of the pricing page has the current figures.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | CBRD | Letter + up to 6 digits (File No.), exactly as issued | `C117853` | The only identifier `/v2/company` accepts. A zero after the letter is part of the number (`C067923`), never padding |
**File No. format:** `/v2/company` accepts the **CBRD File No.** and nothing else: a letter (`C` for companies) followed by up to 6 digits, matching `^[A-Za-z]\d{2,6}$` (e.g. `C117853`, `C61811`, `C067923`). Send it exactly as search returns it: `C61811` and `C061811` are different numbers. Anything else returns `400 Bad Request` with the expected format.
The File No. is **not** the Business Registration Number. The BRN (`125473`, or `C07068818`) identifies a *business registration* under the Business Registration Act, and a company with several registered businesses has several of them — so it is not a per-entity key.
Other numbers you may hold — a BRN, a File No. written without its letter prefix (`61811`), or an FSC global-business licence number (`61811 C1/GBL`, `217346GBC`) — resolve to the File No. through [`/v2/search`](/api-reference/search). Search first, then call `/v2/company` with the `id` it returns.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `brn` | Letter + up to 6 digits, exactly as issued | `C117853` | All registered companies, holds the CBRD **File No.** |
The response key is spelled `brn` for backwards compatibility, but the value it carries is the CBRD File No.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the CBRD File No. returned under `brn` matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
The match uses the CBRD File No., not a Business Registration Number or an FSC licence number.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By File Number | Letter + up to 6 digits | `C117853` | Exact | Exact match returned first (matchType: id); other results may follow |
| By BRN | Letter + 8 digits, or numeric | `C24208879` | Exact | Exact match returned first (matchType: id); other results may follow |
| By licence number or bare File No. | Digits, optionally with a licence category | `61811 C1/GBL`, `217346GBC`, `221058` | Exact | Resolves to the canonical File No. (`C61811`, `C217346`, `C221058`) |
| By Name | Text string | `"MCB GROUP"` | Fuzzy | Multiple results (up to 20) |
**Search resolves what `/v2/company` will not accept.** If you hold a BRN or an FSC global-business licence number, search for it and use the returned `id` — that `id` is always the CBRD File No.
**Mauritius searches are slower than most countries.** Budget several seconds per search (see the Speed section of the pricing page). Prefer a single identifier search over repeated name queries.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies in winding up or liquidation count as inactive and are removed.
## Company Status
Company status is determined **deterministically** from the `statusCode` field in the CBRD data. No AI inference is involved for status mapping.
| Status Code | Local Name | Active? | Notes |
| - | - | - | - |
| `LIVE` | Live | Yes | Verified from CBRD website |
| `ACTIVE` | Active | Yes | |
| `DORMANT` | Dormant | Yes | Registered but temporarily inactive |
| `DEFUNCT` | Defunct | No | Verified from CBRD website |
| `STRUCK` | Struck Off | No | |
| `STRUCK OFF` | Struck Off | No | May appear in either form |
| `DISSOLVED` | Dissolved | No | |
| `WINDING` | Winding Up | No | |
| `WINDING UP` | Winding Up | No | May appear in either form |
| `LIQUIDATION` | In Liquidation | No | |
| `IN LIQUIDATION` | In Liquidation | No | May appear in either form |
The status mapping is fully deterministic with no AI involvement. Dormant companies are still considered active (registered but temporarily inactive). Unknown status codes fall back to checking if the code equals `LIVE` to determine the active flag, and use the raw status code as the local name. Mauritius returns `localName` and `active` only: no `statusDetails` object is returned.
## Legal Forms
Mauritius legal forms are determined **deterministically** from the combination of `orgCategoryCode` and `orgTypeCode` fields in the CBRD data. No AI enrichment is used.
### By Organization Category
| Category Code | Local Name | Standardized | Notes |
| - | - | - | - |
| `DOMESTIC` | Domestic Company | Varies | Most common; see type table below |
| `FOREIGN` | Foreign Company | Branch or Representative Office | Foreign companies registered in Mauritius |
| `GLOBAL BUSINESS COMPANY` | Global Business Company | Limited Liability Company | Licensed under the Financial Services Act |
| `GLOBAL` | Global Business Company | Limited Liability Company | Legacy/abbreviated form |
| `GBC` | Global Business Company | Limited Liability Company | Abbreviation sometimes seen in API |
| `AUTHORISED COMPANY` / `AUTHORISED` | Authorised Company | Other | Unless the organization type sets the form |
### By Organization Type
| Type Code | Combined Local Name | Standardized | English Translation |
| - | - | - | - |
| `PUBLIC` | Public Company (Domestic Company) | Corporation | Public Limited Company |
| `PRIVATE` | Private Company (Domestic Company) | Limited Liability Company | Private Limited Company |
| `CIVIL` | Civil Partnership (category name) | Partnership | Civil Partnership |
| `COMMERCIAL` | Commercial Partnership (category name) | Partnership | Commercial Partnership |
The legal form is constructed by combining the organization type and category (e.g., "Private Company (Domestic Company)"). The standardization logic is fully deterministic: `PUBLIC` maps to Corporation, `PRIVATE` maps to Limited Liability Company, `CIVIL` and `COMMERCIAL` map to Partnership, `FOREIGN` maps to Branch or Representative Office, and `GBC`/`GLOBAL`/`GLOBAL BUSINESS COMPANY` maps to Limited Liability Company. When neither category nor type matches a known code, the standardized form falls back to `Other`.
## Legal Representatives
Legal representatives are extracted from the office bearers listed in the CBRD company details. The extraction is **deterministic** -- no AI is used for role mapping.
### Role Mapping
| Designation (from CBRD) | Standardized Role | Classification |
| - | - | - |
| `DIRECTOR` | Director | Legal Representative |
| `MANAGING DIRECTOR` | Managing Director | Legal Representative |
| Secretary | Secretary | Other Key Person |
| Auditor | Auditor | Other Key Person |
| `REGISTERED AGENT` | Registered Agent | Other Key Person |
| `MANAGEMENT COMPANY` | Other | Other Key Person |
| `GERANT` / `GÉRANT`, Manager | Other | Other Key Person |
| Chief executive / financial officer | C-Level Executive | Other Key Person |
| Chairman | Chairman of the Board | Other Key Person |
| President, unknown or missing designation | Other | Other Key Person |
Director appointments identify the statutory board context. Signing mode and transaction scope require additional authority evidence. A secretary, auditor, registered agent or management company title alone does not establish general representation; a separate director or delegated appointment is needed. The published title list is a reference vocabulary, not an exhaustive register classifier.
### Extraction Logic
| Field | Notes |
| - | - |
| Full name | Individuals: split into firstName (all words except last) and lastName (last word) |
| Role | Mapped to standard role names via substring matching |
| Start date | DD/MM/YYYY format converted to ISO (YYYY-MM-DD) |
| Nationality | Country code (e.g., `MU`) |
| Address | Parsed into a structured address when available |
Corporate office bearers are returned with `type: "company"` and their legal name.
**Resigned officers are excluded.** Office bearers with a `resignationDate` are automatically filtered out. Only currently active officers are included in the response.
## Other Key Persons
The `otherKeyPersons` datapoint returns administrative, audit and service-provider appointments from the same CBRD details. Corporate service providers retain `type: "company"`, their legal name and appointment date. Resigned appointments are excluded. Secretary duties cover board guidance, statutory records and filings under [Companies Act 2001, section 166](https://mof.govmu.org/Documents/2025/Legislations/Companies%20Act.pdf); these duties do not by themselves confer general signing powers.
## Shareholders
Shareholders are extracted from the shareholder list in the CBRD company details using **AI parsing** for type classification (individual vs. company).
### Extraction Logic
| Source | Data Extracted |
| - | - |
| CBRD company details (shareholder list) | Shareholder name, type, number of shares, share value, share percentage, address |
### Ownership Fields
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | CBRD |
| `numberOfShares` | Number of shares held | CBRD |
| `type` | Individual or Company | AI-classified from shareholder details |
Shareholder type classification (individual vs. company) is AI-inferred. The structured fields (number of shares, percentage, value) come directly from the CBRD. If the register publishes shareholders but they cannot be parsed, the `shareholders` datapoint fails as unavailable while `company` and `legalRepresentatives` still succeed. An empty array means the register published no shareholders, which is common for Global Business Companies.
## Activity Code Mapping
Mauritius does **not** return activity codes. The CBRD records the nature of business as **free text**, which is returned in `activityDescription` (multiple activities are separated by semicolons).
The CBRD does not use a standardized activity classification system, and no NACE or ISIC codes are returned for Mauritius. The `activities` object is not populated.
## Data Availability Matrix
| Data Type | Domestic Companies | Foreign Companies | GBC Companies | Notes |
| - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | Full data from CBRD portal |
| Legal Representatives | ✅ | ✅ | ✅ | Statutory director appointments; resigned officers filtered |
| Other Key Persons | ✅ | ✅ | ✅ | Administrative, audit and service-provider appointments where filed |
| Shareholders | ✅ | ⚠️ Limited | ✅ | AI-parsed from the CBRD shareholder list |
| Ultimate Beneficial Owners | ❌ | ❌ | ❌ | Not available from CBRD |
| Establishments | ❌ | ❌ | ❌ | Not available from CBRD |
| Activity Codes | ❌ | ❌ | ❌ | Free-text nature of business in `activityDescription` only |
| Documents | ✅ | ✅ | ✅ | Company Details Extract (PDF) |
| Prefill Profile | ❌ | ❌ | ❌ | `mode: "prefill"` returns `fast_source_unavailable` (422, not billed). Mauritius cannot be answered inside the prefill deadline |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing (\~30-60 seconds)
## Documents by Company Type
### All Companies (File Number)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Company Details Extract** | `tradeRegisterExtract` | PDF | ✅ All registered companies | Generated from CBRD |
The Company Details Extract is generated from the CBRD's printable company details view. This is the **only document type** currently available for Mauritius. Estimated delivery time is approximately 60 seconds.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "MU", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "C117853",
"countryCode": "MU",
"identifiers": {"brn": "C117853"},
"legalName": "Example Mauritius Ltd",
"registrationDate": "2015-03-20",
"activityDescription": "Information technology consulting services",
"status": {"localName": "Live", "active": true},
"legalForm": {"localName": "Private Company (Domestic Company)", "standardized": "Limited Liability Company", "englishTranslation": "Private Limited Company"},
"capital": {"amount": 100000, "currency": "MUR"},
"legalAddress": {"addressLine1": "10 Cybercity, Ebene", "countryCode": "MU"}
},
"legalRepresentatives": [
{"entityId": "person_001", "type": "individual", "role": {"localName": "Director", "standardized": "Director"}, "startDate": "2015-03-20", "individual": {"name": {"fullName": "Rajesh KUMAR", "firstName": "Rajesh", "lastName": "KUMAR"}, "nationality": "MU"}}
],
"shareholders": [
{"entityId": "person_001", "type": "individual", "sharePercentage": 60, "individual": {"name": {"fullName": "Rajesh KUMAR"}}},
{"entityId": "company_001", "type": "company", "sharePercentage": 40, "company": {"legalName": "Holding Group Limited"}}
],
"otherKeyPersons": [
{"entityId": "person_002", "type": "individual", "role": {"localName": "Secretary", "standardized": "Secretary"}, "startDate": "2015-03-20", "individual": {"name": {"fullName": "Priya DEVI", "firstName": "Priya", "lastName": "DEVI"}}}
]
}
```
```json theme={null}
{
"company": {
"id": "C117000",
"countryCode": "MU",
"identifiers": {"brn": "C117000"},
"legalName": "MCB Group Public Ltd",
"registrationDate": "2010-06-15",
"activityDescription": "Investment holding and financial services",
"status": {"localName": "Live", "active": true},
"legalForm": {"localName": "Public Company (Domestic Company)", "standardized": "Corporation", "englishTranslation": "Public Limited Company"},
"capital": {"amount": 5000000, "currency": "MUR"},
"legalAddress": {"addressLine1": "9-15 Sir William Newton Street, Port Louis", "countryCode": "MU"}
},
"legalRepresentatives": [
{"entityId": "person_001", "type": "individual", "role": {"localName": "Director", "standardized": "Director"}, "startDate": "2012-01-10", "individual": {"name": {"fullName": "Alain LAW MIN", "firstName": "Alain", "lastName": "LAW MIN"}, "nationality": "MU"}}
],
"shareholders": [
{"entityId": "company_001", "type": "company", "sharePercentage": 45, "company": {"legalName": "National Insurance Holdings Ltd"}},
{"entityId": "person_002", "type": "individual", "sharePercentage": 15, "individual": {"name": {"fullName": "Pierre GIRAUD"}}}
],
"otherKeyPersons": [
{"entityId": "person_003", "type": "individual", "role": {"localName": "Chairman", "standardized": "Chairman of the Board"}, "startDate": "2010-06-15", "individual": {"name": {"fullName": "Jean-Pierre DALAIS", "firstName": "Jean-Pierre", "lastName": "DALAIS"}}}
]
}
```
```json theme={null}
{
"company": {
"id": "C091940",
"countryCode": "MU",
"identifiers": {"brn": "C091940"},
"legalName": "Global Ventures GBC",
"registrationDate": "2008-11-05",
"activityDescription": "International trading and investment activities",
"status": {"localName": "Live", "active": true},
"legalForm": {"localName": "Global Business Company", "standardized": "Limited Liability Company", "englishTranslation": "Global Business Company"},
"capital": {"amount": 1000, "currency": "USD"},
"legalAddress": {"addressLine1": "Suite 301, Tower A, Business Park", "countryCode": "MU"}
},
"legalRepresentatives": [
{"entityId": "person_001", "type": "individual", "role": {"localName": "Director", "standardized": "Director"}, "individual": {"name": {"fullName": "John SMITH"}}}
]
}
```
**Note:** GBC companies commonly use USD as their stated capital currency. Legal form standardization maps to Limited Liability Company.
```json theme={null}
{
"company": {
"id": "F005000",
"countryCode": "MU",
"identifiers": {"brn": "F005000"},
"legalName": "International Corp (Mauritius Branch)",
"registrationDate": "2018-09-01",
"activityDescription": "Representative office and regional management",
"status": {"localName": "Live", "active": true},
"legalForm": {"localName": "Foreign Company", "standardized": "Branch or Representative Office", "englishTranslation": "Foreign Company"},
"legalAddress": {"addressLine1": "Royal Road, Port Louis", "countryCode": "MU"}
},
"legalRepresentatives": [
],
"otherKeyPersons": [
{"entityId": "person_001", "type": "individual", "role": {"localName": "Manager", "standardized": "Other"}, "individual": {"name": {"fullName": "Marie DUVAL", "firstName": "Marie", "lastName": "DUVAL"}, "nationality": "FR"}}
]
}
```
**Note:** Foreign companies are mapped to Branch or Representative Office. Shareholder data may be limited or unavailable.
```json theme={null}
{
"company": {
"id": "C050000",
"countryCode": "MU",
"identifiers": {"brn": "C050000"},
"legalName": "Old Mauritius Trading Ltd",
"registrationDate": "2000-06-15",
"status": {"localName": "Defunct", "active": false},
"legalForm": {"localName": "Private Company (Domestic Company)", "standardized": "Limited Liability Company"}
}
}
```
**Note:** Defunct companies have `active: false`. Limited data may be available compared to active companies. Legal representatives and shareholders may be empty.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Company Details Extract (PDF) | All registered companies, \~60 second delivery |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Full profiles require additional processing** | Full company details and document generation take about 30 to 60 seconds. |
| **The File No. is not the BRN** | They are different numbers of different lengths (RT Knits: File No. `C067973`, BRN `C07068818`), exposed under two separate radios on the CBRD search. `/v2/company` takes the File No.; search resolves a BRN to it. |
| **Licence numbers are not identifiers** | An FSC global-business licence reference such as `61811 C1/GBL` comes from a different regulator, and the Category 1 licence class was abolished in the 2018 reform. Search resolves it (`C61811`); `/v2/company` rejects it with a 400. |
| **Searches are slow** | Mauritius lookups take several seconds, slower than most countries. Prefer one identifier search over repeated name queries. |
| **Date format is DD/MM/YYYY** | The CBRD API returns dates in DD/MM/YYYY format, which is converted to ISO format (YYYY-MM-DD) internally. Invalid dates (wrong number of parts) return `undefined`. |
| **Currency defaults to MUR** | If no currency is specified in the stated capital, Mauritian Rupee (MUR) is used as the default. USD is also common for GBC companies. Capital is summed across all share types when multiple `statedCapital` entries exist. |
| **Shareholder type is AI-inferred** | The CBRD provides shareholder names but classifying them as individual vs. company requires AI parsing. If published shareholders cannot be parsed, the `shareholders` datapoint fails as unavailable; `company` and `legalRepresentatives` still succeed. |
| **No activity codes** | The CBRD does not provide standardized activity codes, and no NACE or ISIC codes are returned. The free-text nature of business is in `activityDescription`. |
| **Resigned officers are filtered** | Office bearers with a resignation date are automatically excluded from the legal representatives response. |
| **Single document type** | Only the Company Details Extract (PDF) is currently available. No financial statements, articles of association, or UBO documents. |
| **No prefill mode** | `mode: "prefill"` returns `fast_source_unavailable` (422) and is not billed. Mauritius cannot be answered inside the prefill deadline, so request it in the default verification mode. |
| **No UBOs, no establishments** | The CBRD does not expose ultimate beneficial owner data or establishment/branch listings. These fields are always empty. |
| **Status codes may appear in multiple forms** | Some status codes appear in both short and long forms (e.g., `STRUCK` and `STRUCK OFF`, `WINDING` and `WINDING UP`). Both forms are handled identically. |
# Verification vs Prefill Mode
Source: https://docs.topograph.co/essentials/modes
When to use verification mode and when to use the faster prefill mode
Every `/v2/company` request runs in either verification mode or prefill mode. The mode changes the product tradeoff: verification prioritizes authoritative data, while prefill prioritizes fast responses for form prefill.
## At a glance
| Question | Verification | Prefill |
| - | - | - |
| Default? | Yes. Omit `mode` or pass `"verification"`. | No. Pass `mode: "prefill"`. |
| Best for | Final KYB checks, compliance review, due diligence. | Sign-up forms, prefill, early screening, conversion-sensitive flows. |
| Data source | Authoritative official sources for the requested datapoint. | The fastest compatible source for the requested datapoint. It may be authoritative or non-authoritative depending on country. |
| Speed | Can take seconds, minutes, or longer for slow registers. | Has a 10-second deadline per datapoint. |
| Completeness | Optimized for eventual completeness. | Optimized for speed. Unsupported or slow datapoints fail quickly. |
| How to inspect result | Check `request.dataStatus.dataPoints[datapoint].authoritative`. | Same. If `authoritative: false`, follow up with verification before final decisions. |
## Verification mode
Verification is the default. Use it when you need data that can support a compliance decision.
```json theme={null}
{
"countryCode": "IT",
"id": "00484960588",
"dataPoints": ["company", "legalRepresentatives"]
}
```
Verification reflects what the relevant official source records at retrieval time. Register data can still lag filings or reflect local legal conventions, so treat it as authoritative register data, not a guarantee that every real-world fact changed at the same time.
## Prefill mode
Prefill mode is for fast customer-facing flows. It helps you prefill forms and run early checks without making every prospect wait for slower register retrieval.
```json theme={null}
{
"countryCode": "IT",
"id": "00484960588",
"dataPoints": ["company", "legalRepresentatives"],
"mode": "prefill"
}
```
Prefill may use the same official source as verification when that source is fast enough. In other countries it may use a faster non-authoritative source. Always inspect the `authoritative` flag before using the response for final verification.
Prefill is not a shortcut for compliance. Use it to reduce friction early in the flow, then verify when the customer reaches a decision point.
## Timeouts and unsupported datapoints
Prefill mode applies a 10-second deadline to each requested datapoint. If a datapoint cannot finish in time, it fails with `onboarding_timeout`. If the country has no fast source for that datapoint, it fails with `fast_source_unavailable`.
```json theme={null}
{
"request": {
"dataStatus": {
"dataPoints": {
"company": {
"status": "succeeded",
"authoritative": true
},
"shareholders": {
"status": "failed",
"error": {
"code": "fast_source_unavailable",
"message": "No fast source is available for this datapoint in prefill mode. Retry without prefill mode or request a different datapoint."
}
}
}
}
}
}
```
Other datapoints in the same request can still succeed. Retry without `mode: "prefill"` when you need the slower verification path.
### Prefill-only countries
The reverse case exists too. A few countries are served entirely from a non-authoritative source, such as a daily bulk extract of the register, and have no live authoritative lane at all. Because `verification` is the default, a request that omits `mode` resolves nothing for them and the datapoint fails with `authoritative_source_unavailable`.
```json theme={null}
{
"request": {
"dataStatus": {
"dataPoints": {
"company": {
"status": "failed",
"error": {
"code": "authoritative_source_unavailable",
"message": "No authoritative source is available for this datapoint in verification mode. Retry in prefill mode, which serves this datapoint from a non-authoritative source."
}
}
}
}
}
}
```
Send the same request with `"mode": "prefill"` and it succeeds, with `authoritative: false` on the datapoint. Lithuania, Moldova and the British Virgin Islands are prefill-only today; each country page states which modes it supports.
The `graph` datapoint is verification-only. Traversing an ownership graph fans out live register lookups node by node, which cannot complete within the prefill deadline, so `graph` always fails with `fast_source_unavailable` in prefill mode. Nothing is fetched and nothing is billed. Request it with the default `verification` mode.
`availableDocuments` is a document listing datapoint. Its behavior depends on the country document catalog and is not simply a fast-source company-data lookup.
## Staged KYB flow
A common integration pattern is:
1. Search for the company.
2. Request `company` and `legalRepresentatives` with `mode: "prefill"` to prefill the form.
3. Let the customer confirm or correct the prefilled fields.
4. Request verification data and documents before final approval.
5. Use webhooks or polling to process slower verification results.
```bash theme={null}
# Step 1: fast prefill
curl -X POST https://api.topograph.co/v2/company \
-H 'Content-Type: application/json' \
-H 'x-api-key: ' \
-d '{
"countryCode": "IT",
"id": "00484960588",
"dataPoints": ["company", "legalRepresentatives"],
"mode": "prefill"
}'
# Step 2: authoritative verification
curl -X POST https://api.topograph.co/v2/company \
-H 'Content-Type: application/json' \
-H 'x-api-key: ' \
-d '{
"countryCode": "IT",
"id": "00484960588",
"dataPoints": ["company", "legalRepresentatives", "shareholders", "availableDocuments"]
}'
```
## Country availability
Mode availability is country-specific. Some countries use the same authoritative source in both modes; others have a faster prefill source with fewer fields; some datapoints are verification-only.
Use [Coverage and pricing](/essentials/coverage-and-pricing) for the live matrix, or call `GET /v2/pricing?countryCode=FR` from your application.
# Moldova
Source: https://docs.topograph.co/essentials/moldova
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Moldova reference is on the [Moldova country page](https://www.topograph.co/countries/md).
## Start here
This guide contains public integration notes for Moldova. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, sources, identifiers, and availability.
This jurisdiction is in beta. Check the live pricing page or contact support before relying on it in production.
**Moldova is prefill-only.** Every request must pass `"mode": "prefill"`. The country is served from a non-authoritative source, so there is no lane for `verification` — which is what `/v2/company` uses when you omit `mode`. A request without it comes back with the datapoint failed and the error code `authoritative_source_unavailable`. See [Modes](/essentials/modes).
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Moldova has one data source: the **ASP State Register open data**, published weekly by the Public Services Agency (Agenția Servicii Publice) at [dataset.gov.md](https://dataset.gov.md).
The register covers all three categories of legal entities:
* **Commercial entities** — SRL, SA, ÎI, cooperative, branch, and all other commercial legal forms. Includes shareholders and activity codes.
* **Non-commercial organizations** — AO, FND, SND, religious associations, political parties, periodical publications. No shareholders or activity codes.
* **State and central bodies** — Ministries, agencies, and public institutions.
Data reflects the latest published weekly export for commercial and non-commercial entities (up to 7 days lag) and the latest monthly export for state bodies (up to 31 days lag). There is no live query to the register.
## Company Identifiers
### Query Identifiers
| Identifier | Format | Example | Notes |
| - | - | - | - |
| **IDNO** | 13 digits, the last a check digit | `1003603151655` | Numărul de identificare de stat. Primary identifier for all registered entities. A few old records carry a shorter number (e.g. `10013`), returned as published. |
A small number of legacy records (pre-IDNO, registered before \~1995) have no IDNO in the open data. These are assigned a synthetic identifier, `md_noidno_` followed by 12 lowercase hexadecimal characters (e.g. `md_noidno_e251fab5710b`), which stays the same across register updates. It is the company `id` search returns for them, and the `identifiers` object contains `md_synthetic` instead of `idno`.
**IDNO structure:** `1XXXYYYZZZZZK`: the digit 1, the last three digits of the year the number was assigned, a 3-digit code of the registering office, a 5-digit sequence number and a check digit. The check digit is the sum of the first 12 digits weighted 7, 3, 1 (repeating), modulo 10.
### Identifiers in API Response
| Identifier | Format | Example | Notes |
| - | - | - | - |
| `idno` | 13 digits, the last a check digit | `1003603151655` | Present for all standard entities. |
| `md_synthetic` | `md_noidno_` + 12 lowercase hex chars | `md_noidno_e251fab5710b` | Present only for legacy pre-IDNO records; also their company `id`. |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the IDNO (`idno`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Example | Match type | Notes |
| - | - | - | - |
| By IDNO (exact) | `1003603151655` | `id` | Exact match returned first; other results may follow. |
| By synthetic id (exact) | `md_noidno_e251fab5710b` | `id` | For legacy records without an IDNO. |
| By name (partial) | `GASTO` | `default` (`exactLegalName` on an exact name match) | Full-text search. Returns up to 20 results. |
Both Romanian (Latin) and Cyrillic company names are indexed. Older records (pre-2000) may have names in Cyrillic script.
Search is free. Only company profile retrieval is charged.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies in liquidation or insolvency count as inactive and are removed.
## Supported Entity Types
| Entity type | Supported | Notes |
| - | - | - |
| Commercial companies | Yes | SRL, SA, SAID, SAIC, SNC, SC, and all other commercial forms |
| Sole traders | Yes | ÎI (Întreprindere individuală), IIA (agricultural) |
| Non-commercial organizations | Yes | AO, FND, SND, religious, political, and other non-profits |
| State and central bodies | Yes | Ministries, agencies, public institutions |
| Dissolved / deregistered | Yes | Included in the open data with a deregistration date |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No live register access** | All data comes from weekly/monthly bulk exports. Real-time queries are not available. |
| **Data lag** | Commercial and non-commercial data is up to 7 days old. State bodies data is up to 31 days old. |
| **No shareholder data for non-commercial and state bodies** | The non-commercial and state bodies datasets do not include a founders/shareholders column. `shareholders` is always absent for these entity types. |
| **Shareholders \~80% coverage** | Approximately 20% of active commercial entities (mainly sole traders ÎI) have no shareholder data in the open data. |
| **ALL CAPS names** | All person names in the raw data are in ALL CAPS. Topograph applies title-casing at ingest time. |
| **Mixed scripts** | \~0.6% of records have names or representatives in Cyrillic script, mainly pre-2000 registrations. Both scripts are searchable. |
| **CAEM division-level codes** | Some entities carry a division-level activity code (e.g. `1300` = all textile manufacturing) rather than a specific 4-digit class. These are mapped to the division-level NACE and ISIC descriptions. |
## Mappings
### Company Status
Status is derived at ingest time from two fields: the deregistration date and role labels in the management column. No explicit status field exists in the open data.
| Local status | English | Standardized status | Closure reason |
| - | - | - | - |
| Activ | Active | `ACTIVE` | — |
| Radiat | Deregistered | `CLOSED` | `LIQUIDATION` |
| În proces de lichidare | In liquidation process | `CLOSED` | `LIQUIDATION` |
| Insolvabil | Insolvent | `UNDER_INSOLVENCY_PROCEEDING` | — |
### Legal Forms
The pricing page lists 48 Moldovan legal forms: 35 commercial, 12 non-commercial, and 1 for state bodies. The most common:
| Local name | English | Standardized |
| - | - | - |
| Societate cu răspundere limitată | Limited Liability Company | Limited Liability Company |
| Întreprindere individuală | Individual Enterprise (sole trader) | Sole Proprietorship |
| Societate pe acţiuni | Joint Stock Company | Corporation |
| Societate pe acţiuni de tip deschis | Open Joint Stock Company | Corporation |
| Societate pe acţiuni de tip închis | Closed Joint Stock Company | Corporation |
| Întreprindere de stat | State Enterprise | Government-Owned Entity |
| Întreprindere municipală | Municipal Enterprise | Government-Owned Entity |
| Cooperativă de producţie | Production Cooperative | Cooperative |
| Societate în nume colectiv | General Partnership | Partnership |
| Societate în comandită | Limited Partnership | Partnership |
| Sucursala întreprinderii nerezidente străine | Branch of a Foreign Non-Resident Enterprise | Branch or Representative Office |
| Asociaţie obştească | Public Association (NGO) | Nonprofit Organization |
| Fundaţie | Foundation | Nonprofit Organization |
| Sindicat | Trade Union | Nonprofit Organization |
See the pricing page for the complete list.
### Legal Representatives
The known catalogue contains 13 source labels, including the generic head designation for state bodies. Registered administrators and liquidators carry their appointment-specific powers; the open data does not establish a sole or joint signing rule.
| Local role | English | Standardized |
| - | - | - |
| Administrator | Director / Manager | Director |
| Conducător | Head / Chief Executive | Director |
| Administrator provizoriu | Provisional Administrator | Administrator |
| Administrator fiduciar | Fiduciary / Trustee Administrator | Administrator |
| Administrator special | Special Administrator | Administrator |
| Administrator din oficiu | Ex officio Administrator | Liquidator |
| Lichidator | Liquidator | Liquidator |
| Administrator al procesului de insolvabilitate | Insolvency Administrator | Receiver |
| Administrator al procedurii planului | Plan Procedure Administrator | Receiver |
### Other Key Persons
Collective-body appointments appear in `otherKeyPersons`. Both individuals and corporate holders are retained when the source identifies them. An unfamiliar appointment remains visible without an assumed signing mandate.
| Local role | English | Standardized |
| - | - | - |
| Direcţie de conducere | Management Board / Board of Directors | Board Member |
| Birou executiv | Executive Office / Board | Board Member |
| Comitet | Committee | Board Member |
| Comisia | Commission / Board | Board Member |
### Activity Codes
Moldova uses **CAEM\_REV2** (Clasificarea Activităților din Economia Moldovei, Rev. 2), which is identical in structure to NACE Rev. 2.
For each CAEM\_REV2 code, the response includes:
| System | Example code | Description source |
| - | - | - |
| `CAEM_REV2` | `6201` | Official BNS nomenclature (Romanian) |
| `NACE` | `62.10` | NACE Rev. 2.1 English description |
| `ISIC` | `621` | Derived via UN NACE↔ISIC correspondence table |
**One code in, one code out.** You get one `NACE` and one `ISIC` code per declared CAEM\_REV2 code. Where a CAEM\_REV2 code has no single equivalent in the target revision, the shared parent class is returned rather than every candidate — see [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
Some older records carry 5-digit legacy **CAEM\_REV11** codes (pre-2005 classification). These are returned under the `CAEM_REV11` key with no NACE or ISIC equivalent.
```
CAEM_REV2 (4-digit) → NACE Rev. 2.1 → ISIC Rev. 5
CAEM_REV11 (5-digit) → no mapping (legacy)
```
## Data Availability
| Data type | Available | Notes |
| - | - | - |
| Company profile | Yes | Name, legal form, status, registration date, address |
| Legal representatives | Yes | Commercial and non-commercial entities |
| Other key persons | Yes | Board and collective appointments; source-dependent coverage |
| Shareholders | Partial | Commercial entities only; \~80% coverage |
| Activity codes (CAEM\_REV2/NACE/ISIC) | Yes | Commercial entities only |
| Ultimate beneficial owners | No | Not in open data |
| Documents | No | Batch-only integration; no detail page to print |
| Financial statements | No | Not published in open data |
## Example API Responses
Query: `POST /v2/company` with `{ "id": "1003603151655", "countryCode": "MD", "dataPoints": ["company", "legalRepresentatives", "shareholders"] }`
```json theme={null}
{
"company": {
"id": "1003603151655",
"countryCode": "MD",
"identifiers": { "idno": "1003603151655" },
"legalName": "Gasto S.R.L.",
"registrationDate": "2003-05-12",
"status": {
"localName": "Activ",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Societate cu răspundere limitată",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"activities": {
"CAEM_REV2": [{ "code": "5610", "description": "Restaurante" }],
"NACE": [{ "code": "56.1", "description": "Restaurants and mobile food service activities" }],
"ISIC": [{ "code": "5610", "description": "Restaurants and mobile food service activities" }]
},
"legalAddress": {
"addressLine1": "MD-2001, CHIȘINĂU, mun. Chișinău, str. Pushkin, 22",
"city": "Chișinău",
"postalCode": "MD-2001",
"countryCode": "MD"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Administrator", "standardized": "Director" },
"individual": { "name": { "fullName": "Popescu Ion" } }
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 100,
"individual": { "name": { "fullName": "Popescu Ion" } }
}
]
}
```
Query: `POST /v2/company` with `{ "id": "1002600001305", "countryCode": "MD", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "1002600001305",
"countryCode": "MD",
"identifiers": { "idno": "1002600001305" },
"legalName": "Asociația Uniunea Producătorilor de Zahăr din Moldova",
"registrationDate": "1998-04-21",
"status": {
"localName": "Activ",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Asociaţie obştească",
"englishTranslation": "Public Association (NGO)",
"standardized": "Nonprofit Organization"
},
"legalAddress": {
"addressLine1": "MUN.CHISINAU, SEC.CENTRU, str. Timiș, 19",
"countryCode": "MD"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Administrator", "standardized": "Director" },
"individual": { "name": { "fullName": "Cuneac Mihail" } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "md_noidno_e251fab5710b",
"countryCode": "MD",
"identifiers": { "md_synthetic": "md_noidno_e251fab5710b" },
"legalName": "Colhozul \"Moldova\"",
"registrationDate": "1993-02-25",
"status": {
"localName": "Radiat",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "LIQUIDATION",
"closureDate": "1999-12-20"
}
},
"legalForm": {
"localName": "Colhoz",
"englishTranslation": "Collective Farm (Kolkhoz)",
"standardized": "Other"
},
"activities": {
"CAEM_REV2": [{ "code": "1300" }],
"NACE": [{ "code": "13", "description": "Manufacture of textiles" }],
"ISIC": [{ "code": "13", "description": "Manufacture of textiles" }]
},
"legalAddress": {
"addressLine1": "MD-4219, ȘTEFAN VODĂ, ERMOCLIA",
"city": "Ermoclia",
"postalCode": "MD-4219",
"countryCode": "MD"
}
}
}
```
Query: `POST /v2/company` with `{ "id": "1006601000037", "countryCode": "MD", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "1006601000037",
"countryCode": "MD",
"identifiers": { "idno": "1006601000037" },
"legalName": "Ministerul Finanțelor",
"status": {
"localName": "Activ",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Organ central / Autoritate publica",
"englishTranslation": "Central Body / Public Authority",
"standardized": "Government-Owned Entity"
},
"legalAddress": {
"addressLine1": "mun. Chișinău, sec. Rîșcani, str. Constantin Tănase 7",
"countryCode": "MD"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Conducător", "standardized": "Director" },
"individual": { "name": { "fullName": "Petru Rotaru" } }
}
]
}
```
# Monaco
Source: https://docs.topograph.co/essentials/monaco
Country-specific identifiers, data sources, and data availability
This guide is outdated and will be removed on 1 November 2026. The up-to-date Monaco reference is on the [Monaco country page](https://www.topograph.co/countries/mc).
## Start here
This guide contains public integration notes for Monaco. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Monaco uses a single official registry, the **RCI** (Répertoire du Commerce et de l'Industrie). For a given entity, **data comes from this sole source**. In verification mode, company data is extracted from the official trade register extract PDF using AI parsing. Prefill mode reads the public extract preview.
### All company types
* **RCI (Répertoire du Commerce et de l'Industrie)**: The official Monaco business register, operated by the Direction du Développement Economique (Business Development Agency) under the Prince's Government of Monaco. The RCI registers all commercial activities, companies other than non-trading companies, and economic interest groups in the Principality. Registration is mandatory within two months of commencing activity. The RCI provides three access methods:
* **Public search**: Returns the company name and RCI number. Used for **search** by name or RCI number.
* **Extract preview**: A public preview of company information (name, legal form, status, activity description, address, NIS number). Used for **prefill mode**, which returns these values as published by the register, without AI enrichment.
* **Trade Register Extract (Paid PDF)**: The official certified extract (Extrait du RCI), retrieved as a paid document (see [pricing](https://www.topograph.co/pricing)) through the RCI portal. Used as the **primary source for full company profiles**. The PDF is parsed by AI to extract comprehensive company data including legal representatives, capital, detailed activity descriptions, and incorporation dates.
In verification mode, `company` and `legalRepresentatives` require retrieving the trade register extract PDF (paid document, see [pricing](https://www.topograph.co/pricing)). The document is automatically retrieved and then parsed by AI for structured data extraction. Retrieved documents are deduplicated to avoid duplicate charges.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **Commercial companies (S)** | RCI | 2 digits + `S` + 5 digits | `99S03612` | SAM, SARL, SCS |
| **Civil entities (C)** | RCI | 2 digits + `C` + 5 digits | `18C21017` | Sociétés civiles |
| **Sole traders (P)** | RCI | 2 digits + `P` + 5 digits | `80P04049` | Natural persons trading in their own name |
**RCI Number Format Breakdown:** `99S03612` = `99` (two digits) + `S` (entity type) + `03612` (sequence number), 8 characters in all. Leading zeros are significant (`07C12518`). In the records we have seen, the letter matches the legal form the register shows: **S** = commercial company, **C** = civil company (e.g. SCI, SCP), **P** = natural person trading in their own name.
**Legacy Alias Format:** Some RCI numbers use `SC` instead of `C` for civil entities (e.g., `18SC21017`). Topograph treats this as a **legacy alias** for the canonical form `18C21017`. Search accepts both formats and always returns the canonical ID. All `/v2/company` requests and document retrieval calls require the canonical ID and will return **not found** if the alias is used.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `rci` | 2 digits + `S`, `C` or `P` + 5 digits | `99S03612` | All entities |
| `statisticalIdentificationNumber` | NAF code of the main establishment (4 digits + a letter) + 5-digit sequence | `6630Y08763` | Prefill mode, when available in the extract preview |
Monaco's tax administration issues intra-EU VAT numbers to Monegasque businesses, but the register does not publish them, so the response carries no VAT identifier.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the RCI number (`rci`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By RCI Number | `\d{2}[A-Z]{1,2}\d{4,5}` | `99S03612` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 2 chars) | `"JULIUS BAER"` | Fuzzy | Multiple results (up to 50) |
**Search uses the RCI public register search.** Name searches support French and English terms with fuzzy matching and return up to 50 results.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Document retrieve required in verification mode** | Verification-mode company data requires retrieving the trade register extract (paid document, see [pricing](https://www.topograph.co/pricing)). The document is automatically retrieved and deduplicated to avoid duplicate charges. |
| **Verification data is AI-parsed** | Unlike most countries where data comes from structured APIs, Monaco verification-mode company data is entirely AI-extracted from a PDF document. Quality depends on document layout consistency. |
| **All activity codes are AI-inferred** | The RCI provides only a free-text activity description. NACE and ISIC codes are always AI-inferred. `isAIInferred` is always `true`. |
| **RCI number canonical format** | The `SC` variant (e.g., `18SC21017`) is a legacy alias. Always use canonical form (`18C21017`). Non-canonical IDs return "not found" on non-search endpoints. |
| **No shareholder data** | Monaco trade register extracts do not contain shareholder information. This data point is not available. |
| **No UBO data** | Ultimate beneficial owner declarations exist in Monaco (required since Law No. 1.362 of 2009) but are not publicly accessible via the RCI. |
| **No establishment data** | The RCI does not provide structured establishment/branch data. |
| **French-only documents** | All official trade register documents are in French. AI parsing handles French-to-English translation of roles and legal forms. |
| **No VAT identifiers** | Monaco's tax administration issues intra-EU VAT numbers to Monegasque businesses, but the register does not publish them, so responses carry no VAT identifier. |
| **Phone numbers sometimes available** | Trade register extracts occasionally include phone numbers, which are extracted when present. |
| **NIS (Statistical Identification Number)** | The NIS is issued by IMSEE (Monaco Statistics) and may appear in extract previews as a secondary identifier. |
| **Duplicate retrieve prevention** | The paid extract is ordered once per company, so concurrent requests do not cause duplicate charges. |
## Mappings
### Company Status
Company status is determined differently depending on the data source:
* **Prefill mode**: Status comes from the register's extract preview. Simple keyword matching: "active" or "actif" maps to Active, anything else maps to Closed.
* **Company Profile**: Status is **AI-parsed** from the trade register extract PDF.
| Local Status | English Translation | Standardized Status | Notes |
| - | - | - | - |
| ACTIVE | Active | Active | Standard active status from extract preview |
| Actif / Active | Active | Active | French/English variant from extract |
| RADIATION\_DEFINITIVE | Definitively struck off | Closed | Company permanently removed from register |
| RADIEE | Struck off | Closed | Variant for struck-off companies |
| EN LIQUIDATION | In Liquidation | Closed | Company undergoing liquidation |
For the prefill profile, status uses simple keyword matching (contains "active" or "actif" = Active, otherwise Closed). For the full company profile, status is AI-parsed from the trade register extract, providing richer detail.
### Legal Forms
Monaco legal forms are sourced from the RCI register. The local legal form name (in French) is preserved. In verification mode, it is enriched with English translation, standardized category, and ISO 20275 code via AI. Prefill mode returns the local name only.
Legal form standardization and ISO 20275 assignment are **AI-enriched**. There is no static deterministic lookup table. The local French legal form name is always preserved verbatim from the RCI register. ISO 20275 codes may not be available for all Monaco-specific legal forms.
| French Local Name | Abbreviation | English Translation | Standardized Form | ISO 20275 |
| - | - | - | - | - |
| Societe Anonyme Monegasque | SAM | Monegasque Public Limited Company | Corporation | CWTQ |
| Societe a Responsabilite Limitee | SARL | Limited Liability Company | Limited Liability Company | DA06 |
| Societe en Nom Collectif | SNC | General Partnership | Partnership | TU6A |
| Societe en Commandite Simple | SCS | Limited Partnership | Partnership | 528Z |
| Societe en Commandite par Actions | SCA | Partnership Limited by Shares | Corporation | PIL2 |
| Societe Civile Particuliere | SCP | Civil Partnership | Partnership | GWZF |
| Personne Physique | - | Sole Trader | Sole Proprietorship | - |
| Succursale | - | Branch Office | Branch or Representative Office | - |
Monaco's legal forms are governed by specific Monegasque legislation (e.g., Law No. 408 of 1945 for SAMs, Law No. 797 of 1966 for SARLs). While similar to French forms, they are distinct legal entities under Monegasque law. For example, the SAM (Societe Anonyme Monegasque) is unique to Monaco and differs from the French SA.
### Legal Representatives
Legal representatives are extracted from the **trade register extract** PDF using AI parsing. This data is only available in the full company retrieval flow, not in prefill mode requests for `company`.
| Aspect | Details |
| - | - |
| **Source** | Trade register extract (Extrait du RCI) PDF |
| **Method** | AI parsing of document text |
| **Availability** | Full company retrieval only (not prefill mode `company`) |
| **AI-inferred** | Yes, extraction from PDF is entirely AI-based |
| **Role enrichment** | Roles are enriched with ISO 5009 standardized names and English translations via AI |
#### Common Legal Representative Roles
| French Role | English Translation | Typical Legal Forms |
| - | - | - |
| Gerant | Manager | SARL, SNC, SCS |
| Co-gerant | Co-Manager | SARL |
| Administrateur | Director | SAM |
| Administrateur-delegue | Managing Director | SAM |
| President | Chairman | SAM |
| Vice-president | Vice Chairman | SAM |
| Directeur | Director | All |
| Directeur general | General Manager | SAM |
| Mandataire | Agent | All |
| Representant legal | Legal Representative | All |
| Pouvoir de signature | Authorized Signatory | All |
Role classification as legal representative vs. other key person is **AI-determined** based on the company's legal form context. Both individuals and corporate entities can hold legal representative roles in Monaco. The AI prompt specifically targets standard Monegasque roles: Gerant, Co-gerant, Administrateur, Administrateur-delegue, President, Vice-president, Directeur, Directeur general, Mandataire, Representant legal, and Pouvoir de signature.
### Shareholders
Shareholders are **not available** for Monaco. The trade register extract does not contain shareholder information. Ownership data is not publicly accessible through the RCI.
### Activity Code Mapping
Monaco uses the French **NAF** classification, but the RCI register publishes only a free-text activity description in French (`activityDescription`). Activity codes are **entirely AI-inferred** from that description, in verification mode only.
```
Activity Description (free text, French) --> NACE Rev. 2 (AI-inferred) --> ISIC Rev. 4 (AI-inferred)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NACE** | Derived from activity description via AI | `46.49` | Yes (always) |
| **ISIC** | Derived from NACE via AI | `4649` | Yes (always) |
Both NACE and ISIC codes are **always AI-inferred** for Monaco companies because the RCI register provides only a free-text activity description, not structured activity codes. The `isAIInferred` flag is always `true` for Monaco activity codes. Activity codes are returned in verification mode only (from the trade register extract PDF). Prefill mode returns the raw `activityDescription` without codes.
## Data Availability
### Data Availability Matrix
| Data Type | Prefill Profile | Company Profile | Notes |
| - | - | - | - |
| Company Name | ✅ | ✅ | From extract preview / trade register extract |
| Legal Form | ✅ Local name only | ✅ AI-enriched | Verification: enriched with English translation + ISO 20275 |
| Status | ✅ Basic | ✅ AI-parsed | Prefill: keyword matching on the extract preview; Profile: AI-parsed |
| Address | ✅ Single line | ✅ AI-parsed | Prefill: full address in `addressLine1`; Profile: structured fields |
| Activity Description | ✅ | ✅ | Free-text field in French |
| Activity Codes (NACE/ISIC) | ❌ | ✅ AI-inferred | Always AI-inferred from activity description |
| Capital | ❌ | ✅ AI-parsed | Only in trade register extract |
| Registration/Incorporation Date | ❌ | ✅ AI-parsed | Only in trade register extract |
| Legal Representatives | ❌ | ✅ AI-parsed | Only in trade register extract |
| Shareholders | ❌ | ❌ | Not available in Monaco |
| Ultimate Beneficial Owners | ❌ | ❌ | Not publicly accessible |
| Establishments | ❌ | ❌ | Not available |
| Phone Numbers | ❌ | ⚠️ | Sometimes available in trade register extract |
| Website | ❌ | ⚠️ | Sometimes available in trade register extract |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available
### Documents by Company Type
All entities registered with the RCI have access to the same document type:
| Document Type | API Category | Format | Cost | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | Paid, see [pricing](https://www.topograph.co/pricing) | Official Extrait du RCI; automatically retrieved for `company` in verification mode; deduplicated to avoid duplicates |
**Paid Document:** The trade register extract is a paid retrieve (see [pricing](https://www.topograph.co/pricing)). When requesting `company` or `legalRepresentatives` in verification mode, this document is automatically retrieved. It is ordered once per company, so retrieved documents are deduplicated to avoid duplicate charges.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "MC", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "18S01234",
"countryCode": "MC",
"identifiers": {
"rci": "18S01234"
},
"legalName": "EXAMPLE SARL",
"commercialNames": ["EXAMPLE BRAND"],
"registrationDate": "2018-01-15",
"incorporationDate": "2018-01-15",
"phones": ["+37712345678"],
"activityDescription": "En Principaute de Monaco et a l'etranger : import-export, ventes en gros, commissions, courtage, representation, achats et ventes aux professionnels et aux particuliers d'articles d'habillement, d'equipement de la personne et de la maison.",
"status": {
"localName": "Active",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "SOCIETE A RESPONSABILITE LIMITEE",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "DA06"
},
"capital": {
"amount": 15000,
"currency": "EUR"
},
"activities": {
"NACE": [
{
"code": "46.49",
"description": "Wholesale of other household goods",
"isAIInferred": true
}
],
"ISIC": [
{
"code": "4649",
"description": "Wholesale of other household goods",
"isAIInferred": true
}
]
},
"legalAddress": {
"addressLine1": "1 Avenue de la Principaute",
"city": "MONACO",
"postalCode": "98000",
"countryCode": "MC"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"startDate": "2020-01-01",
"role": {
"localName": "GERANT",
"englishTranslation": "Manager",
"standardized": "Manager"
},
"individual": {
"nationality": "MC",
"name": {
"fullName": "Jean Pierre Dupont",
"firstName": "Jean Pierre",
"lastName": "Dupont",
"title": "M."
},
"birthDate": {
"day": 15,
"month": 3,
"year": 1985
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "96S03173",
"countryCode": "MC",
"identifiers": {
"rci": "96S03173"
},
"legalName": "EXAMPLE BANK S.A.M.",
"registrationDate": "1996-03-08",
"incorporationDate": "1996-02-15",
"activityDescription": "Operations de banque et de credit, operations de change, gestion de fortunes, conseil en investissement et toutes activites connexes.",
"status": {
"localName": "Active",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Societe Anonyme Monegasque",
"englishTranslation": "Monegasque Public Limited Company",
"standardized": "Corporation",
"iso20275Code": "CWTQ"
},
"capital": {
"amount": 12000000,
"currency": "EUR"
},
"activities": {
"NACE": [
{
"code": "64.19",
"description": "Other monetary intermediation",
"isAIInferred": true
}
],
"ISIC": [
{
"code": "6419",
"description": "Other monetary intermediation",
"isAIInferred": true
}
]
},
"legalAddress": {
"addressLine1": "10 Boulevard des Moulins",
"city": "MONTE-CARLO",
"postalCode": "98000",
"countryCode": "MC"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "PRESIDENT",
"englishTranslation": "Chairman",
"standardized": "Chairman"
},
"individual": {
"name": {
"fullName": "Marie Claire Martin",
"firstName": "Marie Claire",
"lastName": "Martin"
},
"birthDate": {
"month": 7,
"year": 1970
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "ADMINISTRATEUR-DELEGUE",
"englishTranslation": "Managing Director",
"standardized": "Managing Director"
},
"individual": {
"name": {
"fullName": "Philippe Bernard",
"firstName": "Philippe",
"lastName": "Bernard"
},
"birthDate": {
"month": 11,
"year": 1975
}
}
}
]
}
```
Query: `POST /v2/company` with `{ "id": "21P07125", "countryCode": "MC", "mode": "prefill", "dataPoints": ["company"] }`
```json theme={null}
{
"company": {
"id": "21P07125",
"countryCode": "MC",
"identifiers": {
"rci": "21P07125"
},
"legalName": "Sophie Laurent",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Personne Physique"
},
"activityDescription": "Design graphique et decoration d'interieur.",
"legalAddress": {
"addressLine1": "3 Rue Grimaldi 98000 MONACO",
"countryCode": "MC"
}
}
}
```
**Note:** Prefill mode is a lightweight, fast response. It returns the values published on the extract preview as-is: the local legal form name, the full address in `addressLine1`, and the free-text activity description. It does not include activity codes, legal representatives, capital, or incorporation date.
```json theme={null}
{
"company": {
"id": "85S02456",
"countryCode": "MC",
"identifiers": {
"rci": "85S02456"
},
"legalName": "Ancienne Boutique SARL",
"registrationDate": "1985-06-20",
"incorporationDate": "1985-05-10",
"activityDescription": "Commerce de detail de vetements et accessoires de mode.",
"status": {
"localName": "Radiee",
"active": false,
"statusDetails": {
"status": "CLOSED"
}
},
"legalForm": {
"localName": "SOCIETE A RESPONSABILITE LIMITEE",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "DA06"
},
"capital": {
"amount": 7500,
"currency": "EUR"
},
"activities": {
"NACE": [
{
"code": "47.71",
"description": "Retail sale of clothing in specialised stores",
"isAIInferred": true
}
],
"ISIC": [
{
"code": "4771",
"description": "Retail sale of clothing, footwear and leather articles in specialised stores",
"isAIInferred": true
}
]
},
"legalAddress": {
"addressLine1": "15 Rue de la Turbie",
"city": "MONACO",
"postalCode": "98000",
"countryCode": "MC"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "GERANT",
"englishTranslation": "Manager",
"standardized": "Manager"
},
"individual": {
"name": {
"fullName": "Pierre Durand",
"firstName": "Pierre",
"lastName": "Durand"
},
"birthDate": {
"month": 9,
"year": 1960
}
}
}
]
}
```
**Note:** Closed companies have `active: false` and a status like "Radiee" (struck off). The trade register extract is still available for retrieve for closed companies.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Format | Cost | Notes |
| - | - | - | - | - |
| `tradeRegisterExtract` | Official Extrait du RCI | PDF | Paid, see [pricing](https://www.topograph.co/pricing) | All registered entities |
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_abc123",
"name": "Trade register extract",
"description": "Trade register extract from Monaco RCI",
"format": "pdf"
}
}
}
```
# Company Monitoring
Source: https://docs.topograph.co/essentials/monitoring
Documentation on the feature to track company changes
## Supported Countries for Monitoring
Monitoring is available in many countries. See the full list and live coverage at [topograph.co/pricing](https://topograph.co/pricing).
Monitoring availability and commercial terms are account-specific. Use the pricing page and dashboard for the current source of truth before enabling monitoring at scale.
## What is Monitoring?
Topograph provides automated, continuous tracking of company data in official registers in the supported countries.
Each check compares the company's register data with the previous check, categorizes what changed, and delivers a webhook notification when something important happened.
Think of it as a watchdog for public company data that:
* **Checks regularly** for changes in the register for monitored companies (daily in most countries)
* **Ignores noise**: a difference that only comes from how the data is formatted or ordered, or a value the register keeps switching back and forth, is not reported
* **Notifies you instantly** when significant changes occur
* **Auto-deactivates** when companies cease to exist
In Italy, changes come from the register's own weekly update rather than a daily check, so a notification can arrive up to about a week after the change was registered.
## Core Concepts
### Monitor
A **Monitor** tracks a specific company in a specific country for changes. When you create a monitor, you'll receive notifications whenever significant changes occur in that company's data.
### Change Categories
Each detected change is assigned one of 7 categories, by fixed rules on the field that changed, to help you route and prioritize notifications:
1. **`status`** - Legal lifecycle events (bankruptcy, liquidation, dissolution)
2. **`address`** - Registered address or jurisdiction changes
3. **`ownership`** - Beneficial ownership or shareholding changes
4. **`financial`** - Share capital changes
5. **`legalRepresentatives`** - Legal representatives, directors, authorized signatories, or other key persons
6. **`other`** - Any other meaningful change (name, activities, financial figures other than share capital)
7. **`disappeared`** - Company no longer exists in register (triggers deactivation)
### Credential-Gated Datapoints
A small number of datapoints require your own account credentials for a third-party register -- for example, `ultimateBeneficialOwners` in Germany is sourced from the Transparenzregister, which by law only grants access to obliged entities making their own AML/KYC check (see the [Germany](https://www.topograph.co/countries/de) page). If you monitor a company in one of these countries without configuring the required [register credentials](/essentials/register-credentials) on your workspace:
* The monitor is still created and all other datapoints are unaffected.
* The response from `POST /v2/monitors` includes a `datapointNotices` array naming the affected datapoint and pointing you at the vault.
* The datapoint is skipped on scheduled rechecks rather than failing silently every day -- once you configure the credential, it resumes automatically on the next check.
* You'll receive a one-time `monitor.datapoint_blocked` webhook when the datapoint becomes unavailable, and `monitor.datapoint_unblocked` once you've configured credentials and it resumes. These fire once per transition, not on every daily recheck.
## Getting Started
### Step 1: Create a Monitor
To start monitoring a company, send a POST request:
```bash theme={null}
curl -X POST https://api.topograph.co/v2/monitors \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-d '{
"companyId": "932884117",
"countryCode": "FR",
"metadata": {
"caseId": "case-12345"
}
}'
```
**Response:**
```json theme={null}
{
"id": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"metadata": {
"caseId": "case-12345"
}
}
```
**Important:** The `id` returned is your Monitor ID, which you can use to stop monitoring for the related company.
`metadata` is optional: arbitrary key-value string pairs stored on the monitor and echoed back in monitor responses and in every `monitor.notification` webhook. Use it to map notifications back to your internal records, such as a case or customer ID. Calling `POST /v2/monitors` again for the same company replaces the stored metadata when the field is provided. Limits: max 50 keys, keys up to 40 characters (longer keys are skipped), values up to 500 characters (longer values are truncated).
### Step 2: Configure Webhooks
Webhooks are configured at the account level. All monitors for your account send notifications to the same webhook endpoint(s).
### Step 3: Handle Webhook Events
When changes are detected, you'll receive a webhook with this structure:
```json theme={null}
{
"type": "monitor.notification",
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T14:23:45.678Z",
"changeCategories": ["status", "financial"],
"monitorHasBeenDeactivated": false,
"metadata": {
"caseId": "case-12345"
}
}
```
### Step 4: Test Your Integration
You don't have to wait for a real change to validate your integration. From a monitor's page in the dashboard, click **Send Test Notification** to deliver a real `monitor.notification` for that monitor to your webhook endpoint.
The event is built exactly as a genuine change notification is: your own `monitorId`, your own `metadata`, the real company. This matters if your workflow routes on `metadata` you set at monitor creation, because the generic sample payload in the webhooks portal carries neither.
You can choose the change category, and optionally send the deactivation variant (`changeCategories: ["disappeared"]` with `monitorHasBeenDeactivated: true`) to exercise your cleanup branch. Your monitor stays active and its next scheduled check is unaffected.
The same call is available on the API:
```bash theme={null}
curl -X POST https://api.topograph.co/v2/monitors/{monitorId}/test-notification \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "changeCategories": ["status"] }'
```
Both fields are optional; the default is `{"changeCategories": ["other"], "monitorHasBeenDeactivated": false}`. The response echoes the exact payload delivered.
A test notification is deliberately indistinguishable from a real one, so that what you test is what you'll get in production. There is no test flag in the payload. If your pipeline opens a case for every notification, a test will open a real case.
## Webhook Payload Deep Dive
### Understanding Each Field
#### `monitorId` (string)
* **What it is:** Unique identifier for the monitor, the same `id` returned by `POST /v2/monitors`
* **Format:** CUID (e.g., "clh3k9n0x000008l63vog8wkp")
* **Use case:** Track which monitor triggered the notification, look it up with `GET /v2/monitors/{id}`, or stop it with `DELETE /v2/monitors/{id}`
#### `companyId` (string)
* **What it is:** The company's official register number
* **Examples:** "932884117" (France), "Augsburg HRB 34617" (Germany)
* **Use case:** Match to your internal company records
#### `countryCode` (string)
* **What it is:** ISO 3166-1 alpha-2 country code
* **Examples:** "FR", "DE", "GB", "IT"
* **Use case:** Route to country-specific handlers
#### `timestamp` (string)
* **What it is:** When the change was detected (not when it occurred)
* **Format:** ISO 8601 UTC (e.g., "2025-09-26T14:23:45.678Z")
* **Use case:** Order and deduplicate events
#### `changeCategories` (array of strings)
* **What it is:** Types of changes detected (can be multiple)
* **Possible values:**
* `"status"` - Legal status changed (active → liquidation)
* `"address"` - Registered address changed
* `"ownership"` - Shareholders or UBO changed
* `"financial"` - Share capital changed
* `"legalRepresentatives"` - Legal representatives, directors or other key persons changed
* `"other"` - Other changes (name, activities, etc.)
* `"disappeared"` - Company no longer exists
* **Examples:**
* `["status"]` - Company entered bankruptcy
* `["address", "financial"]` - Moved offices AND updated capital
* `["disappeared"]` - Company dissolved and removed from register
* **Use case:** Route to appropriate teams/systems
#### `metadata` (object, optional)
* **What it is:** The key-value pairs you provided when creating the monitor
* **Example:** `{ "caseId": "case-12345" }`
* **Use case:** Map the notification back to your internal records without keeping your own monitor-to-case mapping
* **Note:** Only present when you set metadata on the monitor
#### `monitorHasBeenDeactivated` (boolean)
* **What it is:** Whether this monitor is being permanently deactivated
* **When true:** Company disappeared from register (404/not found)
* **When false:** Normal change notification
* **Critical:** When `true`, you should:
1. Remove the company from your monitoring dashboard
2. Stop expecting future notifications
3. Investigate why the company disappeared
4. The monitor cannot be reactivated - you must create a new one if the company reappears
## Example Webhook Scenarios
### Scenario 1: Company Enters Liquidation
```json theme={null}
{
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T10:15:00.000Z",
"changeCategories": ["status"],
"monitorHasBeenDeactivated": false
}
```
**Example action:** Raise the potential credit risk to your team.
### Scenario 2: Ownership Change
```json theme={null}
{
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T10:15:00.000Z",
"changeCategories": ["ownership"],
"monitorHasBeenDeactivated": false
}
```
**Example action:** Trigger UBO re-verification.
### Scenario 3: Company Disappeared
```json theme={null}
{
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T10:15:00.000Z",
"changeCategories": ["disappeared"],
"monitorHasBeenDeactivated": true
}
```
**Example actions:**
1. Mark company as "ceased to exist" in your system
2. Remove from monitoring dashboard
3. Alert relationship managers
4. Do not attempt to reactivate this monitor
### Scenario 4: Multiple Changes
```json theme={null}
{
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T10:15:00.000Z",
"changeCategories": ["address", "financial", "other"],
"monitorHasBeenDeactivated": false
}
```
**Example action:** Launch a comprehensive review.
## Understanding Deactivation
### What Causes Automatic Deactivation?
A monitor is automatically deactivated when a scheduled check finds that the register no longer knows the company (not found). A single not-found result is enough.
A temporary register error, such as a timeout or an outage, does not deactivate a monitor. The check is skipped and the next scheduled check runs as usual.
### What Happens During Deactivation?
When a company disappears, the system:
1. **Detects the Issue**
* Company fetch returns "not found" error
* System identifies this as a disappearance
2. **Processes the Deactivation**
* Logs the not-found event
* Creates final snapshot with "disappeared" status
* Sends webhook notification
* Deactivates the monitor
* Clears cached data
3. **Sends Final Webhook**
```jsonc theme={null}
{
"type": "monitor.notification",
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T10:15:00.000Z",
"changeCategories": ["disappeared"],
"monitorHasBeenDeactivated": true // ← Critical flag
}
```
4. **Cleanup**
* Monitor is permanently deactivated
* Historical data retained for audit
* No future checks will occur
### Handling Deactivation Webhooks
When you receive `monitorHasBeenDeactivated: true`:
```javascript theme={null}
// Example webhook handler
async function handleMonitoringWebhook(payload) {
if (payload.monitorHasBeenDeactivated) {
// Company has disappeared!
await markCompanyAsInactive(payload.companyId);
await removeFromMonitoringDashboard(payload.companyId);
await notifyComplianceTeam({
message: 'Company no longer exists in register',
companyId: payload.companyId,
countryCode: payload.countryCode,
});
// DO NOT try to recreate the monitor immediately
// Investigate why the company disappeared first
} else {
// Normal change processing
await processCompanyChanges(payload);
}
}
```
### Can I Reactivate a Deactivated Monitor?
**No.** Deactivation is permanent. If you want to monitor the company again:
1. Verify the company exists in the register
2. Create a new monitor using `POST /v2/monitors`
3. You'll receive a new monitor ID to track the company
## FAQ
### What happens if a company temporarily disappears?
If a company doesn't appear anymore in the register, the monitor is immediately deactivated. This is permanent - you'll need to create a new monitor if the company reappears.
### Can I get the actual data that changed?
Currently, webhooks only indicate what category of change occurred. Full differential data in webhooks is planned for future releases.
### How is monitoring billed?
Monitoring commercial terms and eligibility can depend on your account and the countries you monitor. Check [topograph.co/pricing](https://topograph.co/pricing) for live coverage and use the dashboard for your account configuration.
### Can I decide what changes trigger webhooks?
Not yet. All detected changes trigger webhooks. Filtering rules will be added in a future release.
### What if I need to monitor thousands of companies?
The system supports large-scale monitoring. Contact support to discuss enterprise volumes.
# Netherlands
Source: https://docs.topograph.co/essentials/netherlands
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Netherlands reference is on the [Netherlands country page](https://www.topograph.co/countries/nl).
## Start here
This guide contains public integration notes for Netherlands. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
The Netherlands uses a single official registry -- the **KVK (Kamer van Koophandel / Chamber of Commerce)** -- accessed through multiple channels. Data retrieval follows a **two-phase model**: basic structured data from the KVK Search API, and detailed data (legal representatives, shareholders, capital, RSIN) from the HTML trade register extract via AI parsing.
* **KVK Search API** -- Provides basic company data in structured JSON: legal name, legal form, status, address, activity description, and trade names. This is a **free, fast API** that returns data immediately. Used for search results and base company profile data.
* **KVK Trade Register Extract (Uittreksel Handelsregister)** -- The official HTML extract from the KVK online trade register. Contains detailed data including legal representatives (`Bestuurders`, `Gevolmachtigden`), shareholders (`Aandeelhouders`, `Vennoten`), SBI activity codes, RSIN, share capital, and employee count. This HTML is **AI-parsed** to extract structured data.
Basic company data comes from KVK Search. Detailed officers, other key persons, shareholders, capital, RSIN and activity codes come from the trade register extract. Known roles use fixed translations and standardized values; unfamiliar titles can require AI enrichment.
Request `otherKeyPersons` in verification mode for supervisory and other non-representing appointments recorded in the extract. Prefill mode does not provide this datapoint. A company with no such appointments returns an empty list.
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Supported domestic BV and NV forms. Uses the KVK number, not an establishment number or RSIN. Example: `NLNHR.34259528`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entities** | KVK | 8 digits (KVK number) | `53781066` | Kamer van Koophandel number -- the universal Dutch business identifier |
**KVK Number Format:** The KVK number is always exactly 8 digits (`^\d{8}$`), and leading zeros are significant. There is no prefix and no published check digit. An establishment has its own 12-digit establishment number (vestigingsnummer), which is a different number.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `kvk` | 8 digits, leading zeros significant | `53781066` | All entities (from Search API) |
| `RSIN` | 9 digits | `813454554` | Legal entities and partnerships information number, from the trade register extract (see [when the extract is bought](#data-sources)). Sole traders have none |
| `VAT` | 9 digits + B + 2 digits | `813454554B01` | Dutch VAT number, returned without the `NL` prefix, when the request buys the trade register extract. For a legal entity the 9 digits are its RSIN; for a sole trader they are a separate number. Taken from the trade register extract when it shows one, otherwise built from the RSIN with subnumber `B01`, which is not always the subnumber in use |
**Identifier Casing:** The KVK number is returned under the lowercase key
`kvk`. `RSIN` and `VAT` are uppercase.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the KVK number (`kvk`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By KVK Number | 8 digits | `53781066` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Philips"` | Fuzzy | Multiple results |
| By VAT Number | `NL` + 9 digits + `B` + 2 digits | `NL859402022B01` | Name-based | The VAT number is validated against VIES, then the KVK is searched by the registered trader name |
**Search Performance:** Use KVK number searches for exact matching and best
performance. Name searches query the KVK Search API and return multiple
results. All search types have built-in retry handling for reliability. Name
search returns one result per KVK number: branches are collapsed onto their
company, and entities without an establishment (for example associations and
foundations) are included.
### Active companies only
Search only returns active companies, so [`activeOnly=true`](/essentials/search#active-companies-only) changes nothing here. Search only returns companies currently registered.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Two-phase data retrieval** | Basic company data comes from the KVK Search API (fast, free); detailed data (legal reps, shareholders, capital) requires fetching and AI-parsing the HTML trade register extract. Legal reps and shareholders take longer to return. |
| **Legal form: two tiers** | The KVK search API returns 23 base legal forms. The trade register extract carries the detailed form (48 values). A BV that is a structuurvennootschap shows as "Besloten Vennootschap" without the extract and "Besloten Vennootschap (blijkens statuten structuurvennootschap)" with it. |
| **No UBO data** | Ultimate beneficial owner information is not available from the KVK API or trade register extract. The UBO register in the Netherlands is not publicly accessible. |
| **Sole shareholders only** | The KVK registers a shareholder only when a company has a **single 100% holder** (`Enig aandeelhouder`). A BV with two or more shareholders publishes no shareholder record at all, so `shareholders` succeeds with an empty list. See [Reading an empty `shareholders` list](#reading-an-empty-shareholders-list). |
| **Null ownership percentages** | Ownership percentages are only extracted when **explicitly stated** in the trade register extract. `null` means "not stated", not "0%". The system never infers or calculates percentages. |
| **Null nationality** | Nationality is always `null` unless explicitly stated in the document. The system does **not** assume Dutch nationality for shareholders of Dutch companies. |
| **SBI codes via AI** | SBI 2008 codes are AI-extracted from the trade register extract HTML. NACE and ISIC are then derived deterministically (no AI). SBI 2025 codes are derived via CBS crosswalk, with LLM disambiguation for ambiguous mappings. Without the extract (prefill mode, or `company` alone), all codes are AI-inferred from the activity description. |
| **Partial document failures** | The four document listing calls (extract, history, financials, statutes) run in parallel. If one fails, partial results are returned. Only if all four fail is an error thrown. |
| **KVK identifier casing** | The KVK number is returned under the lowercase key `kvk`, not `KVK` or `KvK`. |
| **Statutes listing** | Deposited statutes the register has already checked for personal data are listed and can be ordered for instant download. A recently deposited deed that still contains personal data is not listed, because the register only provides it through a manual redaction request (up to about 2 working days). Core registration facts for a new company (incorporation date, legal form, capital, registered office, directors) already appear in the Trade Register Extract, but the full deed text requires that manual request. |
| **Document delivery via email** | Financial statements and statutes are ordered from KVK, delivered via email, then downloaded. This adds latency (\~30 sec). Trade register extracts use a direct online flow. |
| **Company self-filtering** | AI parsing sometimes includes the main company itself as a legal representative or shareholder. The system automatically filters these out by matching on KVK number. |
## Company Status
Company status is determined **deterministically** from the KVK `actief` boolean field. No AI inference is involved in status determination.
| Local Status | English | Standardized Status | Notes |
| - | - | - | - |
| Ingeschreven | Registered | Active | `actief` = true |
| Uitgeschreven | Deregistered | Closed | `actief` = false |
The KVK provides only a binary active/inactive status. There are no detailed
closure reasons (bankruptcy, liquidation, etc.) or insolvency statuses
available from the structured API. More detailed status information may
occasionally be available in the trade register extract via AI parsing, but it
is not systematically extracted.
## Legal Forms
The Netherlands has a **two-tier legal form model**. The level of detail you receive depends on whether the request buys the trade register extract (see [when the extract is bought](#data-sources)).
* **Without the extract** (prefill mode, or `company` alone) the KVK search API returns **23 base legal forms**. These are the values in the `rechtsvorm` field (e.g. "Besloten Vennootschap", "Naamloze Vennootschap", "Publiekrechtelijke Rechtspersoon"). This is a deterministic mapping with no AI involved.
* **With the extract** (a verification request that also asks for `legalRepresentatives` or `shareholders`, or orders the Trade Register Extract document) you get **48 detailed legal forms** extracted from the trade register document. These are the `uitgebreideRechtsvorm` values (e.g. "Besloten Vennootschap (blijkens statuten structuurvennootschap)", "Naamloze Vennootschap (beleggingsmaatschappij met veranderlijk kapitaal)", "Publiekrechtelijke Rechtspersoon: Gemeente"). A dedicated AI parser constrained to the 48-value enum extracts the detailed form from the document.
Both tiers map to the same standardized categories and ISO 20275 codes. The difference is granularity: the search API collapses variants into their parent form, while the extract resolves the specific subtype.
Source: KVK official reference document "Lijst van output: uitgebreide rechtsvormen" (June 2025).
### Without the extract (23 base forms)
| Dutch Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Eenmanszaak | Sole Proprietorship | `Sole Proprietorship` | `4QXM` |
| Eenmanszaak met Meerdere Eigenaren | Sole Proprietorship with Multiple Owners | `Other` | `4QXM` |
| Rederij | Shipping Company | `Corporation` | `UNJ2` |
| Maatschap | Partnership | `Partnership` | `9AAK` |
| Vennootschap Onder Firma | General Partnership | `Partnership` | `62Y3` |
| Commanditaire Vennootschap | Limited Partnership | `Partnership` | `CODH` |
| Rechtspersoon in oprichting | Legal Entity in Formation | `Other` | `EZQW` |
| Besloten Vennootschap | Private Limited Company | `Limited Liability Company` | `54M6` |
| Naamloze Vennootschap | Public Limited Company | `Corporation` | `B5PM` |
| Coöperatie | Cooperative | `Cooperative` | `NFFH` |
| Onderlinge Waarborg Maatschappij | Mutual Guarantee Company | `Cooperative` | `DEO1` |
| Vereniging | Association | `Nonprofit Organization` | `33MN` |
| Vereniging van Eigenaars | Owners' Association | `Other` | `GNXT` |
| Kerkgenootschap | Religious Society or Church | `Nonprofit Organization` | `L7HX` |
| Stichting | Foundation | `Nonprofit Organization` | `V44D` |
| Overige Privaatrechtelijke Rechtspersoon | Other Private Law Legal Entity | `Other` | `M1IZ` |
| Europese naamloze vennootschap (SE) | European Public Limited-Liability Company (SE) | `Corporation` | `BBEB` |
| Europees economisch samenwerkingsverband | European Economic Interest Grouping | `Other` | `5WU6` |
| Europese coöperatieve vennootschap (SCE) | European Cooperative Society (SCE) | `Cooperative` | `BBEB` |
| Kapitaalvennootschap binnen EER | Capital Company within the EEA | `Corporation` | `BBEB` |
| Kapitaalvennootschap buiten EER | Capital Company outside the EEA | `Corporation` | `BBEB` |
| Overige buitenlandse rechtspersoon of vennootschap | Other Foreign Legal Entity or Company | `Other` | `M1IZ` |
| Publiekrechtelijke Rechtspersoon | Public Law Legal Entity | `Government-Owned Entity` | `A0W7` |
### With the extract (48 detailed forms)
With the extract, the legal form is extracted from the trade register document and resolved to one of 48 specific values. The 23 base forms above still appear when the base and detailed form are the same (e.g. "Eenmanszaak" stays "Eenmanszaak"). The additional 25 detailed variants only appear with the extract.
| Dutch Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Besloten Vennootschap | Private Limited Company | `Limited Liability Company` | `54M6` |
| Besloten Vennootschap (blijkens statuten structuurvennootschap) | Private Limited Company (Structure Regime) | `Limited Liability Company` | `54M6` |
| Naamloze Vennootschap | Public Limited Company | `Corporation` | `B5PM` |
| Naamloze Vennootschap (blijkens statuten structuurvennootschap) | Public Limited Company (Structure Regime) | `Corporation` | `B5PM` |
| Naamloze Vennootschap (beleggingsmaatschappij met veranderlijk kapitaal) | Public Limited Company (Variable Capital Investment Company) | `Corporation` | `B5PM` |
| Naamloze Vennootschap (beleggingsmaatschappij met veranderlijk kapitaal blijkens statuten structuurvennootschap) | Public Limited Company (Variable Capital Investment Company, Structure Regime) | `Corporation` | `B5PM` |
| Dutch Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Coöperatie | Cooperative | `Cooperative` | `NFFH` |
| Coöperatie (blijkens statuten structuurcoöperatie) | Cooperative (Structure Regime) | `Cooperative` | `NFFH` |
| Onderlinge Waarborg Maatschappij | Mutual Guarantee Company | `Cooperative` | `DEO1` |
| Onderlinge Waarborg Maatschappij (blijkens statuten onderlinge) | Mutual Guarantee Company (Mutual Statutes) | `Cooperative` | `DEO1` |
| Dutch Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Vereniging (met volledige rechtsbevoegdheid) | Association (with Full Legal Capacity) | `Nonprofit Organization` | `33MN` |
| Vereniging (met beperkte rechtsbevoegdheid) | Association (with Limited Legal Capacity) | `Nonprofit Organization` | `33MN` |
Without the extract, both appear as "Vereniging".
| Dutch Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Overige Privaatrechtelijke Rechtspersoon: Hofje | Other Private Law: Almshouse | `Other` | `M1IZ` |
| Overige Privaatrechtelijke Rechtspersoon: Boermarke | Other Private Law: Agricultural Commons | `Other` | `M1IZ` |
| Overige Privaatrechtelijke Rechtspersoon: Fundatie | Other Private Law: Endowment | `Other` | `M1IZ` |
| Overige Privaatrechtelijke Rechtspersoon: Gilde | Other Private Law: Guild | `Other` | `M1IZ` |
| Overige Privaatrechtelijke Rechtspersoon: Buurtschap | Other Private Law: Hamlet Community | `Other` | `M1IZ` |
Without the extract, all appear as "Overige Privaatrechtelijke Rechtspersoon".
Foreign entities registered in the Netherlands. The KVK profile API returns a dynamic `uitgebreideRechtsvorm` with the foreign legal form name and country of establishment (e.g. "Société à responsabilité limitée (Frankrijk)"). The API response normalizes these to one of the 4 base forms below.
| Dutch Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Kapitaalvennootschap binnen EER | Capital Company within the EEA | `Corporation` | `BBEB` |
| Kapitaalvennootschap buiten EER | Capital Company outside the EEA | `Corporation` | `BBEB` |
| Kapitaalvennootschap buiten EER (formeel buitenlandse vennootschap) | Capital Company outside the EEA (formally foreign company) | `Corporation` | `BBEB` |
| Overige buitenlandse rechtspersoon of vennootschap | Other Foreign Legal Entity or Company | `Other` | `M1IZ` |
| Dutch Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Publiekrechtelijke Rechtspersoon: Adviescollege | Public Law: Advisory Council | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Bedrijfsvoeringsorganisatie (BVO) | Public Law: Shared Services Organization (BVO) | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: De Staat (Baten- en lastendienst) | Public Law: The State (Executive Agency) | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: De Staat (Ministerie) | Public Law: The State (Ministry) | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: De Staat (Zelfstandig onderdeel) | Public Law: The State (Autonomous Unit) | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Europese Groepering voor Territoriale Samenwerking (EGTS) | Public Law: European Grouping of Territorial Cooperation (EGTC) | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Gemeente | Public Law: Municipality | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Lichaam met bevoegdheid krachtens de Grondwet | Public Law: Body with Constitutional Authority | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Openbaar Lichaam op basis van gemeenschappelijke regeling | Public Law: Public Body under Joint Arrangement | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Provincie | Public Law: Province | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Rechtspersoon met Wettelijk Taak (RWT) | Public Law: Entity with Statutory Task (RWT) | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Universiteit of Academisch Ziekenhuis | Public Law: University or Academic Hospital | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Waterschap | Public Law: Water Board | `Government-Owned Entity` | `A0W7` |
| Publiekrechtelijke Rechtspersoon: Zelfstandig Bestuursorgaan (ZBO) | Public Law: Independent Administrative Body (ZBO) | `Government-Owned Entity` | `A0W7` |
Without the extract, all appear as "Publiekrechtelijke Rechtspersoon".
## Legal Representatives
Legal representatives come from the KVK trade register extract. Names, birth dates, appointment dates and representation rules are returned when recorded. The filed role is preserved; known offices use fixed translations and standardized values.
### Role catalogue
We use a **closed list of canonical roles** for the Netherlands. Every `role.localName` you receive in the API response is guaranteed to be one of these values.
The list is built on top of **ISO 5009**, the international standard for official organizational roles published by ISO and maintained by GLEIF. ISO 5009 covers the statutory roles defined in the Dutch Civil Code (directors, supervisory board members, liquidators, and so on). We took the Dutch entries from the ISO 5009 code list and deduplicated them into canonical roles.
On top of that, we added four roles that appear on Dutch trade register extracts but are out of scope for ISO 5009 because they are based on power of attorney (volmacht) rather than corporate governance:
* **Gevolmachtigde** and **Gevolmachtigd handelsagent**, registered via KVK Form 13
* **Procuratiehouder**, a historical commercial volmacht role
* **Bewindvoerder**, a trustee appointed during suspension of payments
Shareholder roles (Aandeelhouder, Vennoot, Eigenaar) are not part of this list. They live in the `shareholders` field of the API response.
### Full role enum
The catalogue covers the offices below. A person’s placement in `legalRepresentatives` or `otherKeyPersons` follows their recorded representation powers, rather than their title alone. Each ISO 5009 role can map to multiple OOR codes because the code depends on the legal form of the company. For example, "Bestuurder" is `KHNVNO` for a BV, `TK4BXG` for an NV, and `PPIUMW` for a Stichting.
| Dutch name | English | Standardized | ISO 5009 OOR codes |
| - | - | - | - |
| Bestuurder | Director | `Director` or `Board Member` | KHNVNO (BV), TK4BXG (NV), PPIUMW (Stichting) |
| Bestuurder / bestuurslid | Director / Board Member | `Director` | W9JQJP (Vereniging) |
| Uitvoerend bestuurder | Executive Director | `Executive Director` | TFPVDK (BV), 7BGHMI (NV) |
| Niet uitvoerend bestuurder | Non-Executive Director | `Non-Executive Director` | VA30FP (BV), HHZHF9 (NV) |
| Voorzitter bestuur | Chairman of the Management Board | `Chairman of the Board` | 080BGK (BV), 934G9A (NV) |
| Voorzitter | Chairman | `Chairman` | 9W99BU (Vereniging) |
| Commissaris | Supervisory Board Member | `Supervisory Board Member` | GRP0OJ (BV), TP7XTW (NV), RERTFR (Stichting), LMY8OH (Vereniging) |
| Voorzitter raad van commissaren | Chairman of the Supervisory Board | `Chairman of the Board` | WPGA3Y (NV) |
| Secretaris | Secretary | `Secretary` | PV9S1F (Vereniging) |
| Penningmeester | Treasurer | `Treasurer` | GQ8JOW (Vereniging) |
| Vertegenwoordigingsbevoegde | Authorized Signatory (statutory) | `Authorized Signatory` | CHOFER (BV), RPL5H6 (NV), SXRUU6 (Vereniging), WNHFP9 (Stichting) |
| Vereffenaar | Liquidator | `Liquidator` | 7PTVPF (BV), WBJNBK (NV) |
| Curator | Court-Appointed Administrator | `Administrator` | ALIVPM (NV), SYLJPO (BV) |
| Beheerder | Administrator | `Administrator` | OIEAWD (Maatschap) |
| Beheerder / Beherend Vennoot | Managing Partner | `Managing Partner` | BF4XP2 (VOF) |
| Beherend Vennoot | General Partner | `General Partner` | BKH1IX (CV) |
| Gevolmachtigde | Authorized Representative | `Authorized Signatory` | Topograph extension (Boek 3 volmacht) |
| Gevolmachtigd handelsagent | Authorized Commercial Agent | `Authorized Signatory` | Topograph extension (Boek 3 volmacht) |
| Procuratiehouder | Procurator | `Authorized Signatory` | Topograph extension (historical volmacht) |
| Bewindvoerder | Trustee (suspension of payments) | `Administrator` | Topograph extension (Boek 3 bewind) |
### Role normalization
Dutch trade register extracts sometimes use informal variants or add authority scope to a role name. Known variants are normalized to a published office. Unrecognized labels are preserved rather than forced into one of the examples below.
| What the extract says | What you receive |
| - | - |
| Statutair bestuurder in the formal board section | Bestuurder |
| Bestuurder - Alleen/zelfstandig bevoegd | Bestuurder |
| Bestuurder - Gezamenlijk bevoegd | Bestuurder |
| Directeur, CEO, CFO or COO outside a formal board/representation section | Original filed title |
| Gevolmachtigde - Beperkte volmacht | Gevolmachtigde |
| Gevolmachtigde - Onbeperkte volmacht | Gevolmachtigde |
Signing authority (sole or joint) is kept in `representationMode`, with the recorded scope when available. The role title does not override those conditions. An `iso5009Code` is included only when the official role matches the company’s legal form; it can be omitted when no match is established.
### Fields extracted per legal representative
| Field | Dutch source term | Description |
| - | - | - |
| Birth date | Geboortedatum | Date of birth |
| Start date | Datum in functie | Date the person started in the role |
| Role | (from the extract) | Known canonical office, or the original title when unknown |
| Name title | Mr., Mrs., Dr., etc. | Honorific prefix only |
## Other Key Persons
Verification mode returns non-representing appointments in `otherKeyPersons`. Supervisory board members and their chair belong here. One-tier non-executive directors and management-board members belong here when the extract does not grant them representation powers. A non-executive director can instead be a legal representative when the extract records those powers.
Founder or association-membership appointments may also appear. Ownership alone remains in `shareholders`, without creating an additional officer role.
| Dutch name | English | Standardized | ISO 5009 OOR codes |
| - | - | - | - |
| Commissaris | Supervisory Board Member | `Supervisory Board Member` | GRP0OJ (BV), TP7XTW (NV), RERTFR (Stichting), LMY8OH (Vereniging) |
| Voorzitter raad van commissaren | Chairman of the Supervisory Board | `Chairman of the Board` | WPGA3Y (NV) |
| Oprichter | Founder | `Other` | AJ86T4 (BV), 6ITGMW (NV), KLUFYX (Stichting) |
| Lid | Member | `Other` | 1AHQJK (Vereniging) |
## Shareholders
Shareholders are **AI-extracted** from the same KVK trade register extract as the officer data.
### Dutch Terms for Shareholders
| Dutch Term | English | Entity Type | Found In |
| - | - | - | - |
| Aandeelhouders | Shareholders | BV, NV companies | Capital companies |
| Vennoten | Partners | VOF, CV partnerships | Partnerships |
| Eigenaar | Owner | Eenmanszaak (sole proprietorship) | Sole proprietorships |
### Extraction Logic
| Source | When Used | Data Extracted |
| - | - | - |
| **Trade Register Extract HTML** | Always (AI-parsed) | Partners, Shareholders, Owners with names and optional share percentages |
### Ownership Fields
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | Only if **explicitly stated** in document (null if not stated) |
| `type` | Individual or Company | Determined from AI parsing context |
| `nationality` | Nationality | Only if **explicitly stated** (null by default -- never assumes Dutch) |
**Critical: Ownership Percentages**
Share percentages are only extracted when explicitly stated in the trade register extract (e.g., "50%", "33,33%"). The system does **not** infer or calculate percentages. If no percentage is mentioned, `sharePercentage` is `null`. Do not assign 100% to each shareholder. Nationality is also `null` unless explicitly stated -- the system does not assume Dutch nationality.
Shareholder data depends on the entity type. For BV/NV companies the register
publishes a shareholder **only when a single party holds 100% of the shares**
(see [Reading an empty `shareholders` list](#reading-an-empty-shareholders-list)).
VOF/CV partnerships list their partners, and an Eenmanszaak its owner.
Stichtingen (foundations) and Verenigingen (associations) have no
shareholders.
### Reading an empty `shareholders` list
Dutch law only obliges a company to register its shareholder when there is
**exactly one** holding 100% of the shares (`Enig aandeelhouder`,
Handelsregisterwet 2007 art. 17-18 and Handelsregisterbesluit 2008 art. 22). A
BV or NV with two or more shareholders registers **nothing**: the
Handelsregister simply has no shareholder record for it, and neither does the
Uittreksel.
So for the Netherlands:
| Response | Meaning |
| - | - |
| `shareholders: [ { … 100% } ]` | The company has a registered sole shareholder. |
| `shareholders: []` with `status: "succeeded"` | The register holds **no shareholder record**. Almost always a company with two or more shareholders — **not** a company without owners. |
| `shareholders` key absent | The datapoint was not requested, failed, or is still running. Check `dataStatus`. |
An empty `shareholders` list is **not** a terminal node in an ownership chain.
It means the Dutch register does not publish this company's ownership, not
that the chain ends. Measured across 4,322 real KVK extracts: 2,435 carry a
sole shareholder and only 2 carry a multi-holder list.
When the list is empty and you need to continue the traversal:
* **`legalRepresentatives`** — a Dutch holding structure is very often managed by
its own parent, so a corporate `Bestuurder` with its own KVK number is usually
the next entity up.
* **Trade Register History** (`Uittreksel Handelsregister Historie`) — shows any
sole-shareholder registration the company has had in the past, with start and
end dates. If the history has none either, the company has never had a
registered sole shareholder.
* **Financial Statements** (`Jaarrekeningen`) — consolidated accounts frequently
name the parent in the notes.
* **Deed of incorporation / statutory amendment** (`Akte van oprichting` /
`Statutenwijziging`) — the notarial deed names the subscribing shareholders at
the time it was executed.
## Activity Code Mapping
The Netherlands uses the **SBI (Standaard Bedrijfsindeling)** classification. SBI 2008 codes (5-digit) are extracted from the trade register extract via AI parsing. From these, **NACE Rev 2.1** and **ISIC Rev 5** codes are derived **deterministically** (no AI), and **SBI 2025** codes are derived via the official CBS crosswalk (with LLM disambiguation for ambiguous mappings).
### Company Profile (with Trade Register Extract)
```
TRE (AI-parsed) → SBI 2008 codes
→ truncate to 4 digits + insert dot → NACE Rev 2.1 (deterministic)
→ formal ISIC↔NACE mapping → ISIC Rev 5 (deterministic)
→ CBS crosswalk → SBI 2025 (1:1 resolved or LLM-disambiguated)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **SBI 2025** | Derived from SBI 2008 via CBS crosswalk | `47120` | Yes (AI-extracted from HTML + crosswalk disambiguation) |
| **NACE Rev 2.1** | Derived from SBI 2008 (truncate + dot), upconverted | `47` | No (deterministic) |
| **ISIC Rev 5** | Formal mapping from NACE | `47` | No (deterministic) |
**One code in, one code out.** You get one `NACE` and one `ISIC` code per declared SBI code. Where an SBI code has no single equivalent in the target revision, the shared parent class is returned rather than every candidate — SBI 2008 `47190`, for example, returns NACE `47` rather than both `47.12` and `47.91`. See [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
**Main activity.** The KVK trade register distinguishes the *hoofdactiviteit* from secondary activities. When the extract designates one, that SBI code carries `isMainActivity: true`, and the NACE, ISIC and SBI 2025 codes derived from it inherit the flag. Without the extract, the single code inferred from the activity description is flagged as the main activity and is marked `isAIInferred: true` alongside. Absence of the flag means the source did not say — not that the code is secondary.
### Company profile without the extract (Search API only)
```
Activity description (activiteitomschrijving)
→ LLM inference → ISIC codes
→ formal ISIC↔NACE mapping → NACE Rev 2.1 (deterministic)
→ CBS crosswalk → SBI 2025 (1:1 resolved or LLM-disambiguated)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **SBI 2025** | Derived from NACE via CBS crosswalk | `64110` | Yes |
| **NACE Rev 2.1** | Derived from ISIC (formal mapping) | `64.11` | Yes (source ISIC is AI-inferred) |
| **ISIC Rev 5** | LLM-inferred from activity description | `6411` | Yes |
**Deterministic vs. AI-inferred:** When the trade register extract is
available (company profile), NACE and ISIC are derived deterministically from
SBI 2008 codes (`isAIInferred: false`). SBI 2025 codes use the CBS crosswalk
\-- 1:1 mappings are resolved automatically, ambiguous mappings (multiple SBI
2025 candidates for one NACE code) are disambiguated by an LLM using the
company's activity description. When only the search API is available
(prefill mode, or `company` alone), all codes are AI-inferred from the activity description
text.
## Data Availability Matrix
| Data Type | BV/NV | VOF/CV | Eenmanszaak | Stichting/Vereniging | Notes |
| - | - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | ✅ Async | Basic data from Search API + AI enrichment from trade register |
| Legal Representatives | ✅ | ✅ | ✅ | ✅ | Extracted from the trade register extract; representation powers determine the person list |
| Other Key Persons | Conditional | Conditional | Conditional | Conditional | Verification mode only: non-representing appointments recorded in the extract |
| Shareholders | ✅ | ✅ (as partners) | ✅ (as owner) | ❌ | AI-parsed; VOF/CV show partners, EMZ shows owner |
| Ultimate Beneficial Owners | ❌ | ❌ | ❌ | ❌ | Not available from KVK (UBO register not publicly accessible) |
| Establishments | ❌ | ❌ | ❌ | ❌ | Not yet implemented |
| Activity Codes | ✅ | ✅ | ✅ | ✅ | SBI 2025, NACE, ISIC. With the extract: SBI 2008 from TRE → deterministic NACE/ISIC. Without it: AI-inferred from description. |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
## Documents by Company Type
### All Companies
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Uittreksel Handelsregister (Trade Register Extract)** | `tradeRegisterExtract` | PDF | ✅ When available | Online extract from KVK (\~30 sec, 24h fast search dataset) |
| **Uittreksel Handelsregister Historie (Trade Register History)** | `tradeRegisterHistory` | PDF | ✅ When available | Historical extract from KVK listing registration changes since incorporation (online flow) |
| **Jaarrekening (Financial Statements)** | `financialStatements[]` | PDF | ✅ When filed | Annual accounts from KVK (delivered via email, 99-year fast search dataset) |
| **Statuten (Articles of Association)** | `articlesOfAssociation[]` | PDF | ✅ When filed | Corporate statutes from KVK (delivered via email, 99-year fast search dataset) |
**Trade Register Extract:** The Uittreksel is an HTML document fetched from
the KVK website and converted to PDF for delivery. The HTML content is
AI-parsed to extract structured data.
**Document Delivery Methods:** The trade register extract uses a direct
**online flow** (fast, \~30 sec). Financial statements and statutes use a
**mail flow**: the document is ordered from KVK, delivered via email, then
downloaded and saved. This adds latency but is the only retrieval method
available for these document types.
**Document Listing:** Documents are listed via four parallel KVK API calls:
(1) trade register extract availability, (2) trade register history
availability, (3) financial statements, (4) statutes. If one source fails,
partial results are still returned. Only if all four fail is an error thrown.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "NL", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "12345678",
"countryCode": "NL",
"identifiers": { "kvk": "12345678", "RSIN": "123456789", "VAT": "123456789B01" },
"legalName": "Voorbeeld Tech B.V.",
"activityDescription": "Ontwikkeling van software en IT-diensten.",
"status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Besloten Vennootschap", "englishTranslation": "Private Limited Company", "standardized": "Limited Liability Company", "iso20275Code": "54M6" },
"capital": { "amount": 100000, "currency": "EUR" },
"activities": {
"SBI": [{ "code": "62010", "description": "Ontwikkeling en productie van software", "isAIInferred": true }],
"NACE": [{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": false }]},
"legalAddress": { "addressLine1": "Herengracht 100", "city": "Amsterdam", "postalCode": "1015 AA", "countryCode": "NL" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Bestuurder", "standardized": "Director" }, "individual": { "name": { "fullName": "Jan de Vries" }, "birthDate": { "year": 1980, "month": 5, "day": 15 } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Gevolmachtigde", "standardized": "Authorized Signatory" }, "individual": { "name": { "fullName": "Anna Bakker" }, "birthDate": { "year": 1985, "month": 9 } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Jan de Vries" } } },
{ "entityId": "company_001", "type": "company", "sharePercentage": 60, "company": { "legalName": "Holding Groep B.V.", "id": "87654321" } }
]
}
```
```json theme={null}
{
"company": {
"id": "98765432",
"countryCode": "NL",
"identifiers": { "kvk": "98765432" },
"legalName": "Oude Fabriek N.V.",
"activityDescription": "Vervaardiging van textielproducten.",
"status": { "localName": "Uitgeschreven", "active": false, "statusDetails": { "status": "CLOSED" } },
"legalForm": { "localName": "Naamloze Vennootschap", "englishTranslation": "Public Limited Company", "standardized": "Corporation", "iso20275Code": "B5PM" },
"activities": {
"SBI": [{ "code": "13200", "description": "Weven van textiel", "isAIInferred": true }],
"NACE": [{ "code": "13.20", "description": "Weaving of textiles", "isAIInferred": false }],
"ISIC": [{ "code": "1312", "description": "Weaving of textiles", "isAIInferred": false }]},
"legalAddress": { "addressLine1": "Industrieweg 25", "city": "Rotterdam", "postalCode": "3024 AA", "countryCode": "NL" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Bestuurder", "standardized": "Director" }, "individual": { "name": { "fullName": "Pieter Jansen" }, "birthDate": { "year": 1965, "month": 3 } } }
]
}
```
**Note:** Closed companies have `active: false` and status `Uitgeschreven` (Deregistered). No detailed closure reason is available from the KVK.
```json theme={null}
{
"company": {
"id": "87654321",
"countryCode": "NL",
"identifiers": { "kvk": "87654321" },
"legalName": "Bakkerij van den Berg V.O.F.",
"activityDescription": "Vervaardiging van brood en banketbakkerswerk.",
"status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Vennootschap Onder Firma", "englishTranslation": "General Partnership", "standardized": "Partnership", "iso20275Code": "62Y3" },
"legalAddress": { "addressLine1": "Kalverstraat 50", "city": "Utrecht", "postalCode": "3511 AA", "countryCode": "NL" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Beherend Vennoot", "standardized": "General Partner" }, "individual": { "name": { "fullName": "Pieter van den Berg" } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Beherend Vennoot", "standardized": "General Partner" }, "individual": { "name": { "fullName": "Maria van den Berg" } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Pieter van den Berg" } } },
{ "entityId": "person_002", "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Maria van den Berg" } } }
]
}
```
**Note:** VOF partners (`Vennoten`) appear as both legal representatives (with the canonical role `Beherend Vennoot`) and shareholders. Ownership percentages are typically not stated for partnerships, so `sharePercentage` is `null`.
```json theme={null}
{
"company": {
"id": "11223344",
"countryCode": "NL",
"identifiers": { "kvk": "11223344" },
"legalName": "Consultancy Van Dijk",
"activityDescription": "Advisering op het gebied van management en bedrijfsvoering.",
"status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Eenmanszaak", "englishTranslation": "Sole Proprietorship", "standardized": "Sole Proprietorship", "iso20275Code": "4QXM" },
"legalAddress": { "addressLine1": "Keizersgracht 200", "city": "Amsterdam", "postalCode": "1016 AA", "countryCode": "NL" }
},
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Sophie van Dijk" } } }
]
}
```
**Note:** For sole proprietorships, the owner (`Eigenaar`) appears as a shareholder. The entrepreneur is the company itself.
```json theme={null}
{
"company": {
"id": "55667788",
"countryCode": "NL",
"identifiers": { "kvk": "55667788" },
"legalName": "Stichting Kunstbehoud Nederland",
"activityDescription": "Behoud en promotie van Nederlands cultureel erfgoed.",
"status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Stichting", "englishTranslation": "Foundation", "standardized": "Nonprofit Organization", "iso20275Code": "V44D" },
"legalAddress": { "addressLine1": "Museumplein 10", "city": "Amsterdam", "postalCode": "1071 DJ", "countryCode": "NL" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Bestuurder", "standardized": "Director" }, "individual": { "name": { "fullName": "Willem de Groot" }, "birthDate": { "year": 1970, "month": 8, "day": 20 } } }
]
}
```
**Note:** Foundations (Stichtingen) have no shareholders -- they are non-profit entities with a board of directors (`Bestuurders`). No UBOs are available from the KVK.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Uittreksel Handelsregister PDF | When available (\~30 sec, online flow) |
| `tradeRegisterHistory` | Uittreksel Handelsregister Historie PDF | When available (online flow) |
| `financialStatements[]` | Jaarrekening (annual accounts) | When filed, PDF format (mail flow) |
| `articlesOfAssociation[]` | Statuten (corporate statutes) | When filed, PDF format (mail flow) |
# Norway
Source: https://docs.topograph.co/essentials/norway
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Norway reference is on the [Norway country page](https://www.topograph.co/countries/no).
## Start here
This guide contains public integration notes for Norway. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Norway uses a single official registry for all company data.
* **Bronnysundregistrene (BR-Reg / The Bronnoysund Register Centre)** -- Operated by the Norwegian government, BR-Reg maintains the **Enhetsregisteret** (Entity Register) and **Foretaksregisteret** (Business Register). It is the **sole data source** for all Norwegian entities. It provides comprehensive company data including legal form, status, management roles, activity codes (NACE), employees, addresses, contact information, and sub-entities (establishments). The API covers all entity types: commercial companies, sole proprietorships, non-profits, and public institutions.
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Domestic AS and ASA companies. Example: `NOFOR.923609016`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entities** | BR-Reg | 9 digits (Organization Number), starting with 8 or 9; the last digit is a modulus-11 check digit | `923609016` | Organisasjonsnummer, accepts spaces or dots as separators |
**Organization Number Format:** The organization number is 9 digits. It can be entered in three formats: `923609016` (no separators), `923 609 016` (spaces), or `923.609.016` (dots). All formats are normalized by stripping separators, and the response carries the number without separators: `923609016`.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `organisasjonsnummer` | 9 digits | `923609016` | All entities |
| `VAT` | 9 digits + MVA | `923609016MVA` | VAT-registered companies (auto-generated) |
**VAT Number Auto-Generation:** The VAT number is automatically generated by appending `MVA` to the organization number when the company has `registrertIMvaregisteret = true`. It is not a separate identifier from the registry.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the organisation number (`organisasjonsnummer`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Organization Number | 9 digits | `923609016` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Organization Number (spaces) | 3+3+3 digits | `923 609 016` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Organization Number (dots) | 3.3.3 digits | `923.609.016` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Equinor"` | Fuzzy | Multiple results (up to 20) |
**Search Performance:** Use identifier-based searches (organization number) for best performance and exact matching. Name searches query the BR-Reg REST API and may return multiple results.
Identifier searches (organization number) perform exact lookups and are faster than name searches.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies in bankruptcy or winding up count as inactive and are removed.
## Fast search data
Norway company data is **periodically synchronized** from the Enhetsregisteret open dataset into a fast search index.
### Search
Search queries hit the **fast search index first** for instant results, with automatic fallback to the live BR-Reg API if the fast search index misses.
### Companies in fast search data
The fast search index contains **all active Norwegian entities** from the Enhetsregisteret. Companies in the following states are **excluded** from the fast search dataset:
| Excluded Status | Flag | Reason |
| - | - | - |
| Bankruptcy | `konkurs = true` | Company is in bankruptcy proceedings |
| Under Liquidation | `underAvvikling = true` | Voluntary liquidation in progress |
| Forced Dissolution | `underTvangsavviklingEllerTvangsopplosning = true` | Court-ordered dissolution |
Active companies without any of these flags are included regardless of legal form (AS, ENK, ANS, etc.).
### Company data
The fast search index serves search only. Company data requests read the live register, and prefill and verification requests return the same data.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Organization number normalization** | The 9-digit organization number accepts three input formats: `923609016`, `923 609 016`, `923.609.016`. All are normalized by stripping spaces and dots, and the response carries the number without separators (`923609016`). |
| **VAT number auto-generation** | VAT numbers are not stored in the registry. They are automatically generated by appending `MVA` to the organization number when `registrertIMvaregisteret = true`. |
| **No shareholder or UBO data** | The BR-Reg public API does not expose ownership, shareholder, or beneficial ownership information. |
| **Up to 3 NACE codes** | Norway provides up to 3 structured NACE activity codes (`naeringskode1`, `naeringskode2`, `naeringskode3`). These are official registry codes, never AI-inferred. |
| **Address preference** | The system prefers `forretningsadresse` (business address) over `postadresse` (postal address) for `legalAddress`. Establishments prefer `beliggenhetsadresse` (location address). |
| **Registration date priority** | Registration date uses a preference chain: `stiftelsesdato` (founding date) > `registreringsdatoEnhetsregisteret` (entity register date) > `oppstartsdato` (start date). |
| **Resigned roles filtered** | Roles with `fratraadt = true` (resigned) are excluded from both legal representatives and other key persons. |
| **Phone number formatting** | Norwegian phone numbers are formatted to E.164 format by prepending `+47` if the number is 8 digits and does not already include the country code. |
| **Activity description sources** | Activity description is sourced from `aktivitet` (activity text array) first, falling back to `vedtektsfestetFormaal` (statutory purpose) if unavailable. |
| **Annual reports by financial year** | Annual reports are listed separately for each financial year filed with the register. |
## Mappings
### Company Status
Company status is determined **deterministically** from boolean flags in the BR-Reg API response. No AI inference is involved in status determination.
| Local Status | English | Standardized Status | Closure Reason | Notes |
| - | - | - | - | - |
| Aktiv | Active | Active | -- | Default status when no closure flags are set |
| Konkurs | Bankruptcy | Closed | Bankruptcy | `konkurs = true` |
| Under avvikling | Under Liquidation | Under Insolvency Proceeding | Voluntary Dissolution | `underAvvikling = true` |
| Under tvangsavvikling eller tvangsopplosning | Under Forced Liquidation | Under Insolvency Proceeding | Court Order | `underTvangsavviklingEllerTvangsopplosning = true` |
| Opphort | Ceased | Closed | Other | `nedleggelsesdato` or `slettedato` is set |
Status determination uses a priority chain: (1) `konkurs` (bankruptcy), (2) `underAvvikling` (voluntary liquidation), (3) `underTvangsavviklingEllerTvangsopplosning` (forced liquidation), (4) presence of `nedleggelsesdato` or `slettedato` (cessation/deletion date). If none apply, the company is Active.
### Legal Forms
Norway uses the `organisasjonsform.kode` from the BR-Reg API. The system translates the code to English using a **deterministic** pre-computed lookup table covering all known organisasjonsform codes. For known codes, standardized classification is applied directly; for unrecognized codes, AI-based classification is used as fallback.
Legal forms are classified from official registry data. For known codes, standardized classification is applied directly; for unrecognized codes, AI-based classification is used as fallback.
#### Companies
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Aksjeselskap | Private limited company | Limited Liability Company | YI42 |
| Allmennaksjeselskap | Public limited company | Corporation | IQGE |
| Europeisk selskap | Societas Europaea | Corporation | V06W |
#### Sole Proprietorships
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Enkeltpersonforetak | Sole proprietorship | Sole Proprietorship | EXD7 |
#### Partnerships
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Ansvarlig selskap | General partnership | Partnership | 326Y |
| Delt ansvarlig selskap | General partnership with shared liability | Partnership | 326Y |
| Kommandittselskap | Limited partnership | Partnership | M9IQ |
| Partrederi | Shipping partnership | Partnership | AEV1 |
#### Cooperatives
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Selskap med begrenset ansvar | Cooperative | Cooperative | Q0Q1 |
| Boligbyggelag | Housing cooperative | Cooperative | 9DI1 |
| Borettslag | Housing cooperative | Cooperative | O0EU |
| Samvirkeforetak | Cooperative | Cooperative | K5P8 |
#### Non-profit Organizations
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Forening/lag/innretning | Association | Nonprofit Organization | FSBD |
| Den norske kirke | Church of Norway | Nonprofit Organization | 4ZRR |
| Stiftelse | Foundation | Nonprofit Organization | 3C7U |
#### Government-Owned Entities
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Fylkeskommunalt foretak | County enterprise | Government-Owned Entity | 5ZTZ |
| Fylkeskommune | County | Government-Owned Entity | KX7D |
| Interkommunalt selskap | Inter-municipal company | Government-Owned Entity | YTMC |
| Kommunalt foretak | Municipal enterprise | Government-Owned Entity | 3L58 |
| Kommune | Municipality | Government-Owned Entity | 3L58 |
| Statsforetak | Public administration entity | Government-Owned Entity | 50TD |
| Statsforetak | State enterprise | Government-Owned Entity | 50TD |
| Staten | The State | Government-Owned Entity | - |
#### Branch / Representative Office
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Norskregistrert utenlandsk foretak | Norwegian branch of foreign company | Branch or Representative Office | 4ZRR |
#### Other
| Local Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Gjensidig forsikringsselskap | Mutual insurance company | Other | 8S9H |
| Ikke registreringspliktig juridisk person | Non-mandatory legal entity | Other | 4ZRR |
| Konkursbo | Bankruptcy estate | Other | PB3V |
| Organisasjonsledd | Organisational sub-unit | Other | - |
| Pensjonskasse | Pension fund | Other | BJ65 |
| Sameie | Co-ownership | Other | - |
| Sparebank | Savings bank | Other | R71C |
| Tvangsam | Forced co-ownership | Other | - |
| Verdipapirfond | Securities fund | Other | LJJW |
### Legal Representatives
The current register publishes 27 role codes, including administrative relationships that are not person appointments. Known offices use fixed English translations and standardized values. The person’s office and their individual signing capacity are separate.
For an AS, the board represents the company collectively. An ordinary chair, vice-chair or member appears under `otherKeyPersons` unless the retrieved data establishes an individual mandate, or the complete registered AS board contains exactly one current member. Employee-elected members count as board members; substitutes do not establish a one-person board.
`Daglig leder` is `Managing Director`, with statutory capacity limited to daily management. `Innehaver` is `Owner`; a registered general partner is `General Partner`. ANS and DA partners appear as `Partner` in `legalRepresentatives` when no board is registered; a registered board or a missing form prevents that inference. Detailed signature combinations and restrictions may require separate register information and are not inferred from these titles.
| Register office | Standardized | Response list |
| - | - | - |
| Daglig leder | Managing Director | `legalRepresentatives` |
| Innehaver | Owner | `legalRepresentatives` |
| Komplementar | General Partner | `legalRepresentatives` |
| Bestyrende reder | Managing Director | `legalRepresentatives` |
| Bostyrer | Receiver | `legalRepresentatives` |
| Styrets leder, without an individual mandate | Chairman of the Board | `otherKeyPersons` |
| Nestleder, without an individual mandate | Vice Chairman of the Board | `otherKeyPersons` |
| Styremedlem, without an individual mandate | Board Member | `otherKeyPersons` |
| Varamedlem | Board Member | `otherKeyPersons` |
| Revisor | Auditor | `otherKeyPersons` |
| Regnskapsfører | Other | `otherKeyPersons` |
| Forretningsfører | Other | `otherKeyPersons` |
| Observatør | Board Observer | `otherKeyPersons` |
| Norsk representant for utenlandsk enhet, without an individual mandate | Other | `otherKeyPersons` |
| Eierkommune, ownership alone | Other | `otherKeyPersons` |
Corporate office holders retain their company identity. A municipal owner or an administrative foreign-entity representative is not treated as a general company signer solely because of that relationship. A title or the word “alone” does not establish signing authority; a negated grant is not a positive mandate.
### Shareholders
Shareholder data is **not available** from the BR-Reg API. The Norwegian business registry does not expose ownership or shareholder information through its public API.
Unlike Denmark (which provides shareholder data via CVR) or the Netherlands (which extracts shareholder data from trade register extracts via AI parsing), Norway's public registry API does not include any ownership data.
### Other Key Persons
Other key persons include board members, auditors, accountants, business managers, and other non-executive roles. Both individual and corporate entities can hold these roles (e.g., an auditing firm as `REVI`).
### Ultimate Beneficial Owners
UBO data is **not available** from the BR-Reg API. The Norwegian business registry does not expose beneficial ownership information through its public API endpoints.
### Activity Codes
Norway uses the **SN2007 (Standard for naeringsgruppering)** classification, which is the Norwegian implementation of NACE Rev. 2. Activity codes come directly from the BR-Reg API structured fields (`naeringskode1`, `naeringskode2`, `naeringskode3`).
```
SN2007 (Norwegian) -> NACE Rev. 2 (European) -> ISIC Rev. 5 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NACE** | `naeringskode1.kode` (primary) | `62.010` | No (official from registry) |
| **NACE** | `naeringskode2.kode` (secondary) | `49.500` | No (official from registry) |
| **NACE** | `naeringskode3.kode` (tertiary) | `35.110` | No (official from registry) |
| **ISIC** | Derived from NACE via the formal correspondence | `6201` | No (AI only when no correspondence exists) |
**AI Enrichment:** NACE codes are **never** AI-inferred for Norway -- they come directly from the registry as structured data. ISIC codes are derived from the register's NACE codes through the formal NACE to ISIC correspondence. AI is used only when no correspondence exists for any of the company's codes. Every activity item includes an `isAIInferred` flag.
**Multiple Activity Codes:** Norway supports up to 3 NACE activity codes per company: `naeringskode1` (primary business activity), `naeringskode2` (secondary), and `naeringskode3` (tertiary). Each includes both the code and a Norwegian description. The register's primary code (`naeringskode1`) is flagged with `isMainActivity: true` on the NACE entry, and the ISIC code derived from it inherits the flag. Secondary and tertiary codes carry no flag.
## Data Availability
### Data Availability Matrix
| Data Type | Commercial Companies | Sole Entrepreneurs | Non-Profits | Public Entities | Notes |
| - | - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | ✅ Async | Full data from BR-Reg API |
| Legal Representatives | ✅ | ✅ | ✅ | ✅ | Deterministic from roles API |
| Other Key Persons | ✅ | ⚠️ Limited | ✅ | ✅ | Board members, auditors, etc. |
| Shareholders | ❌ | ❌ | ❌ | ❌ | Not available from BR-Reg |
| Ultimate Beneficial Owners | ❌ | ❌ | ❌ | ❌ | Not available from BR-Reg |
| Establishments | ✅ | ✅ | ✅ | ✅ | From sub-entities (underenheter) |
| Activity Codes | ✅ | ✅ | ✅ | ✅ | NACE from naeringskode fields |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Documents
#### All Companies
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Enhetsutskrift (Trade Register Extract)** | `tradeRegisterExtract` | PDF | ✅ Always available | Official extract (\~30 sec delivery) |
| **Arsregnskap (Annual Report)** | `financialStatements[]` | PDF | ✅ When filed | Annual reports by fiscal year (\~30 sec delivery) |
**Trade Register Extract:** The Enhetsutskrift is always available for any registered entity. It is retrieved from the official register and generated as a PDF with an estimated delivery time of \~30 seconds.
**Annual Reports:** Financial statements are listed for every financial year with a filed annual report. Each year with an annual report generates a separate document entry with period information (start and end dates of the fiscal year). The document name follows the pattern `Arsregnskap {year}` (e.g., "Arsregnskap 2024"). Annual reports are fetched and deduplicated permanently since they do not change once published.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "NO", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "123456789",
"countryCode": "NO",
"identifiers": {
"organisasjonsnummer": "123456789",
"VAT": "123456789MVA"
},
"legalName": "Nordisk Teknologi AS",
"registrationDate": "2015-06-15",
"activityDescription": "Utvikling og salg av programvare.",
"status": {
"localName": "Aktiv",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Aksjeselskap",
"englishTranslation": "Private Limited Company",
"standardized": "Limited Liability Company"
},
"employeeCount": {
"exact": 25
},
"activities": {
"NACE": [
{
"code": "62.010",
"description": "Programmeringstjenester",
"isAIInferred": false
},
{
"code": "62.020",
"description": "Konsulentvirksomhet tilknyttet informasjonsteknologi",
"isAIInferred": false
}
],
"ISIC": [
{
"code": "6201",
"description": "Computer programming activities",
"isAIInferred": false
}
]
},
"legalAddress": {
"addressLine1": "Karl Johans gate 10",
"city": "OSLO",
"postalCode": "0154",
"region": "OSLO",
"countryCode": "NO"
},
"phones": [
"+4712345678"
],
"website": "https://www.example.no"
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Daglig leder",
"englishTranslation": "Managing Director",
"standardized": "Managing Director"
},
"individual": {
"name": {
"fullName": "Lars Hansen",
"firstName": "Lars",
"lastName": "Hansen"
},
"birthDate": {
"year": 1980,
"month": 3,
"day": 15
}
}
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Styremedlem",
"englishTranslation": "Board Member",
"standardized": "Board Member"
},
"individual": {
"name": {
"fullName": "Erik Berg",
"firstName": "Erik",
"lastName": "Berg"
}
}
},
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Revisor",
"englishTranslation": "Auditor",
"standardized": "Auditor"
},
"company": {
"id": "987654321",
"legalName": "Norsk Revisjon AS"
}
},
{
"entityId": "person_003",
"type": "individual",
"role": {
"localName": "Styrets leder",
"englishTranslation": "Chairman of the Board",
"standardized": "Chairman of the Board"
},
"individual": {
"name": {
"fullName": "Kari Olsen",
"firstName": "Kari",
"lastName": "Olsen"
}
}
}
],
"establishments": [
{
"name": "Nordisk Teknologi AS Avd Oslo",
"id": "912345678",
"active": true,
"address": {
"city": "OSLO",
"postalCode": "0154",
"countryCode": "NO"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "987654321",
"countryCode": "NO",
"identifiers": { "organisasjonsnummer": "987654321" },
"legalName": "Hansen Konsult",
"registrationDate": "2020-01-10",
"activityDescription": "Bedriftsradgivning og administrativ radgivning.",
"status": { "localName": "Aktiv", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Enkeltpersonforetak", "englishTranslation": "Sole Proprietorship", "standardized": "Sole Proprietorship" },
"employeeCount": { "exact": 1 },
"activities": {
"NACE": [{ "code": "70.220", "description": "Bedriftsradgivning og annen administrativ radgivning", "isAIInferred": false }],
"ISIC": [{ "code": "7020", "description": "Management consultancy activities", "isAIInferred": false }]
},
"legalAddress": { "addressLine1": "Storgata 5", "city": "BERGEN", "postalCode": "5003", "region": "BERGEN", "countryCode": "NO" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Innehaver", "englishTranslation": "Owner", "standardized": "Partner" }, "individual": { "name": { "fullName": "Morten Hansen", "firstName": "Morten", "lastName": "Hansen" } } }
]
}
```
**Note:** Sole proprietorships (`ENK`) have the owner (`Innehaver`) as the only legal representative. No shareholders or board members are present.
```json theme={null}
{
"company": {
"id": "111222333",
"countryCode": "NO",
"identifiers": { "organisasjonsnummer": "111222333" },
"legalName": "Gammel Bedrift AS (konkurs)",
"registrationDate": "2010-05-20",
"status": {
"localName": "Konkurs",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "BANKRUPTCY",
"additionalInfo": "Company is in bankruptcy proceedings"
}
},
"legalForm": { "localName": "Aksjeselskap", "englishTranslation": "Private Limited Company", "standardized": "Limited Liability Company" },
"legalAddress": { "addressLine1": "Industrivegen 20", "city": "TRONDHEIM", "postalCode": "7030", "countryCode": "NO" }
},
"legalRepresentatives": [],
"otherKeyPersons": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Bostyrer", "englishTranslation": "Bankruptcy Trustee/Administrator", "standardized": "Other" }, "individual": { "name": { "fullName": "Advokat Nilsen", "firstName": "Advokat", "lastName": "Nilsen" } } }
]
}
```
**Note:** Bankrupt companies have `konkurs = true`, status is `CLOSED` with closure reason `BANKRUPTCY`. A bankruptcy trustee (`Bostyrer`, code `BOBE`) may appear as an other key person.
```json theme={null}
{
"company": {
"id": "555666777",
"countryCode": "NO",
"identifiers": {
"organisasjonsnummer": "555666777"
},
"legalName": "Norsk Idrettslag",
"registrationDate": "2005-03-01",
"activityDescription": "Fremme idrettsaktiviteter og organisere lokale sportsarrangementer.",
"status": {
"localName": "Aktiv",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Forening/lag/innretning",
"englishTranslation": "Association",
"standardized": "Nonprofit Organization"
},
"employeeCount": {
"exact": 3
},
"activities": {
"NACE": [
{
"code": "93.120",
"description": "Idrettslag og -klubber",
"isAIInferred": false
}
],
"ISIC": [
{
"code": "9312",
"description": "Activities of sports clubs",
"isAIInferred": false
}
]
},
"legalAddress": {
"addressLine1": "Idrettsveien 12",
"city": "STAVANGER",
"postalCode": "4001",
"region": "STAVANGER",
"countryCode": "NO"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Styremedlem",
"englishTranslation": "Board Member",
"standardized": "Board Member"
},
"individual": {
"name": {
"fullName": "Tor Eriksen",
"firstName": "Tor",
"lastName": "Eriksen"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Styrets leder",
"englishTranslation": "Chairman of the Board",
"standardized": "Chairman of the Board"
},
"individual": {
"name": {
"fullName": "Ingrid Bakke",
"firstName": "Ingrid",
"lastName": "Bakke"
}
}
}
]
}
```
**Note:** Non-profits (`FLI`) are retrieved from the same BR-Reg API as commercial companies. They may have board members, chairman, and auditors. No shareholders or UBOs.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Enhetsutskrift PDF | Always available (\~30 sec) |
| `financialStatements[]` | Arsregnskap (annual reports by year) | When filed, with period data |
# Ownership Graph
Source: https://docs.topograph.co/essentials/ownership-graph
Traverse multi-level ownership structures across countries automatically
The `graph` datapoint builds a complete ownership tree by recursively fetching shareholders across multiple countries and traversal depths. Starting from a root company, Topograph follows corporate shareholder chains (resolving each company in its local registry) to produce a full graph of entities and ownership relationships.
The result includes UBO (Ultimate Beneficial Owner) calculations based on accumulated ownership and control established from ownership percentages.
`graph` is a verification-only datapoint. The traversal resolves each node against its live local register, so it cannot complete within the prefill deadline. Requesting `graph` with `mode: "prefill"` fails immediately with `fast_source_unavailable`, without fetching or billing anything. See [Modes](/essentials/modes).
`graph` is not available in [development environments](/guides/development-environment): requests for it there fail with `datapoint_not_supported`.
## Example Request
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "AT",
"id": "36416d",
"dataPoints": ["graph"],
"graphMaxBudget": 500
}'
```
## How It Works
1. **Root fetch**: Retrieves the company profile and shareholders from the root company's registry
2. **Shareholder resolution**: For each corporate shareholder, searches the relevant country's registry to find the company
3. **Recursive traversal**: Fetches shareholders for each resolved company, building the tree level by level
4. **UBO calculation**: Identifies individuals through accumulated ownership or ownership-based control
The traversal runs breadth-first with bounded concurrency. Each level completes before the next starts.
## Traversal Limits
The graph traversal has built-in limits to control scope and cost:
| Limit | Default | Description |
| - | - | - |
| **Budget** | No limit when `graphMaxBudget` is omitted (the depth and entity limits still apply) | Maximum credit cents to spend on company lookups during traversal. The primary control for graph scope. |
| **Max depth** | 10 levels | Maximum depth of shareholder chain to follow |
| **Max entities** | 500 | Maximum total entities (companies + individuals) in the graph |
| **Execution timeout** | 6 hours | Safety net for stuck traversals. Should never be reached in normal operation |
When any limit is reached, the graph returns all data collected up to that point with a `stoppedReason` indicating why traversal stopped.
**Need higher limits?** If your use case requires deeper traversals or more entities, [contact us](mailto:hello@topograph.co) to discuss your requirements.
## Stopped Reasons
The `metadata.stoppedReason` field indicates how the traversal ended:
| Reason | Meaning |
| - | - |
| `completed` | All shareholder chains were fully resolved |
| `budget_exhausted` | The `graphMaxBudget` limit was reached |
| `max_depth_reached` | Maximum traversal depth was reached |
| `max_nodes_reached` | Maximum entity count was reached |
| `timeout` | Execution timeout was reached (indicates a system issue) |
## Response Structure
The graph result is included alongside the standard company data:
```json theme={null}
{
"request": {
"requestId": "uuid-v4",
"companyId": "36416d",
"countryCode": "AT",
"dataStatus": {
"dataPoints": {
"graph": { "status": "succeeded" }
}
}
},
"graph": {
"nodes": [
{
"nodeId": "AT:36416d",
"type": "company",
"flags": {
"isRoot": true,
"status": "found",
"isUbo": false
},
"company": {
"legalName": "Example Handels GmbH",
"countryCode": "AT",
"id": "36416d"
}
},
{
"nodeId": "FR:301189718",
"type": "company",
"flags": {
"isRoot": false,
"status": "found",
"isUbo": false,
"isUboProxy": true
},
"company": {
"legalName": "Holding Internationale",
"countryCode": "FR",
"id": "301189718"
},
"totalOwnershipPercentage": 61
}
],
"edges": [
{
"id": "AT:36416d->FR:301189718",
"fromId": "AT:36416d",
"toId": "FR:301189718",
"percentage": 61,
"source": "Extracted from trade register extract"
}
],
"description": "Ownership graph with 2 entities and 1 relationship.",
"metadata": {
"stoppedReason": "completed",
"amountSpent": 200,
"companiesFetched": 2,
"companiesSkipped": 0
}
}
}
```
## Node Flags
| Flag | Type | Description |
| - | - | - |
| `isRoot` | boolean | The company that was originally requested |
| `status` | string | `found`, `pending`, `not_found`, `error`, `placeholder`, `search_resolved`, `budget_truncated`, `coverage_unavailable` |
| `isUbo` | boolean | Individual qualifying through accumulated ownership or ownership-based control |
| `uboCalculationMethod` | string\[] | Qualifying methods: `accumulation`, `domination`, or both. Present for qualifying individuals |
| `isUboProxy` | boolean | Qualifying company without a known qualifying upstream owner. A company whose own shareholder lookup failed or returned no data is not flagged as an ultimate controller |
A node with `status: "budget_truncated"` is a placeholder for a corporate shareholder the traversal did not fetch (because of `graphMaxBudget`, `graphInteractive`, or a depth/entity limit). It carries the `nodeId` and a cost preview, and can be passed to `graphContinueFromNodeIds` in a follow-up request to resume from there.
A node with `status: "coverage_unavailable"` is a corporate shareholder in a country where shareholder data is not available. The branch ends there, and the node cannot be passed to `graphContinueFromNodeIds`.
## UBO calculation
The graph evaluates each individual independently using two methods. `totalOwnershipPercentage` always reports economic ownership, calculated by multiplying percentages along each ownership chain and adding the results across chains.
### Accumulated ownership
`accumulation` qualifies an individual with at least 25% direct or indirect ownership. For example, 60% of a holding company that owns 30% of the target contributes 18%. Another 10% held directly brings the total to 28%.
### Ownership-based control
`domination` qualifies an individual through a majority-control chain or a mixed ownership and control structure:
* More than 50% establishes control of a company. Control can continue through successive majority-controlled companies, including stakes held cumulatively through controlled companies.
* An individual controlling companies that together hold at least 25% directly in the target qualifies through control.
* An individual with at least 25% accumulated ownership in a company controlling the target also qualifies.
| Individual's stake in holding | Holding's stake in target | Economic ownership | Qualifying method |
| - | - | - | - |
| 51% | 40% | 20.4% | `domination` |
| 30% | 60% | 18% | `domination` |
| 50% | 50% | 25% | `accumulation` |
| 60% | 60% | 36% | Both |
A control-qualified individual can therefore have `isUbo: true` while `totalOwnershipPercentage` is below 25%. Exactly 50% does not establish majority control by itself.
These calculations implement the ownership-based rules in Articles 51–54 of [Regulation (EU) 2024/1624](https://eur-lex.europa.eu/eli/reg/2024/1624/oj/eng). The regulation generally applies from 10 July 2027. The calculation does not determine which legal standard applies to your case.
The graph does not assess separate voting rights, board appointment powers, vetoes or contractual control. Missing percentages and unresolved branches cannot establish control. Review source coverage and traversal limits before treating a graph as complete.
These calculated flags belong to the `graph` datapoint. They do not replace beneficial owners reported by a register through the `ultimateBeneficialOwners` datapoint. Existing stored graph results retain their previous calculations; newly calculated graphs and merged continuations use the current rules.
## Interactive mode
Set `graphInteractive: true` to fetch only the entry company and return its direct shareholders. Companies among those shareholders come back as `budget_truncated` placeholders so the caller decides which branches to expand. Each chip click is one fetch and one billing event.
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "AT",
"id": "36416d",
"dataPoints": ["graph"],
"graphInteractive": true
}'
```
`graphInteractive` and `graphMaxBudget` are mutually exclusive. When `graphInteractive` is true, the budget value is ignored.
The response carries `graph.metadata.interactive: true` so a stored result is self-describing, and `graph.metadata.stoppedReason` reads `max_depth_reached`.
## Continuing from a previous request
To extend a graph from one or more `budget_truncated` placeholders, pass their `nodeId`s in `graphContinueFromNodeIds` and link to the parent through `mainRequestId`. `countryCode` and `id` are derived from the parent automatically.
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"dataPoints": ["graph"],
"mainRequestId": "",
"graphContinueFromNodeIds": ["FR:301189718"]
}'
```
Cost deduplication applies across the full request tree: companies already fetched in the parent (or a sibling continuation) are not re-billed.
If the parent request was made with `graphInteractive: true`, every continuation inherits the flag. The seeded node is fetched and its own direct shareholders are surfaced as a fresh layer of placeholders, ready for the next click.
## Best Practices
Use `graphMaxBudget` when you want a single response with as much of the tree as fits within a known cost ceiling. Use `graphInteractive` when you want predictable per-step cost and a deterministic UI: one fetch per request, the rest of the tree visible only as continuation handles you choose to expand.
The `graphMaxBudget` parameter is the primary way to control non-interactive traversal scope. Without it, a non-interactive traversal has no credit ceiling, so always set it (or use `graphInteractive`) to cap spend. Start with a lower budget for exploration, then increase if you need deeper coverage. Each company lookup costs the standard price for that country.
Graph traversal time depends on the number of companies, the countries involved, and registry response times. Simple structures (1-2 levels, single country) complete in seconds. Complex multi-country structures with deep chains can take several minutes. Interactive requests are bounded by a single company fetch, so they return as fast as that country's registry replies.
When a limit is reached, the graph returns everything collected so far. Check `metadata.stoppedReason` to understand why traversal stopped and whether requesting again with a higher budget, or extending via `graphContinueFromNodeIds`, would yield more data.
# Poland
Source: https://docs.topograph.co/essentials/poland
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Poland reference is on the [Poland country page](https://www.topograph.co/countries/pl).
## Start here
This guide contains public integration notes for Poland. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Poland uses a **hybrid approach** across three registers, routing company lookups based on entity type. For a given entity, data comes from a single source determined by the registration prefix and by which register actually holds the entity.
### KRS companies (legal entities)
* **KRS (Krajowy Rejestr Sadowy / National Court Register).** Operated by the Ministry of Justice, the KRS is the **primary source for all legal entities**: limited liability companies (sp. z o.o.), joint-stock companies (S.A.), partnerships, associations, foundations, cooperatives, and other registered entities. Provides company name, legal form, status, address, capital, activity codes (PKD), management board members, procurators, and shareholders (sp. z o.o. only).
* **CRBR (Centralny Rejestr Beneficjentow Rzeczywistych / Central Register of Beneficial Owners).** Poland's official UBO registry, mandatory for all entities registered in KRS. Provides ultimate beneficial owner data including ownership percentages, control types (direct/indirect), and management positions. Accessed programmatically.
* **eKRS Financial Documents Portal (ekrs.ms.gov.pl).** Official portal for financial documents filed by KRS companies. Provides annual financial statements, consolidated statements, management reports, auditor opinions, and approval resolutions. Documents may be in XML format (automatically converted to PDF).
### CEIDG sole proprietors (individual businesses)
* **biznes.gov.pl API.** Government API for the Central Register and Information on Business Activity (CEIDG). Used for **search across both registers** (KRS + CEIDG) and as the **sole data source for sole proprietors**. Provides company name, owner name, address, PKD activity codes, status, and basic contact information.
### Entities in neither register
* **REGON (Krajowy rejestr urzedowy podmiotow gospodarki narodowej / National Official Business Register).** The statistical register maintained by Statistics Poland (GUS), queried through its BIR1.2 API. Entry is compulsory for every entity in the national economy, so REGON is the **only** Polish register covering entities that appear in neither KRS nor CEIDG -- civil-law partnerships (`spolka cywilna`) above all, plus housing communities, foreign representative offices, schools and public-administration bodies. Provides legal name, short name, legal form, registered seat, PKD activity codes, registration and closure dates, and a phone number where the entity declared one. REGON is used **only when KRS and CEIDG both return nothing**: for anything either of them holds, they are the richer source.
### VAT validation
* **VIES (EU VAT Information Exchange System).** In verification mode, the Polish VAT number (PL + NIP) is validated against VIES, with a qualified consultation number when the entity is VAT-registered.
**Three registers, one entity model:** KRS covers legal entities (companies, non-profits, cooperatives), CEIDG covers sole proprietors, and REGON covers everything -- including the entities the other two structurally cannot hold. Our system uses prefixed identifiers (`krs-` / `nip-`) to route requests, and falls back to REGON when neither entrepreneur register recognises the identifier.
**REGON is not an ownership source.** It is a statistical register: it publishes an entity's identity, not who owns or represents it. Beneficial owners come from CRBR and representatives from KRS or CEIDG, so a company served from REGON returns identity fields only.
* **`krs-{number}` prefix**: Routes to the KRS API. Used for all legal entities registered in the National Court Register (companies, associations, foundations, cooperatives).
* **`nip-{number}` prefix**: Routes to the biznes.gov.pl API. Used for sole proprietors registered in CEIDG.
The prefix is **required** because both KRS and NIP numbers are 10-digit identifiers that could collide. Not all KRS entities have a NIP (e.g., some associations and foundations), making KRS the only reliable identifier for those entities.
**Key Takeaway:** Always use the appropriate prefix when querying. Search results from the API already include the correct prefix.
A `spolka cywilna` is not a separate legal entity under Polish law, so it is registered in **neither KRS nor CEIDG** -- but it does hold its own NIP and REGON, and it is entered in the REGON register with its own name, legal form, seat and PKD codes.
* **Search** by the partnership's NIP or REGON returns the partnership itself, from REGON. It also returns the individual partners, resolved from their CEIDG entries, with `matchType: partialId` -- those results describe the partners, not the partnership.
* **Company lookups** using the partnership's `nip-` identifier return its identity from REGON.
* **Liability sits with the partners**, so a `spolka cywilna` has no share capital and no representatives of its own to return.
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Domestic sp. z o.o. and S.A. companies with a KRS number. Example: `PLKRS.0000028860`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **KRS legal entities** | KRS | `krs-` + 10 digits | `krs-0001010154` | Padded with leading zeros |
| **CEIDG sole proprietors** | CEIDG | `nip-` + 10 digits | `nip-9511901401` | NIP (tax identification number) |
**Prefixed identifiers are required.** Company IDs must use `krs-` or `nip-` prefixes to route to the correct register. Without a prefix, the system cannot determine the data source and will return an error.
**KRS Number Padding:** KRS numbers are always 10 digits with leading zeros (e.g., `0001010154`). When searching by KRS number, shorter inputs are automatically padded to 10 digits.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `krs` | 10 digits | `0001010154` | KRS legal entities only |
| `nip` | 10 digits, the last one a check digit | `7740001454` | Most KRS entities and all CEIDG entities |
| `regon` | 9 digits (or 14 for branches) | `003295237` | Most entities across both registers |
| `VAT` | 10 digits (same as NIP) | `7740001454` | Entities with NIP |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the KRS number (`krs`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By KRS Number | 1-10 digits | `0001010154` | Exact | Exact match returned first (matchType: id); other results may follow |
| By NIP Number | 10 digits | `7740001454` | Not guaranteed unique | `matchType: partialId`. Usually one result, but a NIP can be shared by several KRS entities (see the note below) |
| By REGON Number | 9 or 14 digits | `003295237` | Not guaranteed unique | `matchType: partialId`. Resolves entities in both registers; a REGON can also be shared by several KRS entities, a 9-digit REGON can be the prefix of a 14-digit one, and a 14-digit local-unit REGON resolves to its parent entity |
| By Name | Text string | `"Topograph"` | Contains | Multiple results across KRS + CEIDG |
**Search Performance:** Use identifier-based searches (KRS, NIP, REGON) for best performance. The KRS number is the only one guaranteed to identify a single entity. Name searches query biznes.gov.pl and may return multiple results from both KRS and CEIDG registers.
**Search queries multiple sources in parallel.** For identifier searches, the system queries KRS by KRS number, KRS by NIP, KRS by REGON, CEIDG by NIP, CEIDG by REGON, and the REGON statistical register simultaneously. Results are deduplicated by ID, with KRS results taking precedence over CEIDG when both match. REGON results are used only when no other register recognises the identifier, so an ordinary company is never returned twice.
**A NIP or REGON can return several companies.** Only the KRS number identifies exactly one entity. When a business reorganises through successive legal entities it keeps its tax (NIP) and statistical (REGON) numbers, so those can be shared across several KRS entries — typically one active company plus one or more struck-off predecessors. Searching NIP `7622006714` or REGON `38186693900000`, for example, returns three companies.
Those results carry `matchType: partialId` rather than `id`, and each one has its own `id` (`krs-…`). **Always pass the `id` from the search result to `/v2/company`, never the NIP or REGON**, and retrieve the company data to establish which entity is current — search results do not carry company status.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Sole traders are filtered by their register status. Companies in the court register are returned whatever their status, because search does not report it.
## Company Status
Company status is determined from KRS register data and enhanced with AI mapping. CEIDG (sole proprietor) statuses use a separate mapping path.
### KRS Companies (primary path)
Status is derived from multiple KRS data points: deletion indicators, bankruptcy proceedings, merger records, and name-based liquidation detection.
| Local Status (Polish) | English | Standardized Status | Detection Method |
| - | - | - | - |
| AKTYWNA | Active | Active | Default (no closure indicators) |
| W LIKWIDACJI | In Liquidation | Closed | Company name contains "W LIKWIDACJI" |
| WYKREŚLONA Z REJESTRU | Deleted from Register | Closed | Deletion entries in the KRS extract |
| W UPADŁOŚCI | In Bankruptcy | Under Insolvency Proceeding | Bankruptcy announced but not completed |
| UPADŁOŚĆ ZAKOŃCZONA | Bankruptcy Completed | Closed | Bankruptcy proceedings have completion date |
| PRZEJĘTA PRZEZ INNĄ SPÓŁKĘ | Acquired by Another Company | Closed | Merger/acquisition records in the KRS extract |
| DZIAŁALNOŚĆ ZAWIESZONA | Activity Suspended | Under Insolvency Proceeding | Suspension date present without resumption |
**Closure reasons** (when status is Closed or Under Insolvency Proceeding):
| Scenario | Standardized Closure Reason |
| - | - |
| Deletion from KRS/RP register | Administrative Dissolution |
| Bankruptcy proceedings | Bankruptcy |
| Liquidation (name-based detection) | Liquidation |
| Merger/acquisition | Merger |
**Prefill mode uses a lighter, deterministic mapping.** It reads the register's entity record instead of the full extract, with no AI step. A struck-off company returns `WYKREŚLONY` with closure reason Liquidation, a suspended company returns `DZIAŁALNOŚĆ ZAWIESZONA`, and any other company returns `AKTYWNY`. Verification mode uses the same mapping for a struck-off company whose current extract the register no longer issues.
### CEIDG Sole Proprietors
| Local Status (Polish) | English | Standardized Status | Closure Reason |
| - | - | - | - |
| AKTYWNY | Active | Active | |
| WYLACZNIE\_W\_FORMIE\_SPOLKI | Trading only as a partner of a civil-law partnership | Active | |
| ZAWIESZONY | Suspended | Inactive Not Closed | |
| WYKRESLONY | Deleted | Closed | Voluntary Dissolution |
### Closure Date Priority
The system prioritizes closure dates in the following order:
1. **Deletion finalization date** in the KRS extract header (highest priority)
2. **Register deletion dates** from the KRS deletion records
3. **Bankruptcy completion date**
4. **CEIDG cancellation/cessation dates** (for sole proprietors)
In verification mode, KRS status classification is AI-enhanced. The local Polish status name from KRS is always preserved verbatim. The AI analyzes the status in context to provide standardized mapping. Deterministic rules (deletion, bankruptcy, liquidation) take precedence before AI enrichment.
## Legal Forms
Poland ships a **closed enum of 102 legal forms** sourced directly from the Polish registers: 51 forms the KRS returns, one canonical entry for CEIDG sole traders, and 50 forms from the REGON statistical register for entities held in neither KRS nor CEIDG. There is no AI fallback: an unknown value is rejected with `invalid` at ingestion time so the enum stays accurate and any new form the register introduces surfaces as a deploy blocker.
Provenance:
* **KRS values** were harvested from the full July 2024 snapshot of the Krajowy Rejestr Sadowy (849,757 entities across the commercial register RejP and the association register RejS). The top 13 forms cover 99.7% of the register and the full set is 50 distinct strings. A 51st form, the branch of a foreign entrepreneur, was added in July 2026 after live register responses returned it.
* **CEIDG sole traders** are projected onto a single canonical entry (`Osoba fizyczna prowadząca działalność gospodarczą`), because the biznes.gov.pl API does not expose a `formaPrawna` field for CEIDG entries (a sole trader has no entity-level legal form under Polish law).
* **REGON values** come from the closed `szczególna forma prawna` dictionary published by Statistics Poland (GUS). Only the forms that KRS and CEIDG do not already cover are added, chiefly entities registered only in REGON: civil-law partnerships, housing communities, foreign representative offices, schools and public-administration bodies.
* **ISO 20275 (ELF) codes** are attached as a cross-reference where GLEIF publishes one. Out of the 102 entries, 44 have an ELF code: 43 of the 51 KRS forms and the CEIDG entry. None of the REGON-only forms has one. GLEIF is not the source of the enum; the register is. We attach ELF codes opportunistically for LEI matching and nothing more.
GLEIF's ISO 20275 list for Poland is **incomplete** and is not a safe source of truth. 8 of the 51 KRS forms have no ELF code at all (for example the granular `stowarzyszenie` subtypes, public-benefit organizations without a church link, and branches of foreign entrepreneurs). This is why the enum is built from the register itself, not from ISO 20275.
### Core commercial forms
| Polish Name | Abbr. | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Spółka z ograniczoną odpowiedzialnością | sp. z o.o. | Limited Liability Company | Limited Liability Company | O7XB |
| Spółka akcyjna | S.A. | Joint-Stock Company | Corporation | FJ0E |
| Prosta spółka akcyjna | P.S.A. | Simple Joint-Stock Company | Corporation | B21W |
| Spółka jawna | sp.j. | General Partnership | Partnership | 629I |
| Spółka komandytowa | sp.k. | Limited Partnership | Partnership | BSJT |
| Spółka komandytowo-akcyjna | S.K.A. | Limited Joint-Stock Partnership | Partnership | OMX0 |
| Spółka partnerska | sp.p. | Professional Partnership | Partnership | 3BJG |
| Spółka europejska | SE | European Company | Corporation | J3A3 |
| Europejskie zgrupowanie interesów gospodarczych | EEIG | European Economic Interest Grouping | Partnership | 85PM |
### Cooperatives and mutuals
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Spółdzielnia | Cooperative | Cooperative | 8TOF |
| Spółdzielnia europejska | European Cooperative Society (SCE) | Cooperative | (no ELF) |
| Spółdzielcza kasa oszczędnościowo-kredytowa | Credit Union (SKOK) | Cooperative | H7OD |
| Towarzystwo ubezpieczeń wzajemnych | Mutual Insurance Society (TUW) | Cooperative | WNX1 |
### State and public-sector entities
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Przedsiębiorstwo państwowe | State-Owned Enterprise | Government-Owned Entity | SMIS |
| Instytut badawczy (including Łukasiewicz Research Network) | Research Institute | Government-Owned Entity | KM66 |
| Instytucja gospodarki budżetowej | Budgetary Institution | Government-Owned Entity | CY1M |
| Samodzielny publiczny zakład opieki zdrowotnej | Independent Public Healthcare Institution (SPZOZ) | Government-Owned Entity | 13ZV |
### Associations and foundations
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Stowarzyszenie | Association | Nonprofit Organization | ZZKE |
| Związek stowarzyszeń | Union of Associations | Nonprofit Organization | ZZKE |
| Jednostka terenowa stowarzyszenia posiadająca osobowość prawną | Regional Unit of an Association with Legal Personality | Nonprofit Organization | (no ELF) |
| Stowarzyszenie kultury fizycznej | Sports Association | Nonprofit Organization | (no ELF) |
| Stowarzyszenie kultury fizycznej o zasięgu ogólnokrajowym | Nationwide Sports Association | Nonprofit Organization | (no ELF) |
| Stowarzyszenie ogrodowe | Gardening Association | Nonprofit Organization | (no ELF) |
| Fundacja | Foundation | Nonprofit Organization | 96XK |
### Trade unions and employer associations
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Związek zawodowy | Trade Union | Nonprofit Organization | LT9U |
| Jednostka organizacyjna związku zawodowego posiadająca osobowość prawną | Organizational Unit of a Trade Union | Nonprofit Organization | LT9U |
| Związek zawodowy rolników indywidualnych | Individual Farmers Trade Union | Nonprofit Organization | LT9U |
| Ogólnokrajowy związek międzybranżowy | National Inter-Industry Union | Nonprofit Organization | WOK7 |
| Związek pracodawców | Employers Association | Nonprofit Organization | WOK7 |
| Federacja / Konfederacja związków pracodawców | Federation or Confederation of Employer Associations | Nonprofit Organization | WOK7 |
### Guilds, chambers, and business organizations
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Cech rzemieślniczy | Guild of Craftsmen | Nonprofit Organization | 5F76 |
| Izba rzemieślnicza | Chamber of Crafts | Nonprofit Organization | 5F76 |
| Związek Rzemiosła Polskiego | Polish Crafts Union | Nonprofit Organization | 5F76 |
| Izba gospodarcza | Chamber of Commerce | Nonprofit Organization | 5F76 |
| Inna organizacja podmiotów gospodarczych | Other Business Entity Organization | Nonprofit Organization | FQ5Y |
| Inna organizacja społeczna lub zawodowa | Other Social or Professional Organization | Nonprofit Organization | FQ5Y |
### Agricultural and transport associations
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Kółko rolnicze | Farmers Circle | Nonprofit Organization | FANM |
| Rolnicze zrzeszenie branżowe | Agricultural Branch Association | Nonprofit Organization | 6OYI |
| Związek rolniczych zrzeszeń branżowych | Union of Agricultural Branch Associations | Nonprofit Organization | 6OYI |
| Związki rolników, kółek i organizacji rolniczych | Unions of Farmers and Farmers Circles | Nonprofit Organization | WOK7 |
| Zrzeszenie handlu i usług | Trade and Services Association | Nonprofit Organization | 6OYI |
| Ogólnokrajowa reprezentacja zrzeszeń handlu i usług | National Representation of Trade Associations | Nonprofit Organization | 6OYI |
| Zrzeszenie transportu | Transport Association | Nonprofit Organization | 6OYI |
| Ogólnokrajowe zrzeszenie międzybranżowe | National Inter-Industry Association | Nonprofit Organization | 6OYI |
### Sports bodies
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Związek sportowy | Sports Union | Nonprofit Organization | WOK7 |
| Polski związek sportowy | Polish Sports Union | Nonprofit Organization | WOK7 |
### Public-benefit organizations and church entities
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Inna osoba prawna będąca organizacją pożytku publicznego | Other Legal Person Acting as a Public Benefit Organization | Nonprofit Organization | (no ELF) |
| Nieposiadająca osobowości prawnej organizacja pożytku publicznego | Public Benefit Organization without Legal Personality | Nonprofit Organization | (no ELF) |
| Kościelna osoba prawna będąca organizacją pożytku publicznego | Church Legal Person Acting as a Public Benefit Organization | Nonprofit Organization | SP4S |
| Nieposiadająca osobowości prawnej instytucja kościelna będąca organizacją pożytku publicznego | Church Institution without Legal Personality Acting as a Public Benefit Organization | Nonprofit Organization | SP4S |
### Foreign branches (KRS)
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Oddział zagranicznego przedsiębiorcy | Branch of a Foreign Entrepreneur | Branch or Representative Office | (no ELF) |
### Sole traders (CEIDG)
| Polish Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - |
| Osoba fizyczna prowadząca działalność gospodarczą | Sole Trader (CEIDG) | Sole Proprietorship | ZVVM |
### Entities registered only in REGON
These forms have no ISO 20275 code.
| Polish Name | English Translation | Standardized |
| - | - | - |
| Spółka cywilna | Civil-Law Partnership (s.c.) | Partnership |
| Spółka przewidziana w przepisach innych ustaw niż Kodeks spółek handlowych i Kodeks cywilny | Company Established under Statutes Other than the Commercial Companies Code or the Civil Code | Other |
| Uczelnia | Higher Education Institution | Other |
| Fundusz | Fund | Other |
| Kościół Katolicki | Catholic Church | Nonprofit Organization |
| Inny kościół lub związek wyznaniowy | Other Church or Religious Association | Nonprofit Organization |
| Europejskie ugrupowanie współpracy terytorialnej | European Grouping of Territorial Cooperation (EGTC) | Other |
| Stowarzyszenie niewpisane do KRS | Association Not Entered in the KRS | Nonprofit Organization |
| Organizacja społeczna oddzielnie niewymieniona, niewpisana do KRS | Social Organization Not Otherwise Specified, Not Entered in the KRS | Nonprofit Organization |
| Partia polityczna | Political Party | Nonprofit Organization |
| Samorząd gospodarczy lub zawodowy niewpisany do KRS | Trade or Professional Self-Government Body Not Entered in the KRS | Nonprofit Organization |
| Przedstawicielstwo zagraniczne | Foreign Representative Office | Branch or Representative Office |
| Wspólnota mieszkaniowa | Housing Community | Other |
| Towarzystwo reasekuracji wzajemnej | Mutual Reinsurance Society | Cooperative |
| Główny oddział zagranicznego zakładu reasekuracji | Main Branch of a Foreign Reinsurance Undertaking | Branch or Representative Office |
| Główny oddział zagranicznego zakładu ubezpieczeń | Main Branch of a Foreign Insurance Undertaking | Branch or Representative Office |
| Jednostka badawczo-rozwojowa | Research and Development Unit | Government-Owned Entity |
| Kolumna transportu sanitarnego | Medical Transport Column | Government-Owned Entity |
| Ogólnokrajowa reprezentacja zrzeszeń transportu | Nationwide Representation of Transport Associations | Nonprofit Organization |
| Przedsiębiorstwo zagraniczne | Foreign-Owned Enterprise | Other |
| Związek stowarzyszeń ogrodowych | Union of Gardening Associations | Nonprofit Organization |
| Przedszkole publiczne | Public Preschool | Government-Owned Entity |
| Przedszkole niepubliczne | Non-Public Preschool | Other |
| Publiczna szkoła podstawowa | Public Primary School | Government-Owned Entity |
| Publiczne gimnazjum | Public Lower-Secondary School | Government-Owned Entity |
| Publiczna szkoła ponadpodstawowa | Public Upper-Secondary School | Government-Owned Entity |
| Publiczna szkoła ponadgimnazjalna | Public Post-Lower-Secondary School | Government-Owned Entity |
| Publiczna szkoła artystyczna | Public Arts School | Government-Owned Entity |
| Niepubliczna szkoła podstawowa | Non-Public Primary School | Other |
| Niepubliczne gimnazjum | Non-Public Lower-Secondary School | Other |
| Niepubliczna szkoła ponadpodstawowa | Non-Public Upper-Secondary School | Other |
| Niepubliczna szkoła ponadgimnazjalna | Non-Public Post-Lower-Secondary School | Other |
| Niepubliczna szkoła artystyczna | Non-Public Arts School | Other |
| Publiczna placówka systemu oświaty | Public Education-System Establishment | Government-Owned Entity |
| Niepubliczna placówka systemu oświaty | Non-Public Education-System Establishment | Other |
| Inna publiczna jednostka organizacyjna systemu oświaty | Other Public Education-System Organizational Unit | Government-Owned Entity |
| Inna niepubliczna jednostka organizacyjna systemu oświaty | Other Non-Public Education-System Organizational Unit | Other |
| Publiczny zespół szkół i placówek systemu oświaty | Public Complex of Schools and Education-System Establishments | Government-Owned Entity |
| Niepubliczny zespół szkół i placówek systemu oświaty | Non-Public Complex of Schools and Education-System Establishments | Other |
| Organ władzy lub administracji rządowej | Public Authority or Government Administration Body | Government-Owned Entity |
| Organ kontroli państwowej i ochrony prawa | State Audit or Law Enforcement Body | Government-Owned Entity |
| Wspólnota samorządowa | Local Government Community | Government-Owned Entity |
| Sąd lub trybunał | Court or Tribunal | Government-Owned Entity |
| Skarb Państwa | State Treasury | Government-Owned Entity |
| Państwowa jednostka organizacyjna | State Organizational Unit | Government-Owned Entity |
| Gminna samorządowa jednostka organizacyjna | Municipal Local-Government Organizational Unit | Government-Owned Entity |
| Powiatowa samorządowa jednostka organizacyjna | County Local-Government Organizational Unit | Government-Owned Entity |
| Wojewódzka samorządowa jednostka organizacyjna | Voivodeship Local-Government Organizational Unit | Government-Owned Entity |
| Inna państwowa lub samorządowa osoba prawna | Other State or Local-Government Legal Person | Government-Owned Entity |
| Bez szczególnej formy prawnej | No Special Legal Form | Other |
## Legal Representatives
For KRS entities, `legalRepresentatives` covers the **management board** and the **procurators** only. Supervisory board members are not included. Known Polish role labels use the published translations and standardized values. Extraction and ISO 5009 matching may still use AI. Joint or sole signing follows the representation rule in the extract.
**Board member and shareholder names: use verification mode.** Poland's National Court Register masks personal data on its online lookup, returning names like `W***** L********`. Topograph reads the full names from the official court extract instead, so in **verification mode** `legalRepresentatives` and `shareholders` come back with complete first names and surnames for companies, associations, and foundations. The names are read from the court extract by AI, so verify against the source document before relying on them for compliance.
Details for the response payload:
* **Prefill mode** returns only the company identity fields (name, legal form, registered seat, status, dates). It does not include board members or shareholders, and for companies in the National Court Register it does not include share capital or activity codes either. Use verification mode (the default) when you need them.
* `legalRepresentatives[].individual.name.firstName` and `lastName` are full and unredacted in verification mode.
* `legalRepresentatives[].individual.birthDate` and `gender` are not currently populated for Polish entities.
* `shareholders` are listed for limited liability companies (sp. z o.o.) where the register publishes them, with full names.
* The role (`localName` and `standardized`), structural fields, addresses, capital, and dates are all complete.
The [ultimate beneficial owners](#ultimate-beneficial-owners) datapoint comes from CRBR, a separate Polish register, with full names, birth dates, and nationalities. UBOs and legal representatives answer different questions and one is not a substitute for the other.
### KRS Management Board Roles
| Polish Role | English Translation | Standardized Role |
| - | - | - |
| PREZES ZARZĄDU | President of the Management Board | President |
| WICEPREZES ZARZĄDU | Vice President of the Management Board | Vice President |
| CZŁONEK ZARZĄDU | Management Board Member | Board Member |
| Polish Role | English Translation | Standardized Role |
| - | - | - |
| PROKURENT | Procurator | Authorized Signatory |
| PROKURA SAMOISTNA | Procurator with Sole Signing Authority | Authorized Signatory |
| PROKURA ŁĄCZNA | Procurator with Joint Signing Authority | Authorized Signatory |
| Polish Role | English Translation | Standardized Role |
| - | - | - |
| Wlasciciel | Owner | Owner |
### PESEL, Birth Date and Gender
The PESEL (Polish Personal Identification Number) of KRS management board members and procurators is sensitive personal data and is not part of the response. `birthDate` and `gender` are not currently populated for Polish legal representatives. Full names are returned in verification mode (see the note above).
Procurators (authorized signatories) from KRS are mapped as **additional legal representatives** with the original Polish prokura label and standardized as `Authorized Signatory`. For CEIDG sole proprietors, the entrepreneur is automatically mapped as the sole legal representative with role "Wlasciciel" (Owner).
## Other Key Persons
Other key persons are **not currently extracted** from Polish registries. All management board members and procurators are mapped as legal representatives.
## Shareholders
Shareholders are available for **sp. z o.o. (Limited Liability Companies)** in **verification mode**. They are read by AI from the shareholders section ("Wspólnicy") of the official KRS court extract, with full names for individuals and, for corporate shareholders, the company name and its Polish identifiers (KRS, NIP, REGON) when shown. Verify against the source document before relying on them for compliance.
The court extract lists the number and value of shares each shareholder holds, not a percentage. When two or more shareholders are listed and every one of them has a share count, `sharePercentage` is derived in proportion to those counts. The register only lists shareholders holding at least 10% of the share capital, so a derived percentage is relative to the listed shareholders.
### Limitations
| Legal Form | Shareholder Data Available? | Notes |
| - | - | - |
| sp. z o.o. (LLC) | Yes | Individual and corporate shareholders with share counts |
| S.A. (Joint-Stock) | No | Shareholders not listed in public KRS register |
| sp.k. / sp.j. (Partnerships) | No | Partner data not structured in shareholder format |
| Associations / Foundations | No | Not applicable |
| CEIDG (Sole Proprietors) | No | Not applicable |
For corporate shareholders, Polish identifiers (KRS, NIP, REGON) are included when available. Foreign corporate shareholders without Polish identifiers are included with name only. KRS publishes share counts, not percentages; a percentage is only derived from the counts as described above.
## Ultimate Beneficial Owners
UBO data is sourced from **CRBR (Centralny Rejestr Beneficjentów Rzeczywistych)**, the Polish Central Register of Beneficial Owners operated by the Ministry of Finance. CRBR is a separate register from KRS, established under Polish AML law (transposing 4AMLD/5AMLD), and it is mandatory for almost every entity registered in KRS to disclose its beneficial owners there.
A beneficial owner in CRBR is the natural person who ultimately owns or controls the entity, defined by the Polish AML act as direct or indirect ownership above 25%, or any other form of effective control. Where no natural person meets that threshold (typical for state-owned entities, listed companies, and complex structures), CRBR records senior managing officials as a fallback per the AML directive.
**CRBR is not redacted.** Unlike the KRS online lookup, CRBR returns full first names, surnames, birth dates, nationalities, and a description of how control is exercised. The redaction policy the Ministry of Justice applies to KRS does not apply to CRBR, because the whole point of CRBR is to expose this data for AML and KYC compliance.
Each UBO record returned by the API contains:
| Field | Source | Notes |
| - | - | - |
| `name.firstName` / `lastName` / `fullName` | CRBR | Unredacted |
| `birthDate` | CRBR | Day, month, year |
| `nationality` | CRBR | ISO 3166-1 alpha-2 |
| `control.types[]` | CRBR | `ownership-of-shares` or `significant-influence-or-control` (the latter also covers a senior management position) |
| `control.description` | CRBR | Polish-language description of how the control is exercised, as filed by the entity |
| `control.details[].nature` | CRBR | `direct`, `indirect`, or `unknown` when the filing uses an unrecognised form of control |
| `control.details[].monetaryAmount` | CRBR | When the filing expresses the stake as an amount instead of a percentage, always in PLN |
CRBR returns no UBOs for entities that are exempt from disclosure (state-owned enterprises, the State Treasury, certain public-benefit organizations) or for entities whose ownership chain resolves to a listed parent. In those cases the response contains an empty `ultimateBeneficialOwners` array, which is correct, not a gap.
UBO data is fetched on demand: include `ultimateBeneficialOwners` in the `dataPoints` array on `POST /v2/company`. The UBO extract document returns the full CRBR PDF excerpt for filing in compliance dossiers.
## Activity Code Mapping
Poland uses **PKD (Polska Klasyfikacja Dzialalnosci)**. The registers publish national codes under `PKD` in the source format (`62.01.Z`, division.class.subclass). PKD 2007 and PKD 2025 coexist during the [official transition through 2026](https://bip.stat.gov.pl/dzialalnosc-statystyki-publicznej/rejestr-regon/pkd-2025/). The implemented KRS and REGON activity rows do not stamp the edition, so their codes are retained without a revision suffix or an assumed NACE conversion.
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **PKD** | KRS, CEIDG or REGON | `62.02.Z` | No (official) |
| **NACE / ISIC** | CEIDG activity analysis, where available | Depends on the activity | Can be AI-inferred |
The KRS provides both the **main activity** and **secondary activities**. CEIDG provides a primary PKD code and additional codes. REGON marks one code as the prevailing activity (dzialalnosc przewazajaca) as well.
All three registers declare a prevailing activity, and it is always listed first. The PKD code the register declares as prevailing carries `isMainActivity: true`. Codes without the flag are not necessarily secondary: the flag is only set when the register explicitly declares the main activity.
**AI Enrichment:** Every activity item includes an `isAIInferred` flag. PKD codes are **never** AI-inferred for Poland. For CEIDG sole proprietors, ISIC codes are matched from the PKD codes by an LLM and NACE is derived from them, so those items can carry `isAIInferred: true`.
### Activity Codes by Source
| Source | Classifications returned | Notes |
| - | - | - |
| **KRS** | PKD | Main and additional native PKD codes; edition not stated by the activity input |
| **REGON** | PKD | Native code and source wording, prevailing activity first; edition not stated |
| **CEIDG** | PKD + NACE + ISIC | Primary and additional PKD codes, AI-analyzed |
## Data Availability Matrix
| Data Type | KRS Companies | CEIDG (Sole Proprietors) | Notes |
| - | - | - | - |
| Company Profile | Async | Async | Full data for KRS, limited for CEIDG |
| Legal Representatives | Yes (verification mode, full names) | Yes | KRS: management board and procurators, read from the official court extract. CEIDG: owner mapped from CEIDG metadata. |
| Shareholders | Yes (sp. z o.o., verification mode, full names) | No | Only for Limited Liability Companies, read from the official court extract. Corporate shareholders include their Polish identifiers (KRS, NIP, REGON) when shown. |
| Other Key Persons | No | No | Not currently extracted |
| Ultimate Beneficial Owners | Yes | No | From CRBR (Central Register of Beneficial Owners) |
| Activity Codes | Yes | Yes | PKD codes from KRS or CEIDG |
| Documents | Yes | Yes | Different document sets per register type |
| Financial Statements | Yes | No | From ekrs.ms.gov.pl, automatic XML-to-PDF conversion |
| Establishments | No | No | Not currently extracted |
**Legend:** Yes = Available | No = Not Available | Async = Asynchronous processing
## Documents by Company Type
### KRS Companies (prefix: `krs-`)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Current KRS Extract** | `tradeRegisterExtract` | PDF | Active companies only | Aktualny odpis z KRS |
| **Historical KRS Extract** | `otherDocuments[]` | PDF | All companies | Pelny odpis historyczny z KRS (full history) |
| **UBO Extract** | `ultimateBeneficialOwnersCertificate` | PDF | When UBO data exists | Wyciag z CRBR o beneficjentach rzeczywistych |
| **Financial Statements** | `financialStatements[]` | PDF (auto-converted from XML) | When filed | Annual and consolidated annual financial statements from ekrs.ms.gov.pl |
| **Other eKRS filings** | `otherDocuments[]` | PDF (auto-converted from XML) | When filed | Management reports, auditor opinions, and resolutions from ekrs.ms.gov.pl |
### CEIDG Sole Proprietors (prefix: `nip-`)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **CEIDG Certificate** | `tradeRegisterExtract` | PDF | All entities | Zaswiadczenie z CEIDG |
| **Representatives Document** | `otherDocuments[]` | PDF | All entities | Informacja o pelnomocnikach |
**Current KRS Extract availability:** The current extract (`tradeRegisterExtract`) is **only available for active companies**. Inactive, dissolved, or deleted companies can only access the historical extract (`otherDocuments[]`), which contains the full history including closure details.
### Financial Document Types
Available financial document types from the eKRS portal include the following. Annual and consolidated annual financial statements are returned under `financialStatements[]`; every other filing is returned under `otherDocuments[]`.
* **Roczne sprawozdanie finansowe** -- Annual Financial Statements
* **Skonsolidowane roczne sprawozdanie finansowe** -- Consolidated Annual Financial Statements
* **Sprawozdanie z dzialalnosci** -- Management Reports
* **Opinia bieglego rewidenta** -- Auditor's Opinions
* **Uchwaly o zatwierdzeniu sprawozdan** -- Approval Resolutions
* **Uchwaly o podziale zysku** -- Profit Distribution Resolutions
**Automatic XML-to-PDF Conversion:** Financial documents in Poland are often published in XML format using the Ministry of Finance schema. We automatically convert these XML files to human-readable PDF format using the official Polish government visualization tool at [e-sprawozdania.mf.gov.pl](https://e-sprawozdania.mf.gov.pl/ap/). Both the original XML and the converted PDF are stored and accessible. If conversion fails, the original XML file is still returned.
Due to technical limitations of the Polish financial documents portal, the document format (XML vs PDF) is not available in the `availableDocuments` listing. The `format` field will be `undefined` during listing and is only determined when the document is actually downloaded.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "PL", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "krs-0001234567",
"countryCode": "PL",
"identifiers": { "krs": "0001234567", "nip": "1234567890", "regon": "123456789", "VAT": "1234567890" },
"legalName": "Przyklad Technologia sp. z o.o.",
"registrationDate": "2018-03-20",
"status": { "localName": "AKTYWNA", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Spółka z ograniczoną odpowiedzialnością", "englishTranslation": "Limited Liability Company (sp. z o.o.)", "standardized": "Limited Liability Company", "iso20275Code": "O7XB" },
"capital": { "amount": 50000, "currency": "PLN" },
"activities": {
"PKD": [
{ "code": "62.01.Z", "description": "DZIAŁALNOŚĆ ZWIĄZANA Z OPROGRAMOWANIEM", "isAIInferred": false, "isMainActivity": true },
{ "code": "62.02.Z", "description": "DZIAŁALNOŚĆ ZWIĄZANA Z DORADZTWEM W ZAKRESIE INFORMATYKI", "isAIInferred": false }
]
},
"legalAddress": { "addressLine1": "Aleja Jana Pawla II 29", "city": "Warszawa", "postalCode": "00-867", "countryCode": "PL" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "PREZES ZARZĄDU", "standardized": "President" }, "individual": { "name": { "fullName": "Jan Kowalski", "firstName": "Jan", "lastName": "Kowalski" } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "CZŁONEK ZARZĄDU", "standardized": "Board Member" }, "individual": { "name": { "fullName": "Anna Nowak", "firstName": "Anna", "lastName": "Nowak" } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "individual": { "name": { "fullName": "Jan Kowalski", "firstName": "Jan", "lastName": "Kowalski" } }, "numberOfShares": 500, "sharePercentage": 50 },
{ "entityId": "company_001", "type": "company", "company": { "id": "krs-0009876543", "countryCode": "PL", "legalName": "Holding sp. z o.o.", "identifiers": { "krs": "0009876543" } }, "numberOfShares": 500, "sharePercentage": 50 }
]
}
```
**Note:** In verification mode, representative and shareholder names are read in full from the official court extract. `sharePercentage` is derived from the share counts of the listed shareholders. `birthDate`, `gender` and `nationality` are usually absent for KRS representatives, because the extract does not state them.
```json theme={null}
{
"company": {
"id": "krs-0007654321",
"countryCode": "PL",
"identifiers": { "krs": "0007654321", "nip": "9876543210", "regon": "987654321", "VAT": "9876543210" },
"legalName": "Stara Firma S.A.",
"registrationDate": "2005-01-10",
"status": { "localName": "WYKREŚLONA Z REJESTRU", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "ADMINISTRATIVE_DISSOLUTION", "closureDate": "2023-06-30" } },
"legalForm": { "localName": "Spółka akcyjna", "englishTranslation": "Joint-Stock Company (S.A.)", "standardized": "Corporation", "iso20275Code": "FJ0E" },
"legalAddress": { "addressLine1": "Marszalkowska 10", "city": "Warszawa", "postalCode": "00-001", "countryCode": "PL" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "PREZES ZARZĄDU", "standardized": "President" }, "individual": { "name": { "fullName": "Piotr Wiśniewski", "firstName": "Piotr", "lastName": "Wiśniewski" } } }
],
"shareholders": []
}
```
**Note:** For a company struck off the register, representatives and shareholders reflect the last position recorded before the strike-off, read from the full historical extract. Shareholders are only listed for limited liability companies (sp. z o.o.), so this joint-stock company example has none. Only the historical trade register extract is available as a document.
```json theme={null}
{
"company": {
"id": "nip-1234567890",
"countryCode": "PL",
"identifiers": { "nip": "1234567890", "regon": "123456789", "VAT": "1234567890" },
"legalName": "Jan Kowalski Uslugi Informatyczne",
"registrationDate": "2020-01-15",
"status": { "localName": "AKTYWNY", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Osoba fizyczna prowadząca działalność gospodarczą", "englishTranslation": "Sole Trader (CEIDG)", "standardized": "Sole Proprietorship", "iso20275Code": "ZVVM" },
"activities": {
"PKD": [
{ "code": "62.01.Z", "description": "Dzialalnosc zwiazana z oprogramowaniem" }
]
},
"legalAddress": { "addressLine1": "Krakowska 5", "city": "Krakow", "postalCode": "31-001", "countryCode": "PL" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Wlasciciel", "englishTranslation": "Owner", "standardized": "Owner" }, "individual": { "name": { "fullName": "Jan Kowalski", "firstName": "Jan", "lastName": "Kowalski" }, "nationality": "PL" } }
],
"shareholders": []
}
```
**Note:** CEIDG entities have the entrepreneur mapped as the sole legal representative with role "Wlasciciel" (Owner). No shareholders, UBOs, or financial statements are available.
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "JAN KOWALSKI", "firstName": "JAN", "lastName": "KOWALSKI" },
"birthDate": { "year": 1985, "month": 6, "day": 15 },
"nationality": "PL",
"control": {
"types": ["ownership-of-shares"],
"description": "WSPÓLNIK SPÓŁKI Z O.O. (2500 PLN)",
"details": [
{
"nature": "direct",
"type": "shares",
"monetaryAmount": { "amount": 2500, "currency": "PLN", "formatted": "2500 PLN" }
}
]
}
},
{
"entityId": "person_002",
"name": { "fullName": "KLAUS RÖHRIG", "firstName": "KLAUS", "lastName": "RÖHRIG" },
"birthDate": { "year": 1977, "month": 7, "day": 21 },
"nationality": "AT",
"control": {
"types": ["significant-influence-or-control"],
"description": "POŚREDNIA KONTROLA NAD PODMIOTEM DOMINUJĄCYM WOBEC SPÓŁKI",
"details": [
{
"nature": "indirect",
"type": "shares"
}
]
}
}
]
}
```
**Note:** UBO records are unredacted and verified live. CRBR is operated by the Polish Ministry of Finance, not by the Ministry of Justice that runs KRS, and the redaction policy on KRS does not apply here.
**Note:** UBOs are fetched from the CRBR (Central Register of Beneficial Owners). Three forms of control are recognized: (1) direct ownership of shares or assets (`ownership-of-shares`, nature `direct`), (2) indirect control through a controlling entity (`significant-influence-or-control`, nature `indirect`), and (3) a senior management position under AML law (`significant-influence-or-control`, nature `direct`). Ownership is expressed either as a percentage or as a monetary amount in PLN.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
**For active KRS companies:**
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Aktualny odpis z KRS | Current extract, active companies only |
| `otherDocuments[]` | Pelny odpis historyczny z KRS | Full historical extract |
| `ultimateBeneficialOwnersCertificate` | Wyciag z CRBR | UBO extract, when UBO data exists |
| `financialStatements[]` | Annual and consolidated financial statements | From ekrs.ms.gov.pl |
| `otherDocuments[]` | Other eKRS filings | Management reports, auditor opinions, resolutions |
**For inactive KRS companies:**
| API Category | Document | Notes |
| - | - | - |
| `otherDocuments[]` | Pelny odpis historyczny z KRS | Full historical extract (only document available) |
**For CEIDG entities:**
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Zaswiadczenie z CEIDG | CEIDG certificate |
| `otherDocuments[]` | Informacja o pelnomocnikach | Representatives document |
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefixed identifiers required** | Company IDs must use `krs-` or `nip-` prefixes to route to the correct register. Without a prefix, the system returns an error. |
| **KRS and NIP can collide** | Both KRS and NIP are 10-digit numbers. The prefix system prevents ambiguity. Not all KRS entities have a NIP (e.g., associations, foundations). |
| **Shareholders only for sp. z o.o.** | Only Limited Liability Companies have shareholder data in KRS. Joint-stock companies, partnerships, and CEIDG entities do not expose shareholder information. |
| **Share percentages are derived** | KRS publishes share counts, not ownership percentages. When two or more shareholders are listed and all have a share count, `sharePercentage` is computed in proportion to those counts, relative to the listed shareholders only. |
| **Liquidation detected from company name** | Companies in liquidation are identified by "W LIKWIDACJI" appearing in the legal name, not from a dedicated status field in KRS. |
| **Legal forms are a closed enum** | Poland uses a closed enum of 102 legal forms sourced directly from the registers: 51 KRS forms (50 from the KRS July 2024 snapshot of 849,757 entities plus the foreign-branch form), one canonical CEIDG sole-trader entry, and 50 REGON-only forms. Unknown values are rejected with an `invalid` error at ingestion time. No AI fallback. |
| **ISO 20275 is incomplete for Poland** | 44 of the 102 forms carry an ELF code. The other 58 have none: 8 KRS forms (granular `stowarzyszenie` subtypes, public-benefit organizations, foreign branches) and all 50 REGON-only forms. We attach ELF codes where they exist for LEI matching and ignore the gap elsewhere. |
| **Procurators as legal representatives** | Procurators (authorized signatories) from KRS are mapped as additional legal representatives with the original Polish prokura label, standardized as `Authorized Signatory`. |
| **Financial documents may be XML** | Financial statements from the Ministry of Finance portal may be in XML format. The system automatically converts XML to PDF, but the format is unknown until download. |
| **CEIDG data is limited** | CEIDG (sole proprietor) profiles have significantly less structured data than KRS companies. No shareholders, UBOs, or financial statements are available. The owner is mapped as the sole legal representative. |
| **PKD edition is unstated** | A national subclass (`62.01.Z`) is not a NACE code. KRS and REGON retain native `PKD`; no revision is inferred from code shape or filing date. |
| **Struck-off companies show their last position** | The register no longer issues a current extract for a struck-off company. Representatives and shareholders are read from the full historical extract and reflect the position in force immediately before the strike-off. |
| **Current extract only for active companies** | The Aktualny odpis z KRS (current trade register extract) is unavailable for closed/dissolved companies. Use the historical extract instead. |
| **UBO data from CRBR** | UBO data is fetched from the CRBR registry. This may occasionally be slower than direct API calls. |
# Portugal
Source: https://docs.topograph.co/essentials/portugal
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Portugal reference is on the [Portugal country page](https://www.topograph.co/countries/pt).
## Start here
This guide contains public integration notes for Portugal. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Portugal uses the official commercial register publications and a third-party aggregator of commercial register data for company data. For a given entity, **data comes from a single primary source** (all-or-nothing model). There are two distinct data pathways: one for structured company profile data and one for official document retrieval.
### Company Profile Data
* **Commercial register publications** -- The source of the prefill profile and of verification data. See [Publications](#publications) below.
* **Third-party commercial data aggregator** -- A Portuguese business information platform that republishes commercial register data. Used in verification mode only. It also covers companies the register publications do not, mainly companies incorporated before 2006 (the publications start that year) and a small share of more recent ones. A company report is retrieved from the aggregator and the structured attributes are extracted from it by AI.
### Official Documents
* **Instituto dos Registos e do Notariado (IRN)** -- The Portuguese registration and notary authority, operating under the Ministry of Justice since 2007. Used for **certified document retrieval**. Two certified documents are available: the Certidao de Registo Comercial (permanent commercial register certificate) and the Certidao do Ultimo Pacto Social/Estatutos Atualizados (latest articles of association). Both are delivered via an email-based retrieval flow through the IRN portal. A non-certified trade register extract is built from the register publications. Annual accounts are retrieved as native financial-statement PDFs from the official IES annual accounts database. See [Documents by Company Type](#documents-by-company-type).
### Publications
* **Publicacoes do Registo Comercial** -- Official commercial register publications. Publications include legal announcements, corporate acts, and other mandatory filings. In **verification mode**, the most recent publications are read chronologically and the company profile, legal representatives and shareholders are extracted by AI from them; the most recent publication determines the current company status. In **prefill mode**, base company fields (legal name, NIPC, legal form, status, share capital, address) are reconstructed from the same publications ahead of time with deterministic rules (no AI) and refreshed daily, so they are returned instantly; officers and shareholders are not included. Prefill mode never falls back to the aggregator: if the publications do not cover the entity, use verification mode.
**AI-parsed data:** In verification mode, Portugal's company profile data is AI-parsed. There is no structured company API available. All attributes (including legal form, status, legal representatives, and shareholders) are extracted by AI. The prefill profile is built with deterministic rules, without AI.
### Beneficial ownership
The Registo Central do Beneficiário Efetivo (RCBE) is the source of beneficial ownership information. The official Certidão do RCBE is obtained through a local partner. Request `ultimateBeneficialOwners` in verification mode for structured data, or order `ultimateBeneficialOwnersCertificate` from `availableDocuments` for the source PDF. Delivery is asynchronous and can take several business days. Follow the existing request through webhooks or polling; do not submit repeated orders while it is pending. If the certificate cannot be obtained, the request reports an error rather than a successful empty result.
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Verification only, for domestic sociedades por quotas, including unipessoais, and sociedades anónimas when the source confirms the identity and legal form. Not returned in prefill mode. Availability depends on the source used. Example: `PTIRNMJ.517116022`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | IRN / commercial register | 9-digit NIPC/NIF, last digit a check digit | `517116022` | Numero de Identificacao de Pessoa Coletiva. Sole entrepreneurs use their personal NIF |
**NIPC Format:** The Portuguese NIPC (Numero de Identificacao de Pessoa Coletiva) is a 9-digit tax identification number for legal persons. By law its first digit is `5`, `6`, `8` or `9`; most companies start with `5`, and some with `9` (e.g. `980460603`). Entities the tax authority numbers directly, such as funds, start with `7`, and a sole entrepreneur's personal NIF starts with `1` to `4`. The 9th digit is a check digit: weight the first eight digits `9` down to `2`, sum, and take the remainder modulo 11; the check digit is `0` when the remainder is 0 or 1, otherwise 11 minus the remainder.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `NIF` | 9 digits, last digit a check digit | `517116022` | All registered companies (the NIPC is returned under this key) |
| `VAT` | 9 digits (same as NIF, no `PT` prefix) | `517116022` | Companies with EU VAT registration |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the NIPC/NIF (`NIF`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By NIF/NIPC | 9 digits, optionally with the `PT` VAT prefix | `517116022` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Exemplo Empresa"` | Fuzzy | Multiple results |
**Search implementation:** Portugal search runs two sources in parallel and merges them on NIF. Name and NIF searches both hit the Topograph index built from the register publications. NIF searches additionally query a third-party commercial data aggregator, which covers companies the publications never listed (mainly pre-2006 incorporations). Results include company name, NIF, and address (city/region). Brand results are filtered out.
An empty search result does not mean the company does not exist. Some Portuguese entities are absent from both sources; a NIF can still be fetched directly through `/v2/company`.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Name searches are filtered for companies whose status is known. A tax number lookup may return the company whatever its status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Verification profile data is AI-parsed** | In verification mode, company profile, legal form, status, legal representatives, and shareholders are all extracted via AI parsing. There is no structured API. The prefill profile uses deterministic rules instead. |
| **Email-based document retrieve** | Certificates require an email-based retrieval flow through the IRN portal. A document request is submitted through the IRN portal and the access code is received by email. |
| **Certificate delivery takes minutes** | After obtaining an access code, the system waits for the certificate to become available on the IRN portal. Most certificates are delivered within a few minutes; allow up to about 20 minutes. |
| **Access code reuse (1 year)** | Once obtained, access codes are valid for 1 year. Subsequent requests for the same document type reuse the existing code, bypassing the email retrieval flow entirely. |
| **CAE\_REV3 classification** | Portugal uses CAE\_REV3 (Classificacao de Actividades Economicas), currently CAE\_REV3 Rev. 3 maintained by INE (Statistics Portugal). CAE\_REV3 closely mirrors NACE. Codes are extracted from the source report by AI. |
| **NIPC check digit** | The 9th digit of the NIPC is a check digit calculated using modulo 11 with weights `[9, 8, 7, 6, 5, 4, 3, 2]`. The system can generate valid NIPCs for internal use. |
| **No direct registry API** | Unlike many European countries, Portugal does not offer a structured API for commercial register data. Company data is read from the register publications and from a third-party aggregator of register data. |
| **Pre-2006 companies have no publications** | The commercial register publications start in 2006, so a company incorporated before then may have never published an act. In verification mode those companies are served from a third-party aggregator instead. They are also missing from name search. |
| **Retrieval may be slower than API-based countries** | Both search and company report retrieval require interaction with a web platform, which is inherently slower than direct API calls. |
| **Prefill profile is pre-parsed** | Prefill mode returns base company fields reconstructed from the register publications ahead of time and refreshed daily, rather than reading the publications at request time. This is why it responds instantly, why it carries a `cached_from_registry` data source, and why it excludes officers and shareholders. Use verification mode for those. |
| **Publication-based status detection** | For the prefill profile, company status comes from rules applied to the company's whole publication history. A dissolution or liquidation still in progress keeps the company active, and the start of an administrative dissolution procedure makes it inactive but not closed. A company is closed only once a closure is registered: end of liquidation, immediate extinction, cancellation of the registration, a final administrative dissolution decision, or absorption in a merger. |
| **Legal representative exclusions** | The AI parser is instructed to exclude board members, administrators, and auditors from the legal representatives list. Only persons with active executive authority are returned. |
## Mappings
### Company Status
In verification mode, company status is extracted via **AI parsing**: the AI infers the status from the source content and standardizes it. In prefill mode, status comes from deterministic rules applied to the company's publication history (see [Quirks & Gotchas](#quirks--gotchas)).
| Local Status | English Translation | Standardized Status |
| - | - | - |
| Ativa / Em Actividade | Active | Active |
| Encerrada | Closed | Closed |
| Dissolvida | Dissolved | Closed |
| Em Liquidacao | In Liquidation | Closed |
| Extinta | Extinct / Terminated | Closed |
| Insolvente | Insolvent | Under Insolvency Proceeding |
| Procedimento administrativo de dissolucao iniciado | Administrative dissolution started | Inactive Not Closed |
**AI-inferred status:** Since all company data is AI-parsed from HTML reports, status values may vary in their exact local names depending on how the source presents the information. The AI standardizes these to the Topograph status enum. For the prefill profile, a dissolution or liquidation still in progress stays Active (or Inactive Not Closed once an administrative dissolution procedure has started). Closed requires a registered closure.
### Legal Forms
Portuguese legal forms are extracted from HTML reports via **AI parsing**. The AI identifies the legal form from the company report and provides both the local Portuguese name and standardized classification. ISO 20275 (ELF) codes are assigned via AI enrichment.
#### Key Business Forms
| Abbreviation | Portuguese Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Lda. | Sociedade por Quotas | Private Limited Company | Limited Liability Company | `USOG` |
| S.A. | Sociedade Anonima | Public Limited Company | Corporation | `DFE5` |
| Unipessoal Lda. | Sociedade Unipessoal por Quotas | Single-Member Private Limited Company | Limited Liability Company | `VF4C` |
| S.A.D. | Sociedade Anonima Desportiva | Sports Public Limited Company | Corporation | `W9W3` |
| S.C. | Sociedade em Comandita | Limited Partnership | Partnership | `OXUC` |
| S.N.C. | Sociedade em Nome Coletivo | General Partnership | Partnership | `N66B` |
#### Sole Entrepreneurs
| Abbreviation | Portuguese Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| ENI | Empresario em Nome Individual | Sole Trader | Sole Proprietorship | `VALH` |
#### Cooperatives
| Abbreviation | Portuguese Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| CRL | Cooperativa de Responsabilidade Limitada | Limited Liability Cooperative | Cooperative | `1HGD` |
| SCE | Societas Cooperativa Europaea | European Cooperative Society | Cooperative | `V6YL` |
#### Non-Profits
| Type | Portuguese Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Associacao | Associacao | Association | Nonprofit Organization | `ALPT` |
| Fundacao | Fundacao | Foundation | Nonprofit Organization | `Z0NE` |
#### Public & Government Entities
| Abbreviation | Portuguese Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| EPE | Entidade Publica Empresarial | Public Business Entity | Government-Owned Entity | `A8CT` |
| EM | Empresa Municipal | Municipal Enterprise | Government-Owned Entity | `PIDC` |
| EEM | Entidade Empresarial Municipal | Municipal Business Entity | Government-Owned Entity | `D7OA` |
| EIM | Empresa Intermunicipal | Intermunicipal Enterprise | Government-Owned Entity | `IX01` |
| EMet | Empresa Metropolitana | Metropolitan Enterprise | Government-Owned Entity | `XD16` |
| - | Pessoa Coletiva de Direito Publico | Public Law Legal Entity | Government-Owned Entity | `P5S3` |
#### European & International Forms
| Abbreviation | Portuguese Name | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| AEIE | Agrupamento Europeu de Interesse Economico | European Economic Interest Grouping | Partnership | `99JD` |
| ACE | Agrupamento Complementar de Empresas | Complementary Grouping of Companies | Partnership | `YMLD` |
| - | Pessoa Coletiva Internacional | International Legal Entity | Other | `QFXD` |
Legal form extraction and standardization are entirely **AI-inferred** from the source report content. ISO 20275 (ELF) codes are added via AI enrichment. The local Portuguese legal form name from the source document is always preserved verbatim. The tables above list the most common forms; the AI can recognize additional forms not listed here.
### Legal Representatives
Current office holders are reconstructed from available commercial-register acts and reports. Managers and administrators may carry representation under Portuguese law; oversight, audit, secretary and meeting offices are returned under other key persons unless a separate representative mandate is disclosed. A board appointment does not establish authority to sign alone.
| Portuguese Role | English Translation | Typical Entity Type |
| - | - | - |
| Gerente | Manager | Lda., Unipessoal Lda. |
| Administrador | Administrator/Director | S.A. |
| Presidente do Conselho de Administracao | Chairman of the Board | S.A. |
| Administrador Delegado | Managing Director | S.A. |
| Administrador Unico | Sole Director | S.A. |
| Director-Geral | General Director | Various |
| Presidente | President | Associations, Cooperatives |
| Representante Legal | Legal Representative | Various |
**Role capacity:** Exact known Portuguese titles receive the meaning in the published role catalogue. Short titles such as Presidente, Vogal and Suplente require the constituted body and appointment context; ownership alone does not establish management. Unlisted titles retain their wording with an Other classification. Individual and corporate holders, including audit firms, are supported. Signing clauses are preserved when disclosed; absence of a clause does not establish sole or joint signing.
### Other Key Persons
Verification mode returns available current secretaries, auditors, supervisory members and meeting officers under `otherKeyPersons`, from the same people source as legal representatives. Publication histories may omit current appointments, so an empty roster does not establish that the entity has no office holders. Appointment and cessation events determine the current roster; dissolution alone may leave a liquidator in office until liquidation is completed.
### Shareholders
Shareholders are extracted from HTML reports via **AI parsing**. Both individual and corporate shareholders are supported.
#### Extraction Logic
| Data Extracted | Source | Notes |
| - | - | - |
| Shareholder name | AI-parsed from source report | Full name for individuals, legal name for companies |
| Shareholder type | AI-classified | `individual` or `company` |
| Share percentage | AI-parsed when available | `sharePercentage` field |
| Address | AI-parsed when available | When present in the report |
**Self-reference exclusion:** The AI parser is specifically instructed not to include the queried company itself as a shareholder. Entries listed as "Outros" (Others) without specific details are also excluded.
### Activity Code Mapping
Portugal uses the **CAE\_REV3 (Classificacao Portuguesa de Actividades Economicas)**, currently in Revision 3, maintained by INE (Instituto Nacional de Estatistica / Statistics Portugal). CAE\_REV3 closely mirrors the European NACE standard. The system maps activity codes across three levels:
```
CAE_REV3 Rev. 3 (Portuguese) -> NACE Rev. 2.1 (European) -> ISIC Rev. 5 (International)
```
The response uses the canonical keys `CAE_REV3`, `NACE` and `ISIC`. See [Standardization](/guides/standardization).
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **CAE\_REV3** | Source HTML report (AI-parsed) | `62010` | No (extracted from source) |
| **NACE** | Derived from CAE\_REV3 or AI | `6201` | Sometimes |
| **ISIC** | Derived from NACE or AI | `6201` | Sometimes |
CAE\_REV3 codes are extracted from the source report by AI parsing. The AI is specifically instructed to recognize the CAE\_REV3 classification format. NACE and ISIC derivations use formal mapping tables when possible, with AI fallback. The `isAIInferred` flag distinguishes official vs. AI-derived codes. A code carries `isMainActivity: true` only when the source report explicitly designates it as the company's main activity; when the report lists codes without singling one out, no code is flagged.
## Data Availability
### Data Availability Matrix
| Data Type | Company Profile | Prefill Profile (Publications) | Notes |
| - | - | - | - |
| Company Name & Address | ✅ | ✅ | Prefill returns the address as a single line |
| Legal Form | ✅ | ✅ | AI-inferred with ISO 20275 enrichment in verification; matched against the list of Portuguese legal forms in prefill |
| Company Status | ✅ | ✅ | AI-inferred in verification; rule-based from the publication history in prefill |
| Registration Date | ✅ | ❌ | When available in source |
| Share Capital | ✅ | ✅ | Amount and currency |
| Activity Codes (CAE\_REV3) | ✅ | ❌ | Mapped to NACE/ISIC |
| Activity Description | ✅ | ❌ | Business purpose text |
| Legal Representatives | ✅ | ❌ | Current representative appointments; verification mode |
| Other Key Persons | ✅ | ❌ | Current oversight, audit, secretary and meeting appointments; verification mode |
| Shareholders | ✅ | ❌ | Individual and corporate; verification mode |
| Ultimate Beneficial Owners | ✅ Manual | ❌ | Separate datapoint in verification mode, extracted from the official Beneficial Ownership Register (RCBE) certificate obtained through a local partner. Delivered asynchronously, typically within 1-3 business days |
| Establishments | ❌ | ❌ | Not available from the source |
| Employee Count | ❌ | ❌ | Not available from the source |
**Legend:** ✅ Available | ❌ Not Available | Manual = fulfilled by hand, delivered asynchronously
### Documents by Company Type
#### All Companies (NIPC)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Certidao de Registo Comercial** | `certifiedTradeRegisterExtract` | PDF | ✅ Commercial-register entities | Permanent certificate from IRN. The register does not issue it for entities that exist only in the FCPC (associations, foundations), so it is not listed for those. |
| **Certidao do Ultimo Pacto Social** | `articlesOfAssociation` | PDF | ✅ Commercial-register entities | Latest company statutes from IRN. The register does not issue it for entities that exist only in the FCPC (associations, foundations), so it is not listed for those. |
| **Certidão do RCBE** | `ultimateBeneficialOwnersCertificate` | PDF | Manual, companies with register publications | Official beneficial ownership certificate obtained asynchronously through a local partner, typically within 1-3 business days. |
| **Trade Register Extract** (Compilacao de Publicacoes do Registo Comercial) | `tradeRegisterExtract` | PDF | ✅ Companies with register publications | Non-certified compilation of the company's commercial register publications. Listed only when the company has publications. |
| **Annual Accounts** (Prestacao de Contas) | `financialStatements` | PDF | ✅ Companies that filed annual accounts | One document per fiscal year and accounts type, including the financial statements and available supporting schedules. |
**Commercial register certificates:** The commercial register certificate and latest company statutes are obtained through an email-based retrieval flow via the IRN portal. The process involves: (1) submitting a document request via the IRN portal, (2) receiving an access code by email (up to 5 minutes), (3) waiting for document availability. Most certificates are delivered within a few minutes; allow up to about 20 minutes.
### Document Delivery Flow
| Step | Action | Duration |
| - | - | - |
| 1 | Submit document request via IRN portal | \~30 seconds |
| 2 | Receive access code by email | 1-5 minutes |
| 3 | Wait for document availability | Usually a few minutes |
| 4 | Download PDF | \~10 seconds |
**Access code reuse:** Access codes are valid for 1 year. Subsequent requests for the same company and document type reuse the existing code, reducing delivery time significantly. The code allows retrieval of the most up-to-date version of the document each time it is used.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "PT", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "501442600",
"countryCode": "PT",
"identifiers": { "NIF": "501442600", "VAT": "501442600" },
"legalName": "Exemplo Tecnologia Lda.",
"registrationDate": "2005-09-12",
"activityDescription": "Consultoria em tecnologias de informacao.",
"status": { "localName": "Ativa", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Sociedade por Quotas", "standardized": "Limited Liability Company", "iso20275Code": "USOG" },
"capital": { "amount": 50000, "currency": "EUR" },
"activities": {
"CAE_REV3": [{ "code": "62010", "description": "Actividades de programacao informatica", "isAIInferred": false }],
"NACE": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }],
"ISIC": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Rua Augusta, 100", "city": "Lisboa", "postalCode": "1100-053", "countryCode": "PT" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Gerente", "standardized": "Manager" }, "individual": { "name": { "fullName": "Joao SILVA", "firstName": "Joao", "lastName": "SILVA" } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 75, "individual": { "name": { "fullName": "Joao SILVA" } } },
{ "entityId": "person_002", "type": "individual", "sharePercentage": 25, "individual": { "name": { "fullName": "Maria SANTOS" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "500100144",
"countryCode": "PT",
"identifiers": { "NIF": "500100144", "VAT": "500100144" },
"legalName": "Exemplo Holdings S.A.",
"registrationDate": "1990-01-15",
"activityDescription": "Gestao de participacoes sociais.",
"status": { "localName": "Ativa", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Sociedade Anonima", "standardized": "Corporation", "iso20275Code": "DFE5" },
"capital": { "amount": 5000000, "currency": "EUR" },
"activities": {
"CAE_REV3": [{ "code": "64202", "description": "Actividades das sociedades gestoras de participacoes sociais", "isAIInferred": false }],
"NACE": [{ "code": "6420", "description": "Activities of holding companies", "isAIInferred": true }],
"ISIC": [{ "code": "6420", "description": "Activities of holding companies", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Avenida da Liberdade, 250", "city": "Lisboa", "postalCode": "1250-149", "countryCode": "PT" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Presidente do Conselho de Administracao" }, "individual": { "name": { "fullName": "Carlos FERREIRA" } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Administrador" }, "individual": { "name": { "fullName": "Ana OLIVEIRA" } } }
],
"shareholders": [
{ "entityId": "company_001", "type": "company", "sharePercentage": 60, "company": { "legalName": "Grupo Exemplo SGPS S.A." } },
{ "entityId": "person_001", "type": "individual", "sharePercentage": 40, "individual": { "name": { "fullName": "Carlos FERREIRA" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "509000000",
"countryCode": "PT",
"identifiers": { "NIF": "509000000" },
"legalName": "Antiga Empresa Lda.",
"registrationDate": "2008-04-01",
"status": { "localName": "Encerrada", "active": false, "statusDetails": { "status": "CLOSED" } },
"legalForm": { "localName": "Sociedade por Quotas", "standardized": "Limited Liability Company", "iso20275Code": "USOG" },
"legalAddress": { "addressLine1": "Rua do Comercio, 50", "city": "Porto", "postalCode": "4000-150", "countryCode": "PT" }
}
}
```
**Note:** Closed companies have `active: false`. Data availability (legal representatives, shareholders) may be limited compared to active companies.
```json theme={null}
{
"company": {
"id": "514000123",
"countryCode": "PT",
"identifiers": { "NIF": "514000123", "VAT": "514000123" },
"legalName": "Exemplo Consultoria Unipessoal Lda.",
"registrationDate": "2018-03-20",
"activityDescription": "Consultoria para os negocios e a gestao.",
"status": { "localName": "Ativa", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Sociedade Unipessoal por Quotas", "standardized": "Limited Liability Company", "iso20275Code": "VF4C" },
"capital": { "amount": 1000, "currency": "EUR" },
"activities": {
"CAE_REV3": [{ "code": "70220", "description": "Outras actividades de consultoria para os negocios e a gestao", "isAIInferred": false }],
"NACE": [{ "code": "7022", "description": "Business and other management consultancy activities", "isAIInferred": true }],
"ISIC": [{ "code": "7020", "description": "Management consultancy activities", "isAIInferred": true }]
},
"legalAddress": { "addressLine1": "Rua de Santa Catarina, 15", "city": "Porto", "postalCode": "4000-442", "countryCode": "PT" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Gerente", "standardized": "Manager" }, "individual": { "name": { "fullName": "Pedro COSTA" } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 100, "individual": { "name": { "fullName": "Pedro COSTA" } } }
]
}
```
**Note:** Sociedade Unipessoal por Quotas has a single shareholder (100% ownership) and typically a single manager (Gerente).
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Format | Notes |
| - | - | - | - |
| `certifiedTradeRegisterExtract` | Certidao de Registo Comercial | PDF | Email-based retrieval flow, delivered within minutes |
| `articlesOfAssociation` | Certidao do Ultimo Pacto Social/Estatutos Atualizados | PDF | Latest company statutes, same delivery flow |
| `tradeRegisterExtract` | Trade Register Extract | PDF | Non-certified compilation of the register publications |
| `financialStatements` | Annual Accounts (Prestacao de Contas) | PDF | One entry per fiscal year and accounts type |
```json theme={null}
{
"documents": {
"certifiedTradeRegisterExtract": {
"id": "",
"name": "Certidao de Registo Comercial",
"description": "Permanent certificate from Portuguese authorities (Instituto dos Registos)",
"format": "pdf"
},
"tradeRegisterExtract": {
"id": "",
"name": "Trade Register Extract",
"description": "Non-certified compilation of the company's commercial registry publications (Registo Comercial / IRN)",
"format": "pdf"
},
"articlesOfAssociation": [
{
"id": "",
"name": "Certidao do Ultimo Pacto Social/Estatutos Atualizados",
"description": "Last updated company statutes from Portuguese authorities",
"format": "pdf"
}
],
"financialStatements": [
{
"id": "",
"name": "Annual Accounts 2024",
"format": "pdf"
}
]
}
}
```
## Data Source Priority & Routing
For a given entity, **data comes from a single primary source** -- the system does not merge attributes across data sources (all-or-nothing model).
**Sources in verification mode (company, legal representatives, shareholders):**
* **Publications** -- The commercial register publications for the NIF are read chronologically and the attributes are extracted from them by AI.
* **Third-party aggregator** -- A company report is read and the same attributes are extracted from it by AI. It also covers companies with no publications.
* If neither source has the company, the datapoint fails with a not-found error.
Read `dataSources` on the response for the per-field provenance.
**Source priority in prefill mode (company only):**
1. **Publications** -- Base company fields reconstructed ahead of time from the same publications and refreshed daily.
2. If **no publications** exist for the company, the datapoint fails with a not-found error. Prefill mode does not use the aggregator, so switch to verification mode for those companies.
**Document Retrieval:**
Documents are retrieved directly from the **IRN** (Instituto dos Registos e do Notariado) portal. This is independent of the company profile data source.
### Attribute-Level Source Mapping
All company profile attributes come from a single AI parse of the IRN commercial-register record. Read `dataSources` on the response for the per-field provenance.
| Attribute | Source | Notes |
| - | - | - |
| Company name | **Source** (AI-parsed) | Extracted from report header |
| Legal form | **Source** (AI-parsed) | Enriched with ISO 20275 code |
| Status | **Source** (AI-parsed) | Enriched to standardized status |
| Registered address | **Source** (AI-parsed) | Street, city, postal code |
| Share capital | **Source** (AI-parsed) | Amount and currency |
| Activity codes (CAE\_REV3) | **Source** (AI-parsed) | Enriched to NACE/ISIC |
| Activity description | **Source** (AI-parsed) | Business purpose text |
| Registration date | **Source** (AI-parsed) | Incorporation/registration date |
| Legal representatives | **Source** | Current representative capacity; signing mode only when disclosed |
| Other key persons | **Source** | Current governance and oversight offices, where disclosed |
| Shareholders | **Source** (AI-parsed) | Individuals and companies |
# Pricing and caching
Source: https://docs.topograph.co/essentials/pricing-and-caching
How Topograph data blocks, documents, budgets, and deduplication work
Topograph prices are country-specific and can change as coverage evolves. Use [Coverage and pricing](/essentials/coverage-and-pricing) for the live human-readable catalog and `GET /v2/pricing` for application logic.
View current country coverage, data block availability, document coverage, sources, and prices.
## How billing works
Topograph bills by data block and document. A data block is the smallest billable unit for structured data in a country. A block can cover one or more datapoints, depending on how that country's sources are packaged.
Common datapoints include:
* `company`
* `legalRepresentatives`
* `otherKeyPersons`
* `establishments`
* `shareholders`
* `subsidiaries`
* `ultimateBeneficialOwners`
* `availableDocuments`
* `graph`
Search and request-result polling by `requestId` are not billed as new company data requests. [Global search](/guides/global-search) is billed per search, and only when it finds one good candidate (`status: resolved`). `availableDocuments` lists document metadata; document downloads are billed only when you request specific document IDs.
## 24-hour deduplication
When you request the same billable block for the same company within 24 hours, Topograph deduplicates the charge for your account. The later request links to the previous billing event rather than creating a duplicate charge.
This matters for multi-step flows: you can request `company` first, then request documents or additional datapoints later without accidentally rebilling blocks that were already covered inside the deduplication window.
Store `requestId` values. `GET /v2/company/{requestId}` retrieves the latest result and refreshes signed document URLs without starting a new billable request.
## Included documents
Some official documents are included when a matching data block has already been requested or deduplicated. Inclusion is country-specific and document-specific.
Use the live pricing page or `GET /v2/pricing` to know whether a document is included with a block or billed standalone.
## Budget caps
Use `maxBudget` to cap the cost of the data blocks in a `/v2/company` request, measured against catalog block prices. Documents requested in the same call are not counted against it, because their cost is only known at retrieval time. If not every requested block fits, Topograph prioritizes blocks in this order:
1. Blocks that cover `company` (highest priority)
2. Blocks that cover `legalRepresentatives`
3. Blocks that cover `ultimateBeneficialOwners`
4. Blocks that cover `shareholders`
5. Blocks that cover `subsidiaries`
Datapoints whose block exceeds the remaining budget are marked as failed with `budget_exceeded`, while the other datapoints continue normally.
```json theme={null}
{
"countryCode": "FR",
"id": "932884117",
"dataPoints": ["company", "ultimateBeneficialOwners", "shareholders"],
"maxBudget": 200
}
```
Use `GET /v2/pricing` before submitting budget-capped requests when your application needs to predict which blocks will fit.
## Retrieve pricing programmatically
Use `GET /v2/pricing` to retrieve country-specific availability and pricing in your application.
```bash theme={null}
curl --request GET \
--url 'https://api.topograph.co/v2/pricing?countryCode=FR' \
--header 'x-api-key: '
```
The response includes:
* Data blocks and the datapoints each block covers.
* Mode availability for verification and prefill.
* Whether a mode is authoritative.
* Included document metadata.
* Flat per-datapoint availability for quick lookups.
* Variable-pricing markers when final document or register costs are known only at request time.
## Best Practices
Use the live pricing page for human review and `/v2/pricing` for runtime decisions.
Split requests across your flow when useful. Duplicate covered blocks within the deduplication window are not charged again.
Always store the `requestId` from your requests. You can use it to retrieve the same data later at no additional cost, regardless of when you make the follow-up request.
When a document is included with a data block, requesting them together can simplify your flow.
## Account billing
Manage credits, payment methods, and invoices from the Topograph dashboard. For custom plans or high-volume usage, contact support.
# Register Credentials
Source: https://docs.topograph.co/essentials/register-credentials
Store your own register logins per workspace to unlock credential-gated data
## Overview
Some registers do not serve their data to a third party. They serve it to **you**, under your own account, and log the access on their side. Two cases exist:
* **Access-gated registers.** The register only grants access to the obliged entity performing the check. Germany's Transparenzregister works this way: without your own login, beneficial owners are only available through a slower partner-sourced path, in verification mode.
* **Enrichment registers.** Topograph can always return the public view, but an account holding elevated roles at the register sees more. France's INPI works this way: accounts authorised for the beneficial-owner register get un-redacted personal fields.
For both cases you store your own register login in Topograph's **credential vault**. Credentials are held **per workspace**, so a reseller can give each client workspace its own register account, and each client's requests run under their own credential.
Each workspace holds its own set of register logins, with fallback to the default workspace
Credentials are encrypted on write. No endpoint and no screen ever returns them back
Data fetched under your login is cached against your account only, never shared
***
## Supported Registers
| Register | Source key | What it changes | Without a credential |
| - | - | - | - |
| Germany: Transparenzregister | `de_transparenzregister` | Returns `ultimateBeneficialOwners` for Germany within the request, in both verification and prefill mode | Verification requests go through a partner-sourced path that takes 1 to 3 business days. Prefill requests return `account_configuration_required` |
| France: INPI | `fr_inpi` | Un-redacts UBO personal fields (date of birth, nationality, address) and returns the richer `ultimateBeneficialOwnersCertificate` PDF | The public, redacted view is returned |
The list above is the current one. `GET /v2/vault/sources` tells you the exact payload each register expects. It can also list a register that no request uses yet, so a credential only changes what you get back for the registers in the table above.
```bash theme={null}
curl "https://api.topograph.co/v2/vault/sources" \
-H "x-api-key: YOUR_API_KEY"
```
```json Response theme={null}
[
{
"key": "fr_inpi",
"format": "password_pool",
"fields": [
{
"name": "accounts",
"type": "array",
"required": true,
"secret": false,
"item": {
"fields": [
{ "name": "username", "type": "string", "required": true, "secret": false },
{ "name": "password", "type": "string", "required": true, "secret": true }
]
}
}
]
},
{
"key": "de_transparenzregister",
"format": "email_password",
"fields": [
{ "name": "email", "type": "string", "required": true, "secret": false },
{ "name": "password", "type": "string", "required": true, "secret": true }
]
}
]
```
Field names match the login form of the register itself, so what you type is what we send. Nothing is translated in between.
***
## How Resolution Works
A credential is looked up from the workspace the request is tagged with, then from the default workspace if that workspace has none of its own.
```mermaid theme={null}
flowchart TD
A["Request tagged acme-paris"] --> B{"Credential on acme-paris?"}
B -->|yes| C["Run under the acme-paris login"]
B -->|no| D{"Credential on the default workspace?"}
D -->|yes| E["Run under the default workspace login"]
D -->|no| F["Access-gated: partner-sourced path or account_configuration_required
Enrichment: public view"]
```
This gives you two working patterns:
Store the login on the **default** workspace and leave the other workspaces empty. Every workspace inherits it, so all requests run under the same register account. Use this when your organisation holds one register account and workspaces exist only for cost attribution.
Store a different login on each workspace. A request tagged `client-alpha` runs under the credential stored on `client-alpha`. Nothing is inherited, because the workspace has its own entry. Use this when you are a reseller and each of your clients is the obliged entity for their own checks.
Store a house login on the default workspace and add a specific one only on the workspaces that need it. Workspaces without their own entry fall back to the default. Deleting a workspace's entry silently returns it to the inherited one.
Company requests resolve credentials from the workspace on the request. [Search](/essentials/search) resolves them at account level, so a register login stored on any of your workspaces is used for search regardless of the workspace header.
***
## Configuring a Credential
### From the dashboard
Go to **Workspaces** in [app.topograph.co](https://app.topograph.co), open a workspace and select **Vault**. Each supported register is listed with the fields it needs and shows whether a credential is currently configured.
Managing credentials is restricted to admins of your organisation. Non-admin members do not see the screen.
### From the API
Credentials are written with a `PUT` per register. The path takes the workspace `name`, the same value you put in the `x-topograph-workspace-id` header, so the entry always lands on the workspace you addressed. The UUID `id` is not accepted in the path, and a name that has never been created returns `404`.
```bash theme={null}
curl -X PUT "https://api.topograph.co/v2/workspaces/acme-paris/vault/de_transparenzregister" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payload": {
"email": "compliance@acme.example",
"password": "YOUR_REGISTER_PASSWORD"
}
}'
```
```json Response theme={null}
{
"sourceKey": "de_transparenzregister",
"origin": "customer_provided",
"shape": "email_password",
"ownerWorkspaceId": "253299d1-e8d0-4268-945b-f175f98bc114",
"version": 1,
"createdAt": "2026-08-26T09:12:00.000Z",
"updatedAt": "2026-08-26T09:12:00.000Z",
"expiresAt": null
}
```
The response carries metadata only. The credential itself is never returned by any endpoint, so store your own copy before writing it.
### Registers that accept several accounts
Where the register supports it, you can register more than one login. France's INPI takes a pool: requests are spread across the accounts and fail over automatically when one is locked, expired, or rate-limited.
```bash theme={null}
curl -X PUT "https://api.topograph.co/v2/workspaces/acme-paris/vault/fr_inpi" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payload": {
"accounts": [
{ "username": "kyc-team-1@acme.example", "password": "FIRST_PASSWORD" },
{ "username": "kyc-team-2@acme.example", "password": "SECOND_PASSWORD" }
]
}
}'
```
A pool is replaced as a whole. To add or remove one account, `PUT` the full list again.
***
## Inspecting and Rotating
### List what a workspace holds
```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/acme-paris/vault" \
-H "x-api-key: YOUR_API_KEY"
```
The list shows only the entries the workspace owns. Inherited entries are not listed, so an empty array means "this workspace has nothing of its own", not "no credential applies".
### Check one register
```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/acme-paris/vault/fr_inpi" \
-H "x-api-key: YOUR_API_KEY"
```
This one resolves the same way a request does, so it also reports inherited entries:
```json Response theme={null}
{
"sourceKey": "fr_inpi",
"origin": "customer_provided",
"shape": "password_pool",
"ownerWorkspaceId": "a1b2c3d4-0000-0000-0000-000000000000",
"inheritedFromWorkspaceId": "a1b2c3d4-0000-0000-0000-000000000000",
"version": 3,
"createdAt": "2026-05-02T08:00:00.000Z",
"updatedAt": "2026-08-20T11:30:00.000Z",
"expiresAt": null
}
```
When `inheritedFromWorkspaceId` is present, the credential comes from your default workspace rather than from the workspace you asked about. Both fields carry the workspace UUID `id`, so match them against `GET /v2/workspaces` if you need the name back. A `404` means either the workspace name does not exist, or neither it nor the default holds an entry for that register.
### Rotate
Rotation is another `PUT` on the same source key. The new payload replaces the old one and `version` increments. There is no downtime window: requests already running finish on the credential they started with, and the next fetch from the register uses the new one.
Rotate before the register forces you to. Registers that lock an account after failed logins will keep locking it while an old password is still stored, so replace the entry first, then reset the password at the register if needed.
### Delete
```bash theme={null}
curl -X DELETE "https://api.topograph.co/v2/workspaces/acme-paris/vault/fr_inpi" \
-H "x-api-key: YOUR_API_KEY"
```
Deleting removes the workspace's own entry. If the default workspace still holds one, the workspace goes back to inheriting it. If nothing remains, access-gated registers fall back to their behaviour without a credential (see below) and enrichment registers revert to the public view.
***
## What Happens Without a Credential
For Germany, a verification request is served through a partner-sourced path: the official extract is obtained on your behalf and `ultimateBeneficialOwners` settles in 1 to 3 business days instead of within the request. See the [Germany](https://www.topograph.co/countries/de) page for how that path behaves.
An prefill request cannot wait that long. There, the datapoint fails on its own, with `account_configuration_required` as the error code. The rest of the request is unaffected and the other datapoints are returned normally.
```json theme={null}
{
"request": {
"requestId": "abc-123",
"dataStatus": {
"dataPoints": {
"ultimateBeneficialOwners": {
"status": "failed",
"error": {
"code": "account_configuration_required"
}
}
}
}
}
}
```
Retrying in prefill mode will not help until a credential is stored. See [Reliability & Errors](/guides/reliability-and-errors) for the full error contract.
The request succeeds and returns the public view of the data. For France that means UBO personal fields stay redacted, exactly as they are in the open data. Nothing in the response fails, so check the [France](https://www.topograph.co/countries/fr) page for what the enriched view adds on top.
A [monitor](/essentials/monitoring) on a company whose datapoints are credential-gated is still created, and the response names the affected datapoint in `datapointNotices`. That datapoint is skipped on scheduled rechecks instead of failing every day, and resumes automatically on the next check once you configure the credential. You get a `monitor.datapoint_blocked` webhook when it stops and `monitor.datapoint_unblocked` when it resumes.
***
## Security and Isolation
Every credential is encrypted with AES-256-GCM under a per-entry key before it is written, and the encryption is bound to the account, workspace, source key and version it was written for, so a row cannot be replayed into another context. Plaintext exists only in memory, for the duration of the call to the register.
No endpoint returns a stored credential, including the one that wrote it. Reads return metadata only: which register, which format, which version, when it changed. The dashboard behaves the same way, showing a register as configured without displaying the secret.
Data retrieved under your credential is cached against your account alone. No other customer can be served a result that was fetched with your login, and you are never served one fetched with someone else's. This keeps the access trail the register records on their side matching the data you actually received.
Results are isolated per account, not per workspace. When two of your workspaces hold different logins and ask for the same company within 24 hours, the second request can be answered with the result fetched under the first workspace's login.
A new, rotated or deleted credential applies to the next fetch from the register. A company already fetched for your account in the last 24 hours can still be answered from that earlier result, including one fetched under the public view or the previous login.
***
## API Reference
| Endpoint | Method | Description |
| - | - | - |
| [`/v2/vault/sources`](/api-reference/vault/list-supported-credential-sources) | GET | List supported registers and their payload shapes |
| [`/v2/workspaces/{name}/vault`](/api-reference/vault/list-vault-entries-on-the-workspace-metadata-only) | GET | List the credentials a workspace owns |
| [`/v2/workspaces/{name}/vault/{sourceKey}`](/api-reference/vault/get-one-vault-entry-by-sourcekey-metadata-only) | GET | Check one register, including inherited entries |
| [`/v2/workspaces/{name}/vault/{sourceKey}`](/api-reference/vault/create-or-replace-a-credential) | PUT | Store or rotate a credential |
| [`/v2/workspaces/{name}/vault/{sourceKey}`](/api-reference/vault/delete-a-credential) | DELETE | Remove a credential |
Workspaces themselves are covered on the [Workspaces](/essentials/workspaces) page. If you have never created one, your account already has a `default` workspace and every credential you store lands there.
# Company Data
Source: https://docs.topograph.co/essentials/retrieve_company
How to request company data from public registers via /v2/company
The `/v2/company` endpoint is the single entry point for company data, official documents, and ownership graph traversal. It accepts one company identifier, one country, and the datapoints or documents you want.
Use it for company onboarding, KYB verification, shareholder and UBO checks, subsidiary analysis, official document retrieval, and follow-up polling by `requestId`.
For live country coverage, data block availability, pricing, sources, identifiers, and document catalogs, see [Coverage and pricing](/essentials/coverage-and-pricing).
## Request shape
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "FR",
"id": "928020932",
"dataPoints": ["company", "legalRepresentatives", "availableDocuments"]
}'
```
## Datapoints
Availability varies by country and mode. Use the live pricing pages or `GET /v2/pricing` for country-specific availability.
| Datapoint | What it returns |
| - | - |
| `company` | Core registration record: legal name, identifiers, legal form, status, address, activity codes, capital, and tax identifiers when available. |
| `legalRepresentatives` | Directors, managers, officers, and other people or companies with legal authority to represent the company. |
| `otherKeyPersons` | Non-signing roles such as auditors, supervisory board members, registered agents, or similar roles when the register exposes them separately. |
| `establishments` | Branches, secondary locations, business premises, or registered establishments. |
| `shareholders` | Direct shareholders and ownership details as available from the register or official filings. |
| `subsidiaries` | Companies owned by the queried company, when downstream participation data is available. |
| `ultimateBeneficialOwners` | Declared beneficial owners and control information where available. |
| `availableDocuments` | List of official documents available for the company. Use the returned document IDs in a follow-up request. |
| `graph` | Multi-level ownership traversal across companies and jurisdictions. See [Ownership graph](/essentials/ownership-graph). |
The legacy `companyProfile` datapoint is still accepted for existing integrations. New integrations should request explicit datapoints. See the [migration guide](/guides/migration-data-product-model).
## Legal Entity Identifier (LEI)
The `company` datapoint includes `company.identifiers.lei` when a company identifier uniquely matches a registration or validation reference in the GLEIF database. Existing country identifiers remain available alongside it.
Coverage varies by jurisdiction and entity. The field is absent when there is no unambiguous identifier match; absence does not prove that the company has no LEI. Lapsed and retired LEIs may be returned, while annulled LEIs are excluded.
```json theme={null}
{
"countryCode": "FR",
"identifiers": {
"siren": "421100645",
"lei": "96950066U5XAAIRCPA78"
}
}
```
## Person identities and role entries
`entityId` identifies a person or company within a request. It links occurrences of the same entity across datapoints, such as `legalRepresentatives`, `shareholders`, and `ultimateBeneficialOwners`. It is not a permanent identifier to match people across separate requests.
**An `entityId` can appear more than once in `legalRepresentatives`.** A person holding several roles can have a separate entry for each appointment, with the same `entityId` and different role details or appointment dates.
For example, a Belgian director can also be a member of the management committee:
| Field | First entry | Second entry |
| - | - | - |
| `entityId` | `person_001` | `person_001` |
| `role.localName` | `Administrateur` | `Membre du comité de direction` |
| `role.englishTranslation` | `Director` | `Member of the management committee` |
| `role.standardized` | `Director` | `Director` |
To import one record per person, group entries by `entityId` within the request and retain all associated roles and appointment dates. Neither `entityId` alone nor the combination of `entityId` and `role.standardized` is a unique key for a role entry. Different local roles can share a standardized category. If `entityId` is absent, do not group all entries without an ID into one person.
## Choose a mode
`/v2/company` supports two modes:
* Verification mode is the default and prioritizes authoritative data for compliance.
* Prefill mode (`mode: "prefill"`) prioritizes speed for form prefill and early screening.
Both modes return the same response shape. Read [Verification vs prefill mode](/essentials/modes) before deciding which mode to use in a customer-facing flow.
```json theme={null}
{
"countryCode": "DE",
"id": "HRB123456",
"dataPoints": ["company", "legalRepresentatives"],
"mode": "prefill"
}
```
## Documents
Document retrieval is a two-step flow:
1. Request `availableDocuments`.
2. Pass selected document IDs in the `documents` array.
```json theme={null}
{
"countryCode": "FR",
"id": "928020932",
"documents": ["1c932de4-4610-5506-b48d-4e62529d58e8"]
}
```
Document IDs are opaque and company-specific. Always discover them through `availableDocuments` before requesting a download. See [Document retrieval](/essentials/document-guide).
## Response lifecycle
Every request returns a `request` object with the current status of each datapoint and document.
```json theme={null}
{
"request": {
"companyId": "932884117",
"countryCode": "FR",
"requestId": "253299d1-e8d0-4268-945b-f175f98bc114",
"dataPoints": ["company", "legalRepresentatives"],
"dataStatus": {
"dataPoints": {
"company": {
"status": "succeeded",
"authoritative": true
},
"legalRepresentatives": {
"status": "in_progress"
}
},
"documents": {}
}
}
}
```
| Status | Meaning |
| - | - |
| `succeeded` | The datapoint or document is available. |
| `in_progress` | Retrieval is still running. Poll again or wait for a webhook. |
| `enriching` | A partial result is available while enrichment continues. |
| `failed` | Retrieval failed. Inspect `error.code` and `error.message`. |
The response may be progressive. For example, `company` can succeed before `legalRepresentatives`, documents, or ownership datapoints finish.
### Not every `failed` is an outage
These `error.code` values mean the datapoint is not something we return for this
request, rather than something that went wrong:
| `error.code` | Meaning | Example |
| - | - | - |
| `datapoint_not_applicable` | The datapoint does not apply to this entity. | `shareholders` for a sole trader. A natural person trading in their own name has no share capital, so the owner appears under `legalRepresentatives`. |
| `datapoint_not_supported` | We do not return this datapoint for this country, in any mode. | `ultimateBeneficialOwners` where the country publishes no beneficial-owner register, or where we do not yet source it. |
| `fast_source_unavailable` | The datapoint exists for this country, but not in prefill mode. Retry without `mode: "prefill"`. | `graph` requested in prefill mode. |
| `authoritative_source_unavailable` | The datapoint exists for this country, but only in prefill mode. Retry with `mode: "prefill"`. | `company` in a country served only from a non-authoritative source, requested in verification mode (the default). |
All of them carry `retryable: false`: the same request gets the same answer. Handle them the way you would handle a successful
"nothing to report" answer: don't retry, don't alert, don't block your flow waiting
for them. Filter on the code or on `retryable`. `error.message` is human-readable and
safe to show your own users. The complete list of codes, with `retryable` and the
recommended `retryAfterSeconds` for the ones you can resubmit, is in
[Reliability & Errors](/guides/reliability-and-errors#datapoint-and-document-error-codes).
To know which datapoints a country returns *before* you request them, see
[Coverage and pricing](/essentials/coverage-and-pricing) or `GET /v2/pricing`.
### An empty list is an answer
The list-shaped fields — `legalRepresentatives`, `otherKeyPersons`,
`establishments`, `shareholders`, `subsidiaries`, `ultimateBeneficialOwners` —
follow one rule, in both the API response and the webhook payload:
| Shape | Meaning |
| - | - |
| `[ … ]` | The records the register published. |
| `[]` | The datapoint **succeeded** and the register published no records. We looked; there is nothing there. |
| Key absent | The datapoint was not requested, is still running, or `failed`. Read `dataStatus.dataPoints.` to tell which. |
So a datapoint whose `dataStatus` says `succeeded` always carries its list. You
never have to disambiguate "succeeded with nothing attached" from "never ran" —
`succeeded` plus a missing key cannot happen.
An empty list means *the register holds no such record*, which is not always
the same as *the entity has none*. Some registers only publish part of a
category: the Dutch KVK, for example, registers a shareholder only when a
company has a single 100% holder, so a BV with several shareholders returns
`shareholders: []`. Country pages document these limits — see
[Netherlands](https://www.topograph.co/countries/nl#reading-an-empty-shareholders-list).
## Polling
Use the `requestId` to fetch the latest result. This is free and does not create a new billable request.
```bash theme={null}
curl --request GET \
--url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114 \
--header 'x-api-key: '
```
Poll every few seconds until the requested datapoints and documents are terminal (`succeeded` or `failed`). In production, use [webhooks](/guides/webhooks) when possible.
Some datapoints are [manually delivered](/essentials/manual-delivery) and stay `in_progress` for typically 1–3 business days. For these, webhooks are strongly recommended over polling.
Branch on the status itself rather than enumerating the non-terminal ones. A poller
that waits for anything other than `succeeded` or `failed` will hang if a new
intermediate status is ever introduced.
## PDF extract
Any request can also be returned as a single-file PDF extract, suitable for attaching to a case file or handing to a reviewer.
```bash theme={null}
curl --request GET \
--url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114/pdf \
--header 'x-api-key: ' \
--output company-extract.pdf
```
The extract renders the company profile, legal representatives, shareholders, ultimate beneficial owners, other key persons, establishments and the ownership graph — whichever of those the request asked for and received. Like polling, it is free and never billed again: it renders data the request already paid for, so you can re-download it as often as you need.
### Requesting before a request has finished
By default the extract renders whatever has arrived, exactly as `GET /v2/company/{requestId}` returns partial results while a request is still running.
The extract is built around the `company` datapoint, so it needs company data to render anything. Until `company` has arrived, the endpoint returns `409` with `extract_data_incomplete`, even without `requireComplete`. If the request settles without company data (because `company` was not requested, or it failed), it returns `409` with `extract_no_data`. Include `company` in any request you want an extract for.
A partial extract says so on its own face, so it can never be mistaken for a complete one:
* The seal reads **PARTIAL** instead of **VERIFIED**.
* A **Data completeness** section lists every requested datapoint and whether it was included, is still being retrieved, or failed — with the reason.
* The `X-Topograph-Data-Status` response header carries `complete` or `partial`, so you can branch without opening the file.
If you would rather have an error than a partial file — for an archival export that must not be a snapshot of a half-finished request — pass `requireComplete`:
```bash theme={null}
curl --request GET \
--url 'https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114/pdf?requireComplete=true' \
--header 'x-api-key: ' \
--output company-extract.pdf
```
That returns `409` while any requested datapoint is still running, naming what it is waiting on:
```json theme={null}
{
"code": "extract_data_incomplete",
"message": "The request is still running, so the extract would be partial.",
"pendingDataPoints": ["shareholders"]
}
```
Only datapoints decide completeness. Documents are delivered as separate files and never appear in the extract, so a document still downloading does not hold the PDF back.
### Seal states
| Seal | Meaning |
| - | - |
| `VERIFIED` | Every requested datapoint settled, from authoritative register sources. |
| `PARTIAL` | The request was still running when the extract was generated. |
| `UNVERIFIED` | A datapoint was served from a non-authoritative source — see [Modes](/essentials/modes). |
### Viewing in a browser
The response defaults to `Content-Disposition: attachment`. Pass `disposition=inline` to render it in place instead:
```
GET /v2/company/{requestId}/pdf?disposition=inline
```
## Pricing and budget controls
Topograph bills by data block and document. A 24-hour deduplication window prevents duplicate billing for the same block, company, and account. Request ID lookups are always free.
Use [Pricing and caching](/essentials/pricing-and-caching) for billing mechanics and [Coverage and pricing](/essentials/coverage-and-pricing) for live country-specific prices and availability.
# Romania
Source: https://docs.topograph.co/essentials/romania
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Romania reference is on the [Romania country page](https://www.topograph.co/countries/ro).
## Start here
This guide contains public integration notes for Romania. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Romania uses two data sources from the same register, serving different datapoints, plus the register of beneficial owners and VIES for VAT validation.
* **ONRC Open Data (data.gov.ro)**: Datasets published periodically by ONRC on Romania's Open Data portal. Contains \~4.1M entities with basic company data: legal name, status, legal form, address, activity codes (CAEN), and legal representatives. Used for **search** and, together with the live ONRC register, for **prefill mode**.
* **ONRC Portal (myportal.onrc.ro)**: The National Trade Register Office portal, operated by the Ministry of Justice. All **company profile** data is extracted from the **Certified Trade Register Extract** (Certificat constatator), a comprehensive PDF document that contains the full company record: identification, status, legal form, address, share capital, shareholders, legal representatives, auditors, establishments, and activity codes.
* **ONRC Register of Beneficial Owners (Registrul beneficiarilor reali)**: Kept by ONRC and not publicly searchable. A local partner obtains the official extract, which ONRC only releases against a one-page mandate signed by the requesting client (we provide the template). Source of the **Ultimate Beneficial Owners** datapoint and the **Beneficial Ownership Extract** document.
* **VIES**: In verification mode, a qualified VIES check confirms whether the company is registered for VAT.
**Prefill mode** covers `company`, `legalRepresentatives` and `otherKeyPersons`. It is
built from the ONRC Open Data export, with legal name, registered address,
status and legal form refreshed from the live ONRC register. **Verification
mode** retrieves and parses the Certified Trade Register Extract for
comprehensive data including shareholders, capital, and detailed
establishments.
**Certified Trade Register Extract.** The extract is ordered from ONRC on
demand and typically arrives within a few minutes. Once retrieved, it is
reused for 1 day.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All companies** | ONRC | 2-10 digits (CUI) | `37246510` | Primary identifier, accepted for `search` and `/v2/company` |
| **All companies** | ONRC | Registration number (RC number), slash-separated or 14 characters | `J2017003749401`, `J40/8232/2024` | Accepted for `search` and `/v2/company`. This is the `id` search returns |
Both the **CUI** (Cod Unic de Înregistrare) and the **registration number**
(Număr de ordine în Registrul Comerțului, a.k.a. RC number or cod de
înmatriculare) are accepted by `search` and `/v2/company`. The CUI is the
primary identifier in the catalog, but search results carry the
registration number as `id`, not the CUI. A CUI passed to `/v2/company` is
resolved to the company's registration number before the extract is ordered.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `cui` | 2-10 digits | `37246510` | All companies |
| `registrationNumber` | Slash-separated (`J40/8232/2024`) or 14 characters (`J2017003749401`), see below | `J2017003749401` | All companies |
| `euid` | ROONRC. + registration number in its current form | `ROONRC.J2017003749401` | All companies |
| `VAT` | CUI, without the RO prefix | `37246510` | Verification mode, only when VIES confirms VAT registration |
Holding a CUI does not mean a company is registered for VAT. `identifiers.VAT`
and a verified `taxId` with a VIES consultation number are returned only when
VIES confirms the registration.
**Ordine RC Number Formats:** The registration number (Numar de ordine in Registrul Comertului) can appear in two formats, both issued by the register:
* **With slashes (older form):** letter + county code (1 or 2 digits) + sequence number within the year + registration year, e.g. `J40/8232/2024`, `J03/2/1998`, `F16/655/2004`.
* **14 characters (current form):** letter + 4-digit registration year + 6-digit zero-padded sequence + 2-digit county code (`00` for registrations since 26 July 2024) + check digit, e.g. `J2017003749401`, `J2026014659009`. The check digit is the ASCII code of the letter (J 74, F 70, C 67) plus the sum of the 12 digits that follow, modulo 10.
Every registration since 26 July 2024 uses the 14-character form. A company registered earlier can carry either form; the register moves it to the 14-character form when it records a change of name, registered office, main activity or legal form.
The letter is the register, not the county: `J` legal entities, `F` authorised individuals, sole traders and family businesses, `C` cooperatives. The county is the number that follows (e.g. `40` for Bucharest).
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the CUI (`cui`) or trade-register number (`registrationNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By CUI | 2-10 digits | `37246510` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT number | RO + 2-10 digits | `RO37246510` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Ordine RC Number (slashes) | Letter + digits/slashes | `F16/655/2004` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Ordine RC Number (compact) | Letter + 13 digits | `J2017003749401` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"DECATHLON"` | Fuzzy | Multiple results (up to 10) |
**Search Performance:** Use identifier-based searches (CUI, Ordine RC Number)
for best performance and exact matching. Name searches query the ONRC portal
and may return multiple results.
**Search is free.** Search queries do not incur any cost. Company data is
billed in both modes: in verification mode through the Certified Trade
Register Extract (`company`, `legalRepresentatives`, `shareholders`,
`otherKeyPersons`, `establishments`), and in prefill mode through the
prefill block (`company`, `legalRepresentatives`, `otherKeyPersons`). See the
[pricing page](https://topograph.co/pricing/ro).
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies in insolvency, liquidation or bankruptcy count as inactive and are removed. Companies in judicial reorganisation, or whose activity is only temporarily suspended, are generally kept.
## Prefill mode (fast retrieval)
[`POST /v2/company`](/essentials/retrieve_company) with [`mode: "prefill"`](/essentials/modes) provides fast, cost-effective access to company data for Romania, optimized for prefill requests.
Prefill mode serves `company`, `legalRepresentatives` and `otherKeyPersons`. Data comes from the ONRC Open Data export, with the legal name, registered address, status and legal form refreshed from the live ONRC register. It provides company identifiers, legal name, status, legal form (with ISO 20275), geocoded address, activity codes (CAEN/NACE/ISIC), and legal representatives (both individuals and corporate entities). Activity codes, registration date and share capital stay as published in the export. Auditors, supervisory appointments and ownership-only records in the export are returned as other key persons; their listing does not establish company-signing authority. `shareholders` and `establishments` require verification mode.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **CUI or RC number** | Both the CUI (e.g. `37246510`) and the registration number (cod de înmatriculare, e.g. `J2017003749401` or `J40/8232/2024`) are accepted for search, prefill mode, and verification mode. |
| **All data comes from a single PDF** | In verification mode, Romania extracts all structured data by parsing the Certified Trade Register Extract PDF from ONRC. Data freshness depends on when the document was last generated. |
| **Document retrieve required** | Each company profile request requires retrieving a Certified Trade Register Extract from ONRC (\~3 min retrieval). Documents are deduplicated for 1 day. |
| **Capital in RON (Lei)** | Share capital is always expressed in Romanian Lei (RON), not EUR. |
| **Suspended = Active** | Companies with `suspendata` status are mapped as Active but flagged, as suspension in Romania is temporary. |
| **CAEN = NACE** | CAEN Rev. 2 corresponds to NACE Rev. 2; CAEN Rev. 3 corresponds to NACE Rev. 2.1. The source revision determines how a declared code is converted. Older or unstamped codes are preserved without assuming a revision. |
| **ISIC is deterministic** | CAEN/NACE codes are official from ONRC. ISIC codes are derived deterministically from NACE via the official UN ISIC Rev. 5 ↔ NACE Rev. 2.1 correspondence table. |
| **Legal form standardization is AI-enriched** | The initial deterministic mapping covers common forms (S.R.L., S.A., I.I.). Less common forms are enriched with English translations and ISO 20275 codes via AI. |
| **No financial statements** | Financial statements are not currently available through ONRC. |
| **UBO data is delivered manually** | Beneficial owners are available as the `ultimateBeneficialOwners` datapoint and as the Beneficial Ownership Extract document, both taken from the official ONRC extract obtained by a local partner, typically within 1-3 business days. ONRC requires a mandate signed by the requesting client before it releases the extract; contact support to set it up. Datapoint values are extracted from the extract, so verify them against the document before relying on them for compliance. |
| **Corporate legal representatives** | Romania supports corporate entities (legal persons) as legal representatives, not just individuals. |
| **Closure reasons from document sections** | Closure details (dissolution, liquidation, insolvency) are parsed from the `FAPTE AFLATE SUB INCIDENTA ART. 103` section of the trade register extract. |
| **No employee count** | Employee count data is not available from ONRC. |
| **No business purpose description** | The `activityDescription` field is not populated. Use activity codes instead. |
## Company Status
Company status is extracted directly from the Certified Trade Register Extract. The field `Stare firma` provides the raw status text, which is then mapped to a standardized status.
### Status Mapping
| Romanian Status | English | Standardized Status | Notes |
| - | - | - | - |
| în funcţiune | Operating | Active | Company is actively operating |
| suspendată / suspendat | Suspended | Active | Temporary suspension, mapped as Active but flagged |
| dizolvată / dizolvare | Dissolved | Closed | Company has been voluntarily dissolved |
| dizolvare judiciară | Judicially dissolved | Closed | Company dissolved by court order |
| lichidare | In liquidation | Closed | Company is being liquidated |
| radiat | Struck off | Closed | Company has been removed from register |
| inactivă / inactiv | Inactive | Closed | Company is no longer active |
| insolvenţă / insolventa | Under insolvency | Under Insolvency Proceeding | Insolvency proceedings are underway |
### Closure Reasons
When status is Closed or Under Insolvency Proceeding, closure details are extracted from the `FAPTE AFLATE SUB INCIDENTA ART. 103 ALIN.(1) LIT. f-p)` section of the trade register extract:
| Source | Standardized Closure Reason |
| - | - |
| `Insolvenţă` subsection in FAPTE | Bankruptcy |
| `Lichidare firma` subsection in FAPTE | Liquidation |
| `Dizolvare firma` subsection in FAPTE | Voluntary Dissolution |
| Status line contains "judiciară" (no FAPTE records) | Court Order |
| Status line contains "radiat" (no FAPTE records) | Administrative Dissolution |
Closure dates come from two sources: the `Dată dizolvare:` field in the
`FAPTE` section, or a date embedded directly in the `Stare firmă` status line
(e.g. "radiată în data de 23.04.2002"). The `insolvencyStartDate` and
`closureDate` fields are populated when a date is found. When multiple closure
indicators are present, insolvency takes priority over liquidation, which takes
priority over dissolution.
## Legal Forms
Romania uses local legal form names from ONRC. The mapping from Romanian forms to standardized forms and **ISO 20275 (ELF)** codes uses a **deterministic lookup for common forms** and **AI enrichment for less common forms**.
### Key Business Forms
| Romanian Name | Abbreviation | English Translation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Societate cu raspundere limitata | S.R.L. | Limited Liability Company | Limited Liability Company | XHN1 |
| Societate pe actiuni | S.A. | Joint Stock Company | Corporation | ANDT |
| Persoană fizică autorizată | P.F.A. | Authorized Natural Person | Sole Proprietorship | FJQ8 |
| Intreprindere individuala | I.I. | Sole Proprietorship | Sole Proprietorship | None |
The deterministic mapping covers the three most common Romanian legal forms
(S.R.L., S.A., I.I.). For all other legal forms encountered in ONRC data, the
system uses AI enrichment to provide English translations, standardized types,
and ISO 20275 codes. The local Romanian legal form name is always preserved
verbatim.
## Legal Representatives
Legal representatives are extracted from multiple sections of the Certified Trade Register Extract. Both **individual** and **corporate** legal representatives are supported. Role names are preserved in Romanian and enriched via AI for English translations and standardized roles.
### Document Sections Parsed
The following sections of the Certified Trade Register Extract are parsed for legal representatives:
| Document Section | Description | Person Type |
| - | - | - |
| `REPREZENTANT actionar/asociat/membru (PERSOANA JURIDICA)` | Shareholder/member representative | Corporate |
| `ASOCIAT, reprezentant al detinatorilor in comun de parti sociale (PERSOANA FIZICA)` | Joint ownership representative | Individual |
| `PERSOANE IMPUTERNICITE (PERSOANE JURIDICE)` | Authorized persons | Corporate |
| `PERSOANE IMPUTERNICITE (PERSOANE FIZICE)` | Authorized persons | Individual |
| `ADMINISTRATORI JUDICIARI / LICHIDATORI JUDICIARI / LICHIDATORI (PERSOANE JURIDICE)` | Judicial administrators / Liquidators | Corporate |
| `ADMINISTRATORI JUDICIARI / LICHIDATORI JUDICIARI / LICHIDATORI (PERSOANE FIZICE)` | Judicial administrators / Liquidators | Individual |
| `CURATOR / CURATOR SPECIAL (PERSOANA JURIDICA)` | Curators | Corporate |
| `CURATOR / CURATOR SPECIAL (PERSOANE FIZICE)` | Curators | Individual |
### Role Mapping
| Romanian Role | English Translation | Standardized Role |
| - | - | - |
| Administrator | Administrator | Administrator |
| Director General | Managing Director | Managing Director |
| Persoana imputernicita | Authorized Representative | Authorized Signatory |
| Administrator judiciar | Judicial Administrator | Receiver |
| Lichidator judiciar / Lichidator | Judicial Liquidator / Liquidator | Liquidator |
| Curator / Curator special | Curator / Special Curator | Other |
| Persoana fizica autorizata / Titular | Authorized Natural Person / Holder | Owner |
Known filed titles use the published role reference vocabulary. The authorized-person, insolvency, curator or sole-trader source context establishes the representative capacity; an ownership or oversight title alone does not. Shareholder representatives exercise the holder's rights and are returned as other key persons. Unknown filed titles remain visible without a guessed office. Appointment and mandate-expiration dates are captured when available. Raw `Puteri` or `Atribuţii de reprezentare` text is retained. `DEPLINE` describes scope and does not by itself mean sole representation; explicit separate or joint wording establishes mode, without guessing a signatory count.
### Data Extracted per Representative
| Field | Source | Notes |
| - | - | - |
| Type | Section header | `individual` or `company` |
| Role (local) | `Calitate:` field | Preserved in Romanian |
| Role (English) | AI enrichment | English translation |
| Role (standardized) | Deterministic + AI | Standardized enum |
| Start date | `Data numirii:` | Appointment date (dd.mm.yyyy) |
| End date | `Data expirarii mandatului:` | Mandate expiration (dd.mm.yyyy) |
| Full name | First line of block | All caps |
| Gender | `Sex:` field | MASCULIN / FEMININ (individuals only) |
| Birth date | `Data si locul nasterii:` | dd.mm.yyyy (individuals only) |
| Birth place | `Data si locul nasterii:` | After date, comma-separated (individuals only) |
| Nationality | `Cetatenie:` | Country code derived (individuals only) |
| Company name | First line of block | All caps (corporate only) |
| Registration number | `Numar de inmatriculare/inregistrare:` | (corporate only) |
| Registered address | `SEDIU SOCIAL:` or `Adresa sediu social:` | (corporate only) |
## Other Key Persons
Auditors and censors are extracted from the `CENZORI / AUDITORI` sections of the certified extract. Supervisory appointments and representatives of shareholders are also kept as other key persons. Prefill preserves the audit, oversight and ownership-only capacities available in the export. Both individual and corporate identities are supported.
### Role Mapping
| Romanian Role | English Translation | Standardized Role |
| - | - | - |
| Cenzor | Auditor | Auditor |
| Auditor | Auditor | Auditor |
| Membru în consiliul de supraveghere | Supervisory Board Member | Supervisory Board Member |
| Asociat / Acţionar | Member / Shareholder | Other |
| Reprezentant acţionar/asociat/membru | Shareholder Representative | Other |
Other key persons include both individual and corporate auditors/censors. They
are extracted from the `CENZORI / AUDITORI (PERSOANE JURIDICE)` and `CENZORI /
AUDITORI (PERSOANE FIZICE)` sections. Appointment dates and mandate expiration
dates are captured when available. Data fields extracted are identical to
legal representatives (name, gender, birth date, nationality for individuals;
company name, registration number, address for corporate entities).
## Shareholders
Shareholders are extracted from these sections of the Certified Trade Register Extract:
| Section | Type | Description |
| - | - | - |
| `ASOCIATI PERSOANE FIZICE` | Individual | Natural person shareholders (S.R.L.) |
| `ASOCIATI PERSOANE JURIDICE` | Corporate | Legal entity shareholders (S.R.L.) |
| `ACŢIONARI PERSOANE FIZICE` | Individual | Natural person shareholders (S.A.) |
| `ACŢIONARI PERSOANE JURIDICE` | Corporate | Legal entity shareholders (S.A.) |
| `ACŢIONARI LISTĂ` | Aggregate | Free float, returned as a labelled group with no `id` |
**Sole traders** (registration numbers starting with `F`) have no share
capital. `shareholders` returns `datapoint_not_applicable`, and the trader is
returned under `legalRepresentatives` with the standardized role `Owner`.
### Data Extracted per Shareholder
| Field | Source | Notes |
| - | - | - |
| Type | Section | `individual` or `company` |
| Share percentage | `Cota de participare la beneficii si pierderi:` | Percentage (e.g., `60%`) |
| Number of shares | `Numar parti sociale:` | Integer count |
| Capital contribution | `Aport la capital:` | Amount in LEI (RON) |
| Full name | First line of block | All caps (individuals) |
| Gender | `Sex:` | MASCULIN / FEMININ (individuals) |
| Birth date | `Data si locul nasterii:` | dd.mm.yyyy (individuals) |
| Birth place | `Data si locul nasterii:` | After date (individuals) |
| Nationality | `Cetatenie:` | Country code (individuals) |
| Company name | First line of block | All caps (corporate) |
| Nationality | `Nationalitate:` | Country code (corporate) |
| Registered address | `SEDIU SOCIAL:` | (corporate) |
| Registration number | `Numar de inmatriculare/inregistrare in registrul comertului:` | (corporate) |
Shareholder data includes both ownership percentages and capital
contributions. Capital is always in RON (Romanian Lei). Individual and
corporate shareholders come with detailed identity and address information.
Free-float lists carry only the register's label, share count, percentage and
capital.
## Activity Code Mapping
Romania uses **CAEN** (Clasificarea Activităților din Economia Națională). [CAEN Rev. 3](https://www.onrc.ro/documente/anunturi/2024/INFORMARE%20CAEN%20.pdf) corresponds to NACE Rev. 2.1; earlier CAEN Rev. 2 corresponds to NACE Rev. 2. Each code is interpreted using the revision published by ONRC.
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **CAEN** | Older or unstamped ONRC code, with its Romanian description | Source code | No |
| **CAEN\_REV2** | ONRC code explicitly marked Rev. 2 | `6201` | No |
| **CAEN\_REV3** | ONRC code explicitly marked Rev. 3 | `6210` | No |
| **NACE** | Rev. 2 codes converted to Rev. 2.1; validated Rev. 3 codes mapped directly | `62.10` | No (formal mapping) |
| **ISIC** | Derived from validated NACE Rev. 2.1 through the official correspondence table | `621` | No (formal mapping) |
`CAEN` preserves older or unstamped assignments. `CAEN_REV2` and `CAEN_REV3` appear only when the source states that revision, without duplicating those assignments under `CAEN`. Older or unstamped codes retain their original code and text, without a guessed revision or a derived NACE or ISIC code.
**One code in, one code out.** When a valid declared code has no single equivalent in the target revision, the shared parent category is returned rather than every candidate. See [One code in, one code out](/guides/standardization#one-code-in-one-code-out).
### Activity Codes by Source
| Source | Classifications Returned | Notes |
| - | - | - |
| **ONRC certified extract** | CAEN, source-stamped revision keys, and NACE/ISIC where a valid correspondence exists | Covers declared main and secondary activities |
| **ONRC Open Data** | The same classifications, subject to the revision published for each code | Used in prefill mode |
**Main activity flag:** the certified extract's declared main activity carries `isMainActivity: true`. Derived NACE and ISIC codes inherit the flag. Secondary activities are not flagged. The Open Data record does not distinguish a main activity, so prefill responses have no main-activity flag.
## Data Availability Matrix
| Data Type | ONRC Open Data (Batch) | ONRC Portal (Live) | Notes |
| - | - | - | - |
| Prefill Profile | ✅ Fast | ✅ | Open Data export, identity fields refreshed from the live register |
| Company Profile | - | ✅ Async | Full data from Certified Trade Register Extract |
| Legal Representatives | ✅ | ✅ | Prefill: live authorized-person name; title and available personal details from the export. Verification: full details (birth date, nationality, addresses) |
| Other Key Persons | ✅ | ✅ | Exported oversight/ownership capacities; certified-extract auditors and shareholder representatives |
| Shareholders | - | ✅ | Individuals and corporate, with percentages and capital contributions |
| Ultimate Beneficial Owners | - | ✅ Manual | From the official ONRC beneficial-ownership extract, typically 1-3 business days; requires a signed client mandate |
| Establishments | ❌ | ✅ | Verification mode only: all types (branches, subsidiaries, working points) |
| Activity Codes | ✅ | ✅ | Original CAEN codes; revision keys and deterministic NACE/ISIC where the source revision is known |
| Documents | - | ✅ | Certified Trade Register Extract; Beneficial Ownership Extract |
**Legend:** ✅ Available | ❌ Not Available | Async = Asynchronous processing
## Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Certified Trade Register Extract (Certificat constatator)** | `certifiedTradeRegisterExtract` | PDF | ✅ All companies | Comprehensive company record from ONRC, Romanian language, \~3 min retrieval |
| **Beneficial Ownership Extract** | `ultimateBeneficialOwnersCertificate` | PDF | ✅ All companies | Official extract from the ONRC register of beneficial owners. Delivered manually, typically within 1-3 business days; requires a signed client mandate |
The Certified Trade Register Extract is always available for any registered
company. It is retrieved from ONRC on demand and deduplicated for 1 day. The
Beneficial Ownership Extract is delivered manually (see Quirks & Gotchas).
Financial statements and other document types are not currently available
through ONRC.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "J40/1234/2020", "countryCode": "RO", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "J40/1234/2020",
"countryCode": "RO",
"identifiers": { "registrationNumber": "J40/1234/2020", "cui": "12345678", "euid": "ROONRC.J40/1234/2020" },
"legalName": "EXEMPLU TECH S.R.L.",
"registrationDate": "2020-03-15",
"status": { "localName": "în funcţiune", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Societate cu răspundere limitată", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "XHN1" },
"capital": { "amount": 200, "currency": "RON" },
"activities": {
"CAEN_REV2": [
{ "code": "6201", "description": "Activităţi de realizare a soft-ului la comandă", "isAIInferred": false },
{ "code": "6202", "description": "Activităţi de consultanţă în tehnologia informaţiei", "isAIInferred": false }
],
"NACE": [
{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false },
{ "code": "62.20", "description": "Computer consultancy and computer facilities management activities", "isAIInferred": false }
],
"ISIC": [
{ "code": "621", "description": "Computer programming activities", "isAIInferred": false },
{ "code": "622", "description": "Computer consultancy and computer facilities management activities", "isAIInferred": false }
]
},
"legalAddress": { "addressLine1": "Strada Exemplu Nr. 10", "city": "București", "postalCode": "010101", "countryCode": "RO" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Administrator", "englishTranslation": "Administrator", "standardized": "Administrator" }, "startDate": "2020-03-15", "individual": { "name": { "fullName": "POPESCU ION" }, "gender": "Male", "nationality": "RO", "birthDate": { "day": 15, "month": 6, "year": 1985 } } }
],
"otherKeyPersons": [
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Cenzor", "englishTranslation": "Auditor", "standardized": "Auditor" }, "startDate": "2020-03-15", "endDate": "2025-03-15", "individual": { "name": { "fullName": "IONESCU MARIA" }, "gender": "Female" } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "sharePercentage": 60, "numberOfShares": 12, "nominalCapitalHeld": { "amount": 120, "currency": "RON" }, "individual": { "name": { "fullName": "POPESCU ION" }, "gender": "Male", "birthDate": { "day": 15, "month": 6, "year": 1985 } } },
{ "entityId": "person_003", "type": "individual", "sharePercentage": 40, "numberOfShares": 8, "nominalCapitalHeld": { "amount": 80, "currency": "RON" }, "individual": { "name": { "fullName": "POPESCU ELENA" }, "gender": "Female" } }
],
"establishments": [
{ "name": "Punct de lucru București", "active": true, "creationDate": "2020-06-01", "address": { "addressLine1": "Bulevardul Unirii Nr. 5", "city": "București", "countryCode": "RO" } }
]
}
```
```json theme={null}
{
"company": {
"id": "J40/5678/2015",
"countryCode": "RO",
"identifiers": { "registrationNumber": "J40/5678/2015", "cui": "87654321", "euid": "ROONRC.J40/5678/2015" },
"legalName": "VECHE COMPANIE S.R.L.",
"registrationDate": "2015-06-01",
"status": { "localName": "dizolvare", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "VOLUNTARY_DISSOLUTION" } },
"legalForm": { "localName": "Societate cu răspundere limitată", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "XHN1" },
"capital": { "amount": 200, "currency": "RON" },
"legalAddress": { "addressLine1": "Calea Victoriei Nr. 100", "city": "București", "countryCode": "RO" }
}
}
```
**Note:** Closed companies include status details with closure reason when available (dissolution, liquidation, bankruptcy). Legal representatives and shareholders may still be present from the last trade register extract.
```json theme={null}
{
"company": {
"id": "J12/3456/2018",
"countryCode": "RO",
"identifiers": { "registrationNumber": "J12/3456/2018", "cui": "55555555", "euid": "ROONRC.J12/3456/2018" },
"legalName": "FIRMA INSOLVENTA S.A.",
"registrationDate": "2018-01-20",
"status": { "localName": "insolvenţă", "active": false, "statusDetails": { "status": "UNDER_INSOLVENCY_PROCEEDING", "closureReason": "BANKRUPTCY", "insolvencyStartDate": "2023-05-10" } },
"legalForm": { "localName": "Societate pe acțiuni", "englishTranslation": "Joint Stock Company", "standardized": "Corporation", "iso20275Code": "ANDT" },
"capital": { "amount": 90000, "currency": "RON" },
"legalAddress": { "addressLine1": "Strada Industriei Nr. 50", "city": "Cluj-Napoca", "countryCode": "RO" }
},
"legalRepresentatives": [
{ "entityId": "company_001", "type": "company", "role": { "localName": "Administrator judiciar", "standardized": "Other" }, "startDate": "2023-05-10", "company": { "id": "99887766", "legalName": "CABINET INSOLVENTA S.P.R.L.", "countryCode": "RO", "legalAddress": { "addressLine1": "Strada Justitiei Nr. 12", "city": "Cluj-Napoca", "countryCode": "RO" } } }
]
}
```
**Note:** Companies under insolvency proceedings may have judicial administrators (`Administrator judiciar`) or liquidators (`Lichidator judiciar`) as legal representatives instead of regular directors. These are often corporate entities (insolvency firms).
```json theme={null}
{
"company": {
"id": "J40/9876/2019",
"countryCode": "RO",
"identifiers": { "registrationNumber": "J40/9876/2019", "cui": "44444444", "euid": "ROONRC.J40/9876/2019" },
"legalName": "FILIALA ROMANIA S.R.L.",
"registrationDate": "2019-11-01",
"status": { "localName": "în funcţiune", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Societate cu răspundere limitată", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "XHN1" },
"capital": { "amount": 50000, "currency": "RON" },
"legalAddress": { "addressLine1": "Bulevardul Republicii Nr. 25", "city": "Brașov", "countryCode": "RO" }
},
"shareholders": [
{ "entityId": "company_001", "type": "company", "sharePercentage": 100, "numberOfShares": 500, "nominalCapitalHeld": { "amount": 50000, "currency": "RON" }, "company": { "id": "123456789", "legalName": "PARENT CORP S.A.", "countryCode": "FR", "identifiers": { "siren": "123456789" }, "legalAddress": { "addressLine1": "10 Rue de la Paix", "city": "Paris", "countryCode": "FR" } } }
]
}
```
**Note:** Corporate shareholders include company identification data (name, country, registration number, address). Foreign parent companies are supported with their respective country codes.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `certifiedTradeRegisterExtract` | Certified Trade Register Extract (Certificat constatator) | Always available, \~3 min retrieval |
# Russia
Source: https://docs.topograph.co/essentials/russia
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Russia reference is on the [Russia country page](https://www.topograph.co/countries/ru).
## Start here
This guide contains public integration notes for Russia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
## Data Sources
**EGRUL/EGRIP (Единый государственный реестр юридических лиц / Единый государственный реестр индивидуальных предпринимателей).** The Federal Tax Service (FNS) unified state registers for legal entities and individual entrepreneurs. EGRUL covers companies and organisations; EGRIP covers sole traders. Both are the authoritative primary source for Russian entity data, including legal name, address, identifiers, legal form, status, authorised representatives, shareholders, and branches.
Russia's company data is extracted from the official EGRUL/EGRIP register
extract, which is the authoritative document issued by the Federal Tax Service
(FNS). Company profile, legal representatives, shareholders, and
establishments are all sourced from this document. Processing is
asynchronous: typical wait time is under 2 minutes.
## Company Identifiers
### Query Identifiers
| Company Type | Identifier | Format | Example | Notes |
| - | - | - | - | - |
| **Legal entities** | OGRN | 13 digits, starting with 1 or 5; the last digit is a check digit | `1027700035769` | Primary state registration number |
| **Sole traders** | OGRNIP | 15 digits, starting with 3; the last digit is a check digit | `318028000064743` | Primary registration number for individual entrepreneurs |
| **All entities** | INN | 10 or 12 digits, leading zeros significant | `7708004767` | Tax identification number (10 for legal entities, 12 for individuals). Search returns the entity under its OGRN or OGRNIP |
**Which identifier to use:** OGRN and OGRNIP are unique per entity and are
the most reliable query identifiers. INN can also be used for search, but
note that legal entities have 10-digit INNs while individuals have 12-digit
INNs.
### Identifiers in API Response
| Identifier | Format | Example | Notes |
| - | - | - | - |
| `ogrn` | 13 digits, starting with 1 or 5 | `1027700035769` | Present for all legal entities |
| `ogrnip` | 15 digits, starting with 3 | `318028000064743` | Present for sole traders (ИП) |
| `inn` | 10 or 12 digits | `7708004767` | Present for all entities |
| `kpp` | 9 characters, usually all digits; the 5th and 6th may be uppercase Latin letters | `770801001` | Tax registration reason code; not all entities have one |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the legal-entity registration number (`ogrn`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By OGRN | 13 digits | `1027700035769` | Exact | Exact match returned first (matchType: id); other results may follow |
| By OGRNIP | 15 digits | `318028000064743` | Exact | Exact match returned first (matchType: id); other results may follow |
| By INN | 10 or 12 digits | `7708004767` | Exact | One or more results |
| By Name | Text string, 2-200 chars, Cyrillic or Latin | `"Лукойл"` | Fuzzy | Multiple results |
**Name search:** Queries containing only digits matching an OGRN, OGRNIP, or
INN pattern are treated as identifier searches and bypass the name search
flow. This avoids false matches for numeric strings.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Shareholders only for ООО** | Shareholder data (founders with share percentages and nominal values) is only available for ООО (limited liability companies). ПАО, АО, and ОАО (joint-stock companies) list only their share registrar in the register extract. Sole traders (ИП) have no shareholder concept. |
| **No personal addresses** | Russian law (Federal Law No. 152-FZ on Personal Data) prohibits personal residential addresses from appearing in public register extracts. Person data is limited to name, INN, role, gender, and citizenship. |
| **Sanctioned entity data restrictions** | Since 2022, some entities subject to international sanctions have restricted founder data in the register (marked ОгрДосСв). Shareholder and beneficial ownership data may be absent for these entities. |
| **Role titles are free text** | There is no closed list of authorised representative role titles. Companies define their own titles in their charter. Common titles ("Генеральный директор", "Директор") are mapped deterministically; uncommon titles are AI-enriched. |
| **Cyrillic data** | All data from EGRUL/EGRIP is in Russian (Cyrillic). Legal names, addresses, role titles, and activity descriptions are preserved verbatim. |
| **Processing time** | Company data is extracted asynchronously from the official register extract. Typical processing is under 2 minutes, but large companies with many branches may take longer. |
| **INN search may return multiple results** | Multiple entities can share the same INN in edge cases (e.g. reorganisations). Use OGRN for unambiguous lookups. |
## Mappings
### Company Status
Status is derived deterministically from whether the register records a termination date for the entity.
| Local Status | English Translation | Standardized Status | Notes |
| - | - | - | - |
| Действующее | Active | Active | Entity is currently registered |
| Прекращено | Terminated | Closed | Entity has a termination date in the register (liquidation, reorganisation, or end of sole trader activity) |
The distinction between liquidated, reorganised and in-liquidation entities is not currently exposed.
### Legal Forms
Russia uses the ОКОПФ classifier (OK 028-2012) with over 80 legal form codes. Legal form is detected deterministically from the full legal form written at the start of the company name (e.g. "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО", "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ") and mapped to standardized categories and ISO 20275 codes.
#### Commercial Companies
| Russian Name | Abbreviation | English Translation | Standardized | ELF Code |
| - | - | - | - | - |
| Публичное акционерное общество | ПАО | Public Joint-Stock Company | Corporation | `4TYO` |
| Акционерное общество | АО | Joint-Stock Company | Corporation | `JZBN` |
| Общество с ограниченной ответственностью | ООО | Limited Liability Company | Limited Liability Company | `17R7` |
#### Legacy Forms (pre-2014)
| Russian Name | Abbreviation | English Translation | Standardized | ELF Code |
| - | - | - | - | - |
| Открытое акционерное общество | ОАО | Open Joint-Stock Company | Corporation | `MT3A` |
| Закрытое акционерное общество | ЗАО | Closed Joint-Stock Company | Corporation | — |
#### Sole Traders
| Russian Name | Abbreviation | English Translation | Standardized | ELF Code |
| - | - | - | - | - |
| Индивидуальный предприниматель | ИП | Sole Proprietorship | Sole Proprietorship | `P9CF` |
#### Unitary Enterprises (State-Owned)
| Russian Name | Abbreviation | English Translation | Standardized | ELF Code |
| - | - | - | - | - |
| Федеральное государственное унитарное предприятие | ФГУП | Federal State Unitary Enterprise | Government-Owned Entity | `OCIS` |
| Государственное унитарное предприятие | ГУП | State Unitary Enterprise | Government-Owned Entity | `9RQZ` |
| Муниципальное унитарное предприятие | МУП | Municipal Unitary Enterprise | Government-Owned Entity | `Z3SH` |
#### Non-Commercial Organisations
| Russian Name | English Translation | Standardized | ELF Code |
| - | - | - | - |
| Фонд | Foundation | Nonprofit Organization | varies |
| Автономная некоммерческая организация | Autonomous Non-Commercial Organization | Nonprofit Organization | `1RJ2` |
| Ассоциация (Союз) | Association / Union | Nonprofit Organization | varies |
| Потребительский кооператив | Consumer Cooperative | Cooperative | varies |
| Производственный кооператив | Production Cooperative | Cooperative | `3EAX` |
Legal form mapping is deterministic, based on the legal form at the start of
the entity name (or in parentheses at the end of it). When no known form is
found, `legalForm` is omitted.
### Legal Representatives
Legal representatives are extracted from the register extract. The register lists the person or persons authorised to act on behalf of the entity without a power of attorney (typically the director or head), so an entity can have more than one. For a sole trader (ИП), the entrepreneur is returned as the single legal representative with the standardized role Owner.
| Russian Role | English Translation | Standardized Role |
| - | - | - |
| Генеральный директор | General Director | Chief Executive Officer |
| Директор | Director | Director |
| Президент | President | Chief Executive Officer |
| Управляющий | Manager | Director |
| Председатель | Chairman | Chairman of the Board |
| Председатель правления | Chairman of the Management Board | Chairman of the Board |
| Ректор | Rector | Director |
| Управляющий директор | Managing Director | Chief Executive Officer |
Role titles in the Russian register are free text defined by each company in its charter. The list above covers the most common titles. Uncommon titles are AI-enriched against ISO 5009 standardized role values.
The register records only the current authorised representatives. Historical representatives and board members are not available from EGRUL/EGRIP.
### Shareholders
Shareholder data is available only for ООО entities and is extracted from the register extract.
| Field | Description |
| - | - |
| Shareholder name | Legal name (for entities) or full name (for individuals) |
| INN | Tax ID of the shareholder |
| Nominal share value | Value in Russian roubles from the company's charter capital |
| Share percentage | Percentage of charter capital held |
For ПАО, АО, and ОАО, the register lists only the share registrar (реестродержатель), not individual shareholders. Full shareholder registers for joint-stock companies are held privately by the registrar.
### Activity Code Mapping
Russia uses ОКВЭД (Общероссийский классификатор видов экономической деятельности), whose classes are aligned with EU NACE Rev. 2.
| Classification | Source | Example | Notes |
| - | - | - | - |
| **ОКВЭД** | EGRUL/EGRIP extract | `46.90` | Official Russian activity code, kept in full |
| **NACE** | NACE Rev. 2.1 class transitioned from the ОКВЭД (Rev. 2) class | `46.90` | Deterministic mapping. The code can differ from the ОКВЭД code, because some classes were renumbered in Rev. 2.1 |
| **ISIC** | ISIC Rev. 5 correspondence of the NACE Rev. 2.1 class | `4690` | Deterministic mapping |
## Supported Entity Families
| Entity Family | Supported | Notes |
| - | - | - |
| Legal entities (юридические лица) | ✅ | All commercial and non-commercial forms |
| Sole traders (ИП) | ✅ | Individual entrepreneurs registered in EGRIP |
| State-owned enterprises | ✅ | ФГУП, ГУП, МУП |
| Non-commercial organisations | ✅ | Foundations, ANOs, associations, cooperatives |
| Closed / dissolved entities | ✅ | Liquidated, reorganised, and ceased entities |
## Data Availability
### Data Availability Matrix
| Data Type | Availability | Notes |
| - | - | - |
| Company Profile | ✅ Async | Under 2 min typical |
| Prefill Profile | ❌ | Not available: Russia is served in verification mode only |
| Legal Representatives | ✅ Async | Persons authorised to act without a power of attorney; the entrepreneur for ИП |
| Shareholders | ⚠️ Async | ООО only. Not available for ПАО, АО, OАО, or ИП. |
| Ultimate Beneficial Owners | ❌ | Not available from EGRUL/EGRIP |
| Establishments | ✅ Async | Branches and representative offices |
| Activity Codes | ✅ | ОКВЭД (primary), NACE and ISIC derived deterministically |
| Employee Count | ❌ | Not available from EGRUL/EGRIP |
| Personal Addresses | ❌ | Not included in public register data |
| Share Capital | ✅ | Charter capital amount and currency |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous (under 2 min typical)
### Documents
| Document | API Category | Format | Notes |
| - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | Official EGRUL/EGRIP extract issued by the Federal Tax Service. In Russian (Cyrillic). Also the source for structured company data. |
### Example API Responses
All examples use placeholder data. Query: `POST /v2/company` with `{ "id": "", "countryCode": "RU", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "1027700035769",
"countryCode": "RU",
"identifiers": {
"ogrn": "1027700035769",
"inn": "7708004767",
"kpp": "770801001"
},
"legalName": "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО «НЕФТЯНАЯ КОМПАНИЯ»",
"registrationDate": "1993-04-22",
"status": {
"localName": "Действующее",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Публичное акционерное общество",
"englishTranslation": "Public Joint-Stock Company",
"standardized": "Corporation",
"iso20275Code": "4TYO"
},
"capital": { "amount": 21264081, "currency": "RUB" },
"activities": {
"OKVED_REV2": [{ "code": "06.10", "description": "Добыча сырой нефти" }],
"NACE": [{ "code": "06.10", "description": "Extraction of crude petroleum", "isAIInferred": false }],
"ISIC": [{ "code": "0610", "description": "Extraction of crude petroleum", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "101000, г. Москва, Сретенский бульвар, д. 11",
"city": "Москва",
"postalCode": "101000",
"countryCode": "RU"
}
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": {
"localName": "Президент",
"englishTranslation": "President",
"standardized": "Chief Executive Officer"
},
"individual": {
"name": {
"fullName": "ИВАНОВ ИВАН ИВАНОВИЧ",
"firstName": "ИВАН",
"lastName": "ИВАНОВ"
},
"nationality": "RU"
}
}
]
}
```
**Note:** ПАО does not include shareholder data. The register lists only the share registrar.
```json theme={null}
{
"company": {
"id": "1027721527560",
"countryCode": "RU",
"identifiers": {
"ogrn": "1027721527560",
"inn": "7721546864",
"kpp": "772101001"
},
"legalName": "ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ «КОМПАНИЯ»",
"registrationDate": "2004-11-01",
"status": {
"localName": "Действующее",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Общество с ограниченной ответственностью",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "17R7"
},
"capital": { "amount": 10000000, "currency": "RUB" },
"legalAddress": {
"addressLine1": "143003, Московская область, г. Одинцово, ул. Можайское шоссе, д. 165",
"city": "Одинцово",
"postalCode": "143003",
"countryCode": "RU"
}
},
"legalRepresentatives": [
{
"type": "individual",
"entityId": "person_001",
"role": {
"localName": "Генеральный директор",
"englishTranslation": "General Director",
"standardized": "Chief Executive Officer"
},
"individual": {
"name": {
"fullName": "ПЕТРОВА АННА СЕРГЕЕВНА",
"firstName": "АННА",
"lastName": "ПЕТРОВА"
},
"nationality": "RU"
}
}
],
"shareholders": [
{
"type": "individual",
"entityId": "person_002",
"individual": {
"name": {
"fullName": "КИМ ТАТЬЯНА ВЛАДИМИРОВНА",
"firstName": "ТАТЬЯНА",
"lastName": "КИМ"
}
},
"sharePercentage": 100,
"nominalCapitalHeld": { "amount": 10000000, "currency": "RUB" }
}
]
}
```
**Note:** Shareholders with name, INN, share percentage, and nominal value are available for ООО entities.
```json theme={null}
{
"company": {
"id": "318028000064743",
"countryCode": "RU",
"identifiers": {
"ogrnip": "318028000064743",
"inn": "280112515730"
},
"legalName": "ИНДИВИДУАЛЬНЫЙ ПРЕДПРИНИМАТЕЛЬ СИДОРОВ АЛЕКСЕЙ ПЕТРОВИЧ",
"registrationDate": "2018-03-15",
"status": {
"localName": "Прекращено",
"active": false,
"statusDetails": { "status": "CLOSED" }
},
"legalForm": {
"localName": "Индивидуальный предприниматель",
"englishTranslation": "Sole Proprietorship",
"standardized": "Sole Proprietorship",
"iso20275Code": "P9CF"
},
"legalAddress": {
"addressLine1": "675000, Амурская область, г. Благовещенск",
"countryCode": "RU"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Индивидуальный предприниматель",
"standardized": "Owner"
},
"individual": {
"name": {
"fullName": "СИДОРОВ АЛЕКСЕЙ ПЕТРОВИЧ"
}
}
}
]
}
```
**Note:** The entrepreneur is returned as the single legal representative. Sole traders (ИП) have no share capital, so `shareholders` is not applicable.
Query with `"dataPoints": ["availableDocuments"]`:
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc-uuid-001",
"name": "Trade Register Extract",
"format": "pdf",
"description": "Official extract from EGRUL/EGRIP issued by the Russian Federal Tax Service (FNS). In Russian."
}
}
}
```
# Company Search
Source: https://docs.topograph.co/essentials/search
Find companies and display search results progressively with Server-Sent Events
Search is the entry point to Topograph. Before you can retrieve company data, download documents, or set up monitoring, you need the company's unique identifier. Search gives you that identifier.
For endpoint details, request/response schemas, and code examples, see the [Search API Reference](/api-reference/search/search-for-companies).
## Why Search Matters
Every Topograph integration starts with a company ID:
* **Prefill**: Pass the ID to [`POST /v2/company`](/essentials/retrieve_company) with `mode: "prefill"` to prefill customer forms ([modes](/essentials/modes))
* **Verification**: Pass the ID to [`/v2/company`](/essentials/retrieve_company) to fetch authoritative register data
* **Documents**: Use the ID to retrieve official PDFs from public registers
* **Monitoring**: Use the ID to [track changes](/essentials/monitoring) over time
Search is how you get that ID. It's free, fast, and designed to handle the complexity of finding companies across different countries with different identifier formats.
## How Search Works
Topograph combines multiple data sources to give you the best possible results:
### Live register search
Topograph searches official company registers directly. Each register determines which names and identifiers it supports and how it matches your query. Some support fuzzy matching; others require an exact match.
### Indexed search
In supported countries, an index of company data provides fast results and supports partial names and spelling variations. Recently registered companies or recent changes may appear in the live register before they appear in the index.
When several sources are available, Topograph searches them in parallel and combines their results. This can include more than one live register. Each source has its own response time.
A standard request waits for the search to finish and returns a JSON array. Streaming lets you display the results already found while the other sources continue searching.
## Streaming search
Add `stream=true` to `GET /v2/search`. The response uses **Server-Sent Events (SSE)** with a `Content-Type` of `text/event-stream`, instead of a single JSON response.
Use streaming for an autocomplete or company picker. Users can select a company as soon as it appears, without waiting for the slowest source. Streaming changes when you receive results; it does not make an individual source faster.
### Try it with cURL
Replace `` with your API key. `--no-buffer` prints each event as it arrives.
```bash theme={null}
curl --no-buffer --get 'https://api.topograph.co/v2/search' \
--header 'x-api-key: ' \
--header 'Accept: text/event-stream' \
--data-urlencode 'country=DE' \
--data-urlencode 'query=Siemens' \
--data-urlencode 'stream=true'
```
### Events and result updates
Each event has an `event:` line and a JSON `data:` payload, followed by a blank line. These are named events, so a client must handle `progress`, `complete`, and `error` explicitly.
| Event | Payload | What your application should do |
| - | - | - |
| `progress` | `{ "results": [...] }` | Display the current results and keep the loading indicator active. |
| `complete` | `{ "results": [...] }` | Display the final results and stop loading. An empty array means no matches were found. |
| `error` | `{ "error": { "code": "...", "message": "..." } }` | Stop loading and show a retry option. Previously received results are not a completed search. |
**Every `results` array is the full result list so far, not a batch of new items.** Replace your displayed list on each `progress` or `complete` event. Appending each array would create duplicate entries. Use the combination of `countryCode` and `id` as a stable item key; result order can change as more sources respond.
For example, a stream could look like this (illustrative company data):
```text theme={null}
event: progress
data: {"results":[{"id":"example-1","legalName":"Example Company A","countryCode":"DE"}]}
event: complete
data: {"results":[{"id":"example-1","legalName":"Example Company A","countryCode":"DE"},{"id":"example-2","legalName":"Example Company B","countryCode":"DE"}]}
```
Do not expect one event per source or any fixed number of `progress` events. A search may emit `complete` directly. Always process its results, even if no earlier event arrived.
### Node.js example
This server-side example uses Node.js 22 or later and its built-in `fetch`. It reads complete SSE events even when a network chunk splits a line or contains several events. The callback receives each current result list and whether the search is complete.
Keep your Topograph API key on your server. For a browser interface, call your own backend and forward the result updates to the browser. Do not put the API key in frontend code or a query string.
```javascript theme={null}
import { createInterface } from 'node:readline';
import { Readable } from 'node:stream';
async function streamCompanySearch({ country, query, apiKey, signal, onResults }) {
const url = new URL('https://api.topograph.co/v2/search');
url.search = new URLSearchParams({ country, query, stream: 'true' }).toString();
const response = await fetch(url, {
headers: { 'x-api-key': apiKey, Accept: 'text/event-stream' },
signal,
});
if (!response.ok) throw new Error(`Search HTTP error: ${response.status}`);
if (!response.body) throw new Error('Search response has no body');
if (!response.headers.get('content-type')?.includes('text/event-stream')) {
await response.body.cancel();
throw new Error('Expected a text/event-stream response');
}
const input = Readable.fromWeb(response.body);
const lines = createInterface({ input, crlfDelay: Infinity });
let event = '';
let data = [];
try {
for await (const line of lines) {
if (line === '') {
const eventType = event;
const payloadText = data.join('\n');
event = '';
data = [];
if (!payloadText) continue;
if (eventType === 'progress' || eventType === 'complete') {
const payload = JSON.parse(payloadText);
onResults(payload.results, eventType === 'complete');
if (eventType === 'complete') return;
} else if (eventType === 'error') {
const payload = JSON.parse(payloadText);
throw new Error(`${payload.error.code}: ${payload.error.message}`);
}
} else if (line.startsWith('event:')) {
event = line.slice(6).trim();
} else if (line.startsWith('data:')) {
data.push(line.slice(5).replace(/^ /, ''));
}
}
throw new Error('Search connection closed before a terminal event');
} finally {
lines.close();
input.destroy();
}
}
const controller = new AbortController();
// Call controller.abort() when this query is no longer needed.
try {
await streamCompanySearch({
country: 'DE',
query: 'Siemens',
apiKey: '',
signal: controller.signal,
onResults(results, complete) {
// Replace your stored/displayed list with results; do not append it.
console.log({ results, loading: !complete });
},
});
} catch (error) {
if (!controller.signal.aborted) console.error(error);
}
```
If you use Axios on Node.js, set `responseType: 'stream'` and pass `response.data` to `createInterface` as the input stream. The same SSE event handling applies. Reading the response as JSON, or buffering the full response before parsing it, prevents progressive display.
### Connect it to your interface
* Debounce typing before starting a request. When the query or country changes, cancel the previous connection and ignore any late updates from the old query.
* On each `progress`, replace the displayed list and keep a loading indicator for the remaining results. Let users select a result immediately.
* On `complete`, replace the list one last time and stop loading. Show “No companies found” only if that final list is empty.
* On an SSE `error`, a failed HTTP response, or a connection closing without `complete` or `error`, stop loading and offer a retry. You may keep earlier results visible, but mark the search as incomplete.
* Once the user selects a company, preserve its `id` and `countryCode` for the [company data request](/essentials/retrieve_company). Cancel the search connection if you no longer need updates.
* If your backend forwards the stream, disable response buffering on that route and any intervening proxy. Otherwise, the browser may receive all events together at the end.
A streaming search can remain open for several minutes; see [timeouts](#country-considerations). Receiving no immediate event does not mean there are no matches. Streaming search also does not apply the [`transliterate` option](/essentials/transliteration).
Search streaming and prefill mode are separate options. `stream=true` controls delivery from `GET /v2/search`; `mode: "prefill"` controls data retrieval from `POST /v2/company`. The prefill deadline does not apply to search.
Document lists can also arrive progressively, through webhooks or polling rather than this search SSE endpoint. See [progressive document delivery](/essentials/document-guide#progressive-delivery).
## Understanding Results
### Match Types
Every result includes a `matchReason` that explains how it was found. This helps you assess result quality and build appropriate logic around different confidence levels.
| Match Type | Meaning | Reliability |
| - | - | - |
| `id` | Exact match on a unique identifier (VAT, registration number, etc.) | Guaranteed correct |
| `exactLegalName` | Legal name exactly matches your query | Very high |
| `partialId` | Matched on a partial identifier that isn't globally unique | High, but verify |
| `default` | Generic match from registry search | Depends on registry |
**When `matchType` is `id` or `partialId`**, the response includes an `identifier` field showing exactly what matched (e.g., `{ "VAT": "02580590541" }` or `{ "CCIAA": "TO", "REA Code": "1234567" }`).
**When `matchType` is `default`**, the result came from the registry's own search algorithm. Quality varies significantly: some registries return highly relevant results, others may include tangential matches. Consider `default` results as suggestions that benefit from user confirmation.
Results with `matchType: "default"` depend entirely on the underlying registry's search quality. Always verify these matches when precision matters, especially for automated processing.
### Result Ordering
Results are automatically sorted by match reliability:
1. **`id`**: Guaranteed matches appear first
2. **`exactLegalName`**: Exact name matches second
3. **`partialId`**: Partial identifier matches third
4. **`default`**: Generic matches last
This ordering ensures the most trustworthy results appear at the top. When building UIs, consider visually distinguishing high-confidence matches from `default` matches to help users make informed selections.
### Active companies only
Add `activeOnly=true` to `GET /v2/search` to leave out companies the register reports as no longer active: dissolved, struck off, deregistered or closed.
```bash theme={null}
curl --get 'https://api.topograph.co/v2/search' \
--header 'x-api-key: YOUR_API_KEY' \
--data-urlencode 'country=DE' \
--data-urlencode 'query=Topograph' \
--data-urlencode 'activeOnly=true'
```
The filter only removes what a register positively reports as inactive. When a search source returns a company without any status, the company is kept rather than hidden, so a result is not proof that the company is active: read `company.status` on [`POST /v2/company`](/guides/company-status) before relying on it.
How much the filter can do depends on the country: each country guide has an **Active companies only** paragraph under its search section, and each country's entry in the [catalog](/api-reference) carries the same information as a `search` object:
| Field | Meaning |
| - | - |
| `returnsInactiveCompanies` | Whether search can return companies that are no longer active at all. |
| `activeFilter` | `register`: the register itself excludes inactive companies. `results`: every result carries a status and inactive ones are removed. `partial`: some query shapes or sources carry a status, the rest are not filtered (see `note`). `notNeeded`: search only returns active companies. `unsupported`: inactive companies can appear, but no status is known at search time, so the flag has no effect. |
| `note` | Country-specific caveats, when there are any. |
Set `strictActiveOnly=true` to also exclude companies whose search status is unknown. It implies `activeOnly=true` and returns only results explicitly reported as active. The status can come from a periodic snapshot; use the company endpoint when you need a current verification.
The worldwide search accepts the same `strictActiveOnly` option. Both Topograph MCP search tools expose it as `strict_active_only`.
There is no filter for inactive companies only. Without `activeOnly`, search results are not filtered on status.
## Search by LEI
A Legal Entity Identifier (LEI) works as a query in every country. Send the 20-character LEI and the search returns the company it designates, under the registration number you pass to [`/v2/company`](/essentials/retrieve_company).
```bash theme={null}
curl --get 'https://api.topograph.co/v2/search' \
--header 'x-api-key: YOUR_API_KEY' \
--data-urlencode 'country=FR' \
--data-urlencode 'query=96950066U5XAAIRCPA78'
```
```json theme={null}
[
{
"id": "421100645",
"legalName": "LA BANQUE POSTALE",
"countryCode": "FR",
"matchReason": { "matchType": "id", "identifier": { "siren": "421100645" } }
}
]
```
An LEI search returns that company or nothing. It never returns companies with a similar name, so there is no list to choose from.
| Result | Meaning |
| - | - |
| `matchType: "id"` | The register returned the company under the registration number published for this LEI. |
| `matchType: "exactLegalName"` | No registration number is published for this LEI in that register (common for funds), and the register holds a company under the LEI's legal name. Confirm it before automated processing. |
| Empty list | The entity is in no company register Topograph covers, its country is not covered, or the LEI does not exist or was annulled. |
The LEI decides where the company is registered. With `country=FR` and the LEI of a German company, the result is the German company, with `countryCode: "DE"`. Read `countryCode` from the result, not from your request.
An LEI is not always held by a company. Many funds, pension schemes, trusts and civil partnerships have one but appear in no company register, so searching their LEI returns an empty list. That is the expected answer, not a failure.
LEI records come from GLEIF, the organisation that publishes every LEI, and are refreshed daily. An LEI issued today can take a day to become searchable. Only entities that applied for an LEI have one: most large companies, banks and funds do, most small companies do not.
## Searching Effectively
### Search by Identifier When Possible
If you have a company's VAT number, registration number, tax code or [LEI](#search-by-lei), search with that. Identifier searches return `id` match types, guaranteed 1:1 matches with no ambiguity. This is always the most reliable approach.
### Scope by Country
Always specify the country. Country-scoped searches are faster and return more relevant results. If you're building an onboarding flow, you likely already know the customer's country from earlier in your form.
### Handle Ambiguous Results
When your search returns multiple results with `default` match types, present them to the user for selection rather than auto-selecting. The first result isn't always the right one, and registries don't always order by relevance.
### Use Streaming for Interactive UIs
Use [streaming search](#streaming-search) to display results as they arrive. Users can select a company while other sources are still responding.
## Search in the KYB Flow
Search is the critical first step in a typical KYB onboarding flow:
```mermaid theme={null}
flowchart LR
Search[Search] --> Onboard[Onboard]
Onboard --> Verify[Verify]
Verify --> Monitor[Monitor]
```
1. **Search**: Customer finds their company, you capture the ID
2. **Onboard**: Use the ID with [`POST /v2/company`](/essentials/retrieve_company) and [`mode: "prefill"`](/essentials/modes) to prefill forms quickly (10-second deadline per datapoint)
3. **Verify**: Use the ID with [`/v2/company`](/essentials/retrieve_company) to fetch authoritative register data
4. **Monitor**: Use the ID to [track changes](/essentials/monitoring) and stay compliant
Use the first relevant result to move the customer into the next step. Completion time depends on the sources queried for that country.
## No country? Use global search
Every `/v2/search` call needs a country. When you only have a name (a shareholder listed in a foreign filing, a counterparty on an invoice), send it to `POST /v2/search/global` with anything else you know, in one line of text: `"Bamberger GmbH, Wien"`. It returns ranked candidates across every country Topograph covers, each with its country, registration number and an explanation.
Each US state is its own register, so an American company needs its state. To search every state at once, send `"countries": ["US"]` to global search: it finds the state and searches nothing outside the United States.
How to send what you know, read the answer, and stream the search as it runs.
## Fair Use
Search is free under a fair use policy, proportional to the company lookups it leads to. It's the resolution layer that gives you the ID you pass to [`/v2/company`](/essentials/retrieve_company), so search volume is expected to track the company data you go on to retrieve.
Typeahead is exactly what search is built for. Search accepts partial names and identifiers (a 2-character minimum applies), so you can wire it straight into an autocomplete. Debounce on the client so you send a request when the user pauses typing rather than on every keystroke, and use [streaming mode](#streaming-search) for instant feedback.
What sits outside fair use is using search as a standalone database: high-volume exploratory querying that rarely converts into a company lookup, or enumerating a register to harvest its index. Those patterns may be rate-limited. If you expect very high search throughput, [get in touch](mailto:support@topograph.co) so we can size limits to your flow.
Learn how to combine search with prefill and verification endpoints to build high-conversion KYB flows.
## Country Considerations
Search capabilities vary by country due to differences in registry APIs and data availability:
| Capability | Description |
| - | - |
| **Name search** | Most countries support searching by company name |
| **ID search** | Most countries support searching by registration number or VAT |
| **LEI search** | Every country. See [Search by LEI](#search-by-lei) |
| **Fuzzy matching** | Varies by registry. Some handle typos well, others require exact matches |
| **Response time** | Usually under 2 seconds when results come from a search index. Countries queried live are slower, and some can take 30 seconds or more |
Countries with fast search indexes generally offer faster responses and better fuzzy matching. For detailed country-specific information, browse [Country Guides](https://www.topograph.co/countries/at).
**Allow at least 30 seconds when setting a client-side timeout.** Search returns
once every source for that country has answered, and a country queried live
against its register can take considerably longer than one served from a search
index. The figures above are typical, not guaranteed. A standard search that
runs past about 110 seconds returns `503` with the error code `search_timeout`,
so a client timeout above that never cuts off an answer. A streaming search ends
with an `error` event after 3 minutes.
If your flow cannot wait that long, use [streaming
mode](#streaming-search) and act on results as they
arrive. The first results usually land in about a second, so you can proceed
without waiting for the slowest source.
Company ID formats vary by country. German IDs combine register and city (e.g., "Augsburg HRB 34617"). French IDs are SIREN numbers (9 digits). Italian searches can use VAT, Codice Fiscale, or CCIAA+REA combinations. The ID returned by search is always the correct format to use with other Topograph endpoints.
## Best Practices
* Search by identifier (VAT, registration number) whenever available
* Only trust `id` match types for fully automated processing
* Filter by match type and queue `default` matches for manual review
* Store the company IDs you retrieve for future API calls
* Use streaming mode for instant feedback as results arrive
* Display match type indicators to help users assess result confidence
* Show the matched identifier (VAT, registration number) when available
* Let users confirm their selection rather than auto-selecting ambiguous matches
* Consider showing a "Verified" badge for `id` matches
* Prefer identifier-based searches for maximum reliability
* Stored source data company IDs from search results for subsequent API calls
* Set strict match type requirements, only process `id` matches automatically
* Handle lower-confidence matches in a separate review queue
## Next Steps
Once you have a company ID from search, you're ready to retrieve data:
Verification vs prefill (`mode`) for the same `/v2/company` endpoint
Authoritative data fetched directly from public registers
Complete endpoint documentation with request/response schemas
Country-level details on search capabilities and identifier formats
# Serbia
Source: https://docs.topograph.co/essentials/serbia
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Serbia reference is on the [Serbia country page](https://www.topograph.co/countries/rs).
## Start here
This guide contains public integration notes for Serbia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Serbia uses a single official registry for all entity types. All structured company attributes come exclusively from APR.
* **APR (Agencija za privredne registre)** -- Serbian Business Registers Agency, established in 2005. Maintains registers for commercial companies, sole traders, associations, foundations, and institutions. This is the **primary (and only) source** for all company profile data.
* **APR open-data companies file**: a monthly file APR publishes with every registered company's name, legal form, status, founding date, main activity and municipality. It backs [prefill mode](#prefill-mode) and speeds up search. It lists companies only: entrepreneurs, associations and foundations are not in it.
* **APR Financial Statements Register (fin.apr.gov.rs)** -- A separate APR portal for annual financial reports. Used exclusively for **financial document retrieval**. Not a structured data source for company attributes.
* **CESV (Centralna evidencija stvarnih vlasnika)**: the Central Register of Beneficial Owners, operated by APR. Source of the beneficial ownership certificate and the `ultimateBeneficialOwners` datapoint, both ordered on request.
### Entity Routing
APR organises entities into separate sub-registers. The routing is determined automatically from the entity type returned by the register:
| Entity Category | Entity Types |
| - | - |
| Commercial entities | DOO, AD, OD, KD, JP, Задруга, Огранак, Представништво |
| Sole traders | Предузетник |
| Associations | Удружење, Спортско удружење |
| Foundations & endowments | Фондација, Задужбина |
| Institutions | Установа |
Data comes from a **single source** -- there is no fallback chain and no cross-registry merging.
### Prefill mode
`mode: "prefill"` returns the `company` datapoint from APR's monthly open-data companies file, in milliseconds instead of a live register query. It includes the legal name, registration number, legal form, status, founding date, main activity code and municipality. The file has no street address, tax number (PIB), officers or owners, so `legalRepresentatives`, `shareholders`, `otherKeyPersons` and `establishments` are available in verification mode only.
Prefill mode is **not authoritative**: the file is published monthly, so a change made since the last publication is not reflected yet. Use verification mode, the default, when you need the current register position.
The file covers **companies only**. For an entrepreneur (Предузетник), an association, a foundation or an institution, prefill mode returns `datapoint_not_applicable` with a message to retry without prefill mode. The same answer comes back for a company registered since the last monthly publication. Verification mode queries APR live and covers every entity type. A `datapoint_not_applicable` answer is not charged.
## Company Identifiers
### Query Identifiers
| Format | Example | Name | Notes |
| - | - | - | - |
| 8 digits (MBR), leading zeros significant | `21837792`, `07018835` | Matični broj registracije | Primary company registration number |
The PIB (Poreski identifikacioni broj, 9-digit tax number) is returned as `taxNumber` in the response, but it cannot be used to search for or look up a company.
### Identifiers in API Response
| Identifier | Format | Example | Coverage |
| - | - | - | - |
| `mbr` | 8 digits, leading zeros significant | `21837792` | All entities |
| `taxNumber` | 9 digits, the last a check digit (ISO 7064 MOD 11,10) | `113279163` | \~90% of entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the registration number (`mbr`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By MBR | 8 digits, with leading zeros | `21837792` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text (min 2 chars) | `"BOLT TEAM"` | Fuzzy | Multiple results |
A search by MBR is answered from APR's open-data companies file when the company is in it, and from the live register otherwise (entrepreneurs, associations, foundations, and companies registered since the last monthly publication).
Name searches combine companies from the open-data file, returned first, with a live APR search that also covers entrepreneurs, associations and foundations. Company names written in Cyrillic also match their Latin spelling, so `Đerdap` finds `ЂЕРДАП`. Live results are ordered by register relevance, so the first result is not always the target company. If you know the MBR, use it for reliable exact matching.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Rate limiting** | APR enforces rate limits on detail data retrieval. Requests that hit the limit are retried automatically with a backoff. Avoid querying the same company repeatedly in quick succession. |
| **Pre-2000 company gaps** | Companies registered before 2000 may return partial data due to APR migration issues. Some detail sections may be unavailable. |
| **Cyrillic names** | APR stores all names in Cyrillic script. Names and addresses appear in Cyrillic in the API response. Transliteration is not provided. |
| **No prefill / fast mode** | Serbia does not support a fast retrieval path. All profile requests use the full authoritative fetch (\~1-2 minutes). |
| **Sole trader (Предузетник)** | The owner is the business. The owner is returned in `legalRepresentatives` (role `Предузетник`, standardized `Owner`), and `shareholders` returns a `datapoint_not_applicable` error. |
| **Foundation section set** | Foundations and endowments (Фондација, Задужбина) have reduced data: no share capital. The representative is returned in `legalRepresentatives` and the founders the register publishes are returned in `shareholders`. |
| **Founding documents are scans** | Corporate founding documents (Articles of Association, statutes, amendments) are delivered as PDF, but they are scanned images, so their text is not selectable. Text extraction requires OCR. |
| **Financial statements availability** | Only entities required to file financial statements with APR have data in fin.apr.gov.rs. Foundations and some smaller entities will return no financial statements. |
| **ISIC sometimes AI-inferred** | The KD 2010 to NACE Rev. 2.1 conversion is deterministic. NACE Rev. 2.1 to ISIC Rev. 5 uses formal tables, falling back to AI. |
## Mappings
### Company Status
Status is derived **deterministically** from the APR status field. No AI inference is involved.
| APR Status | English | Standardized Status |
| - | - | - |
| Активно / Активан | Active | Active |
| Обрисано | Deleted | Closed |
| У поступку ликвидације | In liquidation | Closed |
| У поступку стечаја | In bankruptcy | Closed |
| У принудној ликвидацији | In forced liquidation | Closed |
`Активно` is used for commercial entities; foundations and some other entity types use the masculine form `Активан`. Both map to `Active`.
### Legal Forms
Legal form comes from the legal form APR records for the entity. Values listed in the tables below are mapped via a static lookup. Any other value is resolved by AI enrichment. The original Serbian name is always preserved in `localName`.
#### Commercial entities
| Local Name | English | Abbreviation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Друштво са ограниченом одговорношћу | Limited Liability Company | DOO / д.о.о. | Limited Liability Company | `KIU5` |
| Акционарско друштво | Joint Stock Company | AD / а.д. | Corporation | `YVPW` |
| Отворено акционарско друштво | Open Joint Stock Company | AD | Corporation | - |
| Ортачко друштво | General Partnership | OD / о.д. | Partnership | `ZPOY` |
| Командитно друштво | Limited Partnership | KD / к.д. | Partnership | `73PZ` |
| Јавно предузеће | Public Enterprise | JP / ЈП | Government-Owned Entity | `DEF6` |
#### Sole proprietorships
| Local Name | English | Abbreviation | Standardized | ISO 20275 |
| - | - | - | - | - |
| Предузетник | Sole Trader / Entrepreneur | PR / ПР | Sole Proprietorship | `9O67` |
#### Cooperatives
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Задруга | Cooperative | Cooperative | `E7W8` |
| Задружни савез | Cooperative Union | Cooperative | `6UPM` |
#### Non-profits and endowments
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Удружење | Association | Nonprofit Organization | - |
| Спортско удружење | Sports Association | Nonprofit Organization | - |
| Фондација | Foundation | Nonprofit Organization | - |
| Задужбина са општекорисним циљем | Charitable Foundation | Nonprofit Organization | - |
| Задужбина са приватним циљем | Private Endowment | Nonprofit Organization | - |
#### Institutions
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Установа | Institution / Establishment | Other | - |
| Установа културе у приватној својини | Cultural Institution (Private) | Other | - |
| Установа културе у државној својини | Cultural Institution (State) | Other | - |
#### Foreign entity presence
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Представништво страног правног лица | Representative Office of a Foreign Legal Entity | Branch or Representative Office | - |
| Огранак страног правног лица | Branch of a Foreign Legal Entity | Branch or Representative Office | - |
| Огранак страног привредног друштва | Branch of a Foreign Commercial Company | Branch or Representative Office | - |
#### Legacy
| Local Name | English | Standardized | ISO 20275 |
| - | - | - | - |
| Друштвено предузеће | Socially-Owned Enterprise | Other | `88TX` |
APR also registers entities with type **Комора** (Chamber, e.g. Privredna komora Srbije). APR records no legal form for chambers, so the API response returns no legal form for these entities. They are functionally similar to associations but APR treats them as a distinct entity type.
### Legal Representatives
The source sections vary by entity type:
* **Commercial entities** (DOO, AD, OD, KD, JP, cooperatives): statutory representatives, other representatives, and procurists (authorized signatories with powers of attorney).
* **Associations** (Удружење) and **institutions** (Установа): representatives only. No procurists.
* **Foundations and endowments** (Фондација, Задужбина): the foundation's representative. No procurists.
* **Sole traders** (Предузетник): the owner, with role `Предузетник` (standardized `Owner`), including JMBG, birth date and gender when APR publishes them (see Quirks).
The role-name mappings below apply across all entity types.
| APR Role Name | English | Standardized |
| - | - | - |
| Директор | Director | Managing Director |
| Генерални директор | General Director / CEO | Chief Executive Officer |
| Извршни директор | Executive Director | Executive Director |
| Председник извршног одбора | Chairman of the Executive Board | Chief Executive Officer |
| Председник | Chairman / President | Chairman |
| Пословодилац | Managing Director (Cooperative) | Managing Director |
| Заступник | Authorized Representative | Authorized Signatory |
| Прокуриста | Prokurista (Authorized Signatory) | Authorized Signatory |
| Ликвидациони управник | Liquidator | Liquidator |
| Стечајни управник | Bankruptcy Trustee / Receiver | Receiver |
| Остали заступник | Other Representative | Other |
Each legal representative includes name (first + last), birth date, gender, JMBG (13-digit Serbian national ID), and representation mode (`sole` or `joint`). Legal representatives are always returned as individuals.
Unknown role values fall back to AI enrichment. The original APR role name is always preserved in `localName`.
### Other Key Persons
Board members appear in `otherKeyPersons`. Three board types are covered:
Known board offices use fixed role values for members, chairs and vice-chairs. The original position is preserved in `localName`. The representative section establishes the representation context; a supervisory or management-board seat alone does not grant individual signing capacity. This is a known source vocabulary, with unlisted titles preserved.
**Supervisory Board (Надзорни одбор)** -- joint stock companies (AD):
| APR Role Name | English | Standardized |
| - | - | - |
| Члан надзорног одбора | Supervisory Board Member | Supervisory Board Member |
| Председник надзорног одбора | Chairman of the Supervisory Board | Chairman of the Board |
**Executive Board (Извршни одбор)** -- joint stock companies (AD):
| APR Role Name | English | Standardized |
| - | - | - |
| Члан извршног одбора | Executive Board Member | Board Member |
| Председник извршног одбора | Chairman of the Executive Board | Chairman of the Board |
**Board of Directors (Управни одбор)** -- foundations and institutions (associations return no board members):
| APR Role Name | English | Standardized |
| - | - | - |
| Председник управног одбора | Chairman of the Board of Directors | Chairman of the Board |
| Члан управног одбора | Board of Directors Member | Board Member |
| Члан органа управе | Governance Organ Member | Board Member |
### Shareholders
Shareholders come from the members and founders APR publishes for the entity.
**Available for**: commercial companies (DOO, AD, OD, KD, JP, Задруга), including state-owned enterprises. Foundations, endowments and institutions return the founders the register publishes.
**Not applicable for**: sole traders (Предузетник) and associations (Удружење, Спортско удружење). They have no share capital, so `shareholders` returns a `datapoint_not_applicable` error instead of an empty list.
Each shareholder entry includes:
* `sharePercentage` -- ownership percentage (e.g. `100.0`)
* `nominalCapitalHeld` -- subscribed ("Уписан") capital in RSD
* `paidInAmount` -- paid-in ("Уплаћен") capital in RSD
* For individuals: name, JMBG, gender, residence address (city, region)
* For corporate shareholders: legal name, MBR (if a domestic Serbian company)
For public enterprises (Јавно предузеће), the state (Република Србија) appears as a shareholder with role "Оснивач" (Founder) and 100% ownership. The state's APR registration code is `07020171`.
Cooperative members (Задругари) appear in shareholders without a share percentage. Each entry shows the paid-in capital amount only.
### Activity Code Mapping
APR provides a KD 2010 code (e.g., `6201`) for each entity. KD 2010 is the Serbian national classification and is equivalent to NACE Rev. 2. The mapping pipeline:
1. APR provides the 4-digit KD 2010 code + Serbian description
2. The KD 2010 code is read as NACE Rev. 2 (e.g., `6201` → `62.01`) and converted to NACE Rev. 2.1 (`62.10`), which is what `NACE` carries
3. ISIC Rev. 5 is derived from the NACE Rev. 2.1 code (`621`)
See [Activity Codes](/essentials/activity-codes) for how the conversion works.
The single code APR publishes is the entity's prevailing activity (претежна делатност), so the NACE code carries `isMainActivity: true` and the ISIC code derived from it inherits the flag.
When APR provides only a description without a code, AI inference is used to determine the NACE classification (no `isMainActivity` flag in that case).
## Data Availability
### Data Availability Matrix
| Datapoint | DOO / AD / JP | OD / KD | Предузетник | Удружење | Фондација |
| - | - | - | - | - | - |
| Legal name | ✓ | ✓ | ✓ | ✓ | ✓ |
| Status | ✓ | ✓ | ✓ | ✓ | ✓ |
| Legal form | ✓ | ✓ | ✓ | ✓ | ✓ |
| Registration date | ✓ | ✓ | ✓ | ✓ | ✓ |
| Registered address | ✓ | ✓ | ✓ | - | - |
| Tax number (PIB) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Share capital | ✓ | ✓ | - | - | - |
| Activity code (NACE) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Legal representatives | ✓ | ✓ | ✓ (owner) | ✓ | ✓ |
| Procurists | ✓ | ✓ | - | - | - |
| Shareholders | ✓ | ✓ | Not applicable | Not applicable | ✓ (founders) |
| Supervisory board (AD only) | AD only | - | - | - | - |
| Board of directors | - | - | - | - | ✓ |
| Establishments (branches) | ✓ | - | - | - | - |
| Trade register extract | ✓ | ✓ | ✓ | ✓ | ✓ |
| APR documents | ✓ | ✓ | ✓ | ✓ | ✓ |
| Financial statements | ✓ | ✓ | ✓ | - | - |
| Ultimate beneficial owners | ✓ | ✓ | - | ✓ | ✓ |
`ultimateBeneficialOwners` is AI-extracted from the official Serbian UBO Certificate (Izvod iz Centralne evidencije stvarnih vlasnika) from the CESV register. Verify the values against the certificate before relying on them for compliance. The certificate is ordered on request and typically returns within 1 to 3 business days, so it is not part of the live company data block. The Serbian registration duty does not cover entrepreneurs (предузетник) or majority state-owned entities. If no certificate can be supplied, the request reports unavailability rather than a successful empty UBO list.
### Documents by Company Type
| Document | Available For | Format |
| - | - | - |
| Trade Register Extract (Извод из АПР) | All entities | PDF |
| APR Documents | All entities | PDF |
| Financial Statements | Commercial companies, sole traders | PDF |
| Beneficial Ownership Certificate (`ultimateBeneficialOwnersCertificate`, Izvod iz Centralne evidencije stvarnih vlasnika) | All entities | PDF, ordered on request, typically 1 to 3 business days |
**APR Documents** include three categories:
* **Published documents**: Articles of Association, statutes, amendments, shareholder notices, merger plans (scanned images, so the text is not selectable)
* **Registrar decisions** (решења)
* **Bankruptcy court documents** (документи о стечају): rulings and other documents a commercial court filed with APR, such as a decision to open preliminary bankruptcy proceedings. Few companies have any (scanned images)
**Financial statement forms available per filing**:
* Balance Sheet (Биланс стања)
* Income Statement (Биланс успеха)
* Statistical Report (Статистички извештај)
* Notes to Financial Statements (Напомене уз финансијски извештај)
* Cash Flow Statement (Извештај о токовима готовине)
* Statement of Changes in Equity (Извештај о променама на капиталу)
* Other Comprehensive Income (Извештај о осталом резултату)
Report types: Annual (Редовни годишњи), Consolidated (Консолидовани), Extraordinary (Ванредни).
Available years: filings from the last seven years, depending on what the company filed.
## Example API Responses
```json theme={null}
{
"company": {
"legalName": "EXAMPLE SOFTWARE DOO BEOGRAD",
"status": {
"active": true,
"localName": "Активно"
},
"legalForm": {
"localName": "Друштво са ограниченом одговорношћу",
"standardized": "Limited Liability Company"
},
"identifiers": { "mbr": "21837792", "taxNumber": "113279163" },
"registrationDate": "2001-10-04",
"legalAddress": {
"addressLine1": "Булевар Михајла Пупина 10",
"city": "Нови Сад",
"postalCode": "21000",
"countryCode": "RS"
},
"activities": {
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isMainActivity": true }],
"ISIC": [{ "code": "621", "description": "Computer programming activities", "isMainActivity": true }]
},
"capital": { "amount": 1000000, "currency": "RSD" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Директор", "standardized": "Managing Director" },
"representationMode": { "mode": "sole" },
"individual": {
"name": { "fullName": "Јован Петровић", "firstName": "Јован", "lastName": "Петровић" },
"birthDate": { "year": 1975, "month": 3, "day": 15 },
"gender": "Male"
}
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 100.0,
"nominalCapitalHeld": { "amount": 1000000, "currency": "RSD" },
"paidInAmount": { "amount": 1000000, "currency": "RSD" },
"individual": {
"name": { "fullName": "Јован Петровић", "firstName": "Јован", "lastName": "Петровић" },
"residenceAddress": { "city": "Нови Сад", "countryCode": "RS" }
}
}
]
}
```
```json theme={null}
{
"company": {
"legalName": "PRIMER AKCIONARSKO DRUSTVO BEOGRAD",
"status": { "active": true, "localName": "Активно" },
"legalForm": {
"localName": "Акционарско друштво",
"standardized": "Corporation"
},
"identifiers": { "mbr": "17162543", "taxNumber": "100001234" },
"registrationDate": "1991-06-03",
"legalAddress": {
"addressLine1": "Таковска 2",
"city": "Београд",
"postalCode": "11000",
"countryCode": "RS"
},
"capital": { "amount": 10000000000, "currency": "RSD" }
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Генерални директор", "standardized": "Chief Executive Officer" },
"representationMode": { "mode": "sole" },
"individual": {
"name": { "fullName": "Марија Јовановић", "firstName": "Марија", "lastName": "Јовановић" }
}
}
],
"shareholders": [
{
"entityId": "company_001",
"type": "company",
"sharePercentage": 58.11,
"company": {
"legalName": "REPUBLIKA SRBIJA",
"id": "07020171",
"countryCode": "RS"
}
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Председник надзорног одбора", "standardized": "Chairman of the Board" },
"individual": {
"name": { "fullName": "Немања Стефановић", "firstName": "Немања", "lastName": "Стефановић" }
}
}
]
}
```
Note: the owner is the business. The owner is returned in `legalRepresentatives`, and requesting `shareholders` returns a `datapoint_not_applicable` error.
```json theme={null}
{
"company": {
"legalName": "ИВАН ЈОВАНОВИЋ ПРЕДУЗЕТНИК",
"status": { "active": true, "localName": "Активно" },
"legalForm": {
"localName": "Предузетник",
"standardized": "Sole Proprietorship"
},
"identifiers": { "mbr": "65179059", "taxNumber": "123456789" },
"registrationDate": "2010-05-20",
"legalAddress": {
"addressLine1": "Краља Милана 5",
"city": "Крагујевац",
"postalCode": "34000",
"countryCode": "RS"
},
"activities": {
"NACE": [{ "code": "69.20", "description": "Accounting, bookkeeping and auditing activities; tax consultancy", "isMainActivity": true }],
"ISIC": [{ "code": "6920", "description": "Accounting, bookkeeping and auditing activities; tax consultancy", "isMainActivity": true }]
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Предузетник", "standardized": "Owner" },
"individual": {
"name": { "fullName": "Иван Јовановић", "firstName": "Иван", "lastName": "Јовановић" },
"birthDate": { "year": 1980, "month": 7, "day": 1 },
"gender": "Male"
}
}
]
}
```
Note: foundations return no share capital. The representative is returned in `legalRepresentatives` and the founders the register publishes in `shareholders` (not shown here).
```json theme={null}
{
"company": {
"legalName": "PRIMER FONDACIJA BEOGRAD",
"status": { "active": true, "localName": "Активно" },
"legalForm": {
"localName": "Фондација",
"standardized": "Nonprofit Organization"
},
"identifiers": { "mbr": "28829639", "taxNumber": "112345678" },
"registrationDate": "2012-03-15",
"activities": {
"NACE": [{ "code": "88.99", "description": "Other social work activities without accommodation n.e.c.", "isMainActivity": true }],
"ISIC": [{ "code": "8890", "description": "Other social work activities without accommodation", "isMainActivity": true }]
}
},
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Председник управног одбора", "standardized": "Chairman of the Board" },
"individual": {
"name": { "fullName": "Александар Николић", "firstName": "Александар", "lastName": "Николић" }
}
}
]
}
```
```json theme={null}
{
"tradeRegisterExtract": {
"id": "f7d9eed0-5de2-53d9-80b5-e31542af25d8",
"name": "Trade Register Extract",
"description": "Trade register extract from APR",
"format": "pdf"
},
"financialStatements": [
{
"id": "a1b2c3d4-0001-0001-0001-000000000001",
"name": "Balance Sheet",
"description": "Annual Financial Report 2024 · FIN 24642/2025",
"format": "pdf",
"period": { "startDate": "2024-01-01", "endDate": "2024-12-31" }
},
{
"id": "a1b2c3d4-0001-0001-0001-000000000002",
"name": "Income Statement",
"description": "Annual Financial Report 2024 · FIN 24642/2025",
"format": "pdf",
"period": { "startDate": "2024-01-01", "endDate": "2024-12-31" }
},
{
"id": "a1b2c3d4-0001-0001-0001-000000000003",
"name": "Statistical Report",
"description": "Annual Financial Report 2024 · FIN 24642/2025",
"format": "pdf",
"period": { "startDate": "2024-01-01", "endDate": "2024-12-31" }
}
],
"articlesOfAssociation": [
{
"id": "b2c3d4e5-0001-0001-0001-000000000001",
"name": "Articles of Association",
"date": "2001-10-04",
"format": "pdf"
},
{
"id": "b2c3d4e5-0001-0001-0001-000000000002",
"name": "Amendment to the Articles of Association",
"date": "2018-06-12",
"format": "pdf"
}
],
"officialPublications": [
{
"id": "c3d4e5f6-0001-0001-0001-000000000001",
"name": "Resolution on adoption",
"date": "2024-03-15",
"format": "pdf"
}
]
}
```
# Shareholders Extraction
Source: https://docs.topograph.co/essentials/shareholders-extraction
Reconstruct probable shareholder data for countries without direct registry access
`shareholders` is a first-class data block in the Topograph data model. In countries with direct registry access (e.g., Germany, Spain), shareholder data is returned directly from official sources when you request the `shareholders` datapoint.
For countries that don't expose shareholder data directly through official registries, Topograph offers a `shareholders` datapoint that **reconstructs the most probable current shareholder structure** by analyzing available company documents.
The output format is **identical** regardless of whether the data comes from a registry or from document reconstruction. To tell them apart in the response, inspect the `dataSources` object (see [Identifying Reconstructed Shareholders](#identifying-reconstructed-shareholders)).
Sole entrepreneurs and non-profits have no share capital, so the `shareholders` datapoint returns an explicit `datapoint_not_applicable` response for them instead of an empty list. The owner is available under `legalRepresentatives` and `ultimateBeneficialOwners`. See [Sole Entrepreneurs & Non-Profits](/essentials/entity-types).
**Alpha Feature: Best Effort Reconstruction**
This feature reconstructs a **plausible** shareholder structure based on available public documents. Due to the nature of incomplete public records, we cannot guarantee that:
* **All shareholders are captured**, as some may be missing if not disclosed in available documents
* **No extra shareholders appear**, as historical shareholders may be included if no exit was recorded
* **Share amounts are exact**. Percentages and share counts are approximations based on available data
This is a **best-effort reconstruction**, not authoritative registry data. Results should be verified manually for compliance or legal use cases.
**Additional alpha limitations:**
* Processing may take **30 seconds to several minutes**
* Extraction may **fail or return no results** for some companies
* Behavior and pricing may change
## Supported countries
| Country | Code |
| - | - |
| France | FR |
| United Kingdom | GB |
| Belgium | BE |
| Iceland | IS |
See [Coverage and pricing](/essentials/coverage-and-pricing) for live availability and pricing.
## Example Request
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "FR",
"id": "123456789",
"dataPoints": ["shareholders"]
}'
```
## Example Response
The response uses the same `shareholders` structure as countries with direct registry access:
```json theme={null}
{
"request": {
"requestId": "uuid-v4",
"companyId": "123456789",
"countryCode": "FR",
"dataStatus": {
"dataPoints": {
"shareholders": {
"status": "succeeded"
}
}
}
},
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"individual": {
"name": {
"fullName": "Jean Dupont"
}
},
"sharePercentage": 60,
"numberOfShares": 600
},
{
"entityId": "company_001",
"type": "company",
"company": {
"legalName": "Holding SAS",
"countryCode": "FR",
"id": "987654321"
},
"sharePercentage": 40,
"numberOfShares": 400
}
]
}
```
## Corporate shareholder identifiers
A filing names a corporate shareholder by legal name, and only sometimes states a registration number. We confirm any number read from the filing against the national register, and otherwise search by name. Which identifier key you get back tells you how much we were able to establish:
| Outcome | What you get |
| - | - |
| Confirmed against the register | `company.id` plus the country's own key -- `companiesHouseNumber` (UK), `siren` (France), `ondernemingsnummer` (Belgium), `kennitala` (Iceland) |
| A number was read off the filing, but the register did not confirm it | `company.identifiers.registrationNumber` -- the number as stated in the filing, with no claim about which register issued it |
| Nothing to go on | Name only; `company.id` and `company.identifiers` are left undefined |
The country's own key is an assertion that **that** register issued the number, so only a register match can put a value there. A number printed on a filing frequently belongs to somewhere else: a foreign parent's registration in its own country, or another register in the same country -- in the UK, the Mutuals register and the Charity Commission both issue numbers that are not Companies House numbers. Returning those under the local key would dead-end an ownership chain at a company number that does not exist, so we return them under `registrationNumber` instead.
This applies to every country in the table above. If you traverse ownership chains, branch on which key is present: the local key is safe to look up directly, `registrationNumber` is a lead worth resolving through [search](/essentials/search) before you rely on it.
## Identifying Reconstructed Shareholders
Reconstructed shareholders are always tagged as AI-derived in the `dataSources` object. Registry-backed shareholders carry a `live_from_registry` or `cached_from_registry` source instead. Use this to filter or flag best-effort data in your own pipelines.
Three fields on `dataSources.shareholders` describe the reconstruction:
* `overall.type === "ai_analysis"`: the entire list was produced by document reconstruction. The `overall.analysis` field carries the agent's reasoning summary, and `overall.documents` lists the filings it relied on. Each entry names the register it was collected from in `register`, using the same codes as `dataSources..register` and every document's `source.register`. The attribution sits per document rather than on `overall`, because one reconstruction can draw on filings from several registers. It is omitted when the register behind a document is unknown.
* `limitations`: a structured array of gaps the agent flagged (e.g., unparseable documents, missing share-pledge agreements). Present only when gaps were detected.
* `items[i].overall`: per-shareholder narrative explaining how that specific entity was traced. Aligned 1:1 by index with the `shareholders` array. The `entityId` field lets you match items back to shareholders without relying on order.
Per-field sources live under `items[i].fields` and use the same `type` taxonomy, so an individual field (e.g., `sharePercentage`) can be flagged as `ai_analysis` even when the rest of the entity is registry-backed.
### Example `dataSources` Payload
```json theme={null}
{
"dataSources": {
"shareholders": {
"overall": {
"type": "ai_analysis",
"analysis": "Reconstructed from two capital-increase notices (2022, 2024) and the most recent K-bis. No share-pledge agreements available after 2024.",
"documents": [
{ "name": "K-bis", "date": "2025-01-14", "register": "infogreffe" },
{
"name": "Capital increase notice",
"date": "2024-03-02",
"register": "inpi"
}
]
},
"limitations": [
"No filings after March 2024; subsequent transfers would not be captured.",
"One founding-act scan was unreadable and skipped."
],
"items": [
{
"entityId": "shareholder-1",
"overall": {
"type": "ai_analysis",
"analysis": "Retained 60% after the 2024 capital increase.",
"documents": [
{
"name": "Capital increase notice",
"date": "2024-03-02",
"register": "inpi"
}
]
}
},
{
"entityId": "shareholder-2",
"overall": {
"type": "ai_analysis",
"analysis": "Subscribed to 40% of shares in the 2024 round."
}
}
]
}
}
}
```
### Data Source Types
| `type` | Meaning |
| - | - |
| `live_from_registry` | Fresh pull from the official register |
| `cached_from_registry` | Cached copy of an official register record |
| `inferred` | Simple derivation from register data (e.g., code mapping) |
| `ai_analysis` | Reconstructed from documents by an AI agent. Best-effort, verify before relying on it for compliance. |
| `private_source` | Paid or private data provider |
### In the Ownership Graph
Reconstructed shareholders also surface inside the `graph` datapoint. Each company node whose shareholders were reconstructed carries its own block under `dataSources.graph.nodes[].shareholders`, with the same `overall`, `limitations`, and `items` shape documented above. This lets you spot best-effort reconstructions at any depth of the ownership tree, not just for the root company.
## Best Practices
This is a best-effort reconstruction. Use the data for initial research or screening, but verify through official channels for compliance decisions.
If your process needs registry-backed data only, exclude any shareholder whose `dataSources.shareholders.items[i].overall.type` (or any relevant `fields[x].type`) is `ai_analysis`.
The `dataSources.shareholders.limitations` array is written to be human-readable. Display it alongside the reconstructed list so reviewers know what the agent couldn't determine.
Use alongside `ultimateBeneficialOwners` for a more complete ownership picture. UBOs come from official registers where available.
# Singapore (SG)
Source: https://docs.topograph.co/essentials/singapore
Company data coverage for Singapore (ACRA). API support launched in 2026.
This guide is outdated and will be removed on 1 November 2026. The up-to-date Singapore (SG) reference is on the [Singapore (SG) country page](https://www.topograph.co/countries/sg).
## Start here
This guide contains public integration notes for Singapore (SG). Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
Singapore (SG) company data is available via `POST /v2/company` using `countryCode: "SG"`. Coverage and live datapoints are evolving, see the [changelog](/changelog) for the latest updates.
## Identifier format
Singapore companies are identified by their UEN (Unique Entity Number): 9 or 10 characters, digits and uppercase letters, always ending in a check letter. There are three forms.
| Entity | Format | Example |
| - | - | - |
| Businesses (sole proprietorships and partnerships) | 8 digits and a letter | `52898560D` |
| Local companies | 4-digit year, 5 digits and a letter | `201932822G` |
| All other entities (LLPs, foreign companies, and entities registered with other agencies) | `T`, `S` or `R` (for 20, 19 or 18), a 2-digit year, a 2-character entity-type code, 4 digits and a letter | `T17LL0584B` (LLP), `S36FC0753G` (foreign company) |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Unique Entity Number (UEN) matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
## Search
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Data Availability
| Datapoint | Prefill mode | Verification mode | Notes |
| - | - | - | - |
| `company` | Yes | Yes | Prefill mode serves the ACRA Open Data record, with a live BizFile+ lookup for entities not yet in it. Verification mode reads the ACRA Business Profile |
| `legalRepresentatives` | No | Yes | AI-extracted from the ACRA Business Profile. For a sole proprietorship, the owner is returned here |
| `shareholders` | No | Yes | AI-extracted from the ACRA Business Profile. Not applicable to sole proprietorships, which have no share capital |
| `otherKeyPersons` | No | Yes | Auditors, limited partners, registered compliance managers and statutory process representatives from the same Business Profile |
| `subsidiaries` | No | No | ACRA publishes no downstream participation data |
| `ultimateBeneficialOwners` | No | No | Singapore's register of controllers is not public |
| `establishments` | No | No | Not published by ACRA |
| Documents | No | Yes | The ACRA Business Profile, delivered as a PDF trade register extract |
Verification-mode values are AI-extracted from the Business Profile, so verify them against the source before relying on them for compliance. See [Verification vs prefill mode](/essentials/modes) for how to choose a mode.
## Registered appointments and authority
Filed roles use the published reference vocabulary and retain their exact title. Directors, registered executive appointments, sole proprietors and form-qualified partners are returned as legal representatives. A local-company secretary has a specific statutory capacity to execute deeds jointly with a director under [Companies Act section41B](https://sso.agc.gov.sg/Act/CoA1967?ProvIds=pr41B-\&ViewType=Advance\&WiAl=1); that office does not prove unrestricted or sole commercial signing authority. Unknown-context secretaries remain other key persons unless a separate source mandate is recorded.
Auditors, limited partners, LLP/LP compliance managers and statutory process recipients are other key persons. Corporate holders keep their corporate identity, and separate appointments remain separate capacities. Recorded powers and restrictions are preserved; a role alone does not determine signing mode or a minimum signatory count. The reference list covers known report titles and official position families, rather than claiming a complete current register classifier.
## Activity codes
ACRA publishes SSIC (Singapore Standard Industrial Classification) codes for each entity, and distinguishes a **primary** and a **secondary** activity. The primary SSIC code is returned first and flagged with `isMainActivity: true`, and preserves the source description. The secondary code carries no flag. The open-data input does not stamp the assignment edition, so these records retain native `SSIC` without a revision suffix. National prefixes are not used as ISIC codes. [ACRA migrated Bizfile to SSIC 2025 on 9 May 2026](https://www.bizfile.gov.sg/), but this does not identify the edition of an older cached record.
## Example request
```bash theme={null}
curl -X POST https://api.topograph.co/v2/company \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"countryCode": "SG",
"id": "201234567A",
"dataPoints": ["company"]
}'
```
# Slovakia
Source: https://docs.topograph.co/essentials/slovakia
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Slovakia reference is on the [Slovakia country page](https://www.topograph.co/countries/sk).
## Start here
This guide contains public integration notes for Slovakia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Slovakia uses four official sources. For a given entity, **company data comes from the RPO**, **financial statements come from the RÚZ**, the **Trade Register Extract comes from the ORSR**, and **beneficial ownership comes from the commercial register's beneficial-owner records**.
* **RPO (Register právnických osôb, podnikateľov a orgánov verejnej moci).** The Register of Legal Entities, Entrepreneurs and Public Authorities. This is the **structured data source for company data** for all entity types (commercial companies, sole entrepreneurs, non-profits, public entities), available at [rpo.statistics.sk](https://rpo.statistics.sk). Provides company name, legal form, status, registered address, share capital, activity descriptions, statutory bodies (legal representatives), stakeholders (shareholders, other key persons), and statistical codes.
* **RÚZ (Register účtovných závierok).** The Register of Financial Statements, available at [registeruz.sk](https://www.registeruz.sk). Source of the **Financial Statements** documents.
* **ORSR (Obchodný Register Slovenskej Republiky).** The Commercial Register of the Slovak Republic, maintained by the Ministry of Justice. Used **for Trade Register Extract (PDF) retrieval** from [orsr.sk](https://www.orsr.sk). It is **not** a structured data source for company attributes.
* **KÚV (Konečný užívateľ výhod).** Beneficial-owner records filed into the commercial register. They are not published on the register website or in the Trade Register Extract, so they are obtained as an official certificate of facts issued by the registration court. Source of the **Ultimate Beneficial Owners** datapoint and the **Beneficial Ownership Certificate** document.
The RPO aggregates data from multiple source registers (Commercial Register, Trade Licenses Register, etc.) and provides a unified view of legal entities in Slovakia. The ORSR specifically covers commercial companies registered in the court registry system.
## Modes
Slovakia serves `company`, `legalRepresentatives`, `otherKeyPersons`, and `shareholders` in two modes:
| Mode | Source | What you get |
| - | - | - |
| **Prefill** | The RPO open-data export | Fast, non-authoritative. Can trail the register by the interval between imports of the export. Preserves the register's main code under `NACE_SK`; when its code-list stamp identifies NACE Rev. 2.1, returns standardized NACE and formally derived ISIC as well. No activity inference. An entity whose record no longer carries a current name returns not found. |
| **Verification** | The live RPO | Authoritative. Adds AI-standardized activity codes (additional NACE codes and ISIC codes) and address standardization. Includes the Trade Register Extract. |
The activity-code inference and the dissolved-company fallback described below apply to verification mode only.
## Company Identifiers
### Query Identifiers
Slovakia uses a single primary identifier for all entity types:
| Identifier | Slovak Name | English Translation | Format | Example |
| - | - | - | - | - |
| **ICO** | Identifikacne cislo organizacie | Organization Identification Number | 8 digits, the last one a check digit | `35763469` |
**ICO is always 8 digits.** Leading zeros are significant and must be preserved. For example, `00151742` is a valid ICO -- do not strip leading zeros.
**Entities without an ICO.** A small number of register entities (for example attorneys, branches of foreign undertakings, and state enterprises) have no ICO. Search returns them with an id in the form `RPO-`. Use that id as returned for company requests. Their response has no `identifiers.ico`.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `ico` | 8 digits (ICO) | `35763469` | All entity types that have an ICO |
| `euid` | `SKORSR.` followed by 8 digits | `SKORSR.35763469` | Eligible Commercial Register companies |
Slovakia does not return VAT numbers in the company profile response. Eligible companies can also return an EUID alongside their ICO.
### European Unique Identifier (EUID)
Eligible s.r.o. and a.s. companies confirmed in the Commercial Register can return `company.identifiers.euid` in the format `SKORSR.` followed by their 8-digit IČO. It is available in prefill and verification when the register confirms the company’s current identity and legal form. EUID is a response identifier, not a search key.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the IČO (`ico`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By ICO | 8 digits, or `NN NNN NNN` | `35763469` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT number (IČ DPH) | `SK` + 10 digits | `SK2020317068` | Exact | Validated against VIES, then resolved to the company |
| By Name | Text string | `"Slovak Telekom"` | Fuzzy | Multiple results (partial match) |
**Search Performance:** Use ICO-based searches for best performance and exact matching. See the Speed section of the [pricing page](https://topograph.co/pricing/sk) for current search latency.
### Active companies only
The register itself excludes companies that are no longer active when you search with [`activeOnly=true`](/essentials/search#active-companies-only).
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Ownership percentages only for s.r.o.** | Shareholders are returned for all company types the register publishes them for (for example s.r.o. partners, the sole shareholder of an a.s., limited partners). Share percentages and capital contributions are only available where the register publishes named contributions, typically Limited Liability Companies (s.r.o.). Sole entrepreneurs and non-profits have no share capital and return a not-applicable response at no charge. |
| **NACE codes may be AI-inferred** | In verification mode, additional NACE codes are inferred by AI from Slovak activity descriptions (predmet podnikania) and listed after the register's main-activity code. Check the `isAIInferred` flag. |
| **ISIC can be derived or inferred** | A recognized register assignment is formally mapped to ISIC in both modes. Additional verification-mode codes can be inferred from trade descriptions; inspect `isAIInferred`. |
| **Dissolved companies may have limited data** | For companies with status "Zaniknuty subjekt" (Terminated), the register may return empty statutory bodies and stakeholders. In verification mode, basic information (name, address) falls back to search result data. In prefill mode, an entity with no current name returns not found. |
| **Trade Register Extract requires ORSR registration** | The Trade Register Extract is listed for every company, but it can only be retrieved for entities registered in the commercial register (ORSR). Retrieval fails for entities that are not registered there, such as most sole entrepreneurs and non-profits. |
| **ICO is always 8 digits** | The ICO (Organization Identification Number) is always 8 digits. Leading zeros are significant and must be preserved. |
| **Prokurista appears in legal representatives** | Authorized signatories (Prokurista, code 24 in CL010109) are extracted from the RPO stakeholders section and mapped as legal representatives, not other key persons. |
| **Historical roles in other key persons** | Some roles (codes 4-23) can appear in both legal representatives and other key persons. When they appear in stakeholders, they represent historical/former positions. |
| **UBO data is delivered manually** | Beneficial ownership is not published by any Slovak register, nor included in the public RPO data. It is available as the `ultimateBeneficialOwners` datapoint and as the Beneficial Ownership Certificate document, both taken from the official certificate of facts issued by the registration court, typically within 1-3 business days. Datapoint values are extracted from the certificate, so verify them against the document before relying on them for compliance. |
| **Historical currency support** | Companies registered before 2009 (Euro adoption) may have share capital in SKK (Slovak Koruna). The system supports both EUR and historical SKK currency codes. |
## Company Status
Company status is mapped **deterministically** from RPO legal status codes (codelist **CL010108**). No AI inference is involved in status determination.
### Status Code Mapping
| Code | Slovak Status | English | Standardized Status | Notes |
| - | - | - | - | - |
| 1 | Bez zaznamu | No Record / Active | Active | Default active status |
| 7 | Pozastaveny vykon cinnosti | Activity Suspended | Active | Legally still active, business temporarily suspended |
| 8 | Preruseny vykon cinnosti | Activity Interrupted | Active | Legally still active, business temporarily interrupted |
| Code | Slovak Status | English | Standardized Status | Notes |
| - | - | - | - | - |
| 2 | V likvidacii | In Liquidation | Under Insolvency Proceeding | Company is in liquidation process |
| 3 | V konkurze | In Bankruptcy | Under Insolvency Proceeding | Company is in bankruptcy proceedings |
| 4 | V restrukturalizacii | In Restructuring | Under Insolvency Proceeding | Company is undergoing restructuring |
| 5 | Vo vyrovnani | In Settlement | Under Insolvency Proceeding | Company is in settlement proceedings |
| 6 | V nutenej sprave | In Forced Administration | Under Insolvency Proceeding | Company is under forced administration |
| 20 | V konani o prejednani dedicstva | In Inheritance Proceedings | Under Insolvency Proceeding | Company is in inheritance proceedings |
| Code | Slovak Status | English | Standardized Status | Closure Reason |
| - | - | - | - | - |
| 9 | -- | Court decision on invalidity | Closed | Court Order |
| 10 | -- | Decision of partners/body | Closed | Voluntary Dissolution |
| 11 | -- | Time expiration | Closed | Other |
| 12 | -- | Merger (zlucenie) | Closed | Merger |
| 13 | -- | Amalgamation (splynutie) | Closed | Merger |
| 14 | -- | Division (rozdelenie) | Closed | Other |
| 15 | -- | Bankruptcy proceedings ended | Closed | Bankruptcy |
| 16 | -- | Other reason | Closed | Other |
| 17 | -- | Terminated | Closed | Other |
| 18 | -- | License expiration | Closed | Administrative Dissolution |
| Code | Slovak Status | English | Standardized Status | Notes |
| - | - | - | - | - |
| 19 | -- | Record deleted due to technical error | Unknown | Technical/data issue |
**Status priority logic:** (1) If a termination date exists, the company is always mapped to Closed regardless of the status code. (2) Otherwise, the current status code determines the status. (3) If no status information is available, the system defaults to Active.
## Legal Forms
Slovakia uses the official codelist **CL000056** containing **90+ legal forms**. The mapping from these codes to standardized forms and ISO 20275 (ELF) codes is **deterministic**. In verification mode, when the codelist mapping gives no ISO 20275 code, one may be added by lookup, and a form mapped to "Other" may receive a more specific standardized category. Forms shown with `--` in the tables below can therefore still carry an ISO 20275 code in the API response.
ISO 20275 (ELF) codes are only assigned for legal forms that have registered LEI entities in the GLEIF database. Most Slovak legal forms do not have ELF codes assigned in the current GLEIF list (v1.6).
### Key Business Forms
| Code | Slovak Name | Abbr. | English | Standardized | ISO 20275 |
| - | - | - | - | - | - |
| 112 | Spolocnost s rucenim obmedzenym | s.r.o. | Limited Liability Company | Limited Liability Company | VSZS |
| 121 | Akciova spolocnost | a.s. | Joint Stock Company | Corporation | 2EEG |
| 125 | Jednoducha spolocnost na akcie | j.s.a. | Simple Joint Stock Company | Corporation | -- |
| 111 | Verejna obchodna spolocnost | v.o.s. | General Partnership | Partnership | -- |
| 113 | Komanditna spolocnost | k.s. | Limited Partnership | Partnership | KB52 |
| 114 | Spolocnost komanditna na akcie | -- | Partnership Limited by Shares | Corporation | -- |
### Sole Proprietorships
| Code | Slovak Name | English | Standardized |
| - | - | - | - |
| 001 | Samostatne podnikajuca fyzicka osoba | Self-Employed Individual | Sole Proprietorship |
| 100 | Fyzicka osoba-prilezitostne cinna-zapisana v registri | Physical person-occasionally active-in tax roll | Sole Proprietorship |
| 101 | Podnikatel-fyzicka osoba-nezapisany v obchodnom registri | Entrepreneur - Individual (Not in Commercial Reg) | Sole Proprietorship |
| 102 | Podnikatel-fyzicka osoba-zapisany v obchodnom registri | Entrepreneur - Individual (In Commercial Reg) | Sole Proprietorship |
| 103 | Samostatne hospodariacirolnik nezapisany v OR | Private Farmer (Not in Business Register) | Sole Proprietorship |
| 104 | Samostatne hospodariaci rolnik zapisany v OR | Private Farmer (In Business Register) | Sole Proprietorship |
| 105 | Slobodne povolanie-fyzicka osoba | Freelance Professional | Sole Proprietorship |
| 106 | Slobodne povolanie-FO zapisana v OR | Freelance Professional (In Business Register) | Sole Proprietorship |
| 107 | Podnikatel-FO-nezapis.v OR-podnikajuca sucasne ako SHR | Entrepreneur also as Private Farmer (Not in BR) | Sole Proprietorship |
| 108 | Podnikatel-FO-zapis.v OR-podnikajuca sucasne ako SHR | Entrepreneur also as Private Farmer (In BR) | Sole Proprietorship |
| 109 | Podnikatel-FO-nezapis.v OR-podnikajuca sucasne ako osoba so slobodnym povolanim | Entrepreneur also as Freelance (Not in BR) | Sole Proprietorship |
| 110 | Podnikatel-FO-zapis.v OR-podnikajuca sucasne ako osoba so slobodnym povolanim | Entrepreneur also as Freelance (In BR) | Sole Proprietorship |
### Cooperatives
| Code | Slovak Name | English | Standardized | ISO 20275 |
| - | - | - | - | - |
| 205 | Druzstvo | Cooperative | Cooperative | I7AS |
| 131 | Svojpomocne polnohospodarske druzstvo | Self-Aided Agricultural Cooperative | Cooperative | -- |
| 201 | Polnohospodarske druzstvo | Agricultural Cooperative | Cooperative | -- |
| 211 | Druzstevny podnik polnohospodarsky | Cooperative Agricultural Enterprise | Cooperative | -- |
| 231 | Vyrobne druzstvo | Producer Cooperative | Cooperative | -- |
| 232 | Spotrebne druzstvo | Consumer Cooperative | Cooperative | -- |
| 233 | Bytove druzstvo | Housing Cooperative | Cooperative | -- |
| 234 | Ine druzstvo | Other Cooperative | Cooperative | -- |
| 271 | Spolocenstvo vlastnikov bytov a nebytovych priestorov | Owners Association (Residential & Non-Residential) | Cooperative | -- |
| 272 | Pozemkove spolocenstvo | Land Community | Cooperative | -- |
### Non-Profit Organizations
| Code | Slovak Name | English | Standardized | ISO 20275 |
| - | - | - | - | - |
| 116 | Zaujmove zdruzenie | Interest Association | Nonprofit Organization | -- |
| 117 | Nadacia | Foundation | Nonprofit Organization | -- |
| 118 | Neinvesticny fond | Non-Investment Fund | Nonprofit Organization | -- |
| 119 | Neziskova organizacia | Non-Profit Organization | Nonprofit Organization | YRIU |
| 120 | Neziskova organizacia poskytujuca vseobecne prospesne sluzby | Non-Profit Providing Public Services | Nonprofit Organization | -- |
| 701 | Zdruzenie (zvaz, spolok, spolocnost, klub ai.) | Association (Union, Society, Club) | Nonprofit Organization | -- |
| 711 | Politicka strana, politicke hnutie | Political Party / Movement | Nonprofit Organization | -- |
| 721 | Cirkevna organizacia | Church Organization | Nonprofit Organization | -- |
| 741 | Stavovska organizacia - profesna komora | Professional Chamber | Nonprofit Organization | -- |
| 745 | Komora (s vynimkou profesnych komor) | Chamber (Non-Professional) | Nonprofit Organization | -- |
| 751 | Zaujmove zdruzenie pravnickych osob | Association of Legal Entities | Nonprofit Organization | -- |
### Public Law Entities
| Code | Slovak Name | English | Standardized |
| - | - | - | - |
| 301 | Statny podnik | State Enterprise | Government-Owned Entity |
| 311 | Narodna banka Slovenska | National Bank of Slovakia | Government-Owned Entity |
| 321 | Rozpoctova organizacia | Budgetary Organization | Government-Owned Entity |
| 331 | Prispevkova organizacia | Contributory Organization | Government-Owned Entity |
| 333 | Verejna vyskumna institucia | Public Research Institution | Government-Owned Entity |
| 382 | Verejnopravna institucia | Public Law Institution | Government-Owned Entity |
| 601 | Vysoka skola | University | Government-Owned Entity |
| 801 | Obec (obecny urad), mesto | Municipality / City | Government-Owned Entity |
| 803 | Samospravny kraj | Self-Governing Region | Government-Owned Entity |
### Branch Offices
| Code | Slovak Name | English | Standardized | ISO 20275 |
| - | - | - | - | - |
| 002 | Organizacna zlozka podniku | Branch Office | Branch or Representative Office | YGN4 |
| 005 | Podnik zahranicnej osoby (organizacna zlozka podniku) | Enterprise of Foreign Person (Branch) | Branch or Representative Office | -- |
| 501 | Odstepny zavod alebo ina organizacna zlozka podniku | Branch Establishment (Registered) | Branch or Representative Office | -- |
| 931 | Zastupenie zahranicnej pravnickej osoby | Representation of Foreign Legal Entity | Branch or Representative Office | -- |
### European Forms
| Code | Slovak Name | Abbr. | English | Standardized | ISO 20275 |
| - | - | - | - | - | - |
| 123 | Europska spolocnost | SE | European Company | Corporation | -- |
| 122 | Europske zoskupenie hospodarskych zaujmov | EZHZ | European Economic Interest Grouping | Partnership | -- |
| 124 | Europske druzstvo | SCE | European Cooperative Society | Cooperative | -- |
| 804 | Europske zoskupenie uzemnej spoluprace | EGTC | European Grouping of Territorial Cooperation | Government-Owned Entity | -- |
### Financial Institutions
| Code | Slovak Name | English | Standardized |
| - | - | - | - |
| 431 | Banka - akciova spolocnost | Bank - Joint Stock Company | Corporation |
| 432 | Sporitelna | Savings Bank | Corporation |
| 436 | Poistovna - akciova spolocnost | Insurance Company - Joint Stock | Corporation |
| 445 | Komoditna burza | Commodity Exchange | Corporation |
The full CL000056 codelist (90+ legal forms) is available at [MetaIS](https://metais.slovensko.sk/data-objects/codelists/2941). Our system maps every code to provide English translations, standardized categories, and ISO 20275 codes where the codelist allows.
## Legal Representatives
Legal representatives are extracted from **two RPO data arrays**, combined and deduplicated:
| Source | Codelist | When Mapped as Legal Rep |
| - | - | - |
| **statutoryBodies** | CL010113 (58 codes) | All entries are legal representatives (current only) |
| **stakeholders** | CL010109 (5 codes) | Only codes with signing authority (Prokurista, General Partner, Branch Heads) |
The classification of a role as legal representative is **fully deterministic** -- based on codelist codes, not AI inference.
### Complete Statutory Body Role List (CL010113 -- 58 roles)
| Code | Slovak Role | English Translation |
| - | - | - |
| 3 | Konatel | Director |
| 4 | Predseda predstavenstva | Chairman of the Board |
| 5 | Clen predstavenstva | Board Member |
| 6 | Podpredseda predstavenstva | Vice Chairman of the Board |
| 8 | Generalny riaditel | Chief Executive Officer |
| 9 | Riaditel | Director |
| 12 | Predseda | Chairman |
| 13 | Vykonny riaditel | Executive Director |
| 19 | Podnikatel | Entrepreneur |
| 25 | Zastupca generalneho riaditela | Deputy CEO |
| 28 | Prezident | President |
| 95 | Podpredseda | Vice Chairman |
| 97 | Veduci podniku (organizacnej zlozky podniku) | Head of Enterprise Branch |
| 98 | Zastupca riaditela | Deputy Director |
| 99 | Predstavenstvo | Board of Directors |
| Code | Slovak Role | English Translation |
| - | - | - |
| 1 | Spolocnik | Partner |
| 2 | Komplementar | General Partner |
| 84 | Prokurista | Authorized Signatory (Procurator) |
| 85 | Veduci odstepneho zavodu | Head of Branch |
| 88 | Prokurista zahranicnej osoby | Procurator of Foreign Entity |
| Code | Slovak Role | English Translation |
| - | - | - |
| 7 | Veduci organizacnej zlozky | Head of Organizational Unit |
| 10 | Spravca | Administrator |
| 11 | Clen vyboru | Committee Member |
| 17 | Iny statutarny organ | Other Statutory Body |
| 18 | Likvidator | Liquidator |
| 20 | Zastupca podnikatela | Representative of Entrepreneur |
| 21 | Poverena osoba | Authorized Person |
| 24 | Veduci uradu | Head of Office |
| 40 | Clen rady urceny radou | Council Member Appointed by Council |
| 86 | Likvidator zahranicnej osoby | Liquidator of Foreign Entity |
| 87 | Spravca na vykon nutenej spravy | Forced Administration Administrator |
| 89 | Clen spravnej rady | Administrative Board Member |
| 90 | Statutarny organ statutara, ktorym je pravnicka osoba | Statutory Body of Legal Entity |
| 91 | Clen statutarneho organu zahranicnej osoby | Statutory Body Member of Foreign Entity |
| 92 | Clen statutarneho organu | Statutory Body Member |
| 93 | Spravna rada | Administrative Board |
| 94 | Clen druzstva povereny clenskou schoodzou | Cooperative Member Auth. by General Meeting |
| 96 | Vykonny vybor | Executive Committee |
| Code | Slovak Role | English Translation |
| - | - | - |
| 0 | Neurcene | Unspecified |
| 14 | Starosta | Mayor (Village) |
| 15 | Primator | Mayor (City) |
| 16 | Minister | Minister |
| 22 | Rektor | Rector |
| 23 | Clenska schodza | General Meeting |
| 26 | Guverner | Governor |
| 27 | Viceguvernerr | Vice Governor |
| 29 | Regionalny hygienik | Regional Hygienist |
| 30 | Generalny konzul | Consul General |
| 31 | Konzul | Consul |
| 32 | Velvyslanec | Ambassador |
| 33 | Generalny tajomnik sluzobneho uradu | Secretary General of Service Office |
| 34 | Generalny tajomnik | Secretary General |
| 35 | Generalny sekretar | General Secretary |
| 36 | Arcibiskup | Archbishop |
| 37 | Biskup | Bishop |
| 38 | Farar | Pastor |
| 39 | Statny tajomnik | State Secretary |
| 41 | Generalny prokurator | Prosecutor General |
### Legal Representatives from Stakeholders (CL010109 -- 5 codes)
These are stakeholders with signing authority, extracted from the stakeholders array:
| Code | Slovak Role | English Translation |
| - | - | - |
| 2 | Komplementar | General Partner |
| 24 | Prokurista | Authorized Signatory (Procurator) |
| 90 | Prokurista zahranicnej osoby | Procurator of Foreign Entity |
| 96 | Veduci podniku zahranicnej osoby | Head of Foreign Entity Branch |
| 97 | Veduci odstepneho zavodu | Head of Branch |
Legal representatives include both individuals and corporate entities. Role translations are standardized deterministically based on the official codelist [CL010113](https://metais.slovensko.sk/data-objects/codelists/2953). All statutory body entries are current records only -- historical records (with `validTo` set) are filtered out.
## Other Key Persons
Other key persons are extracted from the RPO `stakeholders` array using codelist **CL010109**. These include supervisory board members, administrators, founders, and other roles that are neither legal representatives nor shareholders.
### Complete Other Key Persons Role Mapping (CL010109 -- 40 codes)
| Code | Slovak Role | English Translation |
| - | - | - |
| 8 | Clen dozornej rady | Supervisory Board Member |
| 25 | Predseda spravnej rady | Chairman of Administrative Board |
| 26 | Podpredseda spravnej rady | Vice Chairman of Administrative Board |
| 27 | Clen spravnej rady | Administrative Board Member |
| 28 | Clen dozornej rady | Supervisory Board Member |
| 98 | Clen dozorneho organu | Supervisory Body Member |
| Code | Slovak Role | English Translation |
| - | - | - |
| 16 | Spravca | Administrator |
| 35 | Spravca konkurznej podstaty | Bankruptcy Trustee |
| 36 | Vyrovnavaci spravca | Settlement Administrator |
| 39 | Spravca restrukturalizacneho konania | Restructuring Administrator |
| 86 | Spravca na vykon nutenej spravy | Forced Administration Administrator |
| 88 | Spravca vyrovnacieho konania | Settlement Proceedings Administrator |
| 93 | Likvidator zahranicnej osoby | Liquidator of Foreign Entity |
| Code | Slovak Role | English Translation |
| - | - | - |
| 29 | Zakladatel | Founder |
| 30 | Zriadovatel | Establisher |
| 87 | Zriadovatel ZO | Branch Establisher |
| 95 | Zakladatel statneho podniku | Founder of State Enterprise |
| Code | Slovak Role | English Translation |
| - | - | - |
| 0 | Neurcene | Unspecified |
| 17 | Clen vyboru | Committee Member |
| 31 | Navrhovatel | Proposer |
| 32 | Clen pripravneho vyboru | Preparatory Committee Member |
| 33 | Zodpovedny zastupca | Responsible Representative |
| 37 | Ina zainteresovana osoba | Other Stakeholder |
| Code | Slovak Role | English Translation |
| - | - | - |
| 4 | Konatel | Director (historical) |
| 5 | Predseda predstavenstva | Chairman of the Board (historical) |
| 6 | Podpredseda predstavenstva | Vice Chairman of the Board (historical) |
| 7 | Clen predstavenstva | Board Member (historical) |
| 9 | Generalny riaditel | CEO (historical) |
| 10 | Riaditel | Director (historical) |
| 11 | Zastupca riaditela | Deputy Director (historical) |
| 12 | Vykonny riaditel | Executive Director (historical) |
| 13 | Rektor | Rector (historical) |
| 14 | Guverner | Governor (historical) |
| 15 | Veduci organizacnej zlozky | Head of Organizational Unit (historical) |
| 18 | Predseda | Chairman (historical) |
| 19 | Starosta | Mayor - Village (historical) |
| 20 | Primator | Mayor - City (historical) |
| 21 | Minister | Minister (historical) |
| 22 | Veduci uradu | Head of Office (historical) |
| 23 | Veduci kancelarie | Head of Office/Cabinet (historical) |
Codes 4-23 (marked "historical") are executive roles that can appear in stakeholders when they represent former/historical positions rather than current statutory authority. These same codes in CL010113 represent current legal representatives. Mapping source: [CL010109](https://metais.slovensko.sk/data-objects/codelists/2950).
## Shareholders
Shareholders are extracted from the RPO `stakeholders` array using codelist **CL010109** (7 shareholder codes). Both individual and corporate shareholders are supported.
### Shareholder Codes (CL010109)
| Code | Slovak Role | English Translation |
| - | - | - |
| 1 | Spolocnik | Partner |
| 3 | Komanditista | Limited Partner |
| 89 | v.o.s., ktorej imanie sa prebera | Partnership Whose Assets Are Taken Over |
| 91 | Clen EZHZ | EEIG Member |
| 92 | Spolocnik v.o.s., ktory prevzal jej imanie | Partner Who Took Over Partnership Assets |
| 94 | Jediny akcionar a.s. | Sole Shareholder of JSC |
| 99 | Spolocnik v.o.s. / s.r.o. | Partner of GP / LLC Member |
### Ownership Data
For **s.r.o.** (Limited Liability Companies), ownership data is calculated from RPO deposit records by matching stakeholders to deposits by name:
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Percentage ownership (calculated as `deposit.amount / equity.value * 100`) | RPO deposits + equities |
| `nominalCapitalHeld` | Capital contribution amount | RPO deposits |
| `paidInAmount` | Same as nominalCapitalHeld (deposits are fully paid-in) | RPO deposits |
**Example** (company with 3 shareholders, 7,500 EUR total equity):
| Shareholder | Deposit | Share % |
| - | - | - |
| Ing. Alexander Pomsar | 2,250 EUR | 30% |
| Ing. Igor Buday | 2,250 EUR | 30% |
| Ladislav Zemanek | 3,000 EUR | 40% |
### Ownership Availability by Legal Form
| Legal Form | Code | Deposits | Stakeholders | Ownership % |
| - | - | - | - | - |
| s.r.o. (LLC) | 112 | Named | Yes | Calculable |
| a.s. (JSC) | 121 | None | Yes | N/A |
| v.o.s. (GP) | 111 | None | Partners, when disclosed | N/A |
| k.s. (LP) | 113 | None | None | N/A |
| Druzstvo (Coop) | 205 | Unnamed | None | Cannot match |
Ownership percentages and capital amounts are only available for **s.r.o.** (Limited Liability Companies). Shareholders of other company forms (for example v.o.s. partners or the sole shareholder of an a.s.) are still returned when the register discloses them, without these amounts. Deposit-to-stakeholder matching uses normalized names (lowercase, academic titles removed). Currency is read from the `currency.code` field. Only current deposits (where `validTo` is null) are used.
## Activity Code Mapping
The RPO publishes its main activity in `statisticalCodes.mainActivity` and current trade descriptions separately. The source code and wording are preserved under `NACE_SK` with `isMainActivity: true` in both modes.
The actual code-list stamp `CL010579` identifies [NACE Rev. 2.1](https://metais.slovensko.sk/data-objects/codelists/3166?orderBy=itemCode). Those assignments are formatted as NACE classes and formally mapped to ISIC, retaining the main flag. Unknown or missing stamps remain native; dates and code shape do not establish the edition.
Verification mode can additionally infer activities from the current trade descriptions. Declared source assignments win over inferred duplicates and keep their main marker. The original descriptions are preserved in `activityDescription`.
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **NACE\_SK** | Register main activity, original code and wording | `6210` | No |
| **NACE** | Recognized Rev. 2.1 assignment | `62.10` | No |
| **ISIC** | Formal correspondence from a recognized assignment | `621` | No |
| **NACE / ISIC** | Additional activity inference in verification mode | Depends on the trade description | Yes |
## Ultimate Beneficial Owners
Beneficial ownership is held separately from public RPO company data. A local partner obtains the certificate concerning the commercial register’s beneficial ownership records. Request `ultimateBeneficialOwners` in verification mode for structured data, or order `ultimateBeneficialOwnersCertificate` from `availableDocuments` for the source PDF. Delivery is asynchronous and can take several business days. Follow the existing request through webhooks or polling; do not submit repeated orders while it is pending. If the certificate cannot be obtained, the request reports an error rather than a successful empty result.
## Data Availability Matrix
| Data Type | Commercial Companies (RPO) | Sole Entrepreneurs (RPO) | Non-Profits (RPO) | Notes |
| - | - | - | - | - |
| Company Profile | Yes | Yes | Yes | Full data for commercial companies |
| Legal Representatives | Yes | Yes | Yes | From RPO statutory bodies + stakeholders with signing authority |
| Shareholders | When disclosed | Not applicable | Not applicable | Includes s.r.o. and v.o.s. partners and the sole shareholder of an a.s. Ownership percentages only where the register publishes named contributions (typically s.r.o.). Sole entrepreneurs and non-profits return a not-applicable response at no charge |
| Other Key Persons | Yes | Limited | Limited | Supervisory board, founders, etc. |
| Ultimate Beneficial Owners | Manual | No | Limited | From the official certificate of facts, typically 1-3 business days. Sole entrepreneurs, and most non-profits, are not subject to this filing. See the [pricing page](https://topograph.co/pricing/sk) for availability |
| Activity Codes | Yes | Yes | Yes | Native RPO main code; recognized Rev. 2.1 yields formal NACE/ISIC; additional inference in verification mode |
| Documents | Yes | Limited | Limited | Trade Register Extract (ORSR-registered entities), Financial Statements (entities that file them with the RÚZ), Beneficial Ownership Certificate |
**Legend:** Yes = Available | No = Not Available | Limited = Conditionally Available | Manual = Delivered manually
## Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | Listed for every company; retrievable for ORSR-registered entities only | Extract from ORSR (Obchodny Register). English section headings, Slovak content. Included with the verification company data. |
| **Financial Statements** | `financialStatements` | PDF | Entities that file financial statements with the RÚZ | One document per PDF attachment of each filing, by fiscal year. |
| **Beneficial Ownership Certificate** | `ultimateBeneficialOwnersCertificate` | PDF | Listed for every company | Official certificate of facts on the beneficial-owner entry, issued by the registration court. Delivered manually, typically within 1-3 business days. Sole entrepreneurs are not subject to this filing. |
Entities without ORSR registration, such as most sole entrepreneurs and non-profits, have no trade register extract. Financial statements may still be available if the entity has filed reports in the Register účtovných závierok (RÚZ).
**Trade Register Extract requires ORSR registration.** The extract is listed for every company, but it can only be retrieved for entities registered in the commercial register (ORSR). Retrieval fails for entities that are not registered there, such as most sole entrepreneurs and non-profits.
**Financial statements:** Filed reports are obtained from RÚZ. Availability depends on the entity and reporting year; it does not require the customer to provide eIDAS credentials.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "SK", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "12345678",
"countryCode": "SK",
"identifiers": { "ico": "12345678" },
"legalName": "Priklad s.r.o.",
"registrationDate": "2018-05-10",
"activityDescription": "Pocitacove programovanie; Poradenske sluzby v oblasti informacnych technologii",
"status": { "localName": "Aktivna", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Spolocnost s rucenim obmedzenym", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company", "iso20275Code": "VSZS" },
"capital": { "amount": 5000, "currency": "EUR" },
"activities": {
"NACE_SK": [{ "code": "6210", "description": "Počítačové programovanie", "isMainActivity": true }],
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isMainActivity": true }],
"ISIC": [{ "code": "621", "description": "Computer programming activities", "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "Hlavna 15", "city": "Bratislava", "postalCode": "81101", "countryCode": "SK" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Konatel", "standardized": "Director" }, "individual": { "name": { "fullName": "Jan Novak" }, "birthDate": { "month": 3, "year": 1980 } } }
],
"shareholders": [
{ "entityId": "person_001", "type": "individual", "individual": { "name": { "fullName": "Jan Novak" } }, "sharePercentage": 60, "nominalCapitalHeld": { "amount": 3000, "currency": "EUR" } },
{ "entityId": "person_002", "type": "individual", "individual": { "name": { "fullName": "Peter Horvath" } }, "sharePercentage": 40, "nominalCapitalHeld": { "amount": 2000, "currency": "EUR" } }
],
"otherKeyPersons": [
{ "entityId": "person_003", "type": "individual", "role": { "localName": "Clen dozornej rady", "standardized": "Supervisory Board Member" }, "individual": { "name": { "fullName": "Maria Kovacova" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "87654321",
"countryCode": "SK",
"identifiers": { "ico": "87654321" },
"legalName": "Stara Firma a.s.",
"registrationDate": "2005-01-15",
"activityDescription": "Velkoobchod s priemyselnymi tovarmi",
"status": { "localName": "Zaniknuty subjekt", "active": false, "statusDetails": { "status": "CLOSED" } },
"legalForm": { "localName": "Akciova spolocnost", "englishTranslation": "Joint Stock Company", "standardized": "Corporation", "iso20275Code": "2EEG" },
"capital": { "amount": 25000, "currency": "EUR" },
"legalAddress": { "addressLine1": "Obchodna 42", "city": "Kosice", "postalCode": "04001", "countryCode": "SK" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Predseda predstavenstva", "standardized": "Chairman of the Board" }, "individual": { "name": { "fullName": "Tomas Kral" } } }
]
}
```
**Note:** Closed companies have `active: false`. Shareholders and other key persons may not be available for dissolved companies, as the RPO entity endpoint may return empty arrays.
```json theme={null}
{
"company": {
"id": "47440171",
"countryCode": "SK",
"identifiers": { "ico": "47440171" },
"legalName": "DC GRBA, s.r.o. - v likvidacii",
"registrationDate": "2011-06-20",
"status": {
"localName": "V likvidacii",
"active": false,
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"insolvencyStartDate": "2022-01-15",
"additionalInfo": "Company is in liquidation process (V likvidacii)"
}
},
"legalForm": { "localName": "Spolocnost s rucenim obmedzenym", "standardized": "Limited Liability Company", "iso20275Code": "VSZS" },
"legalAddress": { "addressLine1": "Priemyselna 8", "city": "Bratislava", "postalCode": "82109", "countryCode": "SK" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Likvidator", "standardized": "Liquidator" }, "individual": { "name": { "fullName": "Mgr. Juraj Sprava" } } }
]
}
```
**Note:** Companies under insolvency proceedings have `active: false` with detailed status including `insolvencyStartDate` and `additionalInfo` describing the specific proceeding type.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Trade Register Extract PDF | Retrievable for entities registered in ORSR only. |
| `financialStatements` | Financial Statements PDF | One entry per PDF attachment of each filing, for entities that file with the RÚZ. |
| `ultimateBeneficialOwnersCertificate` | Beneficial Ownership Certificate PDF | Delivered manually, typically within 1-3 business days. |
# Slovenia
Source: https://docs.topograph.co/essentials/slovenia
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Slovenia reference is on the [Slovenia country page](https://www.topograph.co/countries/si).
## Start here
This guide contains public integration notes for Slovenia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
All Slovenian data comes from registers and portals operated by AJPES, the Agency of the Republic of Slovenia for Public Legal Records and Related Services.
* **AJPES Business Register (ePRS).** AJPES maintains the Business Register (Poslovni register Slovenije). The ePRS portal provides verification-mode company profile data, legal representatives, shareholders, and digitally signed Trade Register Extract PDFs for court-registered entities. Accessible at [ajpes.si/prs/](https://www.ajpes.si/prs/).
* **PRS Open Data.** The quarterly open-data extract of the Business Register (\~290K entities). It powers search and the prefill-mode company profile.
* **AJPES eObjave.** The electronic publications portal, source of articles of association. Accessible at [ajpes.si/eObjave/](https://www.ajpes.si/eObjave/).
* **AJPES JOLP.** The public annual report portal, source of financial statements for up to the last 5 fiscal years. Accessible at [ajpes.si/jolp/](https://www.ajpes.si/jolp/).
* **Register dejanskih lastnikov (RDL).** The Slovenian UBO Register. Source of Ultimate Beneficial Owner data and the official Beneficial Ownership Extract, delivered manually in about 1-3 business days.
**Prefill vs. verification.** Prefill mode reads the Business Register's open-data extract, refreshed quarterly. Verification-mode company data and shareholders are live register lookups, billed separately. See [topograph.co/pricing/si](https://topograph.co/pricing/si) for pricing.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All entity types** | AJPES PRS | 10 digits (Registration Number) | `5025796000` | Matična številka (7-digit entity number ending in a check digit + 3-digit unit suffix) |
| **All entity types** | AJPES PRS | 8 digits (Tax Number) | `80267432` | Davčna številka, also accepted for search |
**Registration Number Format:** Slovenian registration numbers (matična številka) are 10 digits, composed of a 7-digit entity number and a 3-digit suffix. The suffix is `000` for the entity itself: `5025796000` has entity number `5025796` and suffix `000`. Branches and other units of an entity have their own registration number, which search also returns: the same 7-digit entity number followed by the unit's sequence number (e.g. `2211254004`). The seventh digit is a check digit (weights 7 to 2 over the first six digits, modulo 11). The register's rules allow a letter in the eighth position for an entity with more than 999 units.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `registrationNumber` | 10 digits (`000` suffix for the entity, another suffix for a branch) | `5025796000` | All entities |
| `taxNumber` | 8 digits (a foreign shareholder's own tax number when it has no Slovenian registration number) | `80267432` | When available (verification mode) |
**VAT Number:** The Slovenian VAT number is the tax number prefixed with `SI` (e.g., `SI80267432`). It is accepted as a search input but is not returned in `identifiers`.
### European Unique Identifier (EUID)
Eligible d.o.o. and d.d. companies can return `company.identifiers.euid` in the format `SIPRS.` followed by their 10-digit registration number. It is available in prefill and verification. Sole traders, associations and establishments are excluded. EUID is a response identifier, not a search key.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the registration number (`registrationNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Registration Number | 10 digits | `5025796000` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Tax Number | 8 digits | `80267432` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Petrol"` | Partial/Contains | Multiple results |
**Search Performance:** Use identifier-based searches (registration number, tax number) for best performance and exact matching. Name searches perform full-text matching and may return multiple results.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Name searches only return active companies; registration-number and tax-number lookups return the company whatever its status.
## Supported Entity Families
| Entity Family | Legal Forms | Notes |
| - | - | - |
| **Companies** | d.o.o. (Limited Liability Company), d.d. (Joint-Stock Company), k.d. (Limited Partnership), d.n.o. (General Partnership) | Court-registered entities with full Trade Register Extract |
| **Sole Traders** | s.p. (Sole Proprietor) | Registered in the Business Register, not the court register |
| **Associations** | društvo (Association), zavod (Institute) | Non-profit entities |
| **Closed Entities** | Partial support | Search defaults to active entities; closed entities may have limited data |
**Court register vs. Business Register.** Court-registered entities (d.o.o., d.d., k.d., d.n.o.) have full profile data including legal representatives, shareholders, and equity interests. Business-register-only entities (s.p., associations) have basic profile data. Trade Register Extract PDFs are only available for court-registered entities.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **d.d. companies have no shareholders** | Joint-stock companies (d.d.) show "No entry" for Partners and Equity Interests because shares are publicly traded. This is expected behavior. |
| **Search defaults to active entities** | The ePRS portal filters to active entities by default. Closed entities may not appear in search results. |
| **UBOs are delivered manually** | Access to the RDL is restricted, so beneficial ownership is obtained through a local partner, separately from public company data. UBOs come from the official Slovenian UBO extract (Izpis iz Registra dejanskih lastnikov), delivered manually in about 1-3 business days. |
| **Quarterly search index updates** | The search index is refreshed quarterly from PRS Open Data. Newly registered entities may not appear immediately, but will be found via the live ePRS fallback. |
| **Activity codes for business-register entities only** | The ePRS extract lists registered activities (SKD codes) only for business-register entities (s.p., associations); court-registered entities (d.o.o., d.d., k.d., d.n.o.) carry none. Where present, the 5-digit SKD codes are returned under `SKD` and also under `NACE`. The activity AJPES labels "Main activity" (glavna dejavnost) is listed first with `isMainActivity: true` in both. |
| **No employee count** | AJPES does not provide employee count data. |
## Company Status
| Mode | `localName` | `active` | Notes |
| - | - | - | - |
| Verification | Entity status text as published in the English ePRS view (e.g. `active`) | `true` when the text contains "active" or "registered" | No `statusDetails` |
| Prefill | `Aktivna` | `true` | `statusDetails.status` is `ACTIVE` |
## Legal Forms
### Companies
| Slovenian Name | Abbr. | English Translation | Standardized |
| - | - | - | - |
| Družba z omejeno odgovornostjo | d.o.o. | Limited Liability Company | Limited Liability Company |
| Delniška družba | d.d. | Joint-Stock Company | Corporation |
| Komanditna družba | k.d. | Limited Partnership | Partnership |
| Družba z neomejeno odgovornostjo | d.n.o. | General Partnership | Partnership |
### Sole Traders
| Slovenian Name | Abbr. | English Translation | Standardized |
| - | - | - | - |
| Samostojni podjetnik | s.p. | Sole Proprietor | Sole Proprietorship |
### Associations & Institutes
| Slovenian Name | English Translation | Standardized |
| - | - | - |
| Društvo | Association | Nonprofit Organization |
| Zavod | Institute | Nonprofit Organization |
## Legal Representatives
Legal representatives come from the ePRS Authorized Representatives section. Filed titles are preserved and known labels have deterministic standardized roles. The registered manner and restrictions are returned when provided; the title alone does not establish individual or unrestricted signing authority.
| Slovenian Role | English Translation | Standardized Role |
| - | - | - |
| Predsednik uprave | Chairman of the Board | Chairman of the Board |
| Član uprave | Board Member | Board Member |
| Direktor | Director | Director |
| Prokurist | Procurator | Authorized Signatory |
| Likvidator | Liquidator | Liquidator |
For sole traders (s.p.), the owner is returned as a legal representative with the standardized role Owner.
## Other Key Persons
The same verification request can return supervisory-body appointments under `otherKeyPersons`. These oversight appointments are separate from any registered representative capacity held by the same person. Names, mailing addresses and appointment dates are returned where the register provides them.
| Office | Standardized Role |
| - | - |
| Member of the Supervisory Board / Član nadzornega sveta | Supervisory Board Member |
| Chair of the Supervisory Board / Predsednik nadzornega sveta | Chairman of the Board |
| Deputy Chair of the Supervisory Board / Namestnik predsednika nadzornega sveta | Vice Chairman of the Board |
## Shareholders
Shareholders are extracted from the ePRS portal for **d.o.o., k.d. and d.n.o. companies**. Both individual and corporate shareholders are supported, with equity interest amounts and percentages when available.
| Field | Description |
| - | - |
| `type` | Individual or Company |
| `sharePercentage` | Ownership percentage (computed from equity interests) |
| `nominalCapitalHeld` | Nominal capital held in EUR |
**Shareholders are available for d.o.o., k.d. and d.n.o. companies.** Joint-stock companies (d.d.) show "No entry" for Partners because shares are publicly traded. For sole traders (s.p.) and associations, the shareholders datapoint returns a not-applicable response and is not charged.
## Ultimate Beneficial Owners
The source is the official extract from the Register dejanskih lastnikov (RDL). Request `ultimateBeneficialOwners` in verification mode for structured data, or order `ultimateBeneficialOwnersCertificate` from `availableDocuments` for the source PDF. Delivery is asynchronous and manual, typically about 1-3 business days. Follow the existing request through webhooks or polling; do not submit repeated orders while it is pending. If the certificate cannot be obtained, the request reports an error rather than a successful empty result.
## Data Availability Matrix
| Data Type | d.o.o. | d.d. | k.d. / d.n.o. | s.p. | Associations |
| - | - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | ✅ Async | ✅ Async |
| Legal Representatives | ✅ | ✅ | ✅ | ✅ (owner) | ❌ |
| Other Key Persons | When recorded in the court register | When recorded in the court register | When recorded in the court register | ❌ | ❌ |
| Shareholders | ✅ | ❌ (publicly traded) | ✅ | ❌ (not applicable) | ❌ (not applicable) |
| Trade Register Extract | ✅ | ✅ | ✅ | ❌ | ❌ |
| Prefill Profile | ✅ | ✅ | ✅ | ✅ | ✅ |
| UBOs | ✅ Manual | ✅ Manual | ✅ Manual | ✅ Manual (subject to an RDL entry) | ✅ Manual (subject to an RDL entry) |
| Activity Codes | ❌ | ❌ | ❌ | ✅ | ✅ |
**Legend:** ✅ Available | ❌ Not Available | Async = Asynchronous processing | Manual = Delivered manually in about 1-3 business days
## Documents
| Document Type | API Category | Format | Notes |
| - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | Digitally signed PDF from AJPES. Available for all court-registered entities. |
| **Articles of Association** | `articlesOfAssociation` | PDF | Akt o ustanovitvi / Statut, from AJPES eObjave. Listed when published. |
| **Financial Statements** | `financialStatements` | Inline XBRL or PDF | Letno poročilo, from AJPES JOLP. Up to the last 5 fiscal years. |
| **Beneficial Ownership Extract** | `ultimateBeneficialOwnersCertificate` | PDF | Official RDL extract (Izpis iz Registra dejanskih lastnikov), obtained through a local partner. Delivered manually in about 1-3 business days. |
**Digitally signed PDFs.** The Trade Register Extract is a digitally signed PDF produced by AJPES. It contains full registration data including company details, legal representatives, shareholders, and equity interests.
## Example API Responses
All examples use **placeholder data**.
Query: `GET /v2/search?country=SI&query=Petrol`
```json theme={null}
[
{
"id": "5025796000",
"countryCode": "SI",
"legalName": "PETROL, Slovenska energetska družba, d.d., Ljubljana",
"address": { "city": "Ljubljana", "countryCode": "SI" },
"matchReason": { "matchType": "default" }
}
]
```
Query: `POST /v2/company` with `{ "id": "5142830000", "countryCode": "SI", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "5142830000",
"countryCode": "SI",
"identifiers": { "registrationNumber": "5142830000", "taxNumber": "47123456" },
"legalName": "PRIMER PODJETJE, svetovanje, d.o.o.",
"registrationDate": "2005-03-15",
"status": { "localName": "active", "active": true },
"legalForm": { "localName": "Družba z omejeno odgovornostjo", "englishTranslation": "Limited Liability Company", "standardized": "Limited Liability Company" },
"capital": { "amount": 7500, "currency": "EUR" },
"legalAddress": { "addressLine1": "Slovenska cesta 50", "city": "Ljubljana", "postalCode": "1000", "countryCode": "SI" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Direktor", "englishTranslation": "Director", "standardized": "Director" }, "startDate": "2005-03-15", "individual": { "name": { "fullName": "Janez NOVAK" } } }
]
}
```
Query: `POST /v2/company` with `{ "id": "5142830000", "countryCode": "SI", "dataPoints": ["shareholders"] }`
```json theme={null}
{
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"sharePercentage": 60,
"individual": { "name": { "fullName": "Janez NOVAK" } },
"nominalCapitalHeld": { "amount": 4500, "currency": "EUR" }
},
{
"entityId": "person_002",
"type": "individual",
"sharePercentage": 40,
"individual": { "name": { "fullName": "Ana HORVAT" } },
"nominalCapitalHeld": { "amount": 3000, "currency": "EUR" }
}
]
}
```
**Note:** Shareholders are available for d.o.o., k.d. and d.n.o. companies. d.d. (joint-stock) companies return empty shareholders as shares are publicly traded.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Trade Register Extract (digitally signed PDF) | Available for all court-registered entities |
| `articlesOfAssociation` | Articles of Association (Akt o ustanovitvi / Statut) | When published on AJPES eObjave |
| `financialStatements` | Annual reports (Letno poročilo) | Up to the last 5 fiscal years |
| `ultimateBeneficialOwnersCertificate` | Beneficial Ownership Extract (Izpis iz Registra dejanskih lastnikov) | Always listed, delivered manually in about 1-3 business days |
# Spain
Source: https://docs.topograph.co/essentials/spain
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Spain reference is on the [Spain country page](https://www.topograph.co/countries/es).
## Start here
This guide contains public integration notes for Spain. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Spain uses four data sources for company information. Structured profile data comes from a public registry portal, document retrieves from an authenticated electronic portal, supplementary data from the BORME (official commercial gazette), and foundations from the Registro de Fundaciones.
### Structured Profile Data
* **OpenData Registradores** (opendata.registradores.org). Operated by the Colegio de Registradores de la Propiedad y Mercantiles de Espana. This is the **primary source for structured company profile data**: company name (denominacion social), legal form (forma social), status (estado), NIF, IRUS, EUID, registered address (domicilio social), share capital, CNAE\_2009 activity code, legal representatives (administradores/cargos), and incorporation date (constitucion). Data is extracted from the registry.
### Document Retrieval
* **SEDE Electronica del Colegio de Registradores** (sede.registradores.org). The official electronic portal of the Colegio de Registradores. Used for **search/NIF resolution** (to obtain the IRUS identifier) and **document retrieval**: trade register extracts (Nota Informativa Mercantil) and financial statements (Deposito de Cuentas). Documents are retrieved with real-time pricing and delivered as PDFs.
Documents are priced in real time by the register, and prices vary with the size of a company's registry history. Documents priced **above €200** by the register are not offered by default: they are excluded from `availableDocuments` and cannot be ordered. This ceiling exists to keep document pricing predictable; it can be **raised on demand** for your account — contact us.
### BORME (Supplementary)
* **BORME** (Boletin Oficial del Registro Mercantil). Spain's official commercial gazette, published daily. Used as a **supplementary enrichment source** for company profiles (activity descriptions, director appointment dates) and as the source of **sole shareholder** information. When the register lists a company without an internal register reference, its company details and officer history come from BORME, provided a matching BORME record is found.
### Registro de Fundaciones (Foundations)
* **Registro de Fundaciones de Competencia Estatal** (Ministerio de Justicia). Spain's national register of state-level foundations. Foundations carry a NIF beginning with **G** and resolve through this register instead of the mercantile sources above. G is not only foundations (savings banks, many economic interest groupings, UTEs, pension funds and mutual guarantee companies carry it too): a G NIF the foundation register does not hold is served from the mercantile sources. It returns the legal name, NIF, registration number, constitution and registration dates, registered seat, purposes (fines), and the governing board (patronato) plus senior management as legal representatives. The legal form is **Fundación**. A printable **Foundation Register Extract** of the public profile is available under `documents.tradeRegisterExtract`.
**Foundations have no shareholders or beneficial owners.** The patronato is the governing body, not an ownership structure, so `shareholders` returns a `datapoint_not_applicable` outcome for foundations. Coverage is limited to foundations of state competence (those operating across more than one autonomous community). Foundations registered only in a regional (autonomous-community) register are not covered.
**Search uses SEDE for NIF resolution.** Name and NIF searches query SEDE to resolve the company's IRUS identifier, then OpenData is queried for structured profile data using that IRUS.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **NIF/CIF** | Letter + 7 digits + check character (digit or letter); the 7 digits can start with 0 | `A82511361` | Primary company identifier for all API operations. Returned as the register records it: a few register records hold a NIF with a character missing (e.g. `A5859731` for `A58597311`) |
| **DNI** (individual entrepreneurs) | 8 digits + check letter | `12345678Z` | For autonomous workers / sole proprietors |
| **VAT** | ES + NIF | `ESA82511361` | Automatically stripped to NIF for search |
| **Hoja registral** | Province code (1 or 2 letters) + hyphen + sheet number | `M-213521` | Mercantile Register sheet reference. A trailing control digit, as published in LEI/GLEIF records (`M-213521-8`), is accepted and stripped |
**Primary Identifier**: We use **NIF** (Numero de Identificacion Fiscal) as the company ID for all Spanish entities.
NIF is the standard Spanish tax identification number. For legal entities, the first letter indicates the legal form (Orden EHA/451/2008):
* **A**: Sociedad Anonima (SA)
* **B**: Sociedad Limitada (SL)
* **C**: Sociedad Colectiva
* **D**: Sociedad Comanditaria
* **E**: Comunidad de bienes and other entities without legal personality
* **F**: Cooperatives
* **G**: Associations and, before 2008, other entity types. Foundations carry G and resolve through the Registro de Fundaciones; a G NIF that is not a foundation is served from the mercantile register
* **H**: Comunidad de propietarios
* **J**: Sociedad Civil
* **N**: Foreign entities
* **P**: Local corporations
* **Q**: Public bodies
* **R**: Religious congregations and institutions
* **S**: State and regional administration bodies
* **U**: Temporary business associations (UTE)
* **V**: Other entity types
* **W**: Permanent establishments of non-resident entities
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| - | - | - | - |
| `nif` | Letter + 7 digits + check character (digit or letter), or 8 digits + check letter for a natural person | `A82511361` | All companies |
| `VAT` | NIF value (without ES prefix) | `A82511361` | All companies |
| `euid` | Country prefix + register code + entity number | `ES28.RM-M28038019301` | When published in the OpenData extract |
| `hoja` | Province code (1 or 2 letters) + hyphen + sheet number | `M-213521` | When the company is matched in the BORME gazette |
**VAT value in the API response does NOT include the ES prefix.** The `identifiers.VAT` field contains only the NIF value itself (e.g., `A82511361`). The country prefix `ES` is stored separately in `taxId.country`. This is consistent with how other EU countries handle VAT numbers.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the NIF (`nif`) or mercantile-register sheet (`hoja`) matches exactly one LEI through a GLEIF registration or validation reference.
A trailing control digit on a GLEIF hoja reference is ignored when matching it to the register sheet.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
Search automatically detects the identifier type and routes to the appropriate handler:
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By NIF/CIF | Letter + 7 digits + check character (digit or letter) | `A82511361` | Exact | Exact match returned first (matchType: id); other results may follow |
| By DNI | 8 digits + check letter | `12345678Z` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT Number | ES + NIF | `ESA82511361` | Exact | Exact match returned first (matchType: id, ES prefix stripped); other results may follow |
| By IRUS | 13 digits | `1000263762669` | Exact | Exact match returned first (matchType: id); other results may follow |
| By hoja registral | Province code + sheet number, optional control digit | `M-213521-8` | Exact | The company holding that Mercantile Register sheet (matchType: id). Useful for resolving the Spanish "Registration Authority Entity ID" found in LEI records |
| By Name | Text string | `"Telefonica"` | Fuzzy | Multiple results (deduplicated by NIF) |
**Search Performance:** Use identifier-based searches (NIF, VAT) for best performance and exact matching. Name searches query SEDE which returns paginated results that are deduplicated by NIF using a scoring algorithm that filters out branches and selects the main entity.
**Branch filtering:** When multiple IRUS entries exist for the same NIF (e.g., branches, offices, agencies), the system uses a scoring algorithm to select the main entity. Branch keywords such as SUCURSAL, URBANA, AGENCIA, OFICINA, and DELEGACION receive a heavy penalty. Current (active) status and shorter names (likely parent entities) receive a bonus.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Only foundations found by name are filtered (an extinguished foundation is removed). Company searches, and NIF lookups of foundations, return the entity whatever its status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **NIF is the primary ID** | Unlike some countries that use a separate registry number, Spain uses the NIF (tax ID) as the company identifier for all API operations. |
| **IRUS is internal only** | The IRUS (Identificador Unico del Registro de Sociedades) is a 13-digit internal registry identifier used for OpenData lookups and document retrieval. It should not be used as a query identifier by API consumers. |
| **VAT = ES + NIF** | Spanish VAT numbers are simply the NIF prefixed with "ES". Having a NIF does **not** guarantee the company is VAT-registered -- companies must be in the ROI (Registro de Operadores Intracomunitarios) for EU cross-border trade. VIES will return invalid for companies not in ROI. |
| **Document prices are dynamic** | Trade register extract and financial statement prices are fetched in real-time from SEDE and may vary. Prices appear in the `price` field before purchase. |
| **€200 document price ceiling** | Documents priced above €200 by the register (rare — a handful in two years, typically companies with very large registry histories) are not listed and cannot be ordered by default. The ceiling can be raised on demand per account. |
| **Shareholders only for unipersonal companies** | Ownership is public only when a company has a single member (socio único), published in BORME. That member is returned as one shareholder holding 100%. Companies with several shareholders publish no ownership, so `shareholders` is returned empty. |
| **No UBO data** | Ultimate Beneficial Owner data is not publicly available through the commercial registry. |
| **SEDE document retrieves** | Document retrieves are processed through the official SEDE portal of the Colegio de Registradores. |
| **"Liquidada" covers every closed sheet** | OpenData shows "Liquidada" for a liquidated company, a company absorbed in a merger and a closed branch alike, and keeps "Vigente" for a company still in liquidation. |
| **OpenData data extraction** | Company data is extracted from the OpenData Registradores portal. |
| **Multiple IRUS per NIF** | Large companies (e.g., banks) can have dozens of IRUS entries for the same NIF, representing branches and offices in different provinces. The NIF resolver scoring algorithm selects the main entity. |
| **Document delivery is asynchronous** | After retrieving a document from SEDE, there may be a short delay before the PDF is available for download. |
| **BORME as supplementary source** | BORME gazette data enriches company profiles with activity descriptions, director appointment dates, and sole shareholder information. |
## Company Status
Company status comes from the OpenData Registradores `Estado` field and from the acts published in the BORME. Every value is mapped **deterministically** to an `active` flag and a standardized status.
### Status Mapping
| Local Status | Source | Standardized Status | `active` | Notes |
| - | - | - | - | - |
| Vigente | OpenData, foundations | Active | `true` | Register sheet in force. A company in liquidation keeps this status until its sheet closes. |
| Liquidada | OpenData | Closed | `false` | Closed register sheet: liquidated, absorbed in a merger, or a closed branch. No closure reason is given. |
| En situación concursal | OpenData ("Concurso"), BORME | Under Insolvency Proceeding | `false` | Insolvency proceedings. |
| Disuelta | BORME | Closed | `false` | Dissolution act published. |
| Extinguida | BORME, foundations | Closed | `false` | Extinction act published, or extinction date recorded for a foundation. |
| Unknown | OpenData | -- | `false` | The register shows no state for the sheet. |
The BORME closes a company (dissolution, extinction, insolvency) but never reopens one: when the BORME records no such act, the register's own state stands. The status list is published on the [pricing page](https://topograph.co/pricing/es). A state the register shows that is not listed above keeps its wording and is classified automatically.
## Legal Forms
Spanish company law makes the legal form part of the company name ("S.L.", "Sociedad Anónima", "S.Coop.", ...), so the legal form is read from the name. When the name carries no form, it is read from the OpenData Registradores "Forma social", which is a register category ("Sociedades de responsabilidad limitada", "Sociedades anónimas", ...) and is returned as the form it denotes. Failing both, the first letter of the NIF gives it (A sociedad anónima, B sociedad limitada, C sociedad colectiva, D sociedad comanditaria, F cooperativa, J sociedad civil, U UTE, W permanent establishment); that letter also tells a sociedad colectiva from a sociedad civil when the name only says "S.C.". The mapping is **deterministic**: each form has a fixed English translation, standardized type and, where GLEIF lists one, an **ISO 20275 (ELF)** code.
| Spanish Legal Form (`localName`) | Abbreviation | English | Standardized | ISO 20275 |
| - | - | - | - | - |
| Sociedad Limitada | SL | Limited liability company | Limited Liability Company | `DP3Q` |
| Sociedad de Responsabilidad Limitada | SRL | Limited liability company | Limited Liability Company | `DP3Q` |
| Sociedad Limitada Nueva Empresa | SLNE | New enterprise limited liability company | Limited Liability Company | -- |
| Sociedad Limitada Profesional | SLP | Professional limited liability company | Limited Liability Company | `JB2M` |
| Sociedad de Responsabilidad Limitada Profesional | SRLP | Professional limited liability company | Limited Liability Company | `JB2M` |
| Sociedad Limitada Laboral | SLL | Employee-owned limited liability company | Limited Liability Company | `1G29` |
| Sociedad de Responsabilidad Limitada Laboral | SRLL | Employee-owned limited liability company | Limited Liability Company | `1G29` |
| Sociedad Limitada Laboral Profesional | SLLP | Professional employee-owned limited liability company | Limited Liability Company | -- |
| Sociedad Anónima | SA | Public limited company | Corporation | `5RDO` |
| Sociedad Anónima Deportiva | SAD | Sports public limited company | Corporation | -- |
| Sociedad Anónima Laboral | SAL | Employee-owned public limited company | Corporation | `R2L8` |
| Sociedad Anónima Profesional | SAP | Professional public limited company | Corporation | `AJ9U` |
| Societas Europaea | SE | European company | Corporation | `9FPZ` |
| Sociedad por Acciones Simplificada | SAS | Simplified joint-stock company | Corporation | -- |
| Sociedad de Inversión de Capital Variable | SICAV | Investment company with variable capital | Corporation | `8EHB` |
| Sociedad Comanditaria Simple | SCOM | Limited partnership | Partnership | `TDD5` |
| Sociedad Comanditaria por Acciones | SCOMPA | Partnership limited by shares | Partnership | `GJL1` |
| Sociedad Regular Colectiva | SRC | General partnership | Partnership | `S6X7` |
| Sociedad Civil | SC | Civil partnership | Partnership | `2W1A` |
| Sociedad Civil Profesional | SCP | Professional civil partnership | Partnership | `2W1A` |
| Unión Temporal de Empresas | UTE | Temporary business association | Partnership | -- |
| Agrupación de Interés Económico | AIE | Economic interest grouping | Partnership | `I2WU` |
| Agrupación Europea de Interés Económico | AEIE | European economic interest grouping | Partnership | `BI3B` |
| Sociedad Cooperativa | SCOOP | Cooperative | Cooperative | `1QU8` |
| Sociedad de Garantía Recíproca | SGR | Mutual guarantee company | Other | `IAS6` |
| Fondo de Inversión | FI | Investment fund | Other | `S0Z5` |
| Fondo de Pensiones | FP | Pension fund | Other | `FH4R` |
| Sociedad Mercantil Estatal | SME | State-owned company | Government-Owned Entity | -- |
| Emprendedor de Responsabilidad Limitada | ERL | Limited liability entrepreneur | Sole Proprietorship | `IT6N` |
| Sucursal en España | SUCURSAL | Branch in Spain | Branch or Representative Office | -- |
| Besloten Vennootschap | BV | Private limited company (Netherlands / Belgium) | Limited Liability Company | -- |
| Naamloze Vennootschap | NV | Public limited company (Netherlands / Belgium) | Corporation | -- |
| Limited Company | LTD | Private limited company | Limited Liability Company | -- |
| Caja de Ahorros | CAJA | Savings bank | Other | `4S57` |
| Cooperativa de Crédito | SCOOPCRED | Credit cooperative | Cooperative | `SS0L` |
| Fundación | FUNDACION | Foundation | Nonprofit Organization | `MDOL` |
Single-member companies are returned under their form: an "S.L.U." is a Sociedad Limitada and an "S.A.U." a Sociedad Anónima. A company whose name and register category both carry no recognisable form keeps the register's wording, with a standardized type.
## Legal Representatives and Other Key Persons
Legal representatives come from the OpenData Registradores "Administradores y cargos" section, the BORME appointment acts and, for foundations, the Registro de Fundaciones. Registered administrators, delegated directors, attorneys and liquidators appear under `legalRepresentatives`. Office-only board members, secretaries, auditors, foundation trustees, substitute officers and owners appear under `otherKeyPersons`. A board or trustee appointment does not by itself establish individual signing authority. General managers and insolvency administrators also require the applicable mandate or court regime; an office label alone is insufficient. The register may omit the detailed signing mandate, restrictions or co-signatories.
The registers print the same office many ways (BORME abbreviates it, OpenData capitalises it at will, the foundation register uses feminine forms and ordinals such as "Presidenta" or "Vicepresidente 1º"). Each is returned under one sentence-case label, with a fixed English translation and standardized role:
| Spanish Role (`localName`) | English | Standardized | Response list |
| - | - | - | - |
| Administrador | Director | Director | `legalRepresentatives` |
| Administrador único | Sole director | Director | `legalRepresentatives` |
| Administrador solidario | Joint and several director | Director | `legalRepresentatives` |
| Administrador mancomunado | Joint director | Director | `legalRepresentatives` |
| Administrador conjunto | Joint director | Director | `legalRepresentatives` |
| Administrador suplente | Alternate director | Other | `otherKeyPersons` |
| Administrador solidario suplente | Alternate joint and several director | Other | `otherKeyPersons` |
| Administrador mancomunado suplente | Alternate joint director | Other | `otherKeyPersons` |
| Consejero | Board member | Board Member | `otherKeyPersons` |
| Consejero delegado | Managing director | Managing Director | `legalRepresentatives` |
| Consejero delegado solidario | Joint and several managing director | Managing Director | `legalRepresentatives` |
| Consejero delegado mancomunado | Joint managing director | Managing Director | `legalRepresentatives` |
| Consejero delegado mancomunado solidario | Joint and several managing director | Managing Director | `legalRepresentatives` |
| Consejero ejecutivo | Executive director | Other | `otherKeyPersons` |
| Consejero dominical | Proprietary director | Non-Executive Director | `otherKeyPersons` |
| Consejero independiente | Independent director | Non-Executive Director | `otherKeyPersons` |
| Consejero coordinador | Lead independent director | Non-Executive Director | `otherKeyPersons` |
| Consejero externo | External director | Non-Executive Director | `otherKeyPersons` |
| Consejero suplente | Alternate board member | Board Member | `otherKeyPersons` |
| Consejero rector | Member of the governing council | Board Member | `otherKeyPersons` |
| Vocal | Board member | Board Member | `otherKeyPersons` |
| Presidente | Chairman | Chairman of the Board | `otherKeyPersons` |
| Vicepresidente | Vice-chairman | Vice Chairman of the Board | `otherKeyPersons` |
| Secretario | Secretary | Secretary | `otherKeyPersons` |
| Secretario no consejero | Non-director secretary | Secretary | `otherKeyPersons` |
| Vicesecretario | Vice-secretary | Secretary | `otherKeyPersons` |
| Vicesecretario no consejero | Non-director vice-secretary | Secretary | `otherKeyPersons` |
| Tesorero | Treasurer | Other | `otherKeyPersons` |
| Suplente | Alternate | Other | `otherKeyPersons` |
| Miembro del consejo rector | Member of the governing council | Board Member | `otherKeyPersons` |
| Miembro del consejo rector suplente | Alternate member of the governing council | Board Member | `otherKeyPersons` |
| Presidente del consejo rector | Chairman of the governing council | Chairman of the Board | `legalRepresentatives` |
| Vicepresidente del consejo rector | Vice-chairman of the governing council | Vice Chairman of the Board | `otherKeyPersons` |
| Secretario del consejo rector | Secretary of the governing council | Secretary | `otherKeyPersons` |
| Tesorero del consejo rector | Treasurer of the governing council | Other | `otherKeyPersons` |
| Miembro del comité ejecutivo | Member of the executive committee | Other | `otherKeyPersons` |
| Presidente del comité ejecutivo | Chairman of the executive committee | Other | `otherKeyPersons` |
| Miembro del comité de auditoría | Member of the audit committee | Auditor | `otherKeyPersons` |
| Miembro del comité de control | Member of the control committee | Supervisor | `otherKeyPersons` |
| Presidente del comité de control | Chairman of the control committee | Other | `otherKeyPersons` |
| Secretario del comité de control | Secretary of the control committee | Secretary | `otherKeyPersons` |
| Miembro de la comisión de control | Member of the control commission | Supervisor | `otherKeyPersons` |
| Director | Manager | Other | `otherKeyPersons` |
| Director general | General manager | C-Level Executive | `otherKeyPersons` |
| Director gerente | Managing director | Other | `otherKeyPersons` |
| Gerente | Manager | Other | `otherKeyPersons` |
| Gerente único | Sole manager | Other | `otherKeyPersons` |
| Apoderado | Attorney-in-fact | Authorized Signatory | `legalRepresentatives` |
| Apoderado general | General attorney-in-fact | Authorized Signatory | `legalRepresentatives` |
| Apoderado solidario | Joint and several attorney-in-fact | Authorized Signatory | `legalRepresentatives` |
| Apoderado mancomunado | Joint attorney-in-fact | Authorized Signatory | `legalRepresentatives` |
| Apoderado mancomunado solidario | Joint and several attorney-in-fact | Authorized Signatory | `legalRepresentatives` |
| Apoderado conjunto | Joint attorney-in-fact | Authorized Signatory | `legalRepresentatives` |
| Apoderado de sucursal | Branch attorney-in-fact | Authorized Signatory | `legalRepresentatives` |
| Representante | Representative of a corporate director | Other | `legalRepresentatives` |
| Representante de sucursal | Branch representative | Authorized Signatory | `legalRepresentatives` |
| Representante fiscal | Tax representative | Other | `otherKeyPersons` |
| Representante del plan | Pension plan representative | Other | `otherKeyPersons` |
| Auditor | Auditor | Auditor | `otherKeyPersons` |
| Auditor de cuentas | Statutory auditor | Auditor | `otherKeyPersons` |
| Auditor titular | Statutory auditor | Auditor | `otherKeyPersons` |
| Auditor suplente | Alternate auditor | Auditor | `otherKeyPersons` |
| Auditor individual | Individual auditor | Auditor | `otherKeyPersons` |
| Auditor conjunto | Joint auditor | Auditor | `otherKeyPersons` |
| Auditor de cuentas consolidadas | Auditor of the consolidated accounts | Auditor | `otherKeyPersons` |
| Auditor de cuentas consolidadas conjunto | Joint auditor of the consolidated accounts | Auditor | `otherKeyPersons` |
| Auditor suplente de cuentas consolidadas | Alternate auditor of the consolidated accounts | Auditor | `otherKeyPersons` |
| Liquidador | Liquidator | Liquidator | `legalRepresentatives` |
| Liquidador único | Sole liquidator | Liquidator | `legalRepresentatives` |
| Liquidador solidario | Joint and several liquidator | Liquidator | `legalRepresentatives` |
| Liquidador mancomunado | Joint liquidator | Liquidator | `legalRepresentatives` |
| Liquidador suplente | Alternate liquidator | Other | `otherKeyPersons` |
| Liquidador judicial | Court-appointed liquidator | Liquidator | `legalRepresentatives` |
| Liquidador concursal | Insolvency liquidator | Liquidator | `legalRepresentatives` |
| Administrador concursal | Insolvency administrator | Other | `otherKeyPersons` |
| Representante del administrador concursal | Representative of the insolvency administrator | Other | `otherKeyPersons` |
| Administrador judicial | Court-appointed administrator | Administrator | `legalRepresentatives` |
| Interventor | Court-appointed supervisor | Supervisor | `otherKeyPersons` |
| Interventor judicial | Court-appointed supervisor | Supervisor | `otherKeyPersons` |
| Mediador concursal | Insolvency mediator | Other | `otherKeyPersons` |
| Socio | Partner | Other | `otherKeyPersons` |
| Socio fundador | Founding partner | Other | `otherKeyPersons` |
| Socio miembro | Member partner | Other | `otherKeyPersons` |
| Socio profesional | Professional partner | Other | `otherKeyPersons` |
| Socio único profesional | Sole professional partner | Other | `otherKeyPersons` |
| Entidad gestora | Management company | Manager | `legalRepresentatives` |
| Entidad depositaria | Depositary | Other | `otherKeyPersons` |
| Entidad promotora | Sponsor | Other | `otherKeyPersons` |
| Entidad de registro contable | Book-entry registration entity | Other | `otherKeyPersons` |
| Comisario | Bondholders’ commissioner | Other | `otherKeyPersons` |
| Delegado | Delegate | Other | `otherKeyPersons` |
| Promotor | Promoter | Other | `otherKeyPersons` |
| Patrono | Trustee | Board Member | `otherKeyPersons` |
| Secretario no patrono | Non-trustee secretary | Secretary | `otherKeyPersons` |
An office printed in a form not listed above keeps the register's wording, and its standardized role is classified automatically.
## Shareholders
Shareholders are included in the company data block. Spanish ownership is public only for **unipersonal** companies (SLU, SAU): when BORME records a sole member (socio único), that member is returned as a single shareholder holding **100%**. Companies with several shareholders publish no ownership information, so `shareholders` is returned empty for them. For foundations, `shareholders` returns a `datapoint_not_applicable` outcome.
## Activity Code Mapping
Spain uses the **CNAE\_2009** (Clasificacion Nacional de Actividades Economicas) classification, which is the Spanish national adaptation of the European NACE standard. The system maps activity codes across three levels:
```
CNAE_2009 2009 (Spanish) -> NACE Rev. 2.1 (European) -> ISIC Rev. 5 (International)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **CNAE\_2009** | OpenData Registradores | `6201` | No (official) |
| **NACE** | Derived from the CNAE\_2009 code, then converted to NACE Rev. 2.1 | `62.10` | No |
| **ISIC** | Derived from NACE through the official NACE/ISIC correspondence | `621` | No (normally) |
OpenData Registradores publishes the CNAE\_2009 code only. The NACE code is derived from it and converted to NACE Rev. 2.1, and the ISIC Rev. 5 code comes from the official NACE to ISIC correspondence, so both normally carry `isAIInferred: false`. AI matching is used only as a last resort when no formal correspondence exists, and the `isAIInferred` flag is then `true`. Each classification is published once, under `CNAE_2009`, `NACE` or `ISIC`.
**Main activity:** OpenData Registradores publishes a single CNAE\_2009 code per company (the "actividad principal"), so it is by definition the main activity. The CNAE\_2009 and NACE entries carry `isMainActivity: true`, and the ISIC code derived from them inherits the flag.
### Activity Code Fields
OpenData Registradores provides the CNAE\_2009 code. NACE and ISIC are derived from it:
| Field | Classification | Example Value |
| - | - | - |
| CNAE\_2009 | CNAE\_2009 2009 | `6201 Actividades de programacion informatica` |
| NACE | NACE Rev. 2.1 | `62.10 Computer programming activities` |
| ISIC | ISIC Rev. 5 | `621 Computer programming activities` |
## Data Availability Matrix
| Data Type | Commercial Companies | Notes |
| - | - | - |
| Company Profile | ✅ Async | Full structured data from OpenData Registradores |
| Legal Representatives | ✅ | Directors and officers from OpenData |
| Other Key Persons | ✅ | Board, secretarial, audit, trustee, substitute and ownership appointments without established individual representation |
| Shareholders | ✅ (sole shareholder only) | Sole member of a unipersonal company, from BORME. Empty for companies with several shareholders |
| Ultimate Beneficial Owners | ❌ | Not publicly available |
| Establishments | ❌ | Not available through OpenData |
| Activity Codes | ✅ | CNAE\_2009 from OpenData, NACE and ISIC derived through official correspondences |
| Trade Register Extract | ✅ (Paid) | PDF from SEDE, real-time pricing |
| Financial Statements | ✅ (Paid) | PDF per fiscal year from SEDE |
**Legend:** ✅ Available | ❌ Not Available | Async = Asynchronous processing
## Documents by Company Type
Documents are retrieved from **SEDE Electronica del Colegio de Registradores** with real-time pricing.
### Commercial Companies (NIF)
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Nota Informativa Mercantil (Trade Register Extract)** | `tradeRegisterExtract` | PDF | ✅ All companies | Real-time pricing from SEDE |
| **Deposito de Cuentas (Financial Statements)** | `financialStatements[]` | PDF | ✅ When filed | Per fiscal year, real-time pricing |
**Document prices are fetched in real-time** from SEDE and displayed in the `price` field before purchase. For trade register extracts, the following data segments are included: capital, social representation, administrators, and attorneys-in-fact.
**Financial statement availability varies.** Not all companies file their annual accounts (Deposito de Cuentas) with the Registro Mercantil. Available fiscal years are listed via a dropdown on SEDE. Each year's price is determined individually.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "ES", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"] }`
```json theme={null}
{
"company": {
"id": "A12345678",
"countryCode": "ES",
"identifiers": {
"nif": "A12345678",
"VAT": "A12345678",
"euid": "ES28.RM-M28038019301"
},
"taxId": {
"type": "eu_vat",
"value": "A12345678",
"country": "ES",
"verification": {
"status": "verified",
"verifiedName": "EXAMPLE CORP SA",
"verifiedAddress": "CALLE GRAN VIA 28, MADRID",
"consultationNumber": "WAPIXXXXXXXXXXXX"
}
},
"legalName": "Example Corp SA",
"registrationDate": "2010-05-15",
"status": {
"localName": "Vigente",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Sociedad Anónima",
"standardized": "Corporation",
"iso20275Code": "5RDO"
},
"capital": {
"amount": 60000,
"currency": "EUR"
},
"activities": {
"CNAE_2009": [{ "code": "6201", "description": "Actividades de programacion informatica", "isAIInferred": false }],
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": false }],
"ISIC": [{ "code": "621", "description": "Computer programming activities", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "Calle Gran Via 28",
"city": "Madrid",
"postalCode": "28013",
"countryCode": "ES"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Administrador único", "standardized": "Director" },
"individual": { "name": { "fullName": "Carlos Garcia Lopez" } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "B98765432",
"countryCode": "ES",
"identifiers": {
"nif": "B98765432",
"VAT": "B98765432"
},
"legalName": "Servicios Digitales SL",
"registrationDate": "2018-11-20",
"status": {
"localName": "Vigente",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Sociedad Limitada",
"standardized": "Limited Liability Company",
"iso20275Code": "DP3Q"
},
"capital": {
"amount": 3000,
"currency": "EUR"
},
"activities": {
"CNAE_2009": [{ "code": "7022", "description": "Otras actividades de consultoria de gestion empresarial", "isAIInferred": false }],
"NACE": [{ "code": "70.20", "description": "Business and other management consultancy activities", "isAIInferred": false }],
"ISIC": [{ "code": "7020", "description": "Business and other management consultancy activities", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "Passeig de Gracia 100",
"city": "Barcelona",
"postalCode": "08008",
"countryCode": "ES"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Administrador solidario", "standardized": "Director" },
"individual": { "name": { "fullName": "Ana Martinez Ruiz" } }
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Administrador solidario", "standardized": "Director" },
"individual": { "name": { "fullName": "Pedro Sanchez Diaz" } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "B55667788",
"countryCode": "ES",
"identifiers": {
"nif": "B55667788",
"VAT": "B55667788"
},
"legalName": "Comercio Antiguo SL",
"registrationDate": "2005-03-10",
"status": {
"localName": "Extinguida",
"active": false,
"statusDetails": { "status": "CLOSED" }
},
"legalForm": {
"localName": "Sociedad Limitada",
"standardized": "Limited Liability Company",
"iso20275Code": "DP3Q"
},
"capital": {
"amount": 3000,
"currency": "EUR"
},
"activities": {
"CNAE_2009": [{ "code": "4771", "description": "Comercio al por menor de prendas de vestir en establecimientos especializados", "isAIInferred": false }],
"NACE": [{ "code": "47.71", "description": "Retail sale of clothing", "isAIInferred": false }],
"ISIC": [{ "code": "4771", "description": "Retail sale of clothing, footwear and leather articles", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "Calle Serrano 45",
"city": "Madrid",
"postalCode": "28001",
"countryCode": "ES"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Liquidador", "standardized": "Liquidator" },
"individual": { "name": { "fullName": "Maria Lopez Fernandez" } }
}
]
}
```
**Note:** Closed companies have `active: false` and status `Extinguida`. Documents may still be available from SEDE.
```json theme={null}
{
"company": {
"id": "B11223344",
"countryCode": "ES",
"identifiers": {
"nif": "B11223344",
"VAT": "B11223344"
},
"taxId": {
"type": "eu_vat",
"value": "B11223344",
"country": "ES",
"verification": {
"status": "unverified"
}
},
"legalName": "Pequena Empresa SL",
"registrationDate": "2020-07-01",
"status": {
"localName": "Vigente",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Sociedad Limitada",
"standardized": "Limited Liability Company",
"iso20275Code": "DP3Q"
}
}
}
```
**Note:** VAT status is `unverified` because the company is not registered in the ROI (Registro de Operadores Intracomunitarios). This is common for small companies that do not engage in EU cross-border trade.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Nota Informativa Mercantil (PDF) | Real-time pricing from SEDE |
| `financialStatements[]` | Deposito de Cuentas (PDF) | Per fiscal year, real-time pricing |
**Trade Register Extract segments included:**
* Capital social (share capital)
* Representacion social (social representation)
* Administradores (directors)
* Apoderados (attorneys-in-fact)
## Data Source Priority & Routing
For a given entity, the system follows this resolution flow:
**Company Profile Resolution Flow:**
1. **SEDE search by NIF** -- Resolves the NIF to an IRUS identifier and returns search results. The resolver selects the main entity (filtering out branches).
2. **OpenData lookup by IRUS** -- Retrieves structured data from OpenData Registradores (name, legal form, status, address, capital, CNAE\_2009, officers, registration date). If SEDE lists the company but gives no IRUS, company details and officer history come from BORME instead, when a matching BORME record is found.
3. **Enrichment** -- Legal form, status and roles are mapped deterministically from the register's values; the address is AI-parsed into components. NACE and ISIC codes are derived from the CNAE\_2009 code through the official correspondences.
4. **VIES VAT validation** -- A qualified VIES check validates the VAT number and obtains a consultation number (legal proof for audits).
**Document Resolution Flow:**
Documents are retrieved through the official SEDE portal of the Colegio de Registradores. Available document types include trade register extracts (Nota Informativa Mercantil) and financial statements (Deposito de Cuentas). Documents are delivered as PDFs after retrieval processing.
### Attribute-Level Source Mapping
| Attribute | Source | Notes |
| - | - | - |
| Company name (denominacion social) | **OpenData** | Official registry name |
| Legal form | **OpenData** and **BORME** (company name, then forma social, then NIF letter) | Deterministic: standardized type + ISO 20275 |
| Status (estado) | **OpenData**; **BORME** closing acts take precedence | Deterministic: standardized status + `active` flag |
| Registered address (domicilio social) | **OpenData** | AI-enriched for structured address components |
| Share capital | **OpenData** | AI-formatted for standardization |
| CNAE\_2009 activity code | **OpenData** | Official, never AI-inferred |
| NACE / ISIC activity codes | **Derived** | From the CNAE\_2009 code through the official correspondences; AI only as a last resort |
| Legal representatives | **OpenData** | From cargos/administradores; roles mapped deterministically |
| Registration date (constitucion) | **OpenData** | Company formation date |
| NIF | **OpenData** / **SEDE** | From search results |
| IRUS | **SEDE** | Resolved during NIF search; internal reference, not returned in `identifiers` |
| EUID | **OpenData** | European Unique Identifier, when available |
| VAT verification | **VIES** | Qualified check with consultation number |
# Subsidiaries
Source: https://docs.topograph.co/essentials/subsidiaries-extraction
Surface the companies in which the queried company holds equity
`subsidiaries` is a first-class data block in the Topograph data model. Where shareholders describe who owns the queried company (the upstream edge), subsidiaries describe what the queried company owns (the downstream edge).
A subsidiary record is always a company. It carries the equity stake the queried company holds in it, plus optional details such as voting rights, nominal capital held, and acquisition or end dates. Classification (controlled, associated, minority investment) is left to the caller. Use the exact percentage or disclosed interval when available.
## Supported Countries
`subsidiaries` is a separate data block from `company` in every country below, and it is available in verification mode only. Where it is AI-extracted from a filed financial statement, availability follows the company's filing obligation rather than our coverage: a company that filed no accounts returns an empty list, and small or micro-entity filers are usually exempt from the disclosure that carries the data.
| Country | Code | Source | Country guide |
| - | - | - | - |
| Belgium | BE | Participating-interests section of the annual accounts filed at the National Bank of Belgium | [Belgium guide](https://www.topograph.co/countries/be#subsidiaries) |
| France | FR | "Filiales et participations" annex of the bilan filed at INPI | [France guide](https://www.topograph.co/countries/fr#subsidiaries) |
| Germany | DE | Shareholdings list (Anteilsbesitzliste) in the annual accounts, or the subsidiaries list in consolidated group accounts | [Germany guide](https://www.topograph.co/countries/de#subsidiaries) |
| Italy | IT | Current equity participations recorded in the Registro Imprese | [Italy guide](https://www.topograph.co/countries/it#subsidiaries) |
| United Kingdom | GB | Subsidiary undertakings note in the accounts filed at Companies House | [UK guide](https://www.topograph.co/countries/gb#subsidiaries) |
A country not listed here does not serve `subsidiaries`: requesting it returns `datapoint_not_supported`, not an empty list. Requesting it in prefill mode for a country that does serve it returns `fast_source_unavailable`, because the data comes from a filing that has to be fetched and parsed. More countries follow the same shape and will be added as their registers expose participation data. Check [Coverage and pricing](/essentials/coverage-and-pricing) for the live list.
## Example Request
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "IT",
"id": "04046761203",
"dataPoints": ["subsidiaries"]
}'
```
## Example Response
```json theme={null}
{
"request": {
"requestId": "uuid-v4",
"companyId": "04046761203",
"countryCode": "IT",
"dataStatus": {
"dataPoints": {
"subsidiaries": { "status": "succeeded" }
}
}
},
"subsidiaries": [
{
"company": {
"legalName": "Ca'Zampa SRL",
"countryCode": "IT",
"id": "12345670123",
"identifiers": { "codiceFiscale": "12345670123" }
},
"sharePercentage": 100,
"numberOfShares": 1000,
"nominalCapitalHeld": { "amount": 10000, "currency": "EUR" },
"acquisitionDate": "2020-06-15"
},
{
"company": {
"legalName": "Joint Venture SPA",
"countryCode": "IT",
"id": "98765430456"
},
"sharePercentage": 25,
"numberOfShares": 250,
"nominalCapitalHeld": { "amount": 25000, "currency": "EUR" },
"acquisitionDate": "2018-09-01"
}
]
}
```
## Field reference
| Field | Type | Notes |
| - | - | - |
| `company` | object | The owned company (`legalName`, `countryCode`, `id`, `identifiers`). |
| `sharePercentage` | number | Exact direct equity stake (0–100). Omitted when only a range is disclosed. |
| `sharePercentageRange` | object | Disclosed direct equity interval: `lower`, `upper` (0–100), and optional `lowerInclusive` / `upperInclusive` flags. |
| `totalSharePercentage` | number | Direct + indirect stake when the source can compute it. |
| `votingRightsPercentage` | number | Voting power, when it differs from equity. |
| `numberOfShares` | number | Absolute share or quota count. |
| `nominalCapitalHeld` | MonetaryAmount | Total nominal value of the equity held. |
| `paidInAmount` | MonetaryAmount | Total amount actually paid for the equity. |
| `acquisitionDate` | ISO 8601 date | When the participation was acquired. |
| `endDate` | ISO 8601 date | When the participation ended (sale, dissolution). Omitted for current participations. |
## Ownership intervals and missing percentages
When the source discloses an interval, `sharePercentageRange` preserves it and `sharePercentage` is omitted. For example, "more than 25% and at most 50%" is returned as:
```json theme={null}
{
"company": { "legalName": "Example Ltd", "countryCode": "GB" },
"sharePercentageRange": {
"lower": 25,
"upper": 50,
"lowerInclusive": false,
"upperInclusive": true
}
}
```
`lowerInclusive` and `upperInclusive` indicate whether the corresponding endpoint is included. They are omitted when the source does not specify inclusivity. A one-sided threshold uses the percentage limits for the other bound: "more than 75%" has a lower bound of 75 (excluded) and an upper bound of 100 (included).
Exact values use only `sharePercentage`, including an explicitly disclosed 0% or 100%. When neither an exact percentage nor an interval is disclosed, both fields are omitted and the company can still appear in the list. Treat missing percentages as unknown, never as zero. No midpoint or endpoint estimate is supplied for an interval.
## Best practices
Topograph does not flag participations as "controlled" or "associated". Apply your own threshold (commonly 50% for control, 20% for significant influence) so the rule stays explicit in your code. For a range, classify only when the whole interval satisfies your rule. If it crosses your threshold or endpoint inclusivity is needed but unspecified, the percentage alone cannot establish the classification.
Request `shareholders` and `subsidiaries` together to see both ends of the ownership graph for the queried company.
Records with a non-empty `endDate` describe past holdings. Filter them out unless you need historical context.
# Sweden
Source: https://docs.topograph.co/essentials/sweden
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Sweden reference is on the [Sweden country page](https://www.topograph.co/countries/se).
## Start here
This guide contains public integration notes for Sweden. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
All company data is sourced from **Bolagsverket** (Swedish Companies Registration Office), the official government agency responsible for registering companies, partnerships, associations, and other legal entities in Sweden. Bolagsverket was established in 2004 when it took over registration duties from the Patent and Registration Office (PRV).
The `company` datapoint also checks the Swedish VAT number against **VIES** (EU VAT Information Exchange System) and adds the verified tax ID to the company.
Three Bolagsverket services are used:
* **Company register** -- Company name, legal form, status, registration and incorporation dates, registered address, share capital, activity description, and officers (funktionarer). Used for `company`, `legalRepresentatives` and `otherKeyPersons`.
* **Open data** -- Basic company information used for search by identifier, and the digitally filed annual reports. The annual reports are listed under `financialStatements` and are what the `shareholders` datapoint reads.
* **Document ordering service** -- The certified trade register extract, articles of association, statutes, minutes, UBO extract, assignment certificates, and the annual report compilation. Which documents can be ordered depends on the company's legal form.
### Ultimate Beneficial Owners
UBO data is extracted by AI from the **UBO Extract** (Registret over verkliga huvudman) document ordered from Bolagsverket. Bolagsverket does not publish UBO data in a structured form.
## Company Identifiers
`company.identifiers.euid` is an optional European Unique Identifier. Domestic aktiebolag (AB) with an organisation number. Personal identity numbers are excluded. Example: `SEBOLREG.5560360793`. It is returned as an output identifier and cannot be used as a search input. See [EUID coverage and interpretation](/essentials/euid).
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Organisationsnummer** | 10 digits (`NNNNNN-NNNN` or `NNNNNNNNNN`), third digit 2 or higher, last digit a Luhn check digit | `5560125790` or `556012-5790` | Primary identifier for companies. Hyphen is optional. |
| **Personnummer** | 12 digits (`YYYYMMDDNNNN` or `YYYYMMDD-NNNN`) | `196405250314` or `19640525-0314` | Used by sole traders (enskild firma). Issued by Skatteverket. Hyphen is optional. |
| **VAT number** | `SE` + 12 digits | `SE556012579001` | Search only (not accepted by `/v2/company`). Company VAT numbers only: SE + organisationsnummer + `01`. For a sole trader, search with the 12-digit personnummer. |
**Organisationsnummer vs personnummer:** Organisation numbers have digits 3-4 (the "month" position) >= 20, distinguishing them from personnummers where those digits are 01-12 (a real birth month). For example, `556012-5790` has "60" in positions 3-4 — an organisation number. `196405250314` has "64" — a personnummer. The search request handles both automatically.
### Identifiers in API Response
| Identifier | Format | Example | Notes |
| - | - | - | - |
| `id` | 10 or 12 digits (no hyphen) | `5560125790` | For companies: 10 digits. For sole traders: 12-digit personnummer. |
| `organizationNumber` | 10 digits | `5560125790` | Returned for companies only. |
| `personalIdentityNumber` | 12 digits | `196405250314` | Returned for sole traders instead of `organizationNumber`. |
| `VAT` | 12 digits (no `SE` prefix) | `556012579001` | Companies: organisationsnummer + `01`. Sole traders: century-stripped personnummer (10 digits) + `01`. |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the organisation number (`organizationNumber`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Organisationsnummer | 10 digits (with or without hyphen) | `5560125790` or `556012-5790` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Personnummer | 12 digits (with or without hyphen) | `196405250314` or `19640525-0314` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT number (companies only) | `SE` + 12 digits | `SE556012579001` | Exact | Exact match returned first (matchType: id); other results may follow |
| By company name | Text string | `"Volvo"` | Contains | Multiple results |
**Identifier normalization:** The search request reads the organisationsnummer out of a company VAT number (the 10 digits between `SE` and the trailing `01`), removes hyphens from organisation numbers and personnummers, and detects sole traders automatically by the personnummer format (12 digits, birth-month digits 01-12 in positions 3-4). A sole trader's VAT number does not resolve, because it carries only 10 of the personnummer's 12 digits: search with the full personnummer instead.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Registration-number lookups drop companies that have been struck off the register; name searches return companies whatever their status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Sole traders use personnummer as identifier** | Sole traders (enskild firma) are registered at Bolagsverket with their personal identity number (personnummer, 12 digits YYYYMMDDNNNN) instead of an organisationsnummer. Pass the personnummer directly as the identifier. The response returns `personalIdentityNumber` in `identifiers` and omits company-specific fields like share capital and board members. |
| **Natural persons return `notFound` on company profile** | A personnummer that belongs to a natural person with no registered business at Bolagsverket returns `resource_not_found` on the `company` datapoint. This is distinct from a registered sole trader (enskild firma) with the same personnummer format but an active Bolagsverket registration. Natural persons can still have purchasable documents (current assignments, prohibition register, insolvency register). |
| **Shareholders come from the annual report, when disclosed** | Bolagsverket does not publish a share register: ownership is restricted to authorities and the company's own shareholders. Some annual reports voluntarily disclose ownership in the ownership note, and that is what the `shareholders` datapoint reads. Disclosure is not required, so most companies return none. Sole traders (enskild firma) have no share capital at all, so the datapoint returns an explicit not-applicable response for them. |
| **UBO = control extent, not ownership** | Bolagsverket reports **control extent** (Omfattning) for UBOs, not ownership percentage. Multiple UBOs can each show 100% control. This reflects influence over the company through shares, agreements, or intermediary entities -- not economic stake. |
| **All activity codes are AI-inferred** | Sweden does not assign standard classification codes. The `verksamhetsbeskrivning` (activity description) is a free-text field in Swedish, and all ISIC/NACE codes are derived by AI. `isAIInferred` is always `true`. |
| **Active = empty status array** | An active company has an **empty** `organisationsstatusar` array from Bolagsverket. Any status entry means the company is inactive. This is the opposite of most registries which explicitly mark companies as active. |
| **Status code system is complex** | Bolagsverket uses dozens of numeric status codes across two categories: `AvregistreradOrganisationstyp` (struck off the register -- codes 21, 31, 37, 41, 51, 53, 60-64, 70, 73, 74, 91, 98) and `AvvecklingsOmstruktureringsforfarande` (ongoing settlement/restructuring -- codes 11, 20, 32, 45, 49, 75, 80, 85, 90, 91, 96). |
| **All documents are in Swedish** | All documents from Bolagsverket (annual reports, trade register extracts, articles of association, UBO extract, etc.) are written in Swedish. English certificates require login and are not available programmatically. |
| **Annual reports: individual filings vs compilation** | Annual reports come in two forms: (1) individual digitally filed reports, one per year (ZIP containing the original filing), and (2) a compilation of all years ordered from Bolagsverket (single PDF). |
| **Legal form is AI-enriched** | Local Swedish legal forms are deterministically mapped to English translations via a static codelist. However, the `standardized` form and `iso20275Code` are AI-enriched. |
| **Share capital in SEK only** | Share capital for AB companies is always denominated in Swedish Kronor (SEK). |
| **Purchasable documents vary by legal form** | The available purchasable documents depend on the company's legal form code. For example, "Articles of Association" (Bolagsordning) applies to AB companies, while "Statutes" (Stadgar) applies to associations. |
| **Ordered documents are not instant** | Certificates, articles of association, statutes, minutes, the UBO extract and the annual report compilation are ordered from Bolagsverket on request. Delivery usually takes about 5 minutes. |
## Mappings
### Company Status
Status is determined **deterministically** from the Bolagsverket register. An empty `organisationsstatusar` array means the company is active. Any status entry triggers mapping through the status code system.
#### Active Status
| Local Status | English Translation | Standardized Status |
| - | - | - |
| Aktiv | Active | `ACTIVE` |
"Aktiv" is not returned by the API -- it is inferred from the absence of any status entries. When `organisationsstatusar` is empty or undefined, the company is considered active.
#### Struck-Off Statuses (AvregistreradOrganisationstyp)
| Code | Swedish Name | English Translation | Standardized Status | Closure Reason |
| - | - | - | - | - |
| 21 | Konkurs | Bankruptcy (struck off) | `UNDER_INSOLVENCY_PROCEEDING` | `BANKRUPTCY` |
| 31 | Likvidation | Liquidation (struck off) | `UNDER_INSOLVENCY_PROCEEDING` | `LIQUIDATION` |
| 37 | Ombildat till bankaktiebolag eller aktiekapitalet inte hojts | Converted to banking company or capital not raised | `CLOSED` | `OTHER` |
| 41 | Fusion | Merger (struck off) | `CLOSED` | `MERGER` |
| 51 | Overksamhet | Inactivity | `CLOSED` | `VOLUNTARY_DISSOLUTION` |
| 53 | Ny innehavare | New owner | `CLOSED` | `OTHER` |
| 60 | Det utlandska foretagets likvidation eller konkurs | Foreign company liquidation or bankruptcy | `CLOSED` | `OTHER` |
| 61 | Verksamheten har upphort | Operations ceased | `CLOSED` | `VOLUNTARY_DISSOLUTION` |
| 62 | Verkstallande direktor saknas | Missing CEO | `CLOSED` | `OTHER` |
| 63 | Beslut av instans | Decision by authority | `CLOSED` | `OTHER` |
| 64 | Arsredovisning saknas | Missing annual report | `CLOSED` | `OTHER` |
| 70 | Aktiekapitalet inte hojts | Share capital not raised | `CLOSED` | `OTHER` |
| 73 | Avregistrerad | Deregistered | `CLOSED` | `OTHER` |
| 74 | Ombildat till bankaktiebolag | Converted to banking company | `CLOSED` | `OTHER` |
| 91 | Delning | Division/split | `CLOSED` | `OTHER` |
| 98 | Gransoverskridande ombildning | Cross-border transformation (struck off) | `CLOSED` | `OTHER` |
#### Ongoing Procedure Statuses (AvvecklingsOmstruktureringsforfarande)
| Code | Swedish Name | English Translation | Standardized Status | Closure Reason |
| - | - | - | - | - |
| 11 | Ackordsforhandling | Composition proceedings | `UNDER_INSOLVENCY_PROCEEDING` | -- |
| 20 | Konkurs | Bankruptcy (ongoing) | `UNDER_INSOLVENCY_PROCEEDING` | `BANKRUPTCY` |
| 32 | Likvidation | Liquidation (ongoing) | `UNDER_INSOLVENCY_PROCEEDING` | `LIQUIDATION` |
| 45 | Overlatande i fusion | Transferring in merger (ongoing) | `CLOSED` | `MERGER` |
| 49 | Overtagande i fusion | Acquiring in merger (ongoing) | `CLOSED` | `MERGER` |
| 75 | Ombildning | Transformation (ongoing) | `CLOSED` | `OTHER` |
| 80 | Foretagsrekonstruktion | Corporate restructuring | `UNDER_INSOLVENCY_PROCEEDING` | -- |
| 85 | Resolution | Resolution (banking/financial sector) | `UNDER_INSOLVENCY_PROCEEDING` | -- |
| 90 | Overlatande vid delning | Transferring in division | `CLOSED` | `OTHER` |
| 96 | Gransoverskridande ombildning | Cross-border transformation (ongoing) | `CLOSED` | `OTHER` |
### Legal Forms
The local legal form (`organisationsform.klartext`) is preserved from Bolagsverket and deterministically mapped to an English translation. The `standardized` form and `iso20275Code` are **AI-enriched**.
#### Key Business Forms
| Code | Swedish Name | English Translation | ISO 20275 |
| - | - | - | - |
| AB | Aktiebolag | Private Limited Company | `XJHM` |
| Publ | Publikt aktiebolag | Public Limited Company | - |
| HB | Handelsbolag | General Partnership | `BEAY` |
| KB | Kommanditbolag | Limited Partnership | `CX05` |
| EK | Ekonomisk forening | Economic Association | `C61P` |
| E | Enskild naringsverksamhet | Sole Proprietorship | - |
| EB | Enkla bolag | Simple Company | `UKOL` |
#### Housing and Cooperative Forms
| Code | Swedish Name | English Translation | ISO 20275 |
| - | - | - | - |
| BRF | Bostadsrattsforening | Housing Cooperative | `SSOM` |
| BF | Bostadsforening | Housing Association | `WZDB` |
| KHF | Kooperativ hyresrattsforening | Cooperative Rental Association | `PDQ0` |
| SF | Sambruksforening | Joint Use Association | `AZTO` |
#### Non-Profits and Foundations
| Code | Swedish Name | English Translation | ISO 20275 |
| - | - | - | - |
| I | Ideell forening som bedriver naringsverksamhet | Non-profit Association | `1TN0` |
| S | Stiftelse som bedriver naringsverksamhet | Foundation | `E9BI` |
| TSF | Trossamfund som bedriver naringsverksamhet | Religious Community | `2UAX` |
#### Financial Institutions
| Code | Swedish Name | English Translation | ISO 20275 |
| - | - | - | - |
| BAB | Bankaktiebolag | Banking Company | `BYQJ` |
| FAB | Forsakringsaktiebolag | Insurance Company | `OJ9I` |
| SB | Sparbank | Savings Bank | `G04R` |
| MB | Medlemsbank | Member Bank | `381R` |
| OFB | Omsesidigt forsakringsbolag | Mutual Insurance Company | `O1QI` |
| OTPB | Omsesidigt tjanstepensionsbolag | Mutual Occupational Pension Company | - |
| TPAB | Tjanstepensionsaktiebolag | Occupational Pension Company | - |
| TPF | Tjanstepensionsforening | Occupational Pension Association | - |
| FOF | Forsakringsforening | Insurance Association | `M0Y0` |
| FF | Forsakringsformedlare | Insurance Broker | - |
#### Branch Offices and European Forms
| Code | Swedish Name | English Translation | ISO 20275 |
| - | - | - | - |
| FL | Filial | Branch Office | - |
| BFL | Utlandsk banks filial | Foreign Bank Branch | - |
| SE | Europabolag | European Company (Societas Europaea) | `54P7` |
| SCE | Europakooperativ | European Cooperative Society | `9YIP` |
| EEIG | Europeisk ekonomisk intressegruppering | European Economic Interest Grouping | `RLJO` |
| EGTS | Europeiska grupperingar for territoriellt samarbete | European Grouping of Territorial Cooperation | `RYFP` |
#### Legacy and Other Forms
| Code | Swedish Name | English Translation | ISO 20275 |
| - | - | - | - |
| Konkursbo | Konkursbo | Bankruptcy Estate | - |
| Kreditmarknadsbolag | Kreditmarknadsbolag | Credit Market Company | - |
| Vardepappersbolag | Vardepappersbolag | Securities Company | - |
Bolagsverket maintains approximately 30 standardized legal form codes. The `iso20275Code` is AI-matched against the GLEIF ISO 20275 code list for every legal form. The codes shown are the Swedish entries on that list; a form marked `-` has no entry of its own. Additional legacy forms may appear in historical records. The API preserves the `localName` exactly as returned by Bolagsverket.
### Legal Representatives
Registered office codes identify appointment context: the board represents collectively, the CEO within ordinary business, and registered signatories within their grant. No individual signing mode is inferred from a title. The published catalogue covers all 36 codes handled by this integration; a fresh complete current Bolagsverket codelist has not been verified. Roles are **deterministically mapped** to English translations; the `iso5009Code` is **AI-enriched**.
| Code | Swedish Name | English Translation | Standardized |
| - | - | - | - |
| OF | Styrelseordforande | Chairman | `Chairman` |
| VD | Verkstallande direktor | CEO | `Chief Executive Officer` |
| LE | Styrelseledamot | Board Member | `Board Member` |
| VOF | Vice styrelseordförande | Vice Chairman | `Vice Chairman of the Board` |
| EVD | Verkställande direktör | Chief Executive Officer | `Chief Executive Officer` |
| EFT | Extern firmatecknare | External Signatory | `Authorized Signatory` |
| PO | Prokurist | Authorized Signatory | `Authorized Signatory` |
| BO (HB) / KP (KB) | Bolagsman / Komplementär | General Partner | `General Partner` |
| LI | Likvidator | Liquidator | `Liquidator` |
| IN | Enskild näringsidkare | Sole Proprietor | `Owner` (only if a named functionary is supplied) |
| ARB (AB/Publ) | Arbetstagarrepresentant | Employee Board Representative | `Board Member` |
**Separate capacities:** Each recorded office is retained. A deputy board member is an other key person unless a separate current signing appointment is also recorded; that separate appointment appears under legal representatives. A board appointment does not certify sole signing, and CEO authority is limited by applicable law.
### Other Key Persons
Audit, contingent deputy and administrative appointments appear as other key persons. Unqualified form-dependent roles retain their filed labels with an appropriate context category. **Both individuals and corporate entities** can hold these roles (e.g., an auditing firm as auditor). Role codes are standardized by Bolagsverket.
#### Executive Management Roles
| Code | Swedish Name | English Translation | Standardized |
| - | - | - | - |
| SU / SUPP | Styrelsesuppleant / Suppleant | Deputy Board Member | `Board Member` |
| VVD | Vice verkstallande direktor | Vice CEO | `C-Level Executive` |
| EVVD | Vice verkstallande direktor | Vice CEO | `C-Level Executive` |
| SVD | Stallforetradande verkstallande direktor | Deputy CEO | `C-Level Executive` |
| VLE | Verkstallande ledamot | Managing Director | `C-Level Executive` |
#### Auditor Roles
| Code | Swedish Name | English Translation | Standardized |
| - | - | - | - |
| REV | Revisor | Auditor | `Auditor` |
| REVT | Revisor (med tillstand) | Auditor (with authorization) | `Auditor` |
| REVH | Huvudansvarig revisor | Principal Auditor | `Auditor` |
| REVS | Revisorssuppleant | Deputy Auditor | `Auditor` |
| REVST | Revisorssuppleant (med tillstand) | Deputy Auditor (with authorization) | `Auditor` |
| REVL | Lekmannarevisor | Lay Auditor | `Auditor` |
| REVSL | Suppleant for lekmannarevisor | Deputy Lay Auditor | `Auditor` |
| HREV | Revisor hallbarhetsrapport | Sustainability Report Auditor | `Auditor` |
| HREVH | Huvudansvarig revisor hallbarhetsrapport | Principal Sustainability Report Auditor | `Auditor` |
| HREVS | Revisorssuppleant hallbarhetsrapport | Deputy Sustainability Report Auditor | `Auditor` |
#### Signatory and Representative Roles
| Code | Swedish Name | English Translation | Standardized |
| - | - | - | - |
\| REP | Representant | Representative | `Other` |
\| DELG | Delgivningsmottagare | Service Agent | `Registered Agent` |
#### Partnership Roles
| Code | Swedish Name | English Translation | Standardized |
| - | - | - | - |
| BO / KP with unqualified form | Bolagsman / Komplementär | Partner / General Partner | `Other` |
| KD | Kommanditdelagare | Limited Partner | `Other` |
#### Other Administrative Roles
| Code | Swedish Name | English Translation | Standardized |
| - | - | - | - |
| FO | Forestandare | Director | `Other` |
| FV | Forvaltare | Administrator | `Other` |
| LS | Likvidatorssuppleant | Deputy Liquidator | `Other` |
| AK | Aktuarie | Actuary | `Other` |
| ARB with unqualified form | Arbetstagarrepresentant | Employee Representative | `Supervisor` |
| FTR | Forsakringstagarrepresentant | Policyholder Representative | `Supervisor` |
A person or entity can hold **multiple roles simultaneously**. Each recorded representative capacity is retained. For other key persons, each non-legal-representative role is listed separately. When an organization holds a role (e.g., an auditing firm), its representative person is also listed with the suffix "(Representative)".
### Shareholders
Bolagsverket does **not** publish a share register. Ownership is restricted to authorities and the company's own shareholders, so there is no register source for it.
What the `shareholders` datapoint reads instead is the **ownership note in the company's annual report**. Swedish companies are not required to disclose ownership there, so most return none. Names and holdings are extracted by AI from the filing, so verify against the source before relying on them for compliance.
Sole traders (enskild firma) have no share capital, so the datapoint does not apply to them at all: it returns an explicit `datapoint_not_applicable` response. The owner's personnummer is returned in `company.identifiers`; no separate person record is returned for the owner. See [Sole Entrepreneurs & Non-Profits](/essentials/entity-types).
### Activity Code Mapping
Sweden does **not** use a national activity code classification in the Bolagsverket registry. Instead, companies register a free-text **verksamhetsbeskrivning** (activity description) in Swedish. The system uses AI enrichment to derive standardized activity codes:
```
Verksamhetsbeskrivning (Swedish free text) --> AI --> ISIC Rev. 5 + NACE Rev. 2.1
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **Activity description** | Bolagsverket (`verksamhetsbeskrivning`) | "Utveckling och forsaljning av programvara" | No (official) |
| **ISIC** | AI-derived from activity description | `6219` - Other computer programming activities | Yes (always) |
| **NACE** | AI-derived from activity description | `62.10` - Computer programming activities | Yes (always) |
**All ISIC and NACE codes for Sweden are AI-inferred** because Bolagsverket does not assign standard classification codes. The AI derives codes from the Swedish-language activity description text. The `isAIInferred` flag is always `true` for Swedish activity codes. The code derived from the verksamhetsbeskrivning is marked as the main activity (`isMainActivity: true`). It always carries `isAIInferred: true`, so it cannot be confused with a main activity assigned by Bolagsverket; a missing flag means the source did not designate a main activity.
## Data Availability
### Data Availability Matrix
| Data Type | AB (Private Ltd) | E (Sole Prop.) | HB/KB (Partnerships) | I (Non-profit) | S (Foundation) | Notes |
| - | - | - | - | - | - | - |
| Company Profile | Yes | Yes | Yes | Yes | Yes | From the Bolagsverket company register |
| Legal Representatives | Yes | No | No | Yes | Yes | Chairman, CEO, board members and deputies. Partners in HB/KB are other key persons |
| Other Key Persons | Yes | No | Yes | Yes | Yes | Auditors, signatories, partners, etc. |
| Shareholders | Limited | Not applicable | No | No | No | AB only, verification mode only: AI-extracted from the ownership note of digitally filed annual reports, often not disclosed |
| UBOs | Yes | No | Limited | Limited | Limited | Via retrieved UBO extract document (AI-parsed) |
| Activity Codes | Yes | Yes | Yes | Yes | Yes | AI-inferred from description (always) |
| Share Capital | Yes | No | No | No | No | AB companies only, always in SEK |
| Employee Count | No | No | No | No | No | Not available from Bolagsverket |
### Documents by Company Type
#### Annual Reports (digital filings)
| Document | Format | Source | Notes |
| - | - | - | - |
| Annual Report (individual filing per year) | ZIP | Bolagsverket open data | Contains the original filing. Digitally filed reports only. Sorted by year descending. |
#### Documents Ordered from Bolagsverket
| Document | Bolagsverket Code | Format | Applicable Legal Forms | Notes |
| - | - | - | - | - |
| Certified Trade Register Extract | REGBEV | PDF | All registered entities | Official extract with company status and registration details |
| Articles of Association | BOLORDN | PDF | AB, BAB, FAB, SE | Business activities, registered office, share capital rules |
| Statutes | STADG | PDF | EK, BRF, I, S, and associations | Governing rules for non-AB entities |
| Annual Reports (compilation) | ARSRED | PDF | All that file reports | Combined annual reports across all filing years |
| Minutes | PROT | PDF | All registered entities | Board meeting or general meeting minutes |
| Ultimate Beneficial Owners Extract | RVHBEV | PDF | All with UBO registration | UBO information from Bolagsverket register |
| Current Assignments | AKTUPPD | PDF | All (registered entities and natural persons) | Current assignments in other entities |
| Current and Previous Assignments | HISTUPPD | PDF | Natural persons (personnummer) | Current and historical assignments |
| Business Prohibition Register | NFBEV | PDF | Natural persons (personnummer) | Whether or not a person has a prohibition to carry on business |
| Insolvency Register of Bankruptcies | PPKKBEV | PDF | Natural persons (personnummer) | Whether or not a person is in bankruptcy |
**Historical Certificates** (HISTBEV) and **English Certificates** (ENGINTYG) are not available. The documents you can order vary by legal form and entity type, and `availableDocuments` lists the ones that apply to each company. See the [Sweden pricing page](https://topograph.co/pricing/se) for document prices.
**Ordered documents are not instant.** These documents are ordered from Bolagsverket on request and are usually delivered within about 5 minutes.
### Example API Responses
All examples use **placeholder data**. Real personal names have been replaced with fictional ones.
```json theme={null}
{
"company": {
"id": "5560001234",
"countryCode": "SE",
"legalName": "Nordisk Teknik AB",
"registrationDate": "2018-03-15",
"incorporationDate": "2018-02-01",
"status": {
"localName": "Aktiv",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Aktiebolag",
"englishTranslation": "Private Limited Company",
"standardized": "Corporation",
"iso20275Code": "XJHM"
},
"capital": {
"amount": 50000,
"currency": "SEK",
"formatted": "50 000 SEK"
},
"activityDescription": "Bolaget skall bedriva utveckling och forsaljning av programvara for industriell automation samt darmed forenlig verksamhet.",
"activities": {
"ISIC": [{ "code": "6219", "description": "Other computer programming activities", "isAIInferred": true, "isMainActivity": true }],
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": {
"addressLine1": "10 Storgatan",
"city": "Stockholm",
"postalCode": "111 22",
"countryCode": "SE",
"state": "Stockholms lan"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Styrelseordforande", "englishTranslation": "Chairman", "standardized": "Chairman", "iso5009Code": "3NXF5M" },
"individual": { "name": { "firstName": "Erik", "lastName": "Lindberg", "fullName": "Erik Johan Lindberg" }, "residenceAddress": { "addressLine1": "5 Vasagatan", "city": "Stockholm", "postalCode": "111 20", "countryCode": "SE" } }
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Verkstallande direktor", "englishTranslation": "CEO", "standardized": "Chief Executive Officer", "iso5009Code": "BF3W0F" },
"individual": { "name": { "firstName": "Sara", "lastName": "Johansson", "fullName": "Sara Maria Johansson" }, "residenceAddress": { "addressLine1": "12 Drottninggatan", "city": "Stockholm", "postalCode": "111 51", "countryCode": "SE" } }
},
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Styrelseledamot", "englishTranslation": "Board Member", "standardized": "Board Member", "iso5009Code": "OWYDPK" },
"individual": { "name": { "firstName": "Anders", "lastName": "Nilsson", "fullName": "Anders Per Nilsson" }, "residenceAddress": { "addressLine1": "3 Kungsgatan", "city": "Gothenburg", "postalCode": "411 19", "countryCode": "SE" } }
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Revisor", "englishTranslation": "Auditor", "standardized": "Auditor" },
"company": { "id": "5560030674", "legalName": "Revisionsfirman Exemplet AB", "countryCode": "SE", "legalAddress": { "city": "Stockholm", "countryCode": "SE" } }
},
{
"entityId": "person_004",
"type": "individual",
"role": { "localName": "Revisor (Representant)", "englishTranslation": "Auditor (Representative)", "standardized": "Auditor" },
"individual": { "name": { "firstName": "Lars", "lastName": "Persson", "fullName": "Lars Henrik Persson" } }
}
],
"shareholders": []
}
```
```json theme={null}
{
"company": {
"id": "5564321000",
"countryCode": "SE",
"legalName": "Gammal Industri Aktiebolag",
"registrationDate": "1989-07-25",
"incorporationDate": "1989-04-28",
"status": {
"localName": "Fusion",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "MERGER",
"closureDate": "2006-01-02",
"additionalInfo": "Status code: 41"
}
},
"legalForm": {
"localName": "Aktiebolag",
"englishTranslation": "Private Limited Company",
"standardized": "Corporation",
"iso20275Code": "XJHM"
},
"capital": {
"amount": 100000,
"currency": "SEK",
"formatted": "100 000 SEK"
},
"activityDescription": "Bolaget skall avse handel och fabriksrorelse betraffande mekaniska verkstadsprodukter, sasom entreprenadmaskiner och fordon.",
"activities": {
"ISIC": [{ "code": "2819", "description": "Manufacture of other general-purpose machinery", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": {
"addressLine1": "Carl Lihnells vag",
"city": "Braas",
"postalCode": "363 41",
"countryCode": "SE",
"state": "Kronobergs lan"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Styrelseordforande", "englishTranslation": "Chairman", "standardized": "Chairman", "iso5009Code": "3NXF5M" },
"individual": { "name": { "firstName": "Karl", "lastName": "Svensson", "fullName": "Karl Anders Svensson" } }
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Verkstallande direktor", "englishTranslation": "CEO", "standardized": "Chief Executive Officer", "iso5009Code": "BF3W0F" },
"individual": { "name": { "firstName": "Gustaf", "lastName": "Rosen", "fullName": "Gustaf Yngve Rosen" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Arbetstagarrepresentant", "englishTranslation": "Employee Representative", "standardized": "Supervisor" },
"individual": { "name": { "firstName": "Bengt", "lastName": "Larsson", "fullName": "Bengt Liss-Erik Larsson" } }
},
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Revisor", "englishTranslation": "Auditor", "standardized": "Auditor" },
"company": { "id": "5560674276", "legalName": "Revisionsfirman Exemplet AB", "countryCode": "SE" }
}
],
"shareholders": []
}
```
**Note:** Closed companies have `active: false`. The `closureReason` reflects the Bolagsverket status code -- code 41 = Fusion (Merger).
```json theme={null}
{
"company": {
"id": "9691234567",
"countryCode": "SE",
"legalName": "Lindberg & Eriksson Handelsbolag",
"registrationDate": "2007-07-02",
"status": {
"localName": "Anmalan om att verksamheten har upphort",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "VOLUNTARY_DISSOLUTION",
"closureDate": "2010-07-05",
"additionalInfo": "Status code: 61"
}
},
"legalForm": {
"localName": "Handelsbolag",
"englishTranslation": "General Partnership",
"standardized": "Partnership",
"iso20275Code": "BEAY"
},
"activityDescription": "Foremal for bolagets verksamhet ar samarbete inom affarsomradet tillverkning och forsaljning av utrustning.",
"activities": {
"ISIC": [{ "code": "2910", "description": "Manufacture of motor vehicles", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": {
"city": "Gothenburg",
"countryCode": "SE",
"state": "Vastra Gotaland County"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Bolagsman", "englishTranslation": "Partner", "standardized": "Other" },
"company": { "id": "5565399853", "legalName": "Nordisk Holding Aktiebolag", "countryCode": "SE" }
},
{
"entityId": "company_002",
"type": "company",
"role": { "localName": "Bolagsman", "englishTranslation": "Partner", "standardized": "Other" },
"company": { "id": "5560139700", "legalName": "Transport Sverige Aktiebolag", "countryCode": "SE" }
},
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Extern firmatecknare", "englishTranslation": "External Signatory", "standardized": "Other" },
"individual": { "name": { "firstName": "Henrik", "lastName": "Bergstrom", "fullName": "Henrik Bergstrom" } }
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Revisor", "englishTranslation": "Auditor", "standardized": "Auditor" },
"individual": { "name": { "firstName": "Rolf", "lastName": "Karlsson", "fullName": "Rolf Olov Anders Karlsson" } }
}
],
"shareholders": []
}
```
**Note:** Partnerships (HB/KB) list partners (`Bolagsman`) as other key persons, not as legal representatives. No share capital is registered for partnerships.
```json theme={null}
{
"company": {
"id": "196405250314",
"countryCode": "SE",
"legalName": "Bergkvist Textil",
"registrationDate": "2003-06-12",
"status": {
"localName": "Aktiv",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Enskild naringsverksamhet",
"englishTranslation": "Sole Proprietorship",
"standardized": "Sole Proprietorship"
},
"activityDescription": "Handel med textil och tillbehor samt darmed forenlig verksamhet.",
"activities": {
"ISIC": [{ "code": "4751", "description": "Retail sale of textiles", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": {
"addressLine1": "7 Lindgatan",
"city": "Vasteras",
"postalCode": "722 15",
"countryCode": "SE",
"state": "Vastmanlands lan"
},
"identifiers": {
"personalIdentityNumber": "196405250314",
"VAT": "640525031401"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [],
"shareholders": []
}
```
**Note:** Sole traders return `personalIdentityNumber` in `company.identifiers` instead of `organizationNumber`. The `id` field holds the 12-digit personnummer. No separate person record is returned for the owner, so `legalRepresentatives` and `otherKeyPersons` are empty. Share capital, board members, and signing rules are not present because they do not apply to sole proprietorships.
```json theme={null}
{
"company": {
"id": "7180004926",
"countryCode": "SE",
"legalName": "Personalforeningen vid Norrlands Maskiner, ekonomisk forening",
"registrationDate": "1974-12-06",
"status": {
"localName": "Likvidation",
"active": false,
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"closureReason": "LIQUIDATION",
"closureDate": "2011-04-27",
"additionalInfo": "Status code: 31"
}
},
"legalForm": {
"localName": "Ekonomisk forening",
"englishTranslation": "Economic Association",
"standardized": "Cooperative",
"iso20275Code": "C61P"
},
"activityDescription": "Foreningen har till andamal att framja medlemmarnas ekonomiska intressen genom att samarbeta med naringsidkaren pa restaurangrorelse.",
"activities": {
"ISIC": [{ "code": "5610", "description": "Restaurants and mobile food service activities", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": {
"city": "Eskilstuna",
"countryCode": "SE",
"state": "Sodermanland County"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Likvidator", "englishTranslation": "Liquidator", "standardized": "Other" },
"individual": { "name": { "firstName": "Nils", "lastName": "Kropp", "fullName": "Nils Anders Kropp" } }
}
],
"shareholders": []
}
```
**Note:** Economic associations (Ekonomisk forening) use "Statutes" (Stadgar) instead of "Articles of Association" (Bolagsordning). When in liquidation, the liquidator appears as an other key person.
```json theme={null}
{
"documents": {
"financialStatements": [
{ "id": "doc_fs_2024", "name": "Annual report - 2024", "description": "Annual report from the Swedish Business Register (Bolagsverket)", "format": "zip" },
{ "id": "doc_fs_2023", "name": "Annual report - 2023", "description": "Annual report from the Swedish Business Register (Bolagsverket)", "format": "zip" },
{ "id": "doc_fs_2022", "name": "Annual report - 2022", "description": "Annual report from the Swedish Business Register (Bolagsverket)", "format": "zip" }
],
"certifiedTradeRegisterExtract": {
"id": "doc_regbev", "name": "Certified Trade Register Extract - PDF", "description": "Extract from the Swedish Business Register", "format": "pdf"
},
"articlesOfAssociation": [
{ "id": "doc_bolordn", "name": "Articles of Association - PDF", "description": "Articles of association for the company", "format": "pdf" }
],
"ultimateBeneficialOwnersCertificate": {
"id": "doc_rvhbev", "name": "Ultimate Beneficial Owners Extract - PDF", "description": "Extract from the register of beneficial owners", "format": "pdf"
},
"otherDocuments": [
{ "id": "doc_prot", "name": "Minutes - PDF", "description": "Minutes from the company's meetings", "format": "pdf" },
{ "id": "doc_aktuppd", "name": "Current Assignments - PDF", "description": "Current assignments for a person or company", "format": "pdf" }
]
}
}
```
**Note:** Minutes, current assignments and the person certificates are listed under `otherDocuments`. Every document in the list, including each yearly annual report, is billed when ordered. See the [Sweden pricing page](https://topograph.co/pricing/se) for document prices.
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "firstName": "Erik", "lastName": "Lindberg", "fullName": "Erik Johan Lindberg" },
"birthDate": { "year": 1975, "month": 6, "day": 15 },
"nationality": "SE",
"residenceAddress": { "countryCode": "SE" },
"control": {
"types": ["significant-influence-or-control"],
"description": "Control extent: 100%. Type of control: through shares, participations, membership, agreements."
}
},
{
"entityId": "person_002",
"name": { "firstName": "Maria", "lastName": "Svensson", "fullName": "Maria Anna Svensson" },
"birthDate": { "year": 1980, "month": 3, "day": 22 },
"nationality": "SE",
"residenceAddress": { "countryCode": "SE" },
"control": {
"types": ["significant-influence-or-control"],
"description": "Control extent: 100%. Type of control: through other companies or associations. Control exercised through: Nordisk Holding AB."
}
}
]
}
```
**Note:** UBO data is AI-extracted from the UBO Extract document ordered from Bolagsverket. The Swedish field "Omfattning" (extent) represents **control extent**, not ownership percentage, and is reported in `control.description`. Multiple UBOs can each show 100% because they each have a control path giving full influence over the company. `control.details[].percentageValue` is not filled from the control extent, because the Swedish register reports control extent, not economic ownership stake.
# Switzerland
Source: https://docs.topograph.co/essentials/switzerland
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Switzerland reference is on the [Switzerland country page](https://www.topograph.co/countries/ch).
## Start here
This guide contains public integration notes for Switzerland. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Switzerland uses official federal and cantonal sources. In verification mode, company data comes from a live Zefix lookup. In prefill mode, a limited company identity comes from the published Zefix linked-data index. Legal representatives and other key persons are extracted from the official cantonal trade register extract in verification mode, with SOGC publications as a fallback for legal representatives.
### All company types
* **Zefix (Zentraler Firmenindex)**: The Central Business Name Index, operated by the Federal Office of Justice (FOJ) since 2004. Zefix aggregates data from all 26 cantonal commercial registers into a single searchable index via a REST API. Live Zefix lookups provide verification-mode company data: legal name, status, legal form, registered address, share capital, activity description (purpose), and identifiers. Zefix data is sourced from the cantonal commercial registers, which are the authoritative registers of record.
* **Zefix linked-data index**: A regularly imported copy of company identity fields for prefill. It provides name, UID, EHRA ID, legal form, and seat (city and canton). It does not distinguish active companies from companies being cancelled, and it omits cancelled companies. The response therefore does not claim a company status.
* **SOGC/SHAB (Swiss Official Gazette of Commerce)**: The Schweizerisches Handelsamtsblatt / Feuille officielle suisse du commerce, published electronically since 2002 and managed by SECO. All commercial register mutations are published in the SOGC as structured text. Used for two purposes: **(1)** as a **fallback source for legal representatives** via AI parsing of publication texts, used when the cantonal trade register extract is unavailable (this fallback is less complete); **(2)** as the source for the **Certificate of Incorporation** document (the SOGC publication announcing the initial registration).
### Cantonal Commercial Registers (for documents)
Switzerland has **26 cantonal commercial registers** (Handelsregisterämter), each maintaining the register of companies domiciled in that canton. While Zefix serves as the central index for company data, the cantonal registers issue the **Trade Register Extract** documents. Trade register extracts are issued by the relevant cantonal commercial register for all 26 cantons; delivery typically takes a few seconds. The same extract is the source of legal representatives and other key persons.
The cantonal commercial registers are the authoritative source of record. Zefix aggregates their data into a searchable central index but does not itself issue official documents. Trade register extracts are issued by the relevant cantonal register.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| - | - | - | - | - |
| **All registered entities** | Zefix | CHE + 9 digits (UID) | `CHE408600128` | `CHE-408.600.128`, `CHE408600128` and `408600128` are all accepted |
**UID Format Breakdown:** `CHE408600128` = `CHE` + 8 digits assigned at random + 1 check digit. The register also writes it `CHE-408.600.128`; the dots and hyphen are only for readability. The UID (Unternehmens-Identifikationsnummer) is assigned by the Federal Statistical Office and is permanent.
**Check digit:** weight the first eight digits 5, 4, 3, 2, 7, 6, 5, 4 and sum them. The check digit is 11 minus the sum modulo 11 (0 when the remainder is 0; a result of 10 is never issued).
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| `uid` | CHE + 9 digits, no separators | `CHE408600128` | UID (Unternehmens-Identifikationsnummer), always present. Search match reasons echo the dotted form `CHE-408.600.128` |
| `ehraId` | 1 to 7 digits | `1499050` | EHRA ID (internal ID of the federal commercial register database), when available |
| `chId` | CH + 11 digits, no separators | `CH55011976311` | CH-ID (former register number, no longer used publicly, printed `CH-550.1.197.631-1`), when available |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Swiss UID (`uid`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By UID (with separators) | CHE-XXX.XXX.XXX | `CHE-408.600.128` | Exact | Exact match returned first (matchType: id); other results may follow |
| By UID (without separators) | CHEXXXXXXXXX | `CHE408600128` | Exact | Exact match returned first (matchType: id); other results may follow |
| By UID (digits only) | XXXXXXXXX | `408600128` | Exact | Exact match returned first (matchType: id); other results may follow |
| By VAT number | UID + MWST, TVA or IVA | `CHE-408.600.128 MWST` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (min 3 chars) | `"Nestlé"` | Fuzzy | Multiple results |
**Search Performance:** Use UID-based searches for best performance and exact matching. Name searches query the Zefix API and may return multiple results. All UID formats (dotted, compact, or the 9 digits alone) are accepted for both search and company data.
Search combines the published Zefix index with live Zefix lookups. Name searches require a minimum of 3 characters and a maximum of 100 characters. Live results can include more status detail than the index.
### Active companies only
With [`activeOnly=true`](/essentials/search#active-companies-only), results are checked against live Zefix before they are returned, also in streamed results, which removes companies being cancelled whenever Zefix also finds them. The linked-data index has no reliable status field, so a result only the index finds is kept, and the filter stays partial for Switzerland. Request the `company` datapoint in verification mode when status matters.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Multi-language company names** | Swiss companies can be registered in German, French, Italian, or Romansh. The `legalForm.localName` reflects the registration language. Translated names appear in `commercialNames`. |
| **All activity codes are AI-inferred** | Zefix provides only a free-text activity description (Zweck / But / Scopo), not structured codes. Both NACE and ISIC are always AI-inferred. `isAIInferred` is always `true`. |
| **Key persons are AI-parsed from the cantonal extract** | Legal representatives and other key persons are extracted by AI from the official cantonal trade register extract and split by the extract's signing-authority column. If the extract cannot be retrieved, legal representatives fall back to SOGC publications (less complete); other key persons have no fallback. |
| **No shareholder data** | Swiss commercial register does not publish structured shareholder data publicly. |
| **No UBO data** | Ultimate beneficial owner data is not publicly accessible in Switzerland. |
| **26 cantonal registers** | Trade register extracts are always issued by the relevant canton. |
| **Deletion date = closure** | When a company has a `deletionDate` in Zefix, it is mapped to Closed status. The deletion date is used as the closure date. |
| **eCH-0097 legal form standard** | Swiss legal forms use the eCH-0097 national data standard. All 38 codes are **deterministically** mapped to standardized forms, and every code with an ISO 20275 ELF code gets it without AI inference. |
| **Capital in CHF** | Most Swiss companies report capital in CHF (Swiss Francs), though some may use EUR or other currencies. The `capital.currency` field reflects the actual currency. |
| **SOGC multilingual publications** | SOGC publications may be in German, French, Italian, or mixed languages. The AI parser handles all three official languages. |
| **Status "BEING\_CANCELLED"** | Zefix has a third status value for companies in the process of being dissolved (in Liquidation). It is returned with `active: false`, and its standardized status is classified from the local status. |
| **Prefill coverage** | Prefill returns only the `company` datapoint and only for companies in the linked-data index. It provides no status, officers, capital, purpose, or dates. Companies being cancelled can remain in the index; cancelled companies are absent. If prefill cannot find a company, request `company` again in verification mode to check the live register. |
## Mappings
### Company Status
Company status comes from Zefix. `active` is `true` only for the `ACTIVE` status. `CANCELLED` companies with a deletion date map to Closed with that closure date; other statuses are classified into the standard categories.
| Zefix Status | English | Standardized Status | Notes |
| - | - | - | - |
| `ACTIVE` | Active | Active | Company is currently active |
| `BEING_CANCELLED` | Being cancelled / In liquidation | Classified from the local status | Company is in the process of dissolution; returned with `active: false` |
| `CANCELLED` | Cancelled / Deleted | Closed | Company has been deleted from the register |
When a company has status `CANCELLED` and a `deletionDate` is present, the deletion date is used as the `closureDate` in the `statusDetails` response. The `BEING_CANCELLED` status corresponds to companies undergoing liquidation proceedings.
### Legal Forms
Switzerland uses the **eCH-0097** data standard (Datenstandard Unternehmensidentifikation) for legal form classification. The system maps all 38 eCH-0097 codes **deterministically** to standardized forms and, where one exists, to their ISO 20275 (ELF) code. No AI inference is involved for codes with an ISO 20275 mapping.
**Multilingual legal form names:** Swiss legal form names from Zefix come in the registration language of the company (German, French, Italian, or English). The `legalForm.localName` reflects this. The eCH-0097 code is used for deterministic mapping regardless of language.
| eCH-0097 | German | French | English | ISO 20275 | Standardized |
| - | - | - | - | - | - |
| 0101 | Einzelunternehmen | Entreprise individuelle | Sole proprietorship | AZA0 | Sole Proprietorship |
| 0103 | Kollektivgesellschaft | Societe en nom collectif | General partnership | MRSY | Partnership |
| 0104 | Kommanditgesellschaft | Societe en commandite | Limited partnership | CQMY | Partnership |
| 0105 | Kommanditaktiengesellschaft | Societe en commandite par actions | Partnership limited by shares | W6A7 | Partnership |
| 0106 | Aktiengesellschaft | Societe anonyme | Company limited by shares | MVII | Corporation |
| 0107 | Gesellschaft mit beschrankter Haftung | Societe a responsabilite limitee | Limited liability company | 3EKS | Limited Liability Company |
| 0108 | Genossenschaft | Cooperative | Cooperative | QSI2 | Cooperative |
| 0109 | Verein | Association | Association | H781 | Nonprofit Organization |
| 0110 | Stiftung | Fondation | Foundation | 2JZ4 | Nonprofit Organization |
| 0111 | Auslandische Niederlassung im HR eingetragen | Succursale etrangere inscrite au RC | Foreign branch registered in commercial register | JB25 | Branch or Representative Office |
| 0113 | Besondere Rechtsform | Forme juridique particuliere | Special legal form | 5BEZ | Other |
| 0114 | Kommanditgesellschaft fur kollektive Kapitalanlagen | Societe en commandite de placements collectifs | Limited partnership for collective investments | TL87 | Partnership |
| 0115 | Investmentgesellschaft mit variablem Kapital (SICAV) | Societe d'investissement a capital variable (SICAV) | Investment company with variable capital | XJOT | Corporation |
| 0116 | Investmentgesellschaft mit festem Kapital (SICAF) | Societe d'investissement a capital fixe (SICAF) | Investment company with fixed capital | 54WI | Corporation |
| 0117 | Institut des offentlichen Rechts | Institut de droit public | Public sector institution | 7MNN | Government-Owned Entity |
| 0118 | Nichtkaufmannische Prokuren | Procurations non-commerciales | Non-commercial power of attorney | KJ9Q | Other |
| 0119 | Haupt von Gemeinderschaften | Responsable d'indivision | Representative of ownership in undivided shares | OBFU | Other |
| 0151 | Schweizerische Zweigniederlassung im HR eingetragen | Succursale suisse inscrite au RC | Swiss branch registered in commercial register | UNA9 | Branch or Representative Office |
| eCH-0097 | German | French | English | ISO 20275 | Standardized |
| - | - | - | - | - | - |
| 0220 | Verwaltung des Bundes | Administration de la Confederation | Federal administration | 2XJA | Government-Owned Entity |
| 0221 | Verwaltung des Kantons | Administration du canton | Cantonal administration | FFTN | Government-Owned Entity |
| 0222 | Verwaltung des Bezirks | Administration du district | District administration | YRGM | Government-Owned Entity |
| 0223 | Verwaltung der Gemeinde | Administration de la commune | Local administration | GP8M | Government-Owned Entity |
| 0224 | Offentlich-rechtliche Korperschaft (Verwaltung) | Corporation de droit public (administration) | Public corporation (administration) | E0NE | Government-Owned Entity |
| 0230 | Unternehmen des Bundes | Entreprise de la Confederation | Federal public company | BF9N | Government-Owned Entity |
| 0231 | Unternehmen des Kantons | Entreprise du canton | Cantonal public company | HX77 | Government-Owned Entity |
| 0232 | Offentliches Unternehmen des Bezirks | Entreprise du district | District public company | VPRH | Government-Owned Entity |
| 0233 | Unternehmen der Gemeinde | Entreprise de la commune | Local public company | L5DU | Government-Owned Entity |
| 0234 | Offentlich-rechtliche Korperschaft (Unternehmen) | Corporation de droit public (entreprise) | Corporate public company | M848 | Government-Owned Entity |
| eCH-0097 | German | French | English | ISO 20275 | Standardized |
| - | - | - | - | - | - |
| 0302 | Einfache Gesellschaft | Societe simple | Simple partnership | 2B81 | Partnership |
| 0312 | Auslandische Niederlassung nicht im HR eingetragen | Filiale etrangere non inscrite au RC | Foreign branch not registered in commercial register | 1BL5 | Branch or Representative Office |
| 0327 | Auslandisches offentliches Unternehmen | Entreprise publique etrangere | Foreign public company | 2WFG | Government-Owned Entity |
| 0328 | Auslandische offentliche Verwaltung | Administration publique etrangere | Foreign public administration | 1RKS | Government-Owned Entity |
| 0329 | Internationale Organisation | Organisation internationale | International organisation | DP2E | Other |
| 0355 | Andere Genossenschaften | Autres societes cooperatives | Other cooperatives | QSI2 | Cooperative |
| 0361 | Trust | Trust | Trust | FJG4 | Trust |
| 0362 | Fonds | Fonds | Fund | FLNB | Other |
| eCH-0097 | German | French | English | ISO 20275 | Standardized |
| - | - | - | - | - | - |
| 0441 | Auslandische Unternehmen | Entreprise etrangere | Foreign enterprise | R9TC | Other |
| 0571 | Rechtsform nicht bestimmt oder unbekannt | Forme juridique non determinee ou inconnue | Legal form not determined or unknown | - | Other |
The full eCH-0097 specification is available at [eCH](https://www.ech.ch/de/ech/ech-0097/5.2.0). ISO 20275 ELF codes are maintained by [GLEIF](https://www.gleif.org/about-lei/code-lists/iso-20275-entity-legal-forms-code-list). All 38 Swiss legal form codes are deterministically mapped, so no AI enrichment is needed for any code that has an ISO 20275 mapping.
### Legal Representatives
Legal representatives are extracted from the **official cantonal trade register extract** (Handelsregisterauszug / extrait du registre du commerce). Zefix publishes no structured officer roster, so the extract's own person table — which states each person's role and signing authority — is fetched and parsed by AI. It may be in German, French, Italian or English depending on the canton.
`legalRepresentatives` contains **people with recorded signing authority**. `representationMode` states sole or joint signing when that rule can be read unambiguously. Known office labels use published translations and standardized values for the recorded signing context. Board members the register lists *without* signing authority, and the statutory auditor, are returned under [`otherKeyPersons`](#other-key-persons) instead — see [Listing the full board](#listing-the-full-board).
If a cantonal portal is temporarily unavailable, the answer falls back to AI parsing of **SOGC publications** (Swiss Official Gazette of Commerce), which is less complete.
| Local Role (German) | Local Role (French) | Local Role (Italian) | English Translation |
| - | - | - | - |
| Geschaftsfuhrer | Gerant | Gerente | Managing Director |
| Direktor | Directeur | Direttore | Director |
| Local Role (German) | Local Role (French) | Local Role (Italian) | English Translation |
| - | - | - | - |
| Prasident des Verwaltungsrates | President du conseil d'administration | Presidente del Consiglio d'amministrazione | Chairman of the Board |
| Vizeprasident des Verwaltungsrates | Vice-president du conseil d'administration | Vicepresidente del Consiglio d'amministrazione | Vice Chairman of the Board |
| Mitglied des Verwaltungsrates | Membre du conseil d'administration | Membro del Consiglio d'amministrazione | Board Member |
| Local Role (German) | Local Role (French) | Local Role (Italian) | English Translation |
| - | - | - | - |
| Prokurist | Fonde de procuration | Procuratore | Authorized Signatory |
Signature types documented in SOGC publications:
* **mit Einzelzeichnung** / avec signature individuelle / con firma individuale = individual signature rights
* **mit Kollektivzeichnung zu zweien** / avec signature collective a deux / con firma collettiva a due = joint signature rights (two jointly)
| Local Role (German) | Local Role (French) | Local Role (Italian) | English Translation |
| - | - | - | - |
| Liquidator | Liquidateur | Liquidatore | Liquidator |
Whether a person is a **legal representative** or an **other key person** is decided by the extract's own "Signing authority" column, not by their job title: anyone the register grants signing authority is a legal representative; anyone it lists without is an other key person. A "Mitglied des Verwaltungsrates" (Board Member) is therefore a legal representative when they can sign and an other key person when the extract says "without signing authority" — in both cases they carry `corporateBody: "board"`. Both individuals and corporate entities can hold roles.
#### Representation Mode
Legal representatives include a `representationMode` field indicating signing authority:
* **`{ mode: "sole" }`**: Can sign alone ("mit Einzelzeichnung" / "avec signature individuelle" / "con firma individuale")
* **`{ mode: "joint", minimumSignatories: 2 }`**: Must sign jointly with one other ("mit Kollektivzeichnung zu zweien" / "avec signature collective à deux" / "con firma collettiva a due")
* **`{ mode: "joint", minimumSignatories: N }`**: Must sign jointly with a specified number of others
* **`null`**: only possible on the SOGC fallback path; on the cantonal-extract path a person with no signing authority is returned under `otherKeyPersons` instead
The field is extracted from the extract's "Signing authority" / "Zeichnungsart" / "Signature mode" column.
### Other Key Persons
People the cantonal extract lists **without signing authority**. They cannot bind the company, which is why they are not returned as legal representatives.
| Role Type | Local names | Notes |
| - | - | - |
| Statutory auditor | Revisionsstelle / Organe de revision / Ufficio di revisione | Almost always an audit firm, returned as `type: "company"` with its own Swiss UID in `company.identifiers.uid`. Carries `corporateBody: "audit"` |
| Board members without signing authority | Mitglied des Verwaltungsrates ("ohne Zeichnungsberechtigung") | Common on larger companies, especially foreign-resident directors. Carries `corporateBody: "board"` |
Requires the cantonal extract. For a company Zefix publishes no cantonal extract link for, this datapoint returns a `no_document_available` error rather than an empty list, and is **not billed**.
#### Listing the full board
Because the split is by signing authority, a company's board of directors can span both arrays. Every person carries a `corporateBody` field naming the body they sit on (`board`, `supervisoryBoard`, `management`, `audit`; absent for an authorized signatory, who holds a power of attorney rather than a seat). Filter across both arrays:
```js theme={null}
const board = [...response.legalRepresentatives, ...response.otherKeyPersons]
.filter((person) => person.corporateBody === 'board');
```
Switzerland has no separate supervisory organ: the Verwaltungsrat is the board of directors, so `supervisoryBoard` is never returned for a Swiss company.
### Shareholders
Shareholder data is **not currently available** for Swiss companies. The Swiss commercial register (Zefix) and SOGC publications do not provide structured shareholder or ownership data in a programmatically accessible format.
| Aspect | Details |
| - | - |
| **Availability** | Not available |
| **Reason** | Swiss commercial register does not publish structured shareholder data publicly |
| **Workaround** | Shareholder information may appear in SOGC publication texts for some legal forms (e.g., GmbH partner lists), but is not systematically extracted |
### Activity Code Mapping
Switzerland does not use a national activity code classification in the Zefix registry. Activity codes are **AI-inferred** from the company's `purpose` (Zweck / But / Scopo) field, which is a free-text description of the company's business activities.
```
Activity Description (free text) → ISIC Rev. 5 (AI-inferred) → NACE Rev. 2.1 (derived)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **ISIC** | Inferred from activity description via AI | `6219` | Yes (always) |
| **NACE** | Derived from the inferred ISIC code via the formal correspondence | `62.10` | Yes (always) |
Both NACE and ISIC codes are **always AI-inferred** for Swiss companies because the Zefix registry provides only a free-text activity description, not structured activity codes. The `isAIInferred` flag is always `true` for Swiss activity codes. The single code inferred from the purpose text is also flagged with `isMainActivity: true`. Since that code is AI-inferred, it is distinguishable from a main activity a register would declare itself; an absent flag means the source did not designate one.
## Data Availability
### Data Availability Matrix
| Data Type | Prefill | Verification | Notes |
| - | - | - | - |
| Company profile | ✅ Limited | ✅ Full | Prefill: name, UID/EHRA ID, legal form, city/canton; no status. Verification: live name, status, address, capital, purpose, and dates. |
| Legal Representatives | ❌ | ⚠️ AI-parsed | People with signing authority, from the cantonal trade register extract; SOGC fallback if a cantonal portal is down |
| Other Key Persons | ❌ | ⚠️ AI-parsed | Statutory auditor and board members without signing authority, from the cantonal extract |
| Shareholders | ❌ | ❌ | Not available from Swiss registries |
| Ultimate Beneficial Owners | ❌ | ❌ | Not publicly accessible in Switzerland |
| Establishments | ❌ | ❌ | Not available via Zefix API |
| Activity Codes | ❌ | ⚠️ AI-inferred | Derived from free-text activity description via AI |
| Documents | Separate request | Separate request | Trade register extract (all 26 cantons) + Certificate of Incorporation (when SOGC exists) |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Documents by Company Type
| Document Type | API Category | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | ✅ All registered companies | Official internet extract from the cantonal commercial register. Available for all 26 cantons. |
| **Certificate of Incorporation** | `certificateOfIncorporation` | PDF | ⚠️ When SOGC exists | SOGC publication announcing the initial registration (`status.neu` mutation). Only available when such a publication exists. |
**Canton-specific document retrieval:** Trade register extracts are issued by the relevant canton's register, selected automatically from the company's cantonal registration. Delivery typically takes a few seconds.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "CH", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "CHE123456789",
"countryCode": "CH",
"identifiers": { "uid": "CHE123456789", "ehraId": "12345678", "chId": "CH12345678901" },
"legalName": "Beispiel Technologie AG",
"commercialNames": ["Example Technology Ltd"],
"registrationDate": "2020-03-15",
"incorporationDate": "2020-03-10",
"activityDescription": "Entwicklung und Vertrieb von Softwareloesungen fuer Unternehmen.",
"status": { "localName": "ACTIVE", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Aktiengesellschaft", "englishTranslation": "Company limited by shares", "standardized": "Corporation", "iso20275Code": "MVII" },
"capital": { "amount": 100000, "currency": "CHF", "formatted": "CHF 100,000" },
"activities": {
"NACE": [{ "code": "62.10", "description": "Computer programming activities", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "6219", "description": "Other computer programming activities", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "10, Bahnhofstrasse", "city": "Zuerich", "postalCode": "8001", "region": "ZH", "countryCode": "CH" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Präsident des Verwaltungsrates", "standardized": "Chairman of the Board" }, "representationMode": { "mode": "joint", "minimumSignatories": 2 }, "individual": { "name": { "fullName": "Hans MUELLER" } } },
{ "entityId": "person_002", "type": "individual", "role": { "localName": "Geschäftsführer", "standardized": "Managing Director" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Anna WEBER" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "CHE987654321",
"countryCode": "CH",
"identifiers": { "uid": "CHE987654321" },
"legalName": "Muster Consulting GmbH",
"registrationDate": "2018-06-01",
"activityDescription": "Erbringung von Beratungsdienstleistungen im Bereich Unternehmensorganisation.",
"status": { "localName": "ACTIVE", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Gesellschaft mit beschraenkter Haftung", "englishTranslation": "Limited liability company", "standardized": "Limited Liability Company", "iso20275Code": "3EKS" },
"capital": { "amount": 20000, "currency": "CHF", "formatted": "CHF 20,000" },
"activities": {
"NACE": [{ "code": "70.20", "description": "Business and other management consultancy activities", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "7020", "description": "Business and other management consultancy activities", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "5, Rue du Marche", "city": "Geneve", "postalCode": "1204", "region": "GE", "countryCode": "CH" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Gérant", "standardized": "Managing Director" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Pierre DUPONT" } } }
]
}
```
```json theme={null}
{
"company": {
"id": "CHE555666777",
"countryCode": "CH",
"identifiers": { "uid": "CHE555666777" },
"legalName": "Alte Firma GmbH",
"status": { "localName": "CANCELLED", "active": false, "statusDetails": { "status": "CLOSED", "closureDate": "2023-06-30" } },
"legalForm": { "localName": "Gesellschaft mit beschraenkter Haftung", "englishTranslation": "Limited liability company", "standardized": "Limited Liability Company", "iso20275Code": "3EKS" },
"capital": { "amount": 20000, "currency": "CHF", "formatted": "CHF 20,000" },
"legalAddress": { "addressLine1": "3, Avenue de la Gare", "city": "Lausanne", "postalCode": "1003", "region": "VD", "countryCode": "CH" }
}
}
```
**Note:** Closed companies have `active: false` with a `closureDate` when available. Legal representatives and other key persons may not be available for dissolved companies when the cantonal register publishes no extract for them.
```json theme={null}
{
"company": {
"id": "CHE111222333",
"countryCode": "CH",
"identifiers": { "uid": "CHE111222333" },
"legalName": "Marco ROSSI, Consulenza",
"registrationDate": "2019-04-15",
"activityDescription": "Consulenza aziendale e servizi di gestione.",
"status": { "localName": "ACTIVE", "active": true },
"legalForm": { "localName": "Entreprise individuelle", "englishTranslation": "Sole proprietorship", "standardized": "Sole Proprietorship", "iso20275Code": "AZA0" },
"activities": {
"NACE": [{ "code": "70.20", "description": "Business and other management consultancy activities", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "7020", "description": "Business and other management consultancy activities", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "Via Nassa 3", "city": "Lugano", "postalCode": "6900", "region": "TI", "countryCode": "CH" }
}
}
```
**Note:** Sole proprietorships (Einzelunternehmen / Entreprise individuelle / Ditta individuale) use the owner's name as the `legalName`. Legal representatives are not typically present.
```json theme={null}
{
"company": {
"id": "CHE444555666",
"countryCode": "CH",
"identifiers": { "uid": "CHE444555666" },
"legalName": "Stiftung fuer Bildung und Forschung",
"registrationDate": "2015-01-20",
"activityDescription": "Foerderung von Bildung und wissenschaftlicher Forschung.",
"status": { "localName": "ACTIVE", "active": true },
"legalForm": { "localName": "Stiftung", "englishTranslation": "Foundation", "standardized": "Nonprofit Organization", "iso20275Code": "2JZ4" },
"activities": {
"NACE": [{ "code": "72.20", "description": "Research and experimental development on social sciences and humanities", "isAIInferred": true, "isMainActivity": true }],
"ISIC": [{ "code": "7220", "description": "Research and experimental development on social sciences and humanities", "isAIInferred": true, "isMainActivity": true }]
},
"legalAddress": { "addressLine1": "Bundesplatz 1", "city": "Bern", "postalCode": "3003", "region": "BE", "countryCode": "CH" }
},
"legalRepresentatives": [
{ "entityId": "person_001", "type": "individual", "role": { "localName": "Praesident des Stiftungsrates", "standardized": "Chairman" }, "representationMode": { "mode": "sole" }, "individual": { "name": { "fullName": "Thomas SCHNEIDER" } } }
]
}
```
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Official cantonal commercial register extract PDF | All registered companies. Delivery typically takes a few seconds. |
| `certificateOfIncorporation` | SOGC incorporation publication PDF | When SOGC publication with `status.neu` mutation exists. Immediate delivery. |
## Data Source Priority & Routing
Verification mode uses a live Zefix lookup for company data. Prefill mode uses the published Zefix index for a limited company identity. Legal representatives and other key persons come from the official cantonal trade register extract via AI parsing in verification mode, with SOGC publications as a fallback for legal representatives only.
**Source Routing:**
1. **Prefill company identity** (name, UID/EHRA ID, legal form, city/canton): **Zefix linked-data index**; no status claim
2. **Verification company data** (name, status, legal form, address, capital, purpose, identifiers): **Zefix API** (live query via REST API)
3. **Legal representatives and other key persons**: **Cantonal trade register extract** (AI-parsed, split by signing authority). If the extract is unavailable, legal representatives fall back to SOGC publications (less complete); other key persons have no fallback
4. **Activity codes**: **AI-inferred** from the free-text `purpose` field in verification mode
5. **Legal form standardization**: **Deterministic** eCH-0097 to ISO 20275 mapping (AI only used as fallback if eCH-0097 code is not in the mapping table)
6. **Status enrichment**: **AI-enriched** for detailed status information in verification mode
### Attribute-Level Source Mapping
| Attribute | Source | Notes |
| - | - | - |
| Company name, legal form | **Zefix API / linked-data index** | Both modes return these identity fields |
| Translated names | **Zefix API** | Verification only, from `translation` array |
| Registered address | **Zefix API / linked-data index** | Verification returns the live address; prefill returns city and canton only |
| Share capital | **Zefix** | From `capitalNominal` and `capitalCurrency` |
| Activity description (purpose) | **Zefix** | From `purpose` field (free text) |
| Activity codes (NACE, ISIC) | **AI** | Inferred from activity description |
| Company status | **Zefix API** | Verification only, from `status` field + `deletionDate`; prefill does not report status |
| Legal representatives, other key persons | **Cantonal register via AI** | AI-parsed from the cantonal trade register extract; SOGC publications as fallback for legal representatives |
| Identifiers (`uid`, `ehraId`, `chId`) | **Zefix API / linked-data index** | Prefill returns UID and EHRA ID; verification can also return CH-ID |
| Registration/incorporation dates | **Zefix** | From SOGC publication dates within Zefix data |
# Transliteration
Source: https://docs.topograph.co/essentials/transliteration
Two ways to work with non-Latin company data: the response flag and the persisted name field
Some of the registers Topograph integrates return company data in non-Latin scripts: Bulgarian and Ukrainian in Cyrillic, Greek in Greek, Chinese (mainland and Hong Kong) in Simplified Chinese. There are two distinct features for working with that data in Latin form. They are independent and can be used together.
## The two features at a glance
| | `transliterate=true` query flag | `companyNameTransliterations` field |
| - | - | - |
| What it does | Rewrites every non-Latin user-facing string in the response into a single Latin form | Lists the canonical Latin spellings of the company's legal and commercial names |
| Scope | Whole response: names, addresses, descriptions, person names, status labels | Company names only |
| Output | Single string per field, replaces the original | `string[]` alongside the original-script name |
| Default | Off. Opt in by setting `transliterate=true` | Always populated when data exists. No flag required |
| Search impact | None. Response-time only | Indexed in search, so Latin queries match records registered only in a non-Latin script |
| Standards | One generic romanization across all scripts | Per-country standards, deduped. Ukrainian: generic folding, KMU 55, ISO 9. Bulgarian: generic folding, the Streamlined System, ISO 9. Greek: generic folding, ELOT 743 |
| When to use | "I don't read Cyrillic, give me the whole payload in Latin" | "Show me the canonical Latin spellings I can display or screen against" |
| Coverage today | All scripts (Cyrillic, Greek, Hangul, Hebrew, Arabic, Thai, CJK) | Ukraine, Bulgaria, Greece, and Greek-script names in Cyprus. Other non-Latin countries follow in later releases |
The two features are aligned: element `[0]` of `companyNameTransliterations` uses the same romanization as the response flag on `legalName`. Capitalisation can differ. For a name registered in capitals, `[0]` is title-cased (`Tovaristvo Z Obmezhenoyu`), while the flag keeps the capitals (`TOVARISTVO Z OBMEZhENOYu`), so compare the two case-insensitively.
The rest of this page documents the response flag. For the per-country name field, see the country page (e.g. [Ukraine](https://www.topograph.co/countries/ua#latin-script-search-and-the-companynametransliterations-field)).
## Response flag: `transliterate=true`
Transliteration is opt-in. Pass `transliterate=true` as a query parameter on `/v2/search` or `/v2/company`, and the response comes back with user-facing string fields rewritten in Latin characters.
## What gets transformed
The transform touches fields that carry user-facing text in the source language:
* Company names: `legalName`, `commercialNames`, `legacyLegalNames`, `legacyCommercialNames`
* Address components: `addressLine1`, `addressLine2`, `city`, `state`, `region`, `careOf`, `poBox`
* Person names: `title`, `firstName`, `middleName`, `lastName`, `fullName`, `suffix`
* Establishment, document, and graph node names: `name`
* Activity, control, and relationship descriptions: `description`, `activityDescription`
* Legal form, role, and status local labels: `localName`
* Status explanations: `additionalInfo`
Fields that are already in Latin form, or that represent identifiers rather than text, are never transformed. That includes `legalNameInEnglish`, `englishTranslation`, `standardized`, `iso20275Code`, `iso5009Code`, `countryCode`, `postalCode`, `id`, dates, URLs, phone numbers, and any numeric or enumerated value. Strings that are already in Latin script pass through untouched regardless of which field they live on.
## What does not change
The flag is a presentation toggle, not a data mutation:
* Cached content on the Topograph side stays in the native script. Repeated calls with and without the flag hit the same cache.
* Billing is unchanged. Transliteration is free.
* Non-Latin fields are replaced with their romanized equivalents in the response. If you need the native-script value as well, issue a second call without the flag.
## How routing works
The API picks a romanization strategy per string based on two signals: the Unicode script of the string and the country code of the record.
| Script detected | Library used | Standard |
| - | - | - |
| Cyrillic | `transliteration` (unidecode) | BGN/PCGN-compatible |
| Greek | `transliteration` (unidecode) | ISO 843 |
| Hangul | `transliteration` (unidecode) | Revised Romanization |
| Hebrew, Arabic, Thai | `transliteration` (unidecode) | ALA-LC compatible |
| CJK with hiragana or katakana | `kuroshiro` + `kuromoji` | Hepburn |
| CJK with kanji only, country = JP | `kuroshiro` + `kuromoji` | Hepburn |
| CJK with kanji only, other country | `pinyin-pro` | Hanyu Pinyin, toneless |
| Latin or ASCII | no-op | . |
Mixed-script strings are handled automatically. A string like `"Nokia 中国"` on a Chinese record becomes `"Nokia Zhong Guo"`: the Latin run passes through untouched and the Chinese run is routed to pinyin.
## Known limitations
Transliteration is a mechanical transform. It is not the same as translation, and it is not the same as the company's own branding in Latin characters.
* **Japanese proper nouns are imperfect.** Kuroshiro reads kanji through a morphological dictionary. For unusual personal and company names, the reading the dictionary picks may differ from the reading the company actually uses. If accuracy on a specific Japanese entity matters, cross-check against the source.
* **Chinese is character-level, not word-level.** Output is spaced per syllable (`Bei Jing Xiao Mi`), not joined (`Beijing Xiaomi`). Word-level joining would require a separate segmentation pass and we do not do it today.
* **Source-provided Latin names are ignored.** Some Hong Kong and Chinese records carry an official English name from the source register. The flag always produces a mechanical romanization of the native string, not that official English name. If you want the official English name, read `legalNameInEnglish` from the unflagged response: that field is never transliterated.
* **Streaming search is not transliterated.** `/v2/search?stream=true` returns Server-Sent Events straight from the search pipeline. The flag is ignored in streaming mode. Use the standard JSON mode when you need transliteration.
* **Determinism across versions.** The output of `pinyin-pro` and `kuroshiro` can change between library or dictionary versions. Library versions are pinned in the API image, so the output is stable within a release.
## Examples
Search a Bulgarian company and get Latin results:
```bash theme={null}
curl -H "x-api-key: $TOPOGRAPH_API_KEY" \
"https://api.topograph.co/v2/search?country=BG&query=%D0%92%D0%B0%D0%B7%D1%80%D0%B0%D0%B6%D0%B4%D0%B0%D0%BD%D0%B5&transliterate=true"
```
Retrieve a Chinese company profile in Latin:
```bash theme={null}
curl -H "x-api-key: $TOPOGRAPH_API_KEY" \
-X POST "https://api.topograph.co/v2/company?transliterate=true" \
-H "Content-Type: application/json" \
-d '{"countryCode":"CN","id":"91310000MA1FL10P8Q","dataPoints":["company"]}'
```
Fetch a previously created request in Latin:
```bash theme={null}
curl -H "x-api-key: $TOPOGRAPH_API_KEY" \
"https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114?transliterate=true"
```
## When to use this
Reach for `transliterate=true` when:
* Your downstream system (CRM, KYC engine, search index, spreadsheet export) only indexes Latin text.
* You want to display company and officer names in a Western UI without glyph fallbacks.
* You are matching names across jurisdictions and need a consistent Latin form on both sides.
Do not reach for it when:
* You need the company's own brand in Latin. Use `legalNameInEnglish` instead when the register provides it.
* You need to preserve the native-script value alongside the Latin form. Issue a second call without the flag, or store the unflagged response and call again with the flag only when rendering.
# United Kingdom
Source: https://docs.topograph.co/essentials/uk
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date United Kingdom reference is on the [United Kingdom country page](https://www.topograph.co/countries/gb).
## Start here
This guide contains public integration notes for United Kingdom. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
All UK company data is sourced from the **Companies House API**, the official public data API operated by [Companies House](https://www.gov.uk/government/organisations/companies-house) -- the UK executive agency responsible for incorporating and dissolving limited companies. Companies House traces its origins to 1844, when the Joint Stock Companies Act first enabled companies to be incorporated by registration.
There is a **single data source** for all UK entities. No priority chain or fallback logic is needed -- all data flows through one unified API.
### All company types
* **Companies House register** -- Structured company data: company name, status, legal form, registered address, SIC codes, officers (directors and secretaries), Persons with Significant Control (PSCs), and the UK establishments of overseas companies. This is our **sole source** for all UK company information.
* **Companies House filing history** -- The PDF documents filed at Companies House (accounts, incorporation documents, confirmation statements, resolutions, etc.).
### How data is organised
* **Company data** (`company`, `legalRepresentatives`, `otherKeyPersons`, `establishments`) covers the company profile (name, status, legal form, address, SIC codes and previous names) and its active officers. Establishments apply to overseas companies (FC prefix) only.
* **Beneficial owners** come from the PSC register, through the separate `ultimateBeneficialOwners` datapoint.
Status, legal forms, declared activity codes and known officer roles use deterministic mappings. Unknown role labels and legal forms may need AI enrichment in verification mode.
## Company Identifiers
### Query Identifiers
| Company Type | Format | Example | Notes |
| - | - | - | - |
| **Standard UK companies** | 8 digits | `00445790` | Most companies in England and Wales. Leading zeros are part of the number |
| **Overseas companies** | FC + 6 digits | `FC027926` | Foreign companies registered in the UK |
| **UK establishments** | BR + 6 digits | `BR001902` | UK branches of overseas companies |
| **Scottish companies** | SC + 6 digits | `SC132832` | Companies registered in Scotland |
| **Northern Ireland companies** | NI + 6 digits | `NI677453` | Companies registered in Northern Ireland |
| **Other prefixed numbers** | 2 letters + 6 digits | `OC303675`, `CE026411` | Other Companies House prefixes, such as LLPs (`OC`) |
| **Less common shapes** | 8 letters and digits | `R0000390`, `IP03289R`, `RS0001FI` | One letter and 7 digits, or letters at both ends |
Every company number is exactly 8 characters: uppercase letters and digits, with no spaces. Numeric-only numbers keep their leading zeros (e.g. `03789983`). Most numbers with letters use a 2-letter prefix and 6 digits, but letters can also appear elsewhere, so validate the length and the character set rather than a list of prefixes.
A 6- or 7-digit number that lost its leading zeros is accepted and zero-padded (`9611950` becomes `09611950`), and lowercase letters are uppercased.
### Identifiers in API Response
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| `companiesHouseNumber` | 8 characters | `03789983` | Always present -- the primary identifier |
`companiesHouseNumber` is the single key for a UK company number wherever it appears in a response. The queried company, related companies (corporate officers and persons with significant control), and reconstructed corporate shareholders all expose their number under `identifiers.companiesHouseNumber`. The same key is used in a search result's `matchReason.identifier`. There is no `companyNumber` key for UK entities.
The one exception is a reconstructed corporate shareholder whose number we read off a filing but could not confirm against Companies House. That number is not necessarily a Companies House number -- it is often a foreign register's, or another UK register's -- so it is returned under the generic `identifiers.registrationNumber` instead. `companiesHouseNumber` on a shareholder always means Companies House confirmed it. See [Shareholders](#shareholders).
The UK does not use VAT numbers as company identifiers in the Companies House register. UK VAT numbers (`GB` + 9 digits, or 12 digits for some branch registrations, e.g. `GB220430231`) are managed by HMRC, not Companies House. They are not returned, and search does not accept them: search by company number or name instead.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the Companies House number matches a registration or validation reference in GLEIF and identifies a single LEI.
The [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two digits. Coverage varies by entity; a missing LEI does not establish that the company has none.
Lapsed or retired LEIs can still be returned. Annulled LEIs are excluded, so the presence of this identifier does not establish current LEI registration status.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Company Number | 8 letters and digits | `03789983`, `SC132832` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string (2-160 chars) | `"TECHNOLOGY UK LIMITED"` | Fuzzy | Multiple results, dissolved companies included |
**Search queries Companies House live.** Exact company-number matching applies to every company number shape, numeric or with letters (e.g. `03789983`, `SC132832`, `R0000390`, `IP03289R`), and to a 6- or 7-digit number that lost its leading zeros. Name search returns dissolved companies too, as the Companies House website does.
Use 8-digit company number searches for best performance and exact matching.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones, from name searches and registration-number lookups alike.
## Quirks & Gotchas
| Quirk | Details | | |
| - | - | - | - |
| **Name format is SURNAME, Firstname** | Companies House returns officer names in "SURNAME, Firstname" format. The system parses this automatically, splitting on the comma. | | |
| **No direct shareholder API** | Companies House does not expose a shareholders endpoint. Shareholders are **AI-reconstructed** from filing history documents (capital, confirmation statements, incorporation documents). | | |
| **PSC = UBO (not shareholder)** | The PSC (Persons with Significant Control) register maps to UBOs, not shareholders. Currently active individual PSCs become UBOs. Corporate and legal-person PSCs are intermediaries and are not returned. | | |
| **Ownership in ranges, not exact** | PSC ownership is expressed as ranges (25-50%, 50-75%, 75-100%), not exact percentages. This is a Companies House data model limitation. | | |
| **Resigned officers filtered out** | Only active (non-resigned) officers are returned. Officers with a resignation date are excluded from the response. | | |
| **SIC codes are UK-specific** | UK SIC 2007 codes are 5 digits and identical to NACE Rev. 2 at the 4-digit level, with UK-specific subclasses at the 5th digit. ISIC Rev. 5 codes are AI-matched from SIC, and NACE Rev. 2.1 codes are derived from ISIC. | | |
| **Overseas companies have establishments** | Companies with FC prefix are foreign companies registered in the UK. They may have UK establishment branches (BR prefix). Establishments are only fetched for FC-prefixed companies. | | |
| **Super-secure PSCs** | Some PSCs are classified as "super-secure" with protected details. These appear as "Person with significant control (protected)" in the UBO data with no personal information. | | |
| **Corporate PSCs are not returned** | Corporate and legal-person PSCs are intermediaries. They are not returned as UBOs or as Other Key Persons. Only currently active individual PSCs and protected (super-secure) PSCs become UBOs. | | |
| **Secretaries are OKPs, not legal reps** | Company secretaries (including corporate secretaries and nominee secretaries) are classified as Other Key Persons, not Legal Representatives. | | |
| **Role includes occupation** | When Companies House provides an officer's occupation, the role `localName` is formatted as \`"Mapped Role | Occupation"`(e.g.,`"Director | Managing Director"\`). |
| **Previous company names preserved** | Companies that have changed names retain their historical names in the `legacyLegalNames` array. | | |
## Mappings
### Company Status
Company status is determined **deterministically** from the Companies House status -- no AI inference is involved.
| Local Status | Standardized Status | Notes |
| - | - | - |
| `active` | Active | Company is currently active |
| `active` (proposal to strike off) | Pending Dissolution | Active company with an open strike-off proposal -- see below |
| `open` | Active | UK establishment (branch of an overseas company) currently open |
| `registered` | Active | Registered entity types such as assurance companies and ICVCs |
| `dissolved` | Closed | Company has been dissolved |
| `closed` | Closed | UK establishment that has been closed |
| `converted-closed` | Closed | Company has been converted or closed |
| `removed` | Closed | Entity has been removed from the register |
| `liquidation` | Closed | Company is in liquidation |
| `administration` | Under Insolvency Proceeding | Company is in administration |
| `receivership` | Under Insolvency Proceeding | Company under receiver action |
| `voluntary-arrangement` | Under Insolvency Proceeding | Company under a voluntary arrangement |
| `insolvency-proceedings` | Under Insolvency Proceeding | Company is subject to insolvency proceedings |
Every value of the published Companies House status list is mapped deterministically, including the `open`/`closed` pair used for UK establishments (`BR`-prefixed numbers). The `localName` field preserves the original Companies House status value, and `status.active` is `true` for the Active rows above. For a company with an active strike-off proposal, the register status stays `active` while `localName` carries the more specific `active-proposal-to-strike-off`, and the standardized status detail is Pending Dissolution. The full list of possible status values is published on the pricing page.
### Filing compliance signals
Companies House publishes a few filing-compliance signals on every company profile. We surface them in two places.
**Pending strike-off.** A company with an active proposal to strike off is still reported by the register as active, so `status.active` stays `true`. The standardized `status.statusDetails.status` is set to `PENDING_DISSOLUTION` so you can tell it apart from a plainly active company, `status.localName` carries the register's `active-proposal-to-strike-off` detail, and there is a short `status.statusDetails.additionalInfo` note. Once the strike-off completes, the company moves to Closed.
**Compliance signals.** Companies House publishes five standing signals on every company profile, surfaced on the cross-country `complianceFlags` object:
| Key | `active: true` means |
| - | - |
| `accountsOverdue` | The statutory annual accounts are overdue |
| `annualFilingOverdue` | The confirmation statement (annual return) is overdue |
| `registeredCharges` | The register records charges or mortgages over the company's assets |
| `insolvencyHistory` | The register records insolvency proceedings in the company's history |
| `liquidated` | The company has been through liquidation |
Each flag object has:
| Field | Description |
| - | - |
| `active` | The register's own answer |
| `dueDate` | The date the filing was due and missed. Overdue flags only, and only while `active` is `true` |
| `source` | The register that reported the signal |
Companies House states all five **both ways**, so for the UK `active: false` is a formal clearance ("Companies House says this company has no registered charges"), not a default. A key is absent only where the payload genuinely omits the field, which happens on some older records. `insolvencyHistory` is historical: a company currently in proceedings is reported through `status.statusDetails.status`.
```json theme={null}
{
"status": { "localName": "active", "active": true, "statusDetails": { "status": "ACTIVE" } },
"complianceFlags": {
"accountsOverdue": { "active": true, "dueDate": "2024-09-30", "source": "companies_house" },
"annualFilingOverdue": { "active": false, "source": "companies_house" },
"registeredCharges": { "active": true, "source": "companies_house" },
"insolvencyHistory": { "active": false, "source": "companies_house" },
"liquidated": { "active": false, "source": "companies_house" }
}
}
```
**Statutory filing calendar.** The UK is the most complete implementation of the cross-country `statutoryFilings` field: Companies House publishes the full calendar for both obligations, the statutory accounts and the confirmation statement.
```json theme={null}
{
"statutoryFilings": {
"accounts": {
"financialYearEnd": "03-31",
"lastFiled": { "periodStart": "2024-04-01", "periodEnd": "2025-03-31" },
"next": {
"periodStart": "2025-04-01",
"periodEnd": "2026-03-31",
"dueDate": "2026-12-31",
"overdue": false
},
"source": "companies_house"
},
"annualFiling": {
"cadence": "annual",
"lastFiled": { "periodEnd": "2025-10-25" },
"next": { "periodEnd": "2026-10-25", "dueDate": "2026-11-08", "overdue": false },
"source": "companies_house"
}
}
}
```
`financialYearEnd` is the Companies House accounting reference date as `MM-DD`. It recurs every year, so it is not a full date. `lastFiled.periodEnd` is the "made up to" date. See [Compliance Signals & Statutory Filings](/essentials/compliance-signals) for the full field reference and the country availability matrix.
### Legal Forms
Legal forms are mapped **deterministically** from the Companies House registered company type to human-readable English descriptions. Since the UK is an English-speaking country, the `localName` and `englishTranslation` fields are identical. The standardized type and the ISO 20275 code come from the same static table, so they are deterministic too. Where Companies House refines the type with a `company_subtype` that has its own ISO 20275 code (Community Interest Companies, private fund limited partnerships), the subtype wins.
| Companies House Code | Legal Form (localName) | Standardized | ISO 20275 |
| - | - | - | - |
| `ltd` | Private limited company | Limited Liability Company | H0PO |
| `ltd` + `community-interest-company` | Community Interest Company (CIC) | Limited Liability Company | 17R0 |
| `plc` | Public limited company | Corporation | B6ES |
| `private-unlimited` | Private unlimited company | Other | 57V7 |
| `private-unlimited-nsc` | Private unlimited company without share capital | Other | 60IF |
| `private-limited-guarant-nsc` | Private limited by guarantee without share capital | Limited Liability Company | 4GJI |
| `private-limited-guarant-nsc-limited-exemption` | Private Limited Company by guarantee without share capital, use of 'Limited' exemption | Limited Liability Company | 4GJI |
| `private-limited-shares-section-30-exemption` | Private Limited Company, use of 'Limited' exemption | Limited Liability Company | H0PO |
| `old-public-company` | Old public company | Corporation | ZQ6S |
| `converted-or-closed` | Converted / closed | Other | - |
| `unregistered-company` | Unregistered company | Other | Q0M5 |
| `other` | Other company type | Other | - |
| Companies House Code | Legal Form (localName) | Standardized | ISO 20275 |
| - | - | - | - |
| `llp` | Limited liability partnership | Partnership | Z0EY |
| `limited-partnership` | Limited partnership | Partnership | ID30 |
| `limited-partnership` + `private-fund-limited-partnership` | Private Fund Limited Partnership (PFLP) | Partnership | 4HTX |
| `limited-partnership` + `spflp` | Scottish Private Fund Limited Partnership (SPFLP) | Partnership | 4HTX |
| `scottish-partnership` | Scottish qualifying partnership | Partnership | NBTW |
| Companies House Code | Legal Form (localName) | Standardized | ISO 20275 |
| - | - | - | - |
| `charitable-incorporated-organisation` | Charitable incorporated organisation | Nonprofit Organization | 7T8N |
| `scottish-charitable-incorporated-organisation` | Scottish charitable incorporated organisation | Nonprofit Organization | STX7 |
| Companies House Code | Legal Form (localName) | Standardized | ISO 20275 |
| - | - | - | - |
| `european-public-limited-liability-company-se` | European public limited liability company (SE) | Corporation | - |
| `united-kingdom-societas` | United Kingdom Societas | Corporation | 468Q |
| `eeig` | European Economic Interest Grouping (EEIG) | Other | - |
| `eeig-establishment` | European Economic Interest Grouping Establishment (EEIG) | Branch or Representative Office | - |
| `ukeig` | United Kingdom Economic Interest Grouping | Other | VYF8 |
| Companies House Code | Legal Form (localName) | Standardized | ISO 20275 |
| - | - | - | - |
| `oversea-company` | Overseas company | Branch or Representative Office | - |
| `registered-overseas-entity` | Overseas entity | Other | - |
| `uk-establishment` | UK establishment company | Branch or Representative Office | - |
| Companies House Code | Legal Form (localName) | Standardized | ISO 20275 |
| - | - | - | - |
| `investment-company-with-variable-capital` | Investment company with variable capital | Corporation | VV0W |
| `icvc-securities` | Investment company with variable capital | Corporation | VV0W |
| `icvc-warrant` | Investment company with variable capital | Corporation | VV0W |
| `icvc-umbrella` | Investment company with variable capital | Corporation | VV0W |
| `assurance-company` | Assurance-company | Corporation | 8CF0 |
| `protected-cell-company` | Protected cell company | Corporation | TT2H |
| Companies House Code | Legal Form (localName) | Standardized | ISO 20275 |
| - | - | - | - |
| `royal-charter` | Royal charter company | Corporation | 9B78 |
| `industrial-and-provident-society` | Industrial and Provident society | Cooperative | XLZV |
| `registered-society-non-jurisdictional` | Registered society | Cooperative | XLZV |
| `northern-ireland` | Northern Ireland company | Other | 4A3J |
| `northern-ireland-other` | Credit union (Northern Ireland) | Cooperative | JTCO |
| `further-education-or-sixth-form-college-corporation` | Further education or sixth form college corporation | Other | - |
Every field is deterministically mapped from the Companies House registered company type and subtype codes using a static lookup table. ISO 20275 codes are the active GLEIF codes for the United Kingdom; a form with no active code returns no `iso20275Code`. A company type that Companies House adds later and the table does not yet know is standardized with AI in verification mode. In prefill mode, `localName` carries the Companies House open-data category instead (for example `Private Limited Company`), with the same standardized type and code. Source: [Companies House API enumerations](https://github.com/companieshouse/api-enumerations/blob/master/constants.yml).
### Legal Representatives
Active officers are read from Companies House. The registered office determines the role classification. Secretaries, limited partners, supervisory-only officers and persons authorised only to accept service are returned under `otherKeyPersons`. Directors, LLP members, general partners and permanent representatives are returned under `legalRepresentatives`. The published office code supplies the standardized value; a separate occupation does not change it.
The role `localName` is built by combining the mapped officer role with the occupation field (when available) using a `" | "` separator. For example, if the officer role is `director` and the occupation is `Managing Director`, the `localName` will be `"Director | Managing Director"`.
Both individuals and corporate entities can hold officer roles. Corporate officers are detected by the presence of an `identification` field.
| Companies House Code | Mapped Role | Notes |
| - | - | - |
| `director` | Director | Most common role for UK companies |
| `corporate-director` | Director | Corporate entity serving as director |
| `nominee-director` | Nominee Director | Director appointed on behalf of another |
| `corporate-nominee-director` | Nominee Director | Corporate entity as nominee director |
| `cic-manager` | CIC Manager | Community Interest Company manager |
| `managing-officer` | Managing Officer | Used for overseas entities |
| `corporate-managing-officer` | Managing Officer | Corporate entity as managing officer |
| Companies House Code | Mapped Role | Notes |
| - | - | - |
| `llp-designated-member` | LLP Designated Member | Designated member of an LLP |
| `corporate-llp-designated-member` | LLP Designated Member | Corporate entity as LLP designated member |
| `llp-member` | LLP Member | Member of an LLP |
| `corporate-llp-member` | LLP Member | Corporate entity as LLP member |
| Companies House Code | Mapped Role | Notes |
| - | - | - |
| `general-partner-in-a-limited-partnership` | General Partner in a Limited Partnership | Active management partner |
| `corporate-general-partner-in-a-limited-partnership` | General Partner in a Limited Partnership | Corporate general partner |
| Companies House Code | Mapped Role | Notes |
| - | - | - |
| `member-of-a-management-organ` | Member of a Management Organ | SE company management organ |
| `corporate-member-of-a-management-organ` | Member of a Management Organ | Corporate entity in management organ |
| `member-of-an-administrative-organ` | Member of an Administrative Organ | SE company administrative organ |
| `corporate-member-of-an-administrative-organ` | Member of an Administrative Organ | Corporate entity in administrative organ |
| `manager-of-an-eeig` | Manager of an EEIG | EEIG manager |
| `corporate-manager-of-an-eeig` | Manager of an EEIG | Corporate entity as EEIG manager |
| Companies House Code | Mapped Role | Notes |
| - | - | - |
| `person-authorised-to-represent` | Person Authorised to Represent | Representing the entity |
| `person-authorised-to-represent-and-accept` | Person Authorised to Represent and Accept | Both roles combined |
| Companies House Code | Mapped Role | Notes |
| - | - | - |
| `judicial-factor` | Judicial Factor | Court-appointed factor (Scottish law) |
| `receiver-and-manager` | Receiver and Manager | Appointed by court or creditor |
### Other Key Persons
Company secretaries, limited partners, supervisory-only officers and persons authorised only to accept service are classified as Other Key Persons.
**Published Other Key Person Roles:**
| Companies House Code | Mapped Role | Standardized |
| - | - | - |
| `secretary` | Secretary | Secretary |
| `corporate-secretary` | Secretary | Secretary |
| `nominee-secretary` | Nominee Secretary | Secretary |
| `corporate-nominee-secretary` | Nominee Secretary | Secretary |
| `limited-partner-in-a-limited-partnership` | Limited Partner in a Limited Partnership | Other |
| `corporate-limited-partner-in-a-limited-partnership` | Limited Partner in a Limited Partnership | Other |
| `member-of-a-supervisory-organ` | Member of a Supervisory Organ | Supervisory Board Member |
| `corporate-member-of-a-supervisory-organ` | Member of a Supervisory Organ | Supervisory Board Member |
| `person-authorised-to-accept` | Person Authorised to Accept | Registered Agent |
A known registered office takes precedence over occupation. A director whose occupation includes “secretary” remains a Director. A secretary may participate in joint document execution with a director under UK law; this does not establish general sole authority. Limited partners and supervisory-only officers do not obtain general representation from those offices. Corporate and legal-person PSCs are not returned as Other Key Persons.
### Shareholders
The Companies House API does not provide a dedicated shareholders endpoint. Shareholders are extracted from filing history documents using **AI-based reconstruction**.
**Extraction Logic:**
| Source Document Category | When Used | Data Extracted |
| - | - | - |
| **Capital documents** | Share allotments, capital changes | Share structure and allottees |
| **Confirmation statements** | Annual returns with shareholding info | Current shareholders |
| **Incorporation documents** | Articles of association, initial subscribers | Initial shareholders |
| **Resolution documents** | Share-related decisions | Share transfers and changes |
The system:
1. Filters available documents to categories likely to contain shareholder information: capital, confirmation statements and annual returns, incorporation, resolutions, PSC filings, corrected re-filings, and re-registrations
2. Downloads the selected PDFs
3. Extracts shareholders using AI parsing
4. Resolves corporate shareholders to their own Companies House number where possible (see below)
5. Returns reconstructed shareholder data with share percentages and ownership details
**Ownership Fields:**
| Field | Description | Source |
| - | - | - |
| `sharePercentage` | Ownership percentage | AI-extracted from documents |
| `type` | Individual or Company | Determined from name patterns |
| `numberOfShares` | Number of shares held | AI-extracted from documents |
**Corporate shareholder identifiers:**
Filings name corporate shareholders by legal name, and only sometimes state a registration number. For each corporate shareholder, we confirm any number read from the filing against Companies House, and otherwise search by name. What comes back depends on what we could establish:
| Outcome | What you get |
| - | - |
| Confirmed against Companies House | `company.id` and `company.identifiers.companiesHouseNumber` -- a real UK company number you can key, dedupe and traverse |
| A number was read off the filing, but Companies House did not confirm it | `company.identifiers.registrationNumber` -- the number as stated in the filing, with no claim about which register issued it |
| Nothing to go on | Name only; `company.id` and `company.identifiers` are left undefined |
The middle row is the one to plan for. A number printed on a UK filing frequently belongs to a foreign register (a US parent's Delaware file number, an Italian or Indian company number) or to another UK register altogether -- the Mutuals register and the Charity Commission both issue numbers that are not Companies House numbers. Returning those under `companiesHouseNumber` would dead-end an ownership chain at a company number that does not exist, so we return them generically instead. **`companiesHouseNumber` on a shareholder means Companies House confirmed it; `registrationNumber` means we are passing on what the filing said.**
Treat the presence of a registration number on a shareholder as best-effort, not guaranteed. The `companiesHouseNumber` "always present" guarantee in the [Company Identifiers](#company-identifiers) table applies to the queried company itself, not to reconstructed shareholders.
Shareholder data is AI-reconstructed from filing history documents and is best-effort. For ownership transparency, the PSC register provides complementary information about individuals and entities with significant control (25%+ ownership or voting rights).
### Activity Code Mapping
UK companies use **UK SIC 2007** (UK Standard Industrial Classification of Economic Activities 2007) codes as returned by Companies House. UK SIC 2007 is maintained by the Office for National Statistics (ONS) and is identical to NACE Rev. 2 at the 4-digit level, with UK-specific 5-digit subclasses.
```
SIC 2007 (UK) → ISIC Rev. 5 (International) → NACE Rev. 2.1 (European)
```
| Classification | Source | Example | AI Inferred? |
| - | - | - | - |
| **SIC\_2007** (`SIC_2007`) | Companies House | `62012` | No (official) |
| **ISIC** | AI-matched from SIC | `6219` | Yes |
| **NACE** | Derived from ISIC (formal mapping table) | `62.10` | Inherits the ISIC flag |
SIC codes are **formally parsed** (never AI-inferred). The `isAIInferred` flag is always `false` for SIC codes. ISIC Rev. 5 codes are AI-matched from the SIC codes, then NACE Rev. 2.1 codes are derived from ISIC through a formal mapping table, so they carry the same `isAIInferred` flag as the ISIC code they come from. Companies can have multiple SIC codes. See [Standardization](/guides/standardization) for the versioned keys.
## Data Availability
### Data Availability Matrix
| Data Type | Regular UK Companies | Overseas Companies (FC) | UK Establishments (BR) | Notes |
| - | - | - | - | - |
| Company Profile | ✅ Async | ✅ Async | ✅ Async | From Companies House Public Data API |
| Legal Representatives | ✅ | ✅ | ✅ | Active directors from officers endpoint |
| Other Key Persons | ✅ | ✅ | ✅ | Secretaries, limited partners, supervisory-only officers and service recipients |
| Shareholders | ✅ (AI-reconstructed) | ⚠️ Limited | ❌ | Reconstructed from filing documents |
| Subsidiaries | ⚠️ (AI-reconstructed) | ❌ | ❌ | From the subsidiary undertakings note in filed accounts. Small and micro-entity filers are exempt from that note |
| Ultimate Beneficial Owners | ✅ | ⚠️ Limited | ❌ | From PSC register (active individuals and protected PSCs only) |
| Establishments | ❌ | ✅ | N/A | UK branches of overseas companies (FC prefix only) |
| Activity Codes (SIC) | ✅ | ✅ | ⚠️ | SIC codes from Companies House |
| Documents | ✅ | ✅ | ⚠️ Limited | PDFs from filing history |
**Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing
### Subsidiaries
`subsidiaries` is available for the UK. It returns the equity participations the queried company holds in other entities, AI-extracted from the subsidiary undertakings / related undertakings note (Companies Act 2006 s409) in the notes to the latest annual accounts filed at Companies House. Verify the values against the filing before relying on them for compliance.
Availability follows UK accounts-filing rules, not our coverage. Small companies filing filleted accounts and micro-entities (FRS 105) are generally exempt from disclosing that note, so they return no subsidiaries even when group relationships exist, and a company that has filed no accounts returns none. Overseas companies (FC) and UK establishments (BR) file no UK accounts, so they return none.
`subsidiaries` is a separate data block from `company`, and it is available in verification mode only. See the [Subsidiaries](/essentials/subsidiaries-extraction) guide for the response shape.
### Documents by Company Type
All UK company documents come from Companies House. Document pricing is listed on the [pricing page](https://topograph.co/pricing/gb). The trade register extract is included when company data is requested in the same call.
| Document Category | API Type | Format | Availability | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | PDF | ✅ All companies | The Companies House company report, in PDF |
| **Articles of Association** | `articlesOfAssociation` | PDF | ✅ When filed | Memorandum and articles, including later amendments filed as resolutions |
| **Certificate of Incorporation** | Other | PDF | ✅ When filed | Other incorporation filings |
| **Annual Accounts** | `financialStatements` | PDF | ✅ When filed | Annual accounts and financial statements |
| **Capital Documents** | Other | PDF | ✅ When filed | Share capital and structure changes |
| **Officer Changes** | Other | PDF | ✅ When filed | Director and secretary appointments/terminations |
| **Confirmation Statements** | Other | PDF | ✅ When filed | Annual confirmation statements (formerly annual returns) |
| **Resolutions** | Other | PDF | ✅ When filed | Company resolutions |
| **Address Changes** | Other | PDF | ✅ When filed | Registered office address changes |
| **Charges / Mortgages** | Other | PDF | ✅ When filed | Charges and mortgages registrations |
| **PSC Filings** | Other | PDF | ✅ When filed | Persons with significant control notifications and cessations |
| **Corrected Filings** | Other | PDF | ✅ When filed | Replacement re-filings of an earlier submission |
| **Re-registrations** | Other | PDF | ✅ When filed | Re-registration filings (e.g. Ltd to PLC) |
| **Miscellaneous** | Other | PDF | ✅ When filed | Other company filings |
The **Trade Register Extract** is always available for all companies. Filing history covers up to 2,000 filings per company.
### Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "GB", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "12345678",
"countryCode": "GB",
"identifiers": { "companiesHouseNumber": "12345678" },
"legalName": "EXAMPLE TECHNOLOGY LIMITED",
"legacyLegalNames": ["EXAMPLE SOLUTIONS LIMITED"],
"registrationDate": "2020-06-15",
"status": {
"localName": "active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Private limited company",
"englishTranslation": "Private limited company",
"standardized": "Limited Liability Company",
"iso20275Code": "H0PO"
},
"activities": {
"SIC_2007": [{ "code": "62012", "description": "Business and domestic software development", "isAIInferred": false }],
"NACE": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }],
"ISIC": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": true }]
},
"legalAddress": {
"addressLine1": "10 Innovation Drive",
"city": "London",
"postalCode": "EC2A 1AB",
"countryCode": "GB"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" },
"individual": {
"name": { "fullName": "SMITH, John Robert", "firstName": "John Robert", "lastName": "SMITH" },
"birthDate": { "month": 3, "year": 1980 }
},
"startDate": "2020-06-15"
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" },
"individual": {
"name": { "fullName": "JONES, Sarah", "firstName": "Sarah", "lastName": "JONES" },
"birthDate": { "month": 11, "year": 1985 }
},
"startDate": "2021-01-10"
}
],
"otherKeyPersons": [
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Secretary", "standardized": "Secretary" },
"individual": {
"name": { "fullName": "WILLIAMS, David", "firstName": "David", "lastName": "WILLIAMS" }
}
}
],
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": { "fullName": "John Robert Smith", "title": "Mr", "firstName": "John", "middleName": "Robert", "lastName": "Smith" },
"birthDate": { "month": 3, "year": 1980 },
"nationality": "GB",
"residenceAddress": { "addressLine1": "10 Innovation Drive", "city": "London", "postalCode": "EC2A 1AB", "countryCode": "GB" },
"control": {
"types": ["ownership-of-shares", "voting-rights"],
"description": "Person with significant control: ownership of shares 75 to 100 percent; voting rights 75 to 100 percent.",
"details": [
{ "type": "shares", "percentageRange": { "lower": 75, "upper": 100 }, "nature": null },
{ "type": "voting-rights", "percentageRange": { "lower": 75, "upper": 100 }, "nature": null }
]
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "00987654",
"countryCode": "GB",
"identifiers": { "companiesHouseNumber": "00987654" },
"legalName": "OLD INDUSTRIES PLC",
"registrationDate": "1998-02-20",
"status": {
"localName": "dissolved",
"active": false,
"statusDetails": { "status": "CLOSED" }
},
"legalForm": {
"localName": "Public limited company",
"englishTranslation": "Public limited company",
"standardized": "Corporation",
"iso20275Code": "B6ES"
},
"activities": {
"SIC_2007": [{ "code": "28110", "description": "Manufacture of engines and turbines", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "1 Industrial Park",
"city": "Birmingham",
"postalCode": "B1 1AA",
"countryCode": "GB"
}
},
"legalRepresentatives": []
}
```
**Note:** Dissolved companies have `active: false` and may have no active officers. Resigned officers are filtered out, so a dissolved company may return an empty `legalRepresentatives` array.
```json theme={null}
{
"company": {
"id": "OC345678",
"countryCode": "GB",
"identifiers": { "companiesHouseNumber": "OC345678" },
"legalName": "EXAMPLE CONSULTING LLP",
"registrationDate": "2018-04-01",
"status": {
"localName": "active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Limited liability partnership",
"englishTranslation": "Limited liability partnership",
"standardized": "Partnership",
"iso20275Code": "Z0EY"
},
"activities": {
"SIC_2007": [{ "code": "69201", "description": "Accounting and auditing activities", "isAIInferred": false }]
},
"legalAddress": {
"addressLine1": "20 Chancery Lane",
"city": "London",
"postalCode": "WC2A 1PL",
"countryCode": "GB"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "LLP Designated Member", "englishTranslation": "LLP Designated Member", "standardized": "Partner" },
"individual": {
"name": { "fullName": "BROWN, Alice", "firstName": "Alice", "lastName": "BROWN" },
"birthDate": { "month": 7, "year": 1975 }
},
"startDate": "2018-04-01"
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "LLP Member", "englishTranslation": "LLP Member", "standardized": "Partner" },
"individual": {
"name": { "fullName": "TAYLOR, Michael", "firstName": "Michael", "lastName": "TAYLOR" },
"birthDate": { "month": 2, "year": 1982 }
},
"startDate": "2018-04-01"
}
]
}
```
**Note:** LLPs use Designated Member and Member roles instead of Director. No secretary role in LLPs.
```json theme={null}
{
"company": {
"id": "FC022268",
"countryCode": "GB",
"identifiers": { "companiesHouseNumber": "FC022268" },
"legalName": "GLOBAL CORP SARL",
"registrationDate": "2005-11-01",
"status": {
"localName": "registered",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Overseas company",
"englishTranslation": "Overseas company",
"standardized": "Branch or Representative Office"
},
"legalAddress": {
"addressLine1": "50 Oxford Street",
"city": "London",
"postalCode": "W1D 1BS",
"countryCode": "GB"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Director", "englishTranslation": "Director", "standardized": "Director" },
"individual": {
"name": { "fullName": "MUELLER, Hans", "firstName": "Hans", "lastName": "MUELLER" }
}
}
],
"establishments": [
{
"name": "GLOBAL CORP UK BRANCH",
"creationDate": "2005-11-01",
"address": {
"addressLine1": "50 Oxford Street",
"city": "London",
"postalCode": "W1D 1BS",
"countryCode": "GB"
}
}
]
}
```
**Note:** Overseas companies (FC prefix) may include UK establishments. The `establishments` array lists UK branches/offices of the foreign parent company. Only companies with FC prefix trigger the establishments fetch.
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"entityId": "person_001",
"name": {
"fullName": "John Robert Smith",
"title": "Mr",
"firstName": "John",
"middleName": "Robert",
"lastName": "Smith"
},
"birthDate": { "month": 3, "year": 1980 },
"nationality": "GB",
"residenceAddress": {
"addressLine1": "10 Innovation Drive",
"city": "London",
"postalCode": "EC2A 1AB",
"countryCode": "GB"
},
"control": {
"types": ["ownership-of-shares", "voting-rights", "appoint-and-remove-directors"],
"description": "Person with significant control: ownership of shares 75 to 100 percent; voting rights 75 to 100 percent; right to appoint and remove directors.",
"details": [
{ "type": "shares", "percentageRange": { "lower": 75, "upper": 100 }, "nature": null },
{ "type": "voting-rights", "percentageRange": { "lower": 75, "upper": 100 }, "nature": null }
]
}
}
]
}
```
**Document availability:** The PSC datapoint returns structured beneficial-owner data. There is no standalone `ultimateBeneficialOwnersCertificate`. Individual PSC filings, when published, appear under `otherDocuments`.
**Note:** UBOs come from the PSC register. Currently active individual PSCs become UBOs with ownership/voting percentage ranges. Ceased PSCs are dropped. Corporate and legal-person PSCs are intermediaries and are not returned. Super-secure PSCs appear with `fullName: "Person with significant control (protected)"`, no personal details, and empty control types.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
**Always available:**
| API Category | Document | Notes |
| - | - | - |
| `tradeRegisterExtract` | Companies House company report | Always available |
**From filing history (when filed):**
| Filing Category | API Type | Notes |
| - | - | - |
| `incorporation` | `articlesOfAssociation` or Other | Memorandum and articles become `articlesOfAssociation` (also when filed under `resolution`). Other incorporation filings are certificates of incorporation |
| `accounts` | `financialStatements` | Annual accounts. The document name carries the register's accounts variant when Companies House states one, e.g. "Annual Accounts (Dormant)" for dormant-company accounts |
| `capital` | Other | Share capital changes |
| `officers` | Other | Officer appointments/terminations |
| `annual-return`, `confirmation-statement` | Other | Confirmation statements (formerly annual returns) |
| `resolution` | Other | Company resolutions |
| `address` | Other | Registered office changes |
| `mortgage` | Other | Charges and mortgages |
| `persons-with-significant-control` | Other | PSC notifications and cessations |
| `document-replacement` | Other | Corrected re-filings |
| `reregistration` | Other | Re-registration filings |
| `change-of-name` | Other | Company name changes |
| `liquidation` | Other | Liquidation documents |
| `miscellaneous` | Other | Other filings |
Document pricing is listed on the [pricing page](https://topograph.co/pricing/gb).
# Ukraine
Source: https://docs.topograph.co/essentials/ukraine
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Ukraine reference is on the [Ukraine country page](https://www.topograph.co/countries/ua).
## Start here
This guide contains public integration notes for Ukraine. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Data Availability](#data-availability)
* [Example API Responses](#example-api-responses)
## Data Sources
Company data comes from the Unified State Register (EDR), which has three distinct datasets. For a given entity, **company data comes from exactly one dataset**. The system routes to the correct dataset based on the identifier format and EDRPOU overlap resolution. Annual financial statements come from a separate open dataset published by the Ministry of Finance (see [Financial Statements](#financial-statements-dataset)).
### Unified State Register (EDR / ЄДР)
The **EDR (Єдиний державний реєстр юридичних осіб, фізичних осіб-підприємців та громадських формувань)** — Unified State Register of Legal Entities, Individual Entrepreneurs and Public Associations — is operated by the **Ministry of Justice of Ukraine** and published as open data at [data.gov.ua](https://data.gov.ua). It contains three separate datasets:
* **UO (Юридичні особи)** — Legal entities: LLCs, JSCs, cooperatives, nonprofits, state bodies, and all other company types. Identified by **EDRPOU** (8-digit code, Код ЄДРПОУ).
* **FOP (Фізичні особи-підприємці)** — Individual entrepreneurs (sole proprietors). Identified by **RECORD** (numeric internal register ID, exposed in the API with a `FOP-` prefix to avoid collision with UO EDRPOU codes).
* **FSU (Відокремлені підрозділи іноземних юридичних осіб)** — Subdivisions of foreign legal entities: representative offices and branches of foreign companies registered in Ukraine. Identified by **EDRPOU** (same 8-digit format as UO, but a separate dataset).
**EDR data is sourced from the government open data bulk dataset** published by the Ministry of Justice of Ukraine at data.gov.ua. No live API access is provided by the Ukrainian government for EDR data — the bulk dataset is the only officially available access method.
### Financial Statements Dataset
Annual financial statements of Ukrainian enterprises are published as open data by the **Ministry of Finance of Ukraine** on [data.gov.ua](https://data.gov.ua). They cover legal entities that file annual statements, for fiscal years 2021 to 2025. Individual entrepreneurs (FOP) do not file under this scheme.
### Dataset Routing
For a given identifier, the system determines the correct dataset as follows:
1. If the identifier starts with `FOP-` (e.g. `FOP-10693269`), route to **FOP** dataset.
2. If the identifier is numeric only, check **FSU first** — this resolves the \~40 known EDRPOU codes that appear in both FSU and UO datasets (FSU takes precedence). If not found in FSU, route to **UO**.
## Company Identifiers
### Query Identifiers
| Dataset | Identifier | Format | Example | Notes |
| - | - | - | - | - |
| **UO** (legal entities) | EDRPOU | 8 digits, leading zeros significant; the last digit is a check digit | `00113968` | Код ЄДРПОУ |
| **FSU** (foreign branches) | EDRPOU | 8 digits, leading zeros significant; the last digit is a check digit | `20018083` | Same format as UO; FSU checked first on ambiguous codes |
| **FOP** (individual entrepreneurs) | RECORD with `FOP-` prefix | `FOP-` + digits (7 or 8 digits in the records we have seen) | `FOP-10693269` | Bare RECORD number also accepted in search |
### Identifiers in API Response
| Identifier | Found in | Format | Example |
| - | - | - | - |
| `edrpou` | UO, FSU | 8 digits, leading zeros significant | `00113968` |
| `record` | FOP | Digits only, 7 or 8 in the records we have seen, no `FOP-` prefix | `10693269` |
FOP records are stored and returned with the `FOP-` prefix as the `id` field (e.g. `FOP-10693269`). The `identifiers.record` field contains the bare numeric value (`10693269`). Search works with both formats.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is optional. It is returned when the EDRPOU code (`edrpou`) matches exactly one LEI through a GLEIF registration or validation reference.
The [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase alphanumeric characters, ending in two check digits.
Coverage varies by entity. An absent `lei` does not prove that the company has no LEI. Lapsed, retired or merged LEIs may be returned; annulled LEIs are excluded.
## Search Capabilities
| Search Type | Example | Match Type | Notes |
| - | - | - | - |
| By EDRPOU | `00113968` | `id` with `identifier.edrpou` | Exact match |
| By FOP RECORD (bare) | `10693269` | `id` with `identifier.record` | Without `FOP-` prefix |
| By FOP RECORD (prefixed) | `FOP-10693269` | `id` with `identifier.record` | With `FOP-` prefix |
| By company name | `ТОВАРИСТВО` | `name` | Cyrillic |
| By company name (Latin) | `Naftogaz`, `Naftohaz`, `Kyivstar` | `name` | Latin queries are matched against `companyNameTransliterations` (see below). Works whether you spell with KMU 55 (`Naftohaz`), GOST (`Naftogaz`), or paste a diacritic form (`Hruŝovka`) |
| By FOP surname | `ІВАНОВ` or `Ivanov` | `name` | Full legal name (Surname + Given + Patronymic). Surname-first ordering makes surname prefix search effective. Latin spellings of the surname also match |
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Latin-script search and the `companyNameTransliterations` field
Ukrainian companies are registered in Cyrillic. To make Latin queries hit them, every Ukrainian company response carries a `companyNameTransliterations: string[]` field with the canonical Latin forms of the legal name and any commercial name. The same array is indexed in search, so a Latin query matches even when the source name is fully in Cyrillic.
Three deterministic standards are generated per company, deduped:
| Standard | Example for «Нафтогаз» | Example for «Хрущовка» | Typical paste source |
| - | - | - | - |
| Generic Latin folding | `Naftogaz` | `Khrushchovka` | Company self-branding (Soviet-era spellings), LEI/GLEIF Latin self-spellings |
| KMU 55 (Ukrainian National 2010) | `Naftohaz` | `Khrushchovka` | UA passports, government documents, post-2018 Wikipedia |
| ISO 9 (academic, diacritics) | `Naftogaz` | `Hruŝovka` | Academic papers, EU databases |
Notes:
* Element `[0]` is the generic-folding variant. It matches what you get from the `transliterate=true` flag (see [Transliteration](/essentials/transliteration)), so the two features stay aligned.
* The diacritic ISO 9 form lets you paste copies like `Hruŝovka` from academic sources and still match. Diacritics are folded on the query side, so the index entry `Hruŝovka` is hit by a query for `Hrusovka` too.
* The field is absent for Latin-script company names where the array would be empty. For non-Latin-script countries other than Ukraine, the field is currently absent (other countries follow in later releases).
* Source-language alternates (`Kyiv` vs `Kiev`, `Lviv` vs `Lvov`, `Odesa` vs `Odessa`) are not derivable from transliteration. Those forms come from transliterating different source-language Cyrillic strings and are not covered today.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **FOP prefix collision prevention** | FOP public IDs are prefixed with `FOP-` because FOP RECORD numbers and UO EDRPOU codes are both plain digits and can coincide. Without the prefix, collisions would occur. Always include `FOP-` when querying a specific individual entrepreneur. |
| **\~40 EDRPOU overlap between FSU and UO** | A small number of EDRPOU codes appear in both the FSU and UO datasets. The system checks FSU first; for these codes, the FSU record takes precedence. |
| **No address data** | The EDR open data bulk dataset does not include registered address information. The `legalAddress` field is always absent for Ukrainian entities. The ADDRESS field exists in the XML schema but is not populated by the Ukrainian government in their open data exports. |
| **One KVED\_2010 code, legal entities only** | For UO entities, the register publishes a single main KVED\_2010 code (КВЕД, the Ukrainian classification of economic activities). When the register text carries a code, it is returned under `activities.KVED_2010` with the derived NACE and ISIC codes. FOP and FSU records carry no activity codes. |
| **FOP has no capital** | Individual entrepreneurs do not have share capital; the `capital` field is absent for all FOP records. |
| **FSU has no capital** | Foreign entity subdivisions do not have share capital under Ukrainian law; the `capital` field is absent for all FSU records. |
| **`в стані припинення` = dissolution process** | The status "in process of termination" maps to `UNDER_INSOLVENCY_PROCEEDING` with `closureReason: LIQUIDATION` (for UO) or `VOLUNTARY_DISSOLUTION` (for FSU foreign branches). The company is not yet closed but is in active dissolution proceedings. |
| **FSU parent company extracted from text** | For FSU records, the foreign parent company details (legalName, countryCode, foreignCode) are parsed from the free-text FOUNDER field in the EDR data. This parsing covers common formats but may miss unusual entries. |
| **FOP farmers** | FOP records of farmers (фермер) carry `activityDescription: "Farmer (фермер)"` rather than a KVED\_2010 code. |
| **Historical records back to \~1991** | The EDR contains records since Ukrainian independence. Older records (pre-1996) may have incomplete data: missing registration date, missing legal form (OPF), or empty founder/signer fields. |
| **`representationMode` is partial** | Signing authority is inferred from the free-text SIGNER field. `mode: sole` is set when the text includes "без обмежень" or "самостійно". `mode: joint` is set when it includes "спільно з" or "разом з". Scopes that defer to the charter ("згідно статуту") or list financial caps leave `representationMode` absent. When set, `particularity.localText` carries the original Ukrainian scope text and `particularity.englishTranslation` provides a translation for common phrases. |
## Mappings
### Company Status
Status is determined **deterministically** from the EDR `STAN` (стан) field — no AI inference is involved.
| Local Status (Ukrainian) | English | Standardized Status | Closure Reason |
| - | - | - | - |
| зареєстровано | Registered | ACTIVE | — |
| зареєстровано, свідоцтво недійсне | Registered, certificate invalid | CLOSED | ADMINISTRATIVE\_DISSOLUTION |
| в стані припинення | In process of termination | UNDER\_INSOLVENCY\_PROCEEDING | LIQUIDATION (UO) / VOLUNTARY\_DISSOLUTION (FSU) |
| припинено | Terminated | CLOSED | Derived from termination reason text |
| скасовано | Cancelled | CLOSED | ADMINISTRATIVE\_DISSOLUTION |
| порушено справу про банкрутство | Bankruptcy proceedings initiated | UNDER\_INSOLVENCY\_PROCEEDING | BANKRUPTCY |
| архівний | Archived | CLOSED | OTHER |
**Closure reasons** for `припинено` (terminated) are parsed from the free-text termination reason field:
| Ukrainian Reason (partial match) | Standardized Closure Reason |
| - | - |
| за її рішенням / за його рішенням | VOLUNTARY\_DISSOLUTION |
| ліквідації / спрощеною процедурою | LIQUIDATION |
| реорганізації | MERGER |
| судового рішення, не пов'язано з банкрутством | COURT\_ORDER |
| банкрутством / банкрутом | BANKRUPTCY |
| смерті / безвісно відсутньою | OTHER |
### Legal Forms
Legal forms are mapped **deterministically** from the EDR `OPF` field — no AI inference is involved. The local Ukrainian name is always preserved verbatim in `legalForm.localName`.
#### Limited Liability & Corporations
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ | Limited Liability Company | Limited Liability Company |
| ТОВАРИСТВО З ДОДАТКОВОЮ ВІДПОВІДАЛЬНІСТЮ | Additional Liability Company | Limited Liability Company |
| ПРИВАТНЕ АКЦІОНЕРНЕ ТОВАРИСТВО (ПрАТ) | Private Joint-Stock Company | Corporation |
| ПУБЛІЧНЕ АКЦІОНЕРНЕ ТОВАРИСТВО (ПАТ) | Public Joint-Stock Company | Corporation |
| АКЦІОНЕРНЕ ТОВАРИСТВО (АТ) | Joint-Stock Company | Corporation |
| ЗАКРИТЕ АКЦІОНЕРНЕ ТОВАРИСТВО (ЗАТ) | Closed Joint-Stock Company | Corporation |
| ВІДКРИТЕ АКЦІОНЕРНЕ ТОВАРИСТВО (ВАТ) | Open Joint-Stock Company | Corporation |
| ДОЧІРНЄ ПІДПРИЄМСТВО | Subsidiary Enterprise | Corporation |
| ІНОЗЕМНЕ ПІДПРИЄМСТВО | Foreign Enterprise | Corporation |
| СПІЛЬНЕ ПІДПРИЄМСТВО | Joint Venture | Partnership |
| ТОВАРНА БІРЖА | Commodity Exchange | Corporation |
| КОРПОРАЦІЯ | Corporation | Corporation |
| КОМАНДИТНЕ ТОВАРИСТВО (КТ) | Limited Partnership | Partnership |
| ПОВНЕ ТОВАРИСТВО (ПТ) | General Partnership | Partnership |
#### Sole Proprietorships & Family Enterprises
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| ФІЗИЧНА ОСОБА-ПІДПРИЄМЕЦЬ | Individual Entrepreneur | Sole Proprietorship |
| ПРИВАТНЕ ПІДПРИЄМСТВО (ПП) | Private Enterprise | Sole Proprietorship |
| СІМЕЙНЕ ПІДПРИЄМСТВО | Family Enterprise | Partnership |
#### Cooperatives
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| КООПЕРАТИВ | Cooperative | Cooperative |
| ВИРОБНИЧИЙ КООПЕРАТИВ | Production Cooperative | Cooperative |
| СІЛЬСЬКОГОСПОДАРСЬКИЙ ВИРОБНИЧИЙ КООПЕРАТИВ | Agricultural Production Cooperative | Cooperative |
| СІЛЬСЬКОГОСПОДАРСЬКИЙ ОБСЛУГОВУЮЧИЙ КООПЕРАТИВ | Agricultural Service Cooperative | Cooperative |
| ОБСЛУГОВУЮЧИЙ КООПЕРАТИВ | Service Cooperative | Cooperative |
| ПІДПРИЄМСТВО СПОЖИВЧОЇ КООПЕРАЦІЇ | Consumer Cooperative Enterprise | Cooperative |
| СПОЖИВЧЕ ТОВАРИСТВО | Consumer Society | Cooperative |
| СПОЖИВЧИЙ КООПЕРАТИВ | Consumer Cooperative | Cooperative |
| ОБ'ЄДНАННЯ СПІВВЛАСНИКІВ БАГАТОКВАРТИРНОГО БУДИНКУ | Apartment Building Co-owners Association | Cooperative |
| САДІВНИЧЕ ТОВАРИСТВО | Gardening Society | Cooperative |
| ЖИТЛОВО-БУДІВЕЛЬНИЙ КООПЕРАТИВ | Housing Construction Cooperative | Cooperative |
| ГАРАЖНИЙ КООПЕРАТИВ | Garage Cooperative | Cooperative |
| КРЕДИТНА СПІЛКА | Credit Union | Cooperative |
| КОЛЕКТИВНЕ ПІДПРИЄМСТВО | Collective Enterprise | Cooperative |
#### Farm Enterprises
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| ФЕРМЕРСЬКЕ ГОСПОДАРСТВО | Farm Enterprise | Partnership |
| СЕЛЯНСЬКЕ (ФЕРМЕРСЬКЕ) ГОСПОДАРСТВО | Peasant (Farm) Enterprise | Partnership |
#### Nonprofits & Civil Society
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| ГРОМАДСЬКА ОРГАНІЗАЦІЯ | Public Organization | Nonprofit Organization |
| ПРОФСПІЛКА | Trade Union | Nonprofit Organization |
| БЛАГОДІЙНА ОРГАНІЗАЦІЯ | Charitable Organization | Nonprofit Organization |
| РЕЛІГІЙНА ОРГАНІЗАЦІЯ | Religious Organization | Nonprofit Organization |
| ПОЛІТИЧНА ПАРТІЯ | Political Party | Nonprofit Organization |
| АСОЦІАЦІЯ | Association | Nonprofit Organization |
| СПІЛКА ОБ'ЄДНАНЬ ГРОМАДЯН | Union of Civil Society Organizations | Nonprofit Organization |
| ОРГАНІЗАЦІЯ (УСТАНОВА, ЗАКЛАД) ОБ'ЄДНАННЯ ГРОМАДЯН | Organization of a Civil Society Association | Nonprofit Organization |
| ПІДПРИЄМСТВО ОБ'ЄДНАННЯ ГРОМАДЯН (РЕЛІГІЙНОЇ ОРГАНІЗАЦІЇ, ПРОФСПІЛКИ) | Enterprise of a Civil Society Organization | Nonprofit Organization |
| ПРИВАТНА ОРГАНІЗАЦІЯ (УСТАНОВА, ЗАКЛАД) | Private Organization (Institution) | Nonprofit Organization |
| ОРГАН САМООРГАНІЗАЦІЇ НАСЕЛЕННЯ | Community Self-Organization Body | Government-Owned Entity |
| ІНШІ ОБ'ЄДНАННЯ ЮРИДИЧНИХ ОСІБ | Other Association of Legal Entities | Nonprofit Organization |
| АДВОКАТСЬКЕ БЮРО | Law Office | Partnership |
| АДВОКАТСЬКЕ ОБ'ЄДНАННЯ | Bar Association | Partnership |
| ОРГАНІЗАЦІЯ ОРЕНДАРІВ | Tenants' Organization | Nonprofit Organization |
#### Government & Public Law
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| КОМУНАЛЬНА ОРГАНІЗАЦІЯ (УСТАНОВА, ЗАКЛАД) | Municipal Organization (Institution) | Government-Owned Entity |
| ДЕРЖАВНА ОРГАНІЗАЦІЯ (УСТАНОВА, ЗАКЛАД) | State Organization (Institution) | Government-Owned Entity |
| КОМУНАЛЬНЕ ПІДПРИЄМСТВО | Municipal Enterprise | Government-Owned Entity |
| ДЕРЖАВНЕ ПІДПРИЄМСТВО | State Enterprise | Government-Owned Entity |
| ОРГАН МІСЦЕВОГО САМОВРЯДУВАННЯ | Local Self-Government Body | Government-Owned Entity |
| ОРГАН ДЕРЖАВНОЇ ВЛАДИ | State Authority Body | Government-Owned Entity |
| ОРГАН ВИКОНАВЧОЇ ВЛАДИ | Executive Authority Body | Government-Owned Entity |
#### Branches & Representative Offices
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| ФІЛІЯ | Branch | Branch or Representative Office |
| ПРЕДСТАВНИЦТВО | Representative Office | Branch or Representative Office |
| ВІДОКРЕМЛЕНИЙ ПІДРОЗДІЛ | Separate Subdivision | Branch or Representative Office |
FSU records (foreign subdivisions) take their legal form from the register's branch type: Представництво (Representative Office), Філія (Branch) or Відокремлений підрозділ (Separate Subdivision). When the branch type is missing, `legalForm.localName` is "Відокремлений підрозділ іноземної юридичної особи" (Separate Subdivision of Foreign Legal Entity). FSU records are always standardized as Branch or Representative Office. A UO record with no legal form whose name starts with "Філія" is also returned as a Branch.
#### Other
| Ukrainian (OPF) | English | Standardized |
| - | - | - |
| ІНШІ ОРГАНІЗАЦІЙНО-ПРАВОВІ ФОРМИ | Other Legal Forms | Other |
### Legal Representatives
Roles are mapped **deterministically** from the EDR SIGNER role text:
| Local Role (Ukrainian) | English | Standardized |
| - | - | - |
| керівник | Director | Director |
| директор | Director | Director |
| генеральний директор | General Director | Chief Executive Officer |
| виконавчий директор | Executive Director | Executive Director |
| голова правління | Chairman of the Board | Chairman of the Board |
| представник | Representative | Director |
| голова | Chairman | Chairman |
| президент | President | President |
| ліквідатор | Liquidator | Liquidator |
| голова комісії з припинення | Termination Commission Chairman | Liquidator |
| розпорядник майна | Property Manager (Receiver) | Receiver |
| підприємець *(FOP only)* | Individual Entrepreneur | Owner |
### Shareholders
* **UO**: Shareholders are extracted from the FOUNDERS (ЗАСНОВНИКИ) section of the EDR record. Both individual and company shareholders are supported, with nominal capital amounts in UAH.
* **FOP**: Not applicable. An individual entrepreneur has no share capital, so the `shareholders` datapoint returns a `datapoint_not_applicable` status. The entrepreneur is returned under `legalRepresentatives` (role Owner) and `ultimateBeneficialOwners` (100%).
* **FSU**: The foreign parent company is represented as a single company shareholder (100%). Includes `countryCode`, `legalName`, and `identifiers.foreignCode` when available in the source data.
## Data Availability
| Datapoint | UO | FOP | FSU |
| - | - | - | - |
| legalName | Yes | Yes | Yes |
| registrationDate | Yes | Yes | Yes |
| legalForm | Yes | Yes | Yes |
| status | Yes | Yes | Yes |
| capital | Partial (not all records) | No | No |
| shareholders | Partial (not all records) | Not applicable | Yes (foreign parent) |
| ultimateBeneficialOwners | Partial (not all records) | Yes (self, 100%) | No |
| legalRepresentatives | Partial (not all records) | Yes (self) | Partial |
| legalRepresentatives\[].representationMode | Partial (when determinable from authority text) | No | Partial |
| legalAddress | No | No | No |
| activityCodes | Partial (KVED\_2010, plus NACE and ISIC, when the EDR string carries a code) | No | No |
| financial statements (document) | Yes, for entities that file them (2021 to 2025) | No | Only when filed |
| certified register extract (document) | Yes (manual, 1 to 3 business days) | No | Yes (manual, 1 to 3 business days) |
The EDR publishes a single KVED\_2010 per entity: the primary activity (основний вид діяльності). When present, the KVED\_2010 code carries `isMainActivity: true`, and the NACE and ISIC codes derived from it inherit the flag.
"Partial" for UO shareholders and legal representatives reflects the EDR open data: the structured FOUNDERS and SIGNERS sections are populated for most entities but may be empty for older records (pre-1996) or for government bodies and state enterprises that do not list individual founders.
`ultimateBeneficialOwners` is a separate data block from `company`. Ukraine publishes beneficial owners as open data alongside the EDR company record, so the BENEFICIARY section is populated for most UO entities but empty for those with no registered beneficiary. For sole entrepreneurs (FOP) the entrepreneur is returned as the sole 100% beneficial owner. FSU records carry none.
## Example API Responses
### 1. Active UO — State Enterprise (LLC equivalent)
A state enterprise with a single government-body shareholder and a director.
```json theme={null}
{
"company": {
"id": "00113968",
"countryCode": "UA",
"identifiers": {
"edrpou": "00113968"
},
"legalName": "ДЕРЖАВНЕ ПІДПРИЄМСТВО \"НАУКОВО-ДОСЛІДНИЙ ІНСТИТУТ\"",
"commercialNames": ["ДП \"НДІ\""],
"registrationDate": "1993-11-16",
"status": {
"localName": "зареєстровано",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "ДЕРЖАВНЕ ПІДПРИЄМСТВО",
"englishTranslation": "State Enterprise",
"standardized": "Government-Owned Entity"
},
"capital": {
"amount": 691087.86,
"currency": "UAH"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "керівник",
"englishTranslation": "Director",
"standardized": "Director"
},
"representationMode": {
"mode": "sole",
"particularity": {
"localText": "без обмежень згідно статуту",
"englishTranslation": "without limitations per charter"
}
},
"individual": {
"name": {
"fullName": "ІВАНОВ ІВАН ІВАНОВИЧ"
}
}
}
],
"shareholders": [
{
"entityId": "company_001",
"type": "company",
"company": {
"legalName": "МІНІСТЕРСТВО ЕНЕРГЕТИКИ УКРАЇНИ"
},
"nominalCapitalHeld": {
"amount": 691087.86,
"currency": "UAH"
}
}
]
}
```
### 2. Active FOP — Individual Entrepreneur
An active individual entrepreneur, returned as their own legal representative. The `shareholders` datapoint is not applicable to individual entrepreneurs, so it is absent here.
```json theme={null}
{
"company": {
"id": "FOP-10693269",
"countryCode": "UA",
"identifiers": {
"record": "10693269"
},
"legalName": "ІВАНОВА ЛЮДМИЛА ДМИТРІВНА",
"registrationDate": "2012-12-10",
"status": {
"localName": "зареєстровано",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "ФІЗИЧНА ОСОБА-ПІДПРИЄМЕЦЬ",
"englishTranslation": "Individual Entrepreneur",
"standardized": "Sole Proprietorship"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "підприємець",
"englishTranslation": "Individual Entrepreneur",
"standardized": "Owner"
},
"individual": {
"name": {
"fullName": "ІВАНОВА ЛЮДМИЛА ДМИТРІВНА"
}
}
}
]
}
```
### 3. Active FSU — Foreign Representative Office
A foreign company's representative office registered in Ukraine. The parent company is the shareholder (100%), with country code and foreign registration number extracted from the EDR source.
```json theme={null}
{
"company": {
"id": "20018083",
"countryCode": "UA",
"identifiers": {
"edrpou": "20018083"
},
"legalName": "ПРЕДСТАВНИЦТВО \"ІНОЗЕМНА КОМПАНІЯ АГ\"",
"registrationDate": "1993-08-30",
"status": {
"localName": "зареєстровано",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Представництво",
"englishTranslation": "Representative Office",
"standardized": "Branch or Representative Office"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "керівник",
"englishTranslation": "Director",
"standardized": "Director"
},
"individual": {
"name": {
"fullName": "ІВАНОВ АНДРІЙ ОРЕСТОВИЧ"
}
}
}
],
"shareholders": [
{
"entityId": "company_001",
"type": "company",
"sharePercentage": 100,
"company": {
"countryCode": "CH",
"legalName": "\"ІНОЗЕМНА КОМПАНІЯ АГ\""
}
}
]
}
```
### 4. Closed UO — Government Body (Liquidated)
A closed government entity with a termination date and closure reason derived from the EDR termination text.
```json theme={null}
{
"company": {
"id": "00010103",
"countryCode": "UA",
"identifiers": {
"edrpou": "00010103"
},
"legalName": "ДЕРЖАВНИЙ ДЕПАРТАМЕНТ ДОКУМЕНТАЦІЇ",
"commercialNames": ["ДД ДД"],
"registrationDate": "2003-06-27",
"status": {
"localName": "припинено",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "LIQUIDATION",
"closureDate": "2011-10-04",
"additionalInfo": "Deregistration of legal entity as a result of liquidation"
}
},
"legalForm": {
"localName": "ОРГАН ДЕРЖАВНОЇ ВЛАДИ",
"englishTranslation": "State Authority Body",
"standardized": "Government-Owned Entity"
},
"capital": {
"amount": 0,
"currency": "UAH"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "керівник",
"englishTranslation": "Director",
"standardized": "Director"
},
"individual": {
"name": {
"fullName": "ІВАНОВ ІВАН ІВАНОВИЧ"
}
}
}
],
"shareholders": []
}
```
### 5. Active UO — Farm Enterprise (ФЕРМЕРСЬКЕ ГОСПОДАРСТВО)
A farm enterprise (standardized as Partnership). Registered in 1995; the individual founder is listed as shareholder.
```json theme={null}
{
"company": {
"id": "22074714",
"countryCode": "UA",
"identifiers": {
"edrpou": "22074714"
},
"legalName": "ФЕРМЕРСЬКЕ ГОСПОДАРСТВО \"ПРИКЛАД\"",
"commercialNames": ["ФГ \"ПРИКЛАД\""],
"registrationDate": "1995-08-22",
"status": {
"localName": "зареєстровано",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "ФЕРМЕРСЬКЕ ГОСПОДАРСТВО",
"englishTranslation": "Farm Enterprise",
"standardized": "Partnership"
},
"capital": {
"amount": 0,
"currency": "UAH"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "керівник",
"englishTranslation": "Director",
"standardized": "Director"
},
"individual": {
"name": {
"fullName": "ІВАНОВ ВАСИЛЬ МИХАЙЛОВИЧ"
}
}
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"individual": {
"name": {
"fullName": "ІВАНОВ ВАСИЛЬ МИХАЙЛОВИЧ"
}
}
}
]
}
```
# Alabama (US)
Source: https://docs.topograph.co/essentials/us-alabama
Entity identifiers, data sources, and implementation details for Alabama (US-AL)
This guide is outdated and will be removed on 1 November 2026. The up-to-date Alabama (US) reference is on the [Alabama (US) country page](https://www.topograph.co/countries/us-al).
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Legal Representatives](#legal-representatives)
* [Other Key Persons](#other-key-persons)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
All entity data comes from the **Alabama Secretary of State — Business Entities Division** via the ARC-SOS public portal ([arc-sos.state.al.us](https://arc-sos.state.al.us)). This is the official online search system for all corporations, limited liability companies, non-profit corporations, limited partnerships, general partnerships, and their foreign equivalents registered in Alabama.
Every request hits the live register. There is no bulk data export or open-data feed. Responses are always authoritative and reflect the register's current state.
Alabama is a single-source integration. All data — company profile, legal
representatives, registered agent, and search — comes from the live Alabama
SoS portal. The Trade Register Extract is included at no extra charge with
the company data block.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Entity ID Number** | 9 digits, leading zeros significant (`000358845`, `001226798`). Accepted with or without dashes (`000-358-845`) and without the leading zeros (`358845`). | `000358845` | Primary identifier assigned by Alabama SoS at registration |
The Alabama Secretary of State moved from 6-digit to 9-digit Entity IDs by adding three leading zeros to existing numbers, so older entities start with `000`. Both forms are accepted: `358845` and `000358845` resolve to the same entity. Responses always return the 9-digit form.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityId` | 9 digits, no dashes, leading zeros | `000358845` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Alabama Holdings"` | Starts with | Multiple results |
| By Entity ID | 1–9 digits | `000358845` | Exact | Single entity |
Name search matches from the beginning of the entity name (starts-with). Use
shorter prefixes for broader results. Dashes are stripped before matching, so
searching `000-358-845` and `000358845` return the same result.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **6-digit legacy IDs** | Entities numbered before the switch to 9 digits are displayed as `000NNNNNN` on the portal. Both `NNNNNN` and `000NNNNNN` are accepted as queries. |
| **Dashes in Entity IDs** | The portal displays IDs as `000-358-845` but the API returns and accepts undashed form `000358845`. |
| **LLCs have no member/manager data** | Alabama law does not require LLCs to publicly disclose their members or managers. LLC lookups return zero `legalRepresentatives` for members and managers. Only Corporations list Directors and Incorporators. |
| **Incorporators are historical** | Incorporators listed on the entity detail page reflect who signed the formation documents. They do not represent current governance and are returned in `otherKeyPersons` with the filed title and standardized role `Other`. |
| **Address format varies** | Older entities (pre-2000) often have only a city and state with no street address. `addressLine1` may be absent for historical records. |
| **Non-entity statuses** | The portal lists Name Reservations, Registered Names, and Previous Names alongside active entities. These are filtered out and return a 404. |
## Mappings
### Company Status
| Portal Status | Active |
| - | - |
| Exists | Yes |
| Cancelled | No |
| Dissolved | No |
| Merged | No |
| Revoked | No |
| Withdrawn | No |
| Converted | No |
Unknown statuses not in the table above are resolved via AI enrichment.
### Legal Forms
51 entity types are registered by Alabama SoS, covering domestic formations under Alabama law and foreign entities registered to do business in Alabama. ISO 20275 ELF codes are assigned to the four most common domestic types; foreign variants carry no ELF code, as the code belongs to the jurisdiction of formation.
| Legal Form | Standardized | ISO 20275 |
| - | - | - |
| Domestic Corporation | Corporation | HFGV |
| Domestic Benefit Corporation | Corporation | - |
| Domestic Professional Corporation | Corporation | - |
| Domestic Public Corporation | Corporation | - |
| Domestic Employee Cooperative Corporation | Corporation | - |
| Domestic Corporation Sole | Corporation | - |
| Legal Form | Standardized | ISO 20275 |
| - | - | - |
| Domestic Non-Profit Corporation | Nonprofit Organization | V65U |
| Domestic Professional Non-Profit Corporation | Nonprofit Organization | - |
| Domestic Homeowners Association | Nonprofit Organization | - |
| Domestic Professional Association | Nonprofit Organization | - |
| Domestic Non-Profit General Partnership | Partnership | - |
| Legal Form | Standardized | ISO 20275 |
| - | - | - |
| Domestic Limited Liability Company | Limited Liability Company | CWRI |
| Domestic Professional Limited Liability Company | Limited Liability Company | - |
| Domestic Series Limited Liability Company | Limited Liability Company | - |
| Domestic Non-Profit Ltd. Liability Company | Limited Liability Company | - |
| Domestic Non-Profit Series Ltd. Liability Company | Limited Liability Company | - |
| Domestic Professional Non-Profit Ltd. Liability Company | Limited Liability Company | - |
| Domestic Professional Series Ltd. Liability Company | Limited Liability Company | - |
| Legal Form | Standardized | ISO 20275 |
| - | - | - |
| Domestic Limited Partnership | Partnership | HN8W |
| Domestic General Partnership | Partnership | - |
| Domestic Limited Liability Partnership | Partnership | - |
| Domestic Registered Limited Liability Partnership | Partnership | - |
| Domestic Ltd. Liability Ltd. Partnership | Partnership | - |
| Legal Form | Standardized |
| - | - |
| Domestic Real Estate Investment Trust | Other |
| Domestic Unincorporated Association | Other |
| Delaware Statutory Trust | Other |
Foreign entities are registered to do business in Alabama after formation elsewhere. No ISO 20275 codes are assigned; the code belongs to the jurisdiction of formation.
| Legal Form | Standardized |
| - | - |
| Foreign Corporation | Corporation |
| Foreign Benefit Corporation | Corporation |
| Foreign Professional Corporation | Corporation |
| Foreign Public Corporation | Corporation |
| Foreign Employee Cooperative Corporation | Corporation |
| Foreign Insurance Corporation | Corporation |
| Foreign Business Entity | Other |
| Foreign Non-Profit Corporation | Nonprofit Organization |
| Foreign Professional Non-Profit Corporation | Nonprofit Organization |
| Foreign Homeowners Association | Nonprofit Organization |
| Foreign Professional Association | Nonprofit Organization |
| Foreign Limited Liability Company | Limited Liability Company |
| Foreign Professional Limited Liability Company | Limited Liability Company |
| Foreign Series Limited Liability Company | Limited Liability Company |
| Foreign Non-Profit Ltd. Liability Company | Limited Liability Company |
| Foreign Non-Profit Series Ltd. Liability Company | Limited Liability Company |
| Foreign Professional Series Ltd. Liability Company | Limited Liability Company |
| Foreign Limited Partnership | Partnership |
| Foreign General Partnership | Partnership |
| Foreign Non-Profit General Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Foreign Registered Limited Liability Partnership | Partnership |
| Foreign Ltd. Liability Ltd. Partnership | Partnership |
| Foreign Real Estate Investment Trust | Other |
| Foreign Unincorporated Association | Other |
### Legal Representatives
Legal representatives are returned for corporations only. Alabama LLCs are not required to publicly disclose their members or managers on the register.
| Portal Role | Standardized Role | Notes |
| - | - | - |
| Director | Director | Current governance role for corporations |
| Manager | Manager | For manager-managed LLCs (rarely disclosed) |
| Member | Other | Other key person; membership alone does not establish powers (rarely disclosed) |
| Incorporator | Other | Other key person; historical formation role |
### Other Key Persons
| Portal Role | Standardized Role |
| - | - |
| Registered Agent | Registered Agent |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Legal name | Yes | |
| Entity ID | Yes | |
| Legal form | Yes | 51 types, standardized + ISO 20275 where applicable |
| Status | Yes | Active/inactive, AI-enriched for unknown values |
| Formation date | Yes | |
| Registration address | Yes | May be city-only for pre-2000 entities |
| Nature of business | Yes | Free-text field, returned in `activityDescription` |
| Directors / Incorporators | Yes | Corporations only |
| Registered agent | Yes | Name and address |
| Shareholders | No | Not collected by the Alabama register |
| Officers (President, Secretary, etc.) | No | Not published on the public portal |
| Ultimate beneficial owners | No | No state UBO register |
| Activity codes (NAICS/SIC) | No | Free-text "Nature of Business" only |
## Documents
| Document | Available | Notes |
| - | - | - |
| Trade Register Extract | Yes | Printable PDF of the ARC-SOS entity detail page, included with all company data requests |
| Filing copies (Articles, Amendments, etc.) | No | Available from the Alabama SoS document portal but requires a US-issued payment card |
## Example API Responses
```json theme={null}
{
"company": {
"id": "000120714",
"countryCode": "US-AL",
"legalName": "SAMPLE MANUFACTURING INCORPORATED",
"legalForm": {
"localName": "Domestic Corporation",
"standardized": "Corporation",
"iso20275Code": "HFGV"
},
"status": { "active": true, "localName": "Exists" },
"legalAddress": {
"addressLine1": "100 COMMERCE DRIVE SUITE 200",
"city": "BIRMINGHAM",
"region": "AL",
"postalCode": "35203",
"countryCode": "US"
},
"registrationDate": "1987-11-23",
"activityDescription": "MANUFACTURING"
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Director", "standardized": "Director" },
"individual": {
"name": { "fullName": "SMITH JOHN A" },
"residenceAddress": {
"addressLine1": "100 COMMERCE DRIVE",
"city": "BIRMINGHAM",
"region": "AL",
"postalCode": "35203",
"countryCode": "US"
}
}
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Incorporator", "standardized": "Other" },
"individual": { "name": { "fullName": "DOE JANE B" } }
},
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"individual": {
"name": { "fullName": "REGISTERED AGENTS OF ALABAMA LLC" },
"residenceAddress": {
"addressLine1": "2 NORTH JACKSON STREET SUITE 605",
"city": "MONTGOMERY",
"region": "AL",
"postalCode": "36104",
"countryCode": "US"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "000605255",
"countryCode": "US-AL",
"legalName": "SAMPLE TECHNOLOGY LLC",
"legalForm": {
"localName": "Foreign Limited Liability Company",
"standardized": "Limited Liability Company"
},
"status": { "active": false, "localName": "Cancelled" },
"legalAddress": {
"city": "HUNTSVILLE",
"region": "AL",
"countryCode": "US"
},
"registrationDate": "2010-03-15"
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"individual": { "name": { "fullName": "JONES ROBERT C" } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "001169235",
"countryCode": "US-AL",
"legalName": "SAMPLE COMMUNITY FOUNDATION",
"legalForm": {
"localName": "Domestic Non-Profit Corporation",
"standardized": "Nonprofit Organization",
"iso20275Code": "V65U"
},
"status": { "active": true, "localName": "Exists" },
"legalAddress": {
"addressLine1": "500 WHITESBURG DRIVE",
"city": "HUNTSVILLE",
"region": "AL",
"postalCode": "35801",
"countryCode": "US"
},
"registrationDate": "2015-06-10",
"activityDescription": "COMMUNITY DEVELOPMENT"
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Director", "standardized": "Director" },
"individual": { "name": { "fullName": "WILLIAMS SARAH K" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"individual": {
"name": { "fullName": "SAMPLE REGISTERED AGENTS INC" },
"residenceAddress": {
"addressLine1": "300 CORPORATE DRIVE",
"city": "BIRMINGHAM",
"region": "AL",
"postalCode": "35242",
"countryCode": "US"
}
}
}
]
}
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "c710ff36-6a0b-55bf-a957-43a6a7f2240d",
"name": "Trade Register Extract",
"description": "Printable extract of the Alabama Secretary of State ARC-SOS Entity Detail page. Includes Entity ID Number, legal name, entity type, status, formation date, registered agent, principal address, nature of business, capital information, and filing history.",
"format": "pdf"
}
}
}
```
# Alaska
Source: https://docs.topograph.co/essentials/us-alaska
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Alaska reference is on the [Alaska country page](https://www.topograph.co/countries/us-ak).
## Start here
This guide contains public integration notes for Alaska. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
Alaska data comes from the **Alaska Department of Commerce, Community, and Economic Development, Division of Corporations, Business and Professional Licensing (CBPL)**. The register covers every entity formed or registered under Title 10 of the Alaska Statutes: business corporations (AS 10.06), nonprofit corporations (AS 10.20), professional corporations (AS 10.45), limited liability companies (AS 10.50), limited partnerships, limited liability partnerships, cooperative associations, and assumed/fictitious business name registrations (AS 10.35). Sole proprietors and other business-license holders, which are not in the corporations register, are covered through the Division's business-license register.
The two modes read the register differently:
* **Prefill** is served from the daily data extracts published by the Division of Corporations. Officials whose title includes Shareholder, Member or Owner are returned as shareholders without an ownership percentage, because the extracts do not carry one.
* **Verification** reads the live register. Shareholders are returned with the ownership percentage the register publishes.
The entity detail page, delivered as the Trade Register Extract, shows the legal name and name variants, current status, AK formation date, duration and expiration, home state, next biennial-report due date, entity mailing and physical addresses, the registered agent with mailing and physical addresses, the officials roster with role labels and any reported ownership percentages, and the full filing history.
**Full filing history available.** Each entity's complete filing history is listed alongside the company data, and each filing is ordered separately. This covers the Creation Filing (Articles of Association), Initial and Biennial Reports, amendments, changes of officials, and other historical filings. The number of filings per entity ranges from a few for recently formed LLCs to 70 or more for long-running corporations.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Alaska Entity Number** | Up to 8 digits for entities in the current numbering; older entities carry a letter suffix: `D`, `F`, `PD` or `PF` (e.g. `72D`, `476F`, `54PD`) | `10310827` | Assigned by the Division of Corporations (CBPL). Pass the number exactly as the register shows it. |
| **Alaska Business License Number** | Up to 7 digits; company ids take the form `AKBL-` | `AKBL-2200860` | Identifies sole proprietors and other business-license holders that are not in the corporations register. |
Entities formed under the older numbering scheme carry a letter suffix (`D`, `F`, `PD` or `PF`), for example `1089D` or `476F`. These are valid entity numbers and must be passed with the suffix. The `AKBL-` prefix on a business license id is added by Topograph so a license number can never be mistaken for an entity number: `identifiers.licenseNumber` holds the bare number, while `company.id` and search results hold the `AKBL-` form.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | Up to 8 digits, or digits plus a `D`, `F`, `PD` or `PF` suffix | `10310827` | Registered entities (corporations, LLCs, partnerships, nonprofits) |
| `licenseNumber` | Up to 7 digits (no `AKBL-` prefix) | `2200860` | Sole proprietors and other business-license holders |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when the entity number has a unique match against Alaska registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Tongass"` | Contains (case-insensitive) | Multiple results |
| By Alaska Entity Number | Digits, optionally with a letter suffix | `10310827` | Exact | Exact match returned first (`matchType: id`) |
**Contains search.** Name search matches any entity whose legal name or name variant contains the query string (case-insensitive). This includes previous legal names, active assumed names, and expired names registered against the entity. Use a longer query string to narrow the result set.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Entity number format varies by era** | Modern entities use 5–8 numeric digits (e.g. `94711`, `10310827`). Entities formed in the 1930s–1940s carry a `D` suffix (e.g. `1089D`, `993D`). Both formats are valid. Pass the number exactly as the register shows it. |
| **Officials data lags up to two years** | Alaska entities file biennial reports every two years on their anniversary date. The officials roster and ownership percentages on file reflect the most recent biennial report. For entities that have not yet filed their next report, officer and ownership data can be up to twenty-four months old. |
| **Ownership percentage is not always present** | The officials table publishes an ownership percentage only when the entity has reported one. When no percentage appears on file, the field is absent. Topograph does not infer a percentage from the number of officials or any other signal. |
| **Multiple name records per entity** | Each entity can carry several name rows: Legal Name, Previous Legal Name, Active Name, and Expired Name. Search returns one result per entity, so a match on a former or assumed name still returns the entity once. Always use the entity number, not the name, to fetch the profile. |
| **Name search includes historical names** | A contains search matches against all name records, including previous and expired names. An entity may appear in search results for a name it no longer uses. |
| **No shareholder or UBO register** | Alaska does not maintain a public beneficial-ownership register. Ownership percentages, when available, come from the officials roster on the entity detail page. The federal beneficial-ownership database is restricted to authorized users. |
| **No activity codes in live profile** | Industry classification codes (NAICS, NACE, ISIC) are not part of the live entity detail page. They are excluded from the Alaska company-data offering today. |
| **Business Name Registrations are included** | Assumed and fictitious name registrations (DBA filings under AS 10.35) appear in the register and in search results alongside full corporations and LLCs. These are name-only registrations, not separate legal entities; they carry no officer or filing history beyond the initial registration. |
| **No federal tax ID** | The federal employer identification number (FEIN) is not disclosed through the Alaska public business register. |
| **Per-filing certificates deferred** | Some filings have a separate Certificate column on the register (for example, a Certificate of Incorporation attached to a Creation Filing). Those certificate PDFs are published by the register but are not yet returned as a separate document type. The Filing PDF itself is always returned when the document type is supported. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type label published by the Division of Corporations on every entity record, and returned verbatim in `legalForm.localName`. The register uses the eleven entity types below. Sole proprietors resolved through the business-license register carry `Business License`.
| Register Label | Notes |
| - | - |
| Limited Liability Company | Formed under AS 10.50 |
| Business Corporation | Formed under AS 10.06 |
| Nonprofit Corporation | Formed under AS 10.20 |
| Business Name Registration | DBA / assumed-name filing under AS 10.35 |
| Limited Partnership | |
| Professional Corporation | Formed under AS 10.45 |
| Limited Liability Partnership | |
| Religious Corporation | |
| Cooperative Corporation | |
| COOP Electric and Telephone | Electric and telephone cooperatives |
| Foreign Corporate Name Registration | Name registration by a foreign corporation |
See the [pricing page](https://topograph.co/pricing/us-ak) for the current list.
### Officer Roles
Known functions use the published role catalogue in both modes. Pure director and ownership functions are other key persons; a compound title that also names an officer retains that officer meaning and every original title.
A manager-managed LLC member is an other key person when the roster names a manager. The register’s office category does not establish unrestricted signing powers, and no sole or joint signing mode is inferred.
The officials roster on the Alaska register lists one or more comma-separated role labels per official (for example, "Director, Shareholder" or "Director, Secretary, Treasurer"). The labels are returned verbatim in `role.localName`, as one comma-joined string per official, with fixed standardized meanings for known functions.
| Common Register Label | Notes |
| - | - |
| Director | Standard corporation director |
| President | Statutory corporation officer |
| Vice President | |
| Secretary | |
| Treasurer | |
| Member | LLC member (member-managed entities) |
| Manager | LLC manager (manager-managed entities) |
| Shareholder | Appears on the officials roster when ownership is reported |
| General Partner | Limited partnerships |
| Organizer | Entity organizer at formation |
In verification mode, officials whose `Owned` field carries an ownership percentage are also returned as shareholders, with that percentage. In prefill mode, officials whose title includes Shareholder, Member or Owner are returned as shareholders with no percentage. An official can appear in both `legalRepresentatives` and `shareholders`.
## Statutory Filings
Alaska entities file a biennial report confirming the entity's particulars are current. The register publishes "Next Biennial Report Due", returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "biennial",
"next": { "dueDate": "2027-01-02" },
"source": "ak_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name. Name variants (previous, active assumed, expired names) are shown on the Trade Register Extract |
| Company status | Yes | Current status from the live register (e.g. Good Standing, Involuntarily Dissolved) |
| Registration date | Partial | Prefill: AK formation date from the register. Verification: shown on the Trade Register Extract only |
| Duration / expiration | Partial | Shown on the Trade Register Extract where set; not returned as a structured field |
| Home state | Partial | Shown on the Trade Register Extract for foreign-registered entities; not returned as a structured field |
| Next biennial due date | Yes | Date of next required biennial report filing |
| Legal address | Yes | Entity physical address, or the mailing address when no physical address is published. Both appear on the Trade Register Extract |
| Legal form | Yes | Entity type label from the register, returned verbatim (see Legal Forms above) |
| Legal representatives | Yes | Officials roster with role labels returned verbatim |
| Shareholders | Yes | Verification: officials with a reported ownership percentage. Prefill: officials titled Shareholder, Member or Owner, with no percentage. No percentage is ever inferred |
| Registered agent | Yes | Agent name. Verification also returns the agent's physical address, or its mailing address when no physical one is published |
| Trade Register Extract | Yes | Included at no extra charge; a formatted PDF of the entity detail page |
| Articles of Association | Yes | Creation Filing PDF, ordered separately |
| Annual Return | Yes | Initial and Biennial Report PDFs, ordered separately |
| Other filings | Yes | Amendments, changes of officials, and other historical filings, ordered separately |
| Per-filing certificates | Roadmap | Certificate PDFs issued alongside certain filings (e.g. Certificate of Incorporation) are published by the register but not yet returned |
| Activity codes | No | Not surfaced on the live entity detail page; excluded from the current offering |
| UBOs | No | No state beneficial-ownership register; federal database is restricted to authorized users |
| Financial data | No | Not collected by the Alaska Division of Corporations |
| Federal tax ID (FEIN) | No | Not disclosed through the public register |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-AK&query=Denali" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "10000977",
"legalName": "DENALI EXAMPLE COMPANY LLC",
"countryCode": "US-AK",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "AK",
"countryCode": "US"
}
}
]
```
### Search by Entity Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-AK&query=10000977" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "10000977",
"legalName": "DENALI EXAMPLE COMPANY LLC",
"countryCode": "US-AK",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-AK", "id": "10000977", "dataPoints": ["company", "legalRepresentatives", "shareholders", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "10000977",
"countryCode": "US-AK",
"identifiers": { "entityNumber": "10000977" },
"legalName": "DENALI EXAMPLE COMPANY LLC",
"registrationDate": "2005-03-15",
"legalForm": {
"localName": "Limited Liability Company"
},
"status": {
"localName": "Good Standing",
"active": true
},
"legalAddress": {
"city": "Anchorage",
"region": "AK",
"postalCode": "99501",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Director, Member" },
"individual": { "name": { "fullName": "Jane A. Placeholder" } }
}
],
"shareholders": [
{
"entityId": "person_001",
"type": "individual",
"individual": { "name": { "fullName": "Jane A. Placeholder" } },
"sharePercentage": 70.0
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Registered Agent" },
"individual": {
"name": { "fullName": "Example Agent LLC" },
"residenceAddress": {
"addressLine1": "123 Placeholder St",
"city": "Juneau",
"region": "AK",
"postalCode": "99801",
"countryCode": "US"
}
}
}
]
}
```
# Arizona
Source: https://docs.topograph.co/essentials/us-arizona
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Arizona reference is on the [Arizona country page](https://www.topograph.co/countries/us-az).
## Start here
This guide contains public integration notes for Arizona. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Status](#company-status)
* [Data Availability](#data-availability)
## Data Sources
Arizona uses a single live integration against the **Arizona Corporation Commission (ACC) Business Center** (`arizonabusinesscenter.azcc.gov`). The ACC Business Center replaced the legacy eCorp portal on 2026-01-12 and is the official register for corporations, limited liability companies, limited partnerships, and other entities formed or qualified to do business in Arizona.
A single profile lookup returns the legal name, entity number, status, formation date, principal physical address, officers and members (reported on the latest filing), statutory agent, and any former legal names the entity has held, all in one call.
**Authoritative live lookups only.** There is no fast/cached path for Arizona: every request fetches current data directly from the ACC Business Center. Both prefill and verification requests use the same authoritative live source.
**No bulk dataset.** The ACC does not publish an open-data extract of Arizona business entities. A paid database extraction request is available from the ACC Records Section but is not automated or recurring, so no fast/snapshot mode is offered.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Arizona Entity Number** | 7 or 8 digits with no prefix, leading zeros significant (e.g. `01138954`, `23906030`), or one letter + 7 or 8 digits (e.g. `L10176615`, `F00005784`, `R18260883`, `N16431384`, `M0900455`). Letters in use: `D`, `F`, `L`, `M`, `N`, `R`. Trade names use a `T` prefix. | `R18260883` | Primary identifier assigned by the Arizona Corporation Commission. Numeric and letter-prefixed forms are both accepted. |
Pass the entity number exactly as it appears in ACC records or in a search result. The letter, when present, is part of the number, and so are leading zeros. Every form is accepted by the search and profile endpoints.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | 7–8 digits, or one letter + 7–8 digits | `R18260883` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–250 chars | `"Sonoran"` | Contains (case-insensitive) | Multiple results |
| By Entity Number | As issued | `R18260883` | Exact | Single match (matchType: id) |
**Contains search.** Name search finds results that contain the query string anywhere in the legal name (case-insensitive). The result set is capped. Use a longer query string to narrow results.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Two entity-number formats** | The ACC issues entity numbers in two forms: a legacy 7–10 digit numeric (pre-2026 portal) and the current "R + 8 digits" form. Both are accepted as query inputs and returned in `entityNumber`. Do not strip the "R" prefix. |
| **Foreign entities are labelled in the legal form** | Entities incorporated outside Arizona and qualified to do business in the state carry `Foreign` in their legal form label (`Domestic` for Arizona entities). The home state or country is not returned. |
| **Statutory agent is an other key person** | The ACC requires every entity to maintain a statutory agent (equivalent to a registered agent). The statutory agent is returned under `otherKeyPersons`, not `legalRepresentatives`. |
| **Officer title is free-text** | The ACC stores officer title as a free-text field. Common values include President, Director, Manager, Member, Managing Member, Secretary, Treasurer, Organizer, and Partner. Titles are normalized by AI enrichment. |
| **Status includes sub-reason** | Company status is returned as a primary label (Active, Inactive, Admin Hold, Pending Active, Pending Inactive) combined with a sub-reason where available (e.g. "Active (In Good Standing)", "Inactive (Voluntarily Dissolved)"). |
| **No shareholder or UBO register** | Arizona corporations and LLCs do not file shareholder lists with the ACC. Arizona does not maintain a public state-level beneficial ownership register. |
| **Previous names are absent, not empty** | `legacyLegalNames` is omitted from the response when an entity has never been renamed, rather than returned as `[]`. Renames are uncommon, so most Arizona entities carry no former names at all. The field lists former names only — the current legal name is never repeated inside it. |
| **Former names are not searchable** | Search matches on the entity's *current* name only. An entity that has been renamed cannot be found by a former name, because Arizona is a live-register integration and the ACC's own search behaves this way. Once you have the entity, its former names are returned on the profile. |
| **Per-filing PDFs not publicly available** | The ACC Business Center lists filed documents (annual reports, articles of organization, statements of change) on each entity's record, but individual filing PDFs are not available through the public unauthenticated path at this time. |
| **Certificate of Good Standing is a paid upgrade** | The Certificate of Good Standing is ordered through the ACC and carries an upstream register fee. It is a paid document separate from the free company data lookup. It is always ordered on the expedited track and is typically delivered within minutes. See the pricing page for current charges. |
## Mappings
### Legal Forms
Legal form is sourced directly from the entity's record type on the ACC Business Center. The local name (e.g. "Domestic For-Profit Corporation", "Foreign Limited Liability Company") is returned alongside a standardized Topograph category. Standardization is performed by AI enrichment against the local name.
Common Arizona entity types include:
| ACC Record Type | Standardized |
| - | - |
| Domestic For-Profit Corporation | Corporation |
| Foreign For-Profit Corporation | Corporation |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Corporation | Nonprofit Organization |
| Domestic Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic General Partnership | Partnership |
| Domestic Professional Corporation | Corporation |
| Domestic Professional Limited Liability Company | Limited Liability Company |
### Officer Roles
The ACC stores officer titles as free-text. Topograph normalizes each title through AI enrichment, producing a standardized role label. The table shows typical results.
| Common ACC Title | Standardized | Notes |
| - | - | - |
| President | President | Corporation statutory officer |
| Vice President | Vice President | |
| Secretary | Secretary | |
| Treasurer | Treasurer | |
| Director | Director | |
| Manager | Manager | LLC manager-managed structure |
| Member | *(AI-inferred)* | LLC member-managed structure |
| Managing Member | *(AI-inferred)* | LLC managing-member variant |
| Organizer | *(AI-inferred)* | LLC / corporation organizer at formation |
| General Partner | General Partner | Limited partnerships |
| Partner | Partner | General partnerships |
Officers, directors, managers, and members are classified as Legal Representatives. The statutory agent is returned as an Other Key Person and is not included in `legalRepresentatives`.
### Company Status
The ACC returns a primary status label combined with a sub-reason where present. The `active` flag in the API response is `true` only for entities with the literal `Active` status.
| ACC Status Label | Active flag | Notes |
| - | - | - |
| Active | `true` | Entity is in good standing |
| Inactive | `false` | Includes voluntarily dissolved, expired entities |
| Admin Hold | `false` | Administrative hold placed by the ACC |
| Pending Active | `false` | Filing submitted, ACC processing not yet complete |
| Pending Inactive | `false` | Dissolution or withdrawal pending ACC processing |
## Data Availability
For full datapoint and document availability, see the [Arizona pricing page](https://topograph.co/pricing/us-az).
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the ACC record |
| Previous names | Yes | Former legal names returned in `legacyLegalNames`, newest first. Omitted entirely when the entity has never been renamed |
| Company status | Yes | Primary status plus sub-reason (e.g. "Active (In Good Standing)") |
| Registration date | Yes | Formation or qualification date as filed with the ACC |
| Legal address | Yes | Principal physical address with street, city, state, and ZIP |
| Legal form | Yes | ACC record type, normalized by AI enrichment |
| Legal representatives | Yes | Officers, directors, managers, and members from the latest ACC filing |
| Statutory agent | Yes | Returned as an other key person (name, type, and address) |
| Foreign jurisdiction | No | Foreign entities are identifiable from the legal form label only |
| Activity codes | No | Not published by the ACC |
| Shareholders | No | Not filed with the ACC |
| UBOs | No | Arizona has no public state-level beneficial ownership register |
| Trade Register Extract | Yes | Free printable record from the ACC Business Center, included at no extra charge with the profile |
| Certificate of Good Standing | Yes | Paid document issued by the ACC; expedited delivery, typically within minutes |
| Per-filing PDFs | No | Individual filing documents are not available through the public path at this time |
| Financial data | No | Not collected by the ACC |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-AZ&query=Sonoran+Example+LLC" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "R00000001",
"legalName": "SONORAN EXAMPLE LLC",
"countryCode": "US-AZ",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "AZ",
"countryCode": "US"
}
}
]
```
### Search by Entity Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-AZ&query=R00000001" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "R00000001",
"legalName": "SONORAN EXAMPLE LLC",
"countryCode": "US-AZ",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-AZ", "id": "R00000001", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "R00000001",
"countryCode": "US-AZ",
"identifiers": { "entityNumber": "R00000001" },
"legalName": "SONORAN EXAMPLE LLC",
"registrationDate": "2010-03-15",
"status": {
"localName": "Active (In Good Standing)",
"active": true
},
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Phoenix",
"region": "AZ",
"postalCode": "85001",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Manager",
"standardized": "Manager"
},
"individual": {
"name": { "firstName": "Jane", "lastName": "Smith", "fullName": "Jane Smith" }
}
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Statutory Agent",
"englishTranslation": "Statutory Agent",
"standardized": "Registered Agent"
},
"company": { "legalName": "ACME REGISTERED AGENTS LLC" }
}
]
}
```
### Company Profile — entity with former names
An entity that has been renamed carries its previous legal names in
`legacyLegalNames`, newest first. This example is a real Arizona entity that
filed Articles of Amendment on 2026-07-23 to change its name.
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-AZ", "id": "23906030", "dataPoints": ["company"]}'
```
```json theme={null}
{
"company": {
"id": "23906030",
"countryCode": "US-AZ",
"identifiers": {
"entityNumber": "23906030"
},
"legalName": "MEDIEVAL MMA LLC",
"legacyLegalNames": ["IRONBLADE MMA LLC"],
"status": {
"localName": "Active (In Good Standing)",
"active": true
},
"registrationDate": "2025-11-06",
"legalForm": {
"localName": "Domestic Limited Liability Company"
},
"legalAddress": {
"addressLine1": "1837 S. Mesa Dr C100",
"city": "MESA",
"region": "AZ",
"postalCode": "85210",
"countryCode": "US"
}
}
}
```
`legacyLegalNames` is **omitted** rather than returned as an empty array when
an entity has never been renamed — which is the common case. Treat its absence
as "no former names on record", not as a failed lookup.
# Arkansas
Source: https://docs.topograph.co/essentials/us-arkansas
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Arkansas reference is on the [Arkansas country page](https://www.topograph.co/countries/us-ar).
## Start here
This guide contains public integration notes for Arkansas. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Filing Status](#filing-status)
* [Data Availability](#data-availability)
## Data Sources
Arkansas uses a single integration against the **Arkansas Secretary of State, Business & Commercial Services** portal (`sos-corp-search.ark.org`). The portal is publicly accessible and covers domestic and foreign entities filed with the SoS: corporations, limited liability companies, limited partnerships, general partnerships, and nonprofits.
The API returns:
* Legal name, filing number, entity type, and filing status
* Principal address
* Filing date
* Officers (when filed with the SoS)
The registered agent appears in `otherKeyPersons`. Formation and other non-representative appointments also retain their filed titles there. For foreign entities, the state of origin appears on the Trade Register Extract.
The printable entity detail page is delivered as the **Trade Register Extract**, included at no extra charge with every company data request.
Arkansas data is retrieved directly from the public SoS portal on each request. There is no snapshot or bulk extract available from this register. Frequently queried entities often respond quickly due to server-side caching on the portal.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Arkansas Filing Number** | 8-9 digits, almost always 9; older filings begin with `100`, `200` or `800`, current with `811` | `811388512` | Assigned by the Arkansas Secretary of State at time of registration |
Arkansas filing numbers are 8-9 digit numerics with no separators or leading zeros. The leading digits are a numbering series, not an entity type, and loosely track registration era: `100…`, `200…` and `800…` are older filings, `811…` is the current series for modern registrations.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `filingNumber` | 8-9 digits, no prefix | `811388512` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-250 chars | `"Walmart"` | Starts-with (case-insensitive) | Multiple results, up to 50 returned |
| By Filing Number | 8-9 digits | `811388512` | Exact | Exact match returned first (`matchType: id`) |
**Result cap.** The SoS portal silently caps search results at 250 rows server-side. Topograph returns up to 50 results ranked alphabetically. For narrow queries this is invisible; for broad name queries (e.g. a single common word) expect truncation without a `truncated` flag in the response.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No identifier prefix or padding** | Filing numbers are plain 8-9 digit integers. Do not add leading zeros or prefixes. Pass the number exactly as returned by search. |
| **`Incorporator/Organizer` is a single role** | The Arkansas SoS uses one label for both LLC organizers and corporation incorporators. The distinction is not recoverable from public data. |
| **Legacy "SEE FILE" officers** | Older filings (typically `100…` series) often carry a `SEE FILE` placeholder in the officers block. This means the officer data exists on paper but is not digitized on the portal. The API returns an empty officers list for these entities. |
| **Status field: `Pending`** | A `Pending` status means the filing has been submitted but not finalized. The `active` field in the response is `undefined` (neither `true` nor `false`) for pending entities. |
| **No shareholders or UBOs** | Arkansas does not publish shareholder lists or beneficial ownership data at the state level. Federal FinCEN BOI records are restricted. |
| **No activity codes** | The Arkansas SoS does not collect NAICS, NACE, or ISIC codes. Industry classification is not available. |
| **Fictitious names live separately** | DBA-style fictitious name registrations are a separate track and are not included in the business entity search index. |
| **Certificate of Good Standing is paid** | The Certificate of Good Standing exists but requires a separate purchase through the Arkansas state payment flow. It is not yet available through Topograph. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type field published by the Arkansas Secretary of State. The raw string is passed through to `legalForm.localName` and also used as input for AI-inferred standardization.
Common entity types observed:
| AR SoS Entity Type | Standardized |
| - | - |
| For Profit Corporation | Corporation |
| Foreign For Profit Corporation | Corporation |
| Non-Profit Corporation | Nonprofit Organization |
| Foreign Non-Profit Corporation | Nonprofit Organization |
| Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| General Partnership | Partnership |
| Limited Liability Partnership | Partnership |
| Professional Association | Corporation |
| Bank | Other |
| Insurance Company | Other |
The table above lists commonly observed types; the register may publish additional variants. Standardization is AI-inferred from the raw entity type.
### Officer Roles
Officer role labels on the Arkansas SoS portal are free-text. Known designations use the published role catalogue; unfamiliar wording is retained for enrichment. An officer title does not establish company-specific signing powers.
| Raw AR Role Label | Standardized (AI-inferred) | Notes |
| - | - | - |
| President | President | |
| Vice President | Vice President | Also observed as `Vice-President` |
| Secretary | Secretary | |
| Assistant Secretary | Secretary | Also observed as `Assistant Sec.` |
| Treasurer | Treasurer | |
| Director | Director | |
| Manager | Manager | |
| Member | (AI-inferred) | Member-managed LLCs |
| Owner | Owner | |
| Incorporator/Organizer | (AI-inferred) | Single AR label covering both LLC organizers and incorporators |
| Incorporator | (AI-inferred) | |
| Organizer | (AI-inferred) | |
Roles not listed above are still included in the response with their raw AR label as `localName`. Standardization is AI-inferred from the raw text.
### Filing Status
| AR SoS Status | `active` field | Notes |
| - | - | - |
| Good Standing | `true` | Entity is in good standing with the SoS |
| Pending | `undefined` | Filing submitted but not yet finalized |
| Dissolved | `false` | |
| Expired | `false` | |
| Forfeited Charter | `false` | Charter revoked, typically for failure to file or pay fees |
| Converted | `false` | Entity converted to another form |
| Merged | `false` | Entity merged into another entity |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Yes | `active: true/false/undefined` plus the raw SoS status string |
| Registration date | Yes | SoS initial filing date |
| Legal address | Yes | Principal address as filed with the SoS |
| Legal form | Yes | Raw entity type from the SoS, with AI-inferred standardization |
| Legal representatives | Yes | Officers as filed; known titles use the published catalogue, with powers qualified |
| Registered agent | No | Shown on the Trade Register Extract; not returned as an API field |
| State of origin | No | Shown on the Trade Register Extract for foreign entities; not returned as an API field |
| Trade Register Extract | Yes | Printed PDF of the SoS entity detail page; included at no extra charge |
| Activity codes | No | Not collected by the Arkansas SoS |
| Shareholders | No | Not published by the Arkansas SoS |
| UBOs | No | No state-level beneficial ownership register; federal FinCEN BOI is restricted |
| Certificate of Good Standing | Roadmap | Requires a separate paid purchase through the Arkansas state portal; not yet integrated |
| Fictitious names (DBAs) | No | Registered under a separate track, not part of the business entity dataset |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-AR&query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "811388512",
"legalName": "ACME HOLDINGS, INC.",
"countryCode": "US-AR",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "AR",
"countryCode": "US"
}
}
]
```
### Search by Filing Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-AR&query=811388512" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "811388512",
"legalName": "ACME HOLDINGS, INC.",
"countryCode": "US-AR",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-AR", "id": "811388512", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "811388512",
"countryCode": "US-AR",
"identifiers": { "filingNumber": "811388512" },
"legalName": "ACME HOLDINGS, INC.",
"registrationDate": "2012-03-15",
"status": {
"localName": "Good Standing",
"active": true
},
"legalForm": {
"localName": "Foreign For Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Little Rock",
"region": "AR",
"postalCode": "72201",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "President",
"englishTranslation": "President"
},
"individual": { "name": { "fullName": "JANE A. EXAMPLE" } }
}
]
}
```
# California
Source: https://docs.topograph.co/essentials/us-california
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date California reference is on the [California country page](https://www.topograph.co/countries/us-ca).
## Start here
This guide contains public integration notes for California. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)
## Data Sources
California data comes from the **California Secretary of State bizfileOnline register** (`bizfileonline.sos.ca.gov`). The register covers domestic and foreign corporations (stock, non-profit, professional, statutory close, cooperative), limited liability companies, limited partnerships, limited liability partnerships, and registered general partnerships.
The free public portal exposes: legal name, entity number, entity type, status, formation date, jurisdiction, registered agent (name, type, and address), principal office address, and mailing address.
**Officer and manager rosters.** Prefill mode returns the officer, director, manager, and member roster filed on the entity's Statements of Information, with governance roles and the registered agent under `otherKeyPersons`. Verification mode reads the live portal detail page, which exposes the registered agent under `otherKeyPersons`; that source returns an empty legal-representative roster.
**LLC manager visibility.** California required LLC Statements of Information to be filed through bizfileOnline starting 2022. LLC entities that have not refiled since then carry only their formation cover sheet with no manager or member data. Corporations are not affected.
**Prefill and verification modes.** Prefill mode returns within about a second from a periodic snapshot of the full California register. Very recent filings may not yet be reflected, and an entity missing from the snapshot is read live instead. Verification mode reads the live bizfileOnline portal for an authoritative result.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **California Entity Number** | Digits only, or `B` followed by 11 digits | `806592` | Primary identifier assigned by the California Secretary of State. Corporations: up to 7 digits, written `C` plus 7 digits by the register (`C0806592`). LLCs and limited partnerships registered before 2025: 12 digits (`201806210004`). Corporations, LLCs and limited partnerships registered since 2025: `B` followed by 11 digits (`B20260142586`). |
Corporation numbers are accepted with or without the `C` prefix and leading zeros, in both `/v2/search` and `/v2/company`. Responses always return them without the prefix or leading zeros (`C0806592` is returned as `806592`). The `B` of the 2025 series is part of the number: keep it.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | Up to 12 digits with no `C` prefix or leading zeros, or `B` followed by 11 digits | `806592` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–250 chars | `"Acme Corporation"` | Contains (case-insensitive) | Multiple results |
| By Entity Number | 4–12 digits with optional `C` prefix, or `B` followed by 11 digits | `806592`, `B20260142586` | Exact (`matchType: id`) | Single result when found |
**Entity number search.** A bare entity number resolves directly to the matching entity and returns its legal name, whether or not you include the `C` prefix or leading zeros.
**Best-match picker.** When multiple entities share the same legal name (for example an older merged-out entity and the current active one), the API prefers the entity with an exact name match and an Active status. If no Active match exists, it falls back to any exact name match, then to the first result.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Duplicate entity numbers under different internal records** | A bare numeric entity number (stripped of the `C` prefix and leading zeros) may collide with an unrelated internal record on the portal. The API always matches on the public entity number to avoid returning the wrong entity. |
| **No state-wide open-data feed** | California publishes no free statewide register extract equivalent to the open-data feeds available for New York or Pennsylvania. |
| **People differ by mode** | Prefill uses the filed officer and manager roster. Verification uses the live portal drawer, which returns the registered agent under `otherKeyPersons` and an empty `legalRepresentatives` roster. |
| **No shareholder or UBO register** | California does not publish shareholders or beneficial owners for any entity type. Federal FinCEN beneficial ownership records under the Corporate Transparency Act are access-restricted to authorized recipients. |
| **No activity codes** | Industry classification codes (NAICS, NACE, ISIC) are not collected by the California Secretary of State. |
| **Paid documents not yet available** | Certified Certificates of Status and certified copies are available from the Secretary of State at a fee. These are not yet offered through Topograph. The Trade Register Extract (printed portal detail page) is included at no extra charge with the company-data block, and the uncertified images of filed documents are listed below. |
| **Filed documents take a live lookup** | Listing an entity's filed documents (Initial Filing, Statements of Information, amendments) reads the live register, so the available-documents call takes about as long as a verification-mode profile. Downloading a listed filing is fast. Only filings the Secretary of State has an image of are listed. |
## Mappings
### Legal Forms
Legal form is read from the `Entity Type` field on the bizfileOnline detail page. bizfile renders the label in ` - - ` form (for example `Stock Corporation - CA - General`). The full label is preserved in `legalForm.localName`. Standardization and the ISO 20275 code match on the full label; a label outside the known vocabulary is standardized on its leading category, without an ISO 20275 code.
| bizfile Entity Type | Standardized | ISO 20275 |
| - | - | - |
| Stock Corporation - CA - General | Corporation | `H1UM` |
| Stock Corporation - CA - Professional | Corporation | `PZR6` |
| Stock Corporation - CA - Close | Corporation | `7CDL` |
| Other stock corporations (CA Benefit, Social Purpose, Insurer; Out of State) | Corporation | |
| Limited Liability Company - CA | Limited Liability Company | `EI4J` |
| Limited Liability Company - Out of State | Limited Liability Company | |
| Limited Partnership - CA | Partnership | `5HQ4` |
| Limited Partnership - Out of State | Partnership | |
| Nonprofit Corporation - CA - Public Benefit | Nonprofit Organization | `K7YU` |
| Nonprofit Corporation - CA - Mutual Benefit | Nonprofit Organization | `G1P6` |
| Nonprofit Corporation - CA - Religious | Nonprofit Organization | `CVXK` |
| Nonprofit Corporation - CA - Mutual Benefit - Credit Union | Nonprofit Organization | `O6AU` |
| Other nonprofit corporations (CA General, Out of State, Corporation Sole) | Nonprofit Organization | |
| General, Agricultural, and Cannabis Cooperatives | Cooperative | |
| Limited Liability Partnership | Partnership | |
| General Partnership | Partnership | |
| Other / unrecognized label | Other | |
bizfile occasionally surfaces niche entity types (Land Trust, Massachusetts Trust). These fall through with `standardized: Other` and the full local label preserved. For the complete and current list of legal forms, see the [pricing page](https://topograph.co/pricing/us-ca).
### Officer Roles
Officer roles are returned in prefill mode. Each title comes from the closed position vocabulary of the California Statement of Information form and is mapped deterministically to a standardized role; the register label is preserved in `role.localName`. Directors and board chairs are governance Other Key Persons. Compound officer/director titles preserve both offices. Executive Officer does not imply CEO, and a role alone does not establish sole or joint signing power. The full list of roles is on the [pricing page](https://topograph.co/pricing/us-ca).
| Common Title | Standardized | Notes |
| - | - | - |
| Chief Executive Officer | Chief Executive Officer | CA corporations |
| President | President | |
| Secretary | Secretary | Statutory corp officer |
| Chief Financial Officer | Chief Financial Officer | |
| Manager | Manager | LLC manager-managed |
| Member | Other | Legal Representative only with explicit member-managed context; otherwise Other Key Person |
| General Partner | General Partner | Limited partnerships |
| Registered Agent | Registered Agent | Other Key Person; receives service of process |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Yes | Active, Suspended (FTB), Dissolved, Cancelled, etc. |
| Registration date | Yes | Initial filing date |
| Legal address | Yes | Principal office address |
| Legal form | Yes | bizfile entity-type label, standardized to Topograph category |
| Registered agent | Yes | Name, type (Individual or Corporation), and address under `otherKeyPersons` |
| Other key persons | Yes | Agent in both modes; directors, chairs and nonrepresenting members from the bulk roster in prefill |
| Legal representatives | Yes | Prefill mode: officer, director, manager, and member roster plus the registered agent. Verification mode: registered agent only. |
| Trade Register Extract | Yes | Printed bizfileOnline detail page, included at no extra charge with the company-data block |
| Initial Filing | Yes | Image of the filing that created or registered the entity: articles of incorporation or organization, or the statement and designation of an out-of-state entity |
| Statements of Information | Yes | Image of each Statement of Information the entity filed: officers or managers, addresses and registered agent at the filing date |
| Other filings | Yes | Amendments, terminations and any other filing the Secretary of State publishes an image of |
| Certified Certificate of Status | No | Available from the Secretary of State at a fee; not yet offered through Topograph |
| Activity description | Bulk source | The Master Unload supplies the filed type of business as `activityDescription` when present; this field is not available in the live detail drawer |
| Activity codes | No | Not collected by the California Secretary of State |
| Shareholders | No | Not published |
| UBOs | No | No public state-level beneficial ownership register |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-CA&query=Acme+Innovations" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567",
"legalName": "ACME INNOVATIONS, INC.",
"countryCode": "US-CA",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "CA",
"countryCode": "US"
}
}
]
```
### Search by Entity Number
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-CA&query=C1234567" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567",
"legalName": "ACME INNOVATIONS, INC.",
"countryCode": "US-CA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-CA", "id": "1234567", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "1234567",
"countryCode": "US-CA",
"identifiers": { "entityNumber": "1234567" },
"legalName": "ACME INNOVATIONS, INC.",
"registrationDate": "2005-03-14",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Stock Corporation - CA - General",
"englishTranslation": "Stock Corporation (General)",
"standardized": "Corporation",
"iso20275Code": "H1UM"
},
"legalAddress": {
"addressLine1": "123 MARKET STREET SUITE 400",
"city": "SAN FRANCISCO",
"postalCode": "94105",
"region": "CA",
"countryCode": "US"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Agent for Service of Process",
"standardized": "Registered Agent"
},
"company": {
"legalName": "CALIFORNIA AGENT SERVICES LLC",
"legalAddress": {
"addressLine1": "500 CORPORATE DR",
"city": "SACRAMENTO",
"postalCode": "95814",
"region": "CA",
"countryCode": "US"
}
}
}
]
}
```
# Colorado
Source: https://docs.topograph.co/essentials/us-colorado
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Colorado reference is on the [Colorado country page](https://www.topograph.co/countries/us-co).
## Start here
This guide contains public integration notes for Colorado. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Company Statuses](#company-statuses)
* [Data Availability](#data-availability)
## Data Sources
Colorado data comes from the **Colorado Secretary of State** business register, through two channels. The register covers every entity filed with the Secretary of State: corporations, foreign corporations, limited liability companies, nonprofit corporations, limited partnerships, limited liability partnerships, general partnerships, and cooperatives.
* **Open data, refreshed daily** (prefill mode). The Secretary of State publishes every registered entity, active and inactive, with legal name, entity ID, entity type, status, formation date, principal address, and registered agent. A status change can take up to a day to appear. This channel also powers name search.
* **Business Database Search** (verification mode). The live, authoritative face of the register: legal name, 11-digit entity ID, status, entity form, formation date, principal office address, and registered agent name and address. It also serves the Trade Register Extract and the Formation Filing.
**Officers and managers are not filed.** Colorado does not require business entities to file owner, officer, director, member, or manager information with the Secretary of State. That information is kept in the entity records at the principal office. The registered agent is returned as an other key person; `legalRepresentatives` is intentionally empty.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Colorado SOS Entity ID** | 11 digits, numeric only | `19931121425` | Assigned by the Colorado Secretary of State. The primary identifier for search and profile lookups. |
The entity ID is 11 digits and purely numeric (`19931121425`, `20248299164`). One historical record in the register's data carries 10 digits (`1923178226`). Pass the ID exactly as returned by search. The full list of filing documents for an entity also uses this ID as the primary key.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityId` | 11 digits, numeric only (one historical record has 10) | `19931121425` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Acme Holdings"` | Full-text, plus exact and starts-with matches (case-insensitive) | Multiple results |
| By Entity ID | 11 digits | `19931121425` | Exact | Exact match returned first (`matchType: id`); other results may follow |
Name search combines a full-text match on the legal name with exact and starts-with matches. Use fuller query strings to narrow the result set.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Officers and managers are not available** | Colorado law does not require entities to file owner, officer, director, member, or manager information with the Secretary of State. These fields are kept in the entity's own records. `legalRepresentatives` is always empty for Colorado entities. |
| **No shareholder or UBO register** | Colorado does not publish shareholders or beneficial owners for any entity type. Federal FinCEN BOI records are separate and not publicly accessible. |
| **Registered agent is an other key person** | The registered agent is surfaced under `otherKeyPersons`, not under `legalRepresentatives`. It receives service of process and has no statutory authority to bind the entity. |
| **No activity codes** | Industry classification codes are not published on Colorado Secretary of State business summary records. |
| **Tax ID is separate** | The Colorado SOS entity ID is not a tax ID. For federal EIN or Colorado state tax IDs, direct the entity to the IRS or Colorado Department of Revenue. |
| **Trade Register Extract is bundled** | The Trade Register Extract (printed current detail page) is included at no extra charge with the company data block. The Formation Filing PDF is ordered separately. |
## Mappings
### Legal Forms
Legal form is sourced from the entity type recorded by the Colorado Secretary of State. Verification mode returns the label shown on the business database (for example `Limited Liability Company`); prefill mode returns the register's full entity-type name, which marks domestic and foreign registrations (for example `Domestic Limited Liability Company`, `Foreign Profit Corporation`). The table below lists the main forms.
| Colorado Entity Form | Standardized |
| - | - |
| Corporation | Corporation |
| Foreign Corporation | Corporation |
| Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Nonprofit Corporation | Nonprofit Organization |
| Limited Partnership | Partnership |
| Limited Liability Partnership | Partnership |
| General Partnership | Partnership |
| Cooperative | Cooperative |
The register also records less common forms, such as public benefit corporations, unincorporated nonprofit associations, limited cooperative associations, credit unions, and ditch and water companies. For the complete list of legal forms, see the [pricing page](https://topograph.co/pricing/us-co).
### Company Statuses
Colorado uses a closed set of status values. `Good Standing` and `Exists` are returned with `active: true`; every other value is returned with `active: false`.
| Status | Active |
| - | - |
| Good Standing | Yes |
| Exists | Yes |
| Delinquent | No |
| Noncompliant | No |
| Voluntarily Dissolved | No |
| Administratively Dissolved | No |
| Judicially Dissolved | No |
| Dissolved (Term Expired) | No |
| Withdrawn | No |
| Revoked | No |
| Merged | No |
| Converted | No |
| Consolidated | No |
| Registered Agent Resigned | No |
| Effectiveness Prevented | No |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the register |
| Company status | Yes | e.g. Good Standing, Voluntarily Dissolved. Live in verification mode; up to a day old in prefill mode |
| Registration date | Yes | Formation date as filed with the Secretary of State |
| Legal address | Yes | Principal office street address, or the mailing address when no street address is on file |
| Legal form | Yes | Entity type from the register, mapped to a standardized category |
| Legal representatives | No | Colorado does not require officer/director/member/manager filings. Returned as an empty array in verification mode; not offered in prefill mode |
| Registered agent | Yes | Name and address, returned as an other key person |
| Activity codes | No | Not published on Colorado SOS records |
| Shareholders | No | Not published |
| UBOs | No | No public beneficial ownership register in Colorado |
| Trade Register Extract | Yes | Printed PDF of the current detail page, included with company data |
| Formation Filing | Yes | PDF of the original formation filing, ordered separately |
| Certified copies | No | Not yet available through Topograph |
| Certificate of Good Standing | No | Not yet available through Topograph |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-CO&query=Acme+Holdings" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "20241234567",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-CO",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "CO",
"countryCode": "US"
}
}
]
```
### Search by Entity ID
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-CO&query=20241234567" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "20241234567",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-CO",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-CO", "id": "20241234567", "dataPoints": ["company", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "20241234567",
"countryCode": "US-CO",
"identifiers": { "entityId": "20241234567" },
"legalName": "ACME HOLDINGS LLC",
"status": {
"localName": "Good Standing",
"active": true
},
"registrationDate": "2024-03-15",
"legalForm": {
"localName": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Denver",
"region": "CO",
"postalCode": "80202",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"individual": {
"name": { "fullName": "JANE SMITH" },
"residenceAddress": {
"addressLine1": "456 Oak Avenue",
"city": "Denver",
"region": "CO",
"postalCode": "80203",
"countryCode": "US"
}
}
}
]
}
```
# Connecticut (US)
Source: https://docs.topograph.co/essentials/us-connecticut
Country-specific identifiers, data sources, and implementation details for the State of Connecticut.
This guide is outdated and will be removed on 1 November 2026. The up-to-date Connecticut (US) reference is on the [Connecticut (US) country page](https://www.topograph.co/countries/us-ct).
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Data Availability](#data-availability)
* [Quirks & Gotchas](#quirks--gotchas)
* [Example API Responses](#example-api-responses)
## Data Sources
Connecticut is served from two independent channels published by the **Connecticut Secretary of the State**.
* **Open data**, refreshed nightly. Covers every domestic and foreign entity registered with the state: stock and non-stock corporations, limited liability companies, limited partnerships, limited liability partnerships, statutory trusts, and chartered variants. Includes the entity record, principals (officers, directors, members, managers, partners), statutory registered agent, filing history, and previous names. Drives the prefill profile and the search index.
* **Public business records search** at service.ct.gov/business. The authoritative live face of the register. Drives the verification profile and the Trade Register Extract.
The two channels are wired into two independent profile blocks. Topograph does not merge attributes across them.
## Company Identifiers
The primary identifier is the **seven-digit account number** assigned by the Connecticut Secretary of the State. Leading zeros are part of the number (`0668349`, `3453337`). It is exposed in two forms: the bare number, and that same number carrying its register prefix, the **Administrative Legal Entity Identifier (ALEI)**:
* **Composite form**: `US-CT.BER:0668349` (the form shown on the Business Records Search portal, returned as `identifiers.alei`).
* **Bare form**: `0668349` (the seven-digit account number, returned as `company.id` and `identifiers.accountNumber`).
Both forms resolve to the same entity. The API accepts either as the `id` parameter and as the search query, and also accepts the number without its leading zeros (`668349`).
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when `accountNumber` has a unique match against Connecticut registration or validation references in GLEIF.
The LEI is a separate global identifier from Connecticut's ALEI (`company.identifiers.alei`).
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
Search by name and search by account number are both supported; the composite ALEI is accepted as a search query too. Previous names recorded against the entity are indexed so legacy names continue to match.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Data Availability
| Datapoint | Prefill | Verification |
| - | - | - |
| `company` | ✅ | ✅ (no legal form, no NAICS) |
| `legalRepresentatives` | ✅ | ✅ (top 3 principals) |
| `otherKeyPersons` (agent) | ✅ | ✅ |
| `activityCodes` (NAICS) | ✅ | ❌ (prefill only) |
| `tradeRegisterExtract` | ✅ | ✅ |
| `shareholders` | ❌ | ❌ |
| `ultimateBeneficialOwners` | ❌ | ❌ |
| Certified documents | ❌ | ❌ |
The two modes return slightly different field sets. The prefill profile is the richer of the two: it includes the legal form, NAICS classification, and the full principal list from the nightly open data. The verification profile is read live from the public business records search and returns the name, status, principal address, top three principals, and the statutory registered agent. Use the prefill mode when you need the richer field set and can tolerate up to a day of staleness; use verification when you need the authoritative live state of the register.
The Trade Register Extract is a printable PDF of the live entity card, bundled with the company-data block at no extra charge.
Shareholder lists are not collected by the Connecticut Secretary of the State for any entity type. Connecticut maintains no state-level beneficial-ownership register.
## Quirks & Gotchas
### One identifier, two public forms
The composite `US-CT.BER:0668349` and the bare `0668349` are accepted interchangeably by the API. Topograph normalises both forms and returns the bare account number as `company.id`; the composite is always available under `identifiers.alei`.
### Status vocabulary
Twenty distinct status values appear across the register. Only `Active` indicates an entity in good standing. Every other label (`Forfeited`, `Dissolved`, `Withdrawn`, `Revoked`, `Cancelled`, `Merged`, and others) marks an entity that is no longer transacting business in Connecticut.
### Connecticut publishes principals, including LLC members
Unlike many US states that hide LLC membership, Connecticut publishes officers, directors, members, managers, and partners for every entity type. Where a principal holds more than one role, Topograph emits a separate `legalRepresentatives` record per role.
### NAICS classification is included
Each entity carries an NAICS classification on the formation survey. Both the six-digit code and the descriptive label are returned under `company.activities.NAICS`.
**Main activity:** the register publishes exactly one NAICS code per entity, so it is by definition the company's main activity. The NAICS entry carries `isMainActivity: true`, and codes derived from it inherit the flag.
## Example API Responses
```bash theme={null}
topo api profile US-CT US-CT.BER:0668349
```
```json theme={null}
{
"company": {
"id": "0668349",
"countryCode": "US-CT",
"legalName": "AETNA INC.",
"identifiers": {
"alei": "US-CT.BER:0668349",
"accountNumber": "0668349"
},
"legalForm": {
"localName": "Stock Corporation",
"englishTranslation": "Stock Corporation",
"standardized": "Corporation"
},
"status": { "localName": "Active", "active": true },
"legalAddress": {
"addressLine1": "151 Farmington Avenue",
"city": "Hartford",
"region": "CT",
"postalCode": "06156",
"countryCode": "US"
},
"registrationDate": "2000-12-13",
"activities": {
"NAICS": [
{
"code": "551112",
"description": "Offices of Other Holding Companies",
"isMainActivity": true
}
]
}
}
}
```
# Delaware
Source: https://docs.topograph.co/essentials/us-delaware
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Delaware reference is on the [Delaware country page](https://www.topograph.co/countries/us-de).
## Start here
This guide contains public integration notes for Delaware. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Entity Statuses](#entity-statuses)
* [Data Availability](#data-availability)
## Data Sources
Delaware data is sourced from the **Delaware Division of Corporations, ICIS eCorp** portal (`icis.corp.delaware.gov/eCorp/`). The register indexes over 1.8 million entities: corporations, LLCs, limited partnerships, statutory trusts, and other business formations registered in Delaware. It is operated by the Delaware Department of State.
Two tiers of data are available:
* **Free-tier lookup (fast, non-authoritative).** Entity name, file number, entity classification, formation date, and registered agent. The official entity status is not available on the free tier.
* **Entity Status Report (paid, authoritative).** The same fields as the free tier, plus the official entity status (Good Standing, Void, Forfeited, and so on), sourced from the paid Delaware Entity Status Report. The report document is also included at no extra charge.
**Status requires the paid tier.** Delaware does not expose entity status on the free portal. To receive `company.status`, request the authoritative mode or include the status data block in your `/v2/company` call. See the pricing page for the current price.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Delaware File Number** | Digits only, no leading zeros. 4 to 8 digits in the records we have seen, most often 7 or 8 | `3177627` | Assigned by the Delaware Division of Corporations at formation. Covers all entity types. |
Pass the file number exactly as the register assigns it: no leading zeros, no separators. File number `3177627` is valid; `03177627` is not. Most file numbers have 7 digits (`3177627`) or 8 (`10171608`), and shorter ones exist (`523608`, `23110`, `4305`). The Division of Corporations does not publish a fixed length. Use `/v2/search` first to resolve a name to the canonical file number before calling `/v2/company`.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `fileNumber` | Digits only, no leading zeros (4 to 8 digits seen) | `3177627` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-100 chars | `"Acme LLC"` | Starts-with (case-insensitive) | Up to 50 results |
| By Delaware File Number | Numeric | `3177627` | Exact (`matchType: id`) | Single result |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use a more specific query to narrow a large result set. Results are capped at 50 per request.
**Foreign qualifications appear in results.** ICIS indexes both domestic entities (formed in Delaware) and foreign qualifications (entities formed elsewhere that are registered to do business in Delaware), and search returns both. Residency is not returned as a field; it is printed on the Entity Status Report. The authoritative record for a foreign qualification lives in its state of formation.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Status requires the paid tier** | The official entity status (Good Standing, Void, Forfeited, and so on) is only available through the paid Entity Status Report. Free-tier lookups return `company.status = undefined`. |
| **No officers or directors on any tier** | Delaware law does not require officers or directors to be disclosed on the public portal. Officer names appear only inside paid annual-report document images and are not available through this API. |
| **LLC members are never disclosed** | Delaware LLC membership is not filed with the state at formation and does not appear on annual reports. This is a statutory privacy feature under Delaware law, not a paywall. |
| **No shareholders or UBOs** | Ownership and beneficial-ownership information is not part of the Delaware public record for any entity type. |
| **No legal address on the free tier** | The free ICIS tier only exposes the registered agent's address, not the entity's legal address. `company.legalAddress` is not populated on the free tier. |
| **No activity codes** | NAICS, SIC, and NACE codes are not collected by the Delaware business register. |
| **Sole proprietors are not indexed** | Sole proprietors register with state tax and county offices, not with the Delaware Division of Corporations. |
| **Entity Status Report deduplication** | The paid Entity Status Report purchase is cached for 24 hours per entity. If you call both `company` and document retrieval within that window, the report is fetched once and billed once. |
| **"Do not quote the query" rule** | Do not wrap name search queries in quotation marks. The register returns an error for quoted inputs. |
## Mappings
### Legal Forms
Delaware classifies entities with two labels: an Entity Kind (the primary classification) and, for corporations, an Entity Type (a sub-classifier). Topograph maps these to a standardized form and to an ISO 20275 ELF code where one exists.
| Local Name | Entity Kind | Entity Type | Standardized | ISO 20275 |
| - | - | - | - | - |
| Corporation | Corporation | General | Corporation | `XTIQ` |
| Close Corporation | Corporation | Close | Corporation | |
| Public Benefit Corporation | Corporation | Public Benefit | Corporation | |
| Non-Stock Corporation | Corporation | Non-Stock | Nonprofit Organization | |
| Professional Corporation | Corporation | Professional | Corporation | `9AAS` |
| Exempt Corporation | Corporation | Exempt | Nonprofit Organization | |
| Limited Liability Company | LLC | | Limited Liability Company | `HZEH` |
| Limited Partnership | LP | | Partnership | `T91T` |
| Limited Liability Partnership | LLP | | Partnership | |
| General Partnership | GP | | Partnership | |
| Statutory Trust | Statutory Trust | | Trust | |
| Trust | Trust | | Trust | |
The full legal form table with ISO 20275 mappings is available on the [Delaware pricing page](https://topograph.co/pricing/us-de).
### Entity Statuses
Entity status is returned only when the paid Entity Status Report is purchased. The Delaware Division of Corporations publishes an official closed enumeration of all possible status values.
| Status Value |
| - |
| Good Standing |
| Voluntarily Cancelled |
| Dissolved |
| Expired |
| Forfeited, Failure to appoint R/A |
| Resign to Appointment |
| Cancelled, Failure to Pay Tax |
| Consolidated |
| Merged |
| Converted |
| AR filed, Tax delinquent |
| Revoked |
| AR delinquent, Tax paid |
| Cancelled, Failure to Appoint R/A |
| Surrendered |
| Transferred |
| AR delinquent, Tax due |
| Void, AR's or Tax Delinquent |
| Withdrawn |
| Ceased Good Standing |
| Relinquished |
| Parent Cancelled |
| Cancelled; Divided |
| PPoB Non-Compliant |
| AR Delinquent, Tax Paid, PPoB Non-Compliant |
| AR Delinquent, Tax Due, PPoB Non-Compliant |
| AR Filed, Tax Due, PPoB Non-Compliant |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the ICIS register |
| Company status | Paid tier only | Available via the Entity Status Report (paid). Not included in the free-tier lookup. |
| File number | Yes | Delaware file number assigned at formation |
| Formation date | Yes | Incorporation or formation date |
| Entity classification | Yes | Entity kind and entity type (e.g. Corporation / General, LLC) |
| Residency | No | Not returned as a field. Domestic or Foreign residency is printed on the Entity Status Report |
| Legal address | No | Not exposed on the free tier. The register only provides the registered agent's address on the free tier. |
| Registered agent | Yes | Name and Delaware office address (street, city, state, postal code); phone number when the agent is an individual |
| Officers / directors | No | Not exposed by the register on any tier. Available only inside paid annual-report document images (not offered via the API). |
| LLC members | No | Not filed with Delaware under state law. This is not a paywall limitation. |
| Shareholders | No | Not part of the Delaware public record |
| UBOs | No | No public beneficial ownership register in Delaware; the federal FinCEN database is restricted |
| Activity codes | No | NAICS / SIC codes not collected by the register |
| Financial data | No | Not collected |
| Entity Status Report | Yes (paid) | Included at no extra charge with the paid status tier. Printable PDF of the official Entity Status Report. |
| Tax and filing history | No | Franchise tax details and filing history are not offered via the API. |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-DE&query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "5000001",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-DE",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "DE",
"countryCode": "US"
}
}
]
```
### Search by File Number
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-DE&query=5000001" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "5000001",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-DE",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile (free tier)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-DE", "id": "5000001", "dataPoints": ["company", "otherKeyPersons"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "5000001",
"countryCode": "US-DE",
"identifiers": { "fileNumber": "5000001" },
"legalName": "ACME HOLDINGS LLC",
"incorporationDate": "2010-03-15",
"legalForm": {
"localName": "Limited Liability Company",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "WYG5"
}
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"legalName": "EXAMPLE REGISTERED AGENTS INC.",
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Wilmington",
"state": "DE",
"postalCode": "19801",
"countryCode": "US-DE"
}
}
}
]
}
```
# Florida
Source: https://docs.topograph.co/essentials/us-florida
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Florida reference is on the [Florida country page](https://www.topograph.co/countries/us-fl).
## Start here
This guide contains public integration notes for Florida. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Person Roles](#person-roles)
* [Data Availability](#data-availability)
**API access:** Florida is in beta. `US-FL` is accepted by `/v2/company` and `/v2/search`, but it is not yet listed in the public `countryCode` enum of the OpenAPI spec.
## Data Sources
Florida uses two complementary sources, both operated by the **Florida Department of State, Division of Corporations (Sunbiz)**.
* **Florida Division of Corporations, Bulk File** (fast path). The Division publishes the full Corporate Data File as a quarterly snapshot (January, April, July, October) and daily delta files. The dataset covers every active Florida profit corporation, non-profit corporation, LLC, limited partnership, and declaration of trust. Each record includes up to 6 people — corporate officers and directors, LLC managers, members and authorized persons, or a limited partnership's general partners — plus the registered agent and core company fields. This is the primary source for company data, search, and prefill checks.
* **Florida Division of Corporations, Live Search** (enrichment path). The public `search.sunbiz.org` detail pages are read at request time in three cases: (a) on every search, by name and by document number, so entities filed after the latest bulk update are still found; (b) when the bulk record is flagged as having more than 6 officers, to retrieve the complete roster; and (c) to deliver PDF documents (Articles of Incorporation or Organization, Annual Reports, amendments) that are not distributed in the bulk file.
**Officer data freshness.** Florida entities file an Annual Report by May 1 each year. Officer data in the bulk file reflects the most recent annual report filed; entities that have not yet filed for the current year carry officers from the prior filing.
## Company Identifiers
### Query Identifiers
| Identifier | Format | Example | Notes |
| - | - | - | - |
| **Document Number** | 12 or 6 characters. 12 characters: one letter + 11 digits (e.g. `P99000001570`, `L22000252360`). 6 characters, on older filings: six digits (e.g. `112252`) or one letter + five digits (e.g. `A17753`, `G10360`). The letter reflects the filing type and period (e.g. `P` = domestic profit corporation, `L` = LLC, `F` = foreign entity); letters in use include `A`, `F`, `G`, `H`, `K`, `L`, `M`, `N`, `P`, `S`, `T` and `W`. | `P99000001570` | Primary identifier assigned by the Division of Corporations. Shown on every Sunbiz entity detail page. |
| **FEI / EIN** | 9 digits. Accepted with or without hyphen (`59-1234567` or `591234567`). | `59-1234567` | Federal employer identification number. Not all entities have one on file. A lookup by FEI may return no result even for an active entity. |
Always use the Document Number as the primary lookup key. FEI / EIN search is available as a convenience but may not resolve every entity.
### Identifiers in API Response
| Field | Format | Example | Found In |
| - | - | - | - |
| `documentNumber` | One letter + 11 digits, six digits, or one letter + five digits | `P99000001570`, `112252` | All entities |
| `feiNumber` | 9 digits (with hyphen) | `59-1234567` | Entities that have reported an EIN to the Division |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Sunshine"` | Relevance-ranked name matching (case-insensitive) | Multiple results, up to about 20 per source |
| By Document Number | 12 or 6 characters | `P99000001570`, `112252` | Exact | Single result returned first (`matchType: id`) |
| By FEI / EIN | 9 digits, with or without hyphen | `59-1234567` | Exact | Single result when the entity has a matching FEI on file |
Name search ranks the full register by relevance to the words in your query. Newly filed entities that are not yet in the bulk file are added from the live register, matched on the beginning of the legal name. Use a longer query string to narrow a large result set.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Document Number prefix is load-bearing** | The letter prefix encodes entity type and is required. `P99000001570` and `99000001570` are treated as different keys. Always pass the identifier exactly as returned by the search endpoint. |
| **Person list capped at 6 in bulk** | The bulk file stores at most 6 people per entity. Entities with more carry a flag, and the full roster is read from the live detail page at request time. If that live read fails the response falls back to the 6 from bulk rather than failing the request, so a very large roster can occasionally be truncated. |
| **A board seat is not automatically a legal representative** | Florida statutes vest corporate powers in the board as a body (F.S. §607.0801(2), §617.0801) and confer no individual authority on a single director. A director or chairman is therefore returned as a `legalRepresentative` only when they are the entity's **sole** board member; where the board has two or more, all of them are returned as `otherKeyPersons` with the standardized role `Board Member`. A corporation or non-profit whose only filed people are board members will legitimately return an **empty `legalRepresentatives`** array with those people under `otherKeyPersons` — around 18% of for-profit corporations and 14% of non-profits that file any person at all. |
| **Registered agent is not a legal representative** | Under Florida statutes (F.S. §605.0113 and §607.0501), the registered agent is the service-of-process contact only. The API returns the registered agent as an `otherKeyPerson`, not a `legalRepresentative`. |
| **No shareholders or UBO data** | Florida does not collect ownership or beneficial-owner information at the state level, and files no share counts or percentages for any entity type. Beneficial ownership reporting is a federal obligation under the Corporate Transparency Act, administered separately by FinCEN. Note that LLC managing members and authorized members, and a limited partnership's general partners, **are** filed and returned — but as `legalRepresentatives`, describing authority to act. They are not an ownership record and carry no stake size. |
| **Accented characters are lost in the bulk file** | The Division's bulk export replaces every non-ASCII character with `?`, so a small number of names arrive damaged (`Villafa?e` for Villafañe, `Mar?a` for María). The live detail page holds the correct characters, but the bulk file is what feeds company data. This affects roughly 0.02% of people. The `?` is preserved as-is — it is never guessed at, because the same placeholder stands for í, á, é, ú, ü, ä, ç and ñ. |
| **No industry classification codes** | Sunbiz does not capture NAICS, SIC, NACE, or ISIC codes. The `activityCodes` datapoint is not available for Florida. |
| **Banks and credit unions file as corporations** | State-chartered banks, trust companies, savings banks, and credit unions register with the Division of Corporations as standard profit corporations. Their regulated classification is maintained by the Florida Office of Financial Regulation and is not layered into the response. |
| **No ISO 20275 code in the response** | The API does not return `iso20275Code` for Florida. The ELF codes in the legal form table below are reference values for the four Florida-domiciled types. Foreign entities have no Florida ELF code, because the ELF code belongs to the jurisdiction where the legal form originated. |
| **Certificate of Status is a paid document** | The Certificate of Status (good-standing certificate) is issued by the Division of Corporations at a per-certificate fee and is a paid upgrade. See the [pricing page](https://topograph.co/pricing/us-fl) for the current charge. |
## Mappings
### Legal Forms
Florida uses a closed set of 11 filing-type codes defined in the Corporate Data File record layout published by the Division of Corporations. The API returns the filing-type code (`DOMP`, `FLAL`, ...) in `legalForm.localName`, together with the standardized category. The ISO 20275 column is reference only: it lists the ELF codes of the four Florida-domiciled types and is not returned in the response.
| Sunbiz Filing Type | Local Name | Standardized | ISO 20275 |
| - | - | - | - |
| `DOMP` | Domestic Profit Corporation | Corporation | `TRI2` |
| `FORP` | Foreign Profit Corporation | Corporation | |
| `DOMNP` | Domestic Non-Profit Corporation | Nonprofit Organization | `3N55` |
| `FORNP` | Foreign Non-Profit Corporation | Nonprofit Organization | |
| `NPREG` | Non-Profit Registration | Nonprofit Organization | |
| `FLAL` | Florida Limited Liability Company | Limited Liability Company | `8N21` |
| `FORL` | Foreign Limited Liability Company | Limited Liability Company | |
| `DOMLP` | Domestic Limited Partnership | Partnership | `5DS0` |
| `FORLP` | Foreign Limited Partnership | Partnership | |
| `TRUST` | Declaration of Trust | Trust | |
| `AGENT` | Designation of Registered Agent | Other | |
The `DOMLP` code covers both plain Limited Partnerships and Limited Liability Limited Partnerships (LLLPs). The Sunbiz filing type does not distinguish between the two. Distinguishing an LLLP requires inspecting the entity name suffix.
### Person Roles
The Corporate Data File stores each person's title in a **4-character free-text field**, not a closed code set: a historical 10% corpus census found more than 5,800 distinct values. Three shapes account for almost all of it, and the raw register string is always returned in `role.localName` — including when it cannot be resolved, so a person the register published is never dropped.
**1. Single-letter office codes, which combine.** Sunbiz builds a multi-office title by concatenating them, so `PD` is a President who is also a director and `PSTD` is President, Secretary, Treasurer and Director.
| Sunbiz Code | Local Name | Standardized | Classification |
| - | - | - | - |
| `P` | President | President | Legal Representative |
| `V`, `VP` | Vice President | Vice President | Legal Representative |
| `T`, `TR` | Treasurer | Treasurer | Legal Representative |
| `S` | Secretary | Secretary | Legal Representative |
| `CEO` | Chief Executive Officer | Chief Executive Officer | Legal Representative |
| `CFO` | Chief Financial Officer | Chief Financial Officer | Legal Representative |
| `COO` | Chief Operating Officer | Chief Operating Officer | Legal Representative |
| `C` | Chairman | Chairman of the Board | Other Key Person |
| `D` | Director | Board Member | Other Key Person |
**2. LLC managers, members and authorized persons.** Manager and managing-member titles describe a management capacity. Explicit authorized-member, authorized-person and representative titles describe an authorization capacity. Plain membership or ownership alone does not establish agency: member authority depends on the company’s management regime and governing documents.
| Sunbiz Code | Local Name | Standardized | Classification |
| - | - | - | - |
| `MGR` | Manager | Manager | Legal Representative |
| `MGRM` | Managing Member | Manager | Legal Representative |
| `AMBR` | Authorized Member | Authorized Signatory | Legal Representative |
| `MBR` | Member | Other | Other Key Person |
| `Owne` | Owner | Other | Other Key Person |
| `AP` | Authorized Person | Authorized Signatory | Legal Representative |
| `AR` | Authorized Representative | Authorized Signatory | Legal Representative |
**3. Partnerships.** A limited partnership's people appear in a General Partner block that has no title column, so a general partner may arrive with a blank title or as `G` / `GP`.
| Sunbiz Code | Local Name | Standardized | Classification |
| - | - | - | - |
| `G`, `GP`, *(blank on an LP)* | General Partner | General Partner | Legal Representative |
| `LP` | Limited Partner | Other | Other Key Person |
| `RA` | Registered Agent | Registered Agent | Other Key Person |
**A board seat does not establish personal signing powers.** Directors and board chairs are returned under `otherKeyPersons`, even when only one board member is listed. Corporate board powers remain subject to the articles and applicable agreements; officers derive their authority from bylaws or the board. A combined title such as `PD` retains the officer meaning and the full source caption, with its actual powers still dependent on the company’s governing documents.
**Titles are often truncated, and one is ambiguous.** Because the field is 4 characters wide, a spelled-out title arrives cut off: `Mana` (Manager), `Pres` (President), `Secr` (Secretary), `Trea` (Treasurer), `Chai` (Chairman), `Dire` (Director). These are resolved normally. The exception is `Auth`, which on the live register expands to both "Authorized Member" and "Authorized Representative" — the truncation is genuinely lossy, so the raw title is preserved under `otherKeyPersons` with the general standardized value `Other`, without inferring a specific office or signing power.
Registered Agent is classified as an Other Key Person (service-of-process contact only, no authority to act on behalf of the entity under F.S. §605.0113 and §607.0501). A Limited Partner likewise has no power to bind the partnership (F.S. §620.1302).
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the Corporate Data File |
| Company status | Yes | Active (`A`) or Inactive (`I`) |
| Registration date | Yes | Initial filing date with the Division of Corporations |
| Legal address | Yes | Principal address from the bulk record |
| Legal form | Yes | Sunbiz filing-type code (closed 11-value vocabulary) with a standardized category |
| Legal representatives | Yes | Corporate officers, LLC managers / members / authorized persons, and LP general partners. Up to 6 from bulk; the full roster is read live when the entity is flagged as having more than 6. Empty when the only filed people are a multi-member board (see Quirks) |
| Board members | Yes | Directors and chairmen of a multi-member board, returned as Other Key Persons with the standardized role `Board Member` |
| Registered agent | Yes | Name and address, returned as an Other Key Person |
| Activity codes | No | Not collected by Sunbiz |
| Shareholders | No | Not published at the state level |
| UBOs | No | Federal FinCEN system only; not available from Sunbiz |
| Trade Register Extract | Yes | Printed PDF of the Sunbiz entity detail page, included at no extra charge with the company data block |
| Articles of Incorporation / Organization | Yes | PDF from Sunbiz, billed separately (see the pricing page), available when the entity has filed formation documents |
| Florida Annual Report | Yes | PDF from Sunbiz, billed separately (see the pricing page); one or more years may be available per entity |
| Amendment / Merger / Name Change filing | Yes | PDF from Sunbiz, billed separately (see the pricing page), available when amendment filings are present on the entity detail page |
| Certificate of Status | Yes (paid) | Issued by the Division of Corporations at a per-certificate fee; see the pricing page |
| Financial statements | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-FL&query=Sunshine" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "P99000001570",
"legalName": "SUNSHINE HOLDINGS INC.",
"countryCode": "US-FL",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "FL",
"countryCode": "US"
}
}
]
```
### Search by Document Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-FL&query=P99000001570" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "P99000001570",
"legalName": "SUNSHINE HOLDINGS INC.",
"countryCode": "US-FL",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-FL", "id": "P99000001570", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "P99000001570",
"countryCode": "US-FL",
"identifiers": {
"documentNumber": "P99000001570",
"feiNumber": "59-1234567"
},
"legalName": "SUNSHINE HOLDINGS INC.",
"status": {
"localName": "Active",
"active": true
},
"registrationDate": "2012-03-14",
"legalForm": {
"localName": "DOMP",
"englishTranslation": "Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "123 Palm Avenue",
"city": "Miami",
"region": "FL",
"postalCode": "33101",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "P",
"standardized": "President"
},
"individual": {
"name": { "fullName": "Jane Sample" }
}
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"legalName": "Sample Registered Agent LLC",
"countryCode": "US",
"legalAddress": {
"addressLine1": "456 Bay Street",
"city": "Tampa",
"region": "FL",
"postalCode": "33601",
"countryCode": "US"
}
}
}
]
}
```
# Georgia
Source: https://docs.topograph.co/essentials/us-georgia
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Georgia reference is on the [Georgia country page](https://www.topograph.co/countries/us-ga).
## Start here
This guide contains public integration notes for Georgia. Use it for identifier formats, search behavior, and state-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
State details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Status](#company-status)
* [Data Availability](#data-availability)
**API access:** Georgia is in beta. `US-GA` is accepted by `/v2/company` and `/v2/search`, but it is not yet listed in the public `countryCode` enum of the OpenAPI spec.
## Data Sources
Georgia uses a single integration against the **Georgia Secretary of State, Corporations Division (eCorp)**. The register is the authoritative state-level record for all entities organized or qualified to do business in Georgia, including domestic and foreign profit corporations, LLCs, limited partnerships, LLLPs, LLPs, nonprofit corporations, and benefit corporations. It covers approximately 1.1 million active entities.
The eCorp portal publishes the entity name, control number, status, formation or registration date, principal office address, registered agent, and, for corporations and nonprofits, an officer roster (CEO, CFO and Secretary). LLCs publish no officers, only the registered agent. This is the only public data source available for Georgia entities at the state level.
**No open-data snapshot.** Georgia does not publish a bulk open-data extract of its business register. All data is read directly from the live eCorp portal at `ecorp.sos.ga.gov`. Both prefill and verification requests are served from the same live source.
**Annual registration freshness.** Every Georgia entity must file an annual registration. Officer and address data is only updated when the entity files its annual registration, so records can lag up to 12 months behind the most recent changes.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Control Number** | Up to 8 characters: 8 digits, 7 digits with leading zeros, or one letter + 6 digits | `H852680` | Assigned by the Georgia Secretary of State Corporations Division (eCorp). |
Control number format varies with the period of registration, not with the entity's origin. Recent entities use 8 digits (e.g. `11078964`). Older entities use 7 digits with leading zeros (e.g. `0003726`) or one letter followed by 6 digits (e.g. `H852680`, `J716207`, `K404041`, `A401954`). A small number of legacy entities carry `0` + a letter + 5 digits (e.g. `0F00549`, `0X10189`). The letter does not tell domestic from foreign entities. Pass the control number exactly as the register or a prior search result returns it.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `controlNumber` | Up to 8 characters (7–8 digits, or one letter + 6 digits) | `H852680` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Delta"` | Starts-with (case-insensitive) | Multiple results, up to 20 per query |
| By Control Number | Up to 8 chars | `H852680` | Exact | Exact match returned first (`matchType: id`) |
**Starts-with search.** Name search anchors on the beginning of the legal name and is case-insensitive. Names that start with "The" are also matched without typing the article, so `Coca-Cola` also returns `THE COCA-COLA COMPANY`. Narrow the query to reduce the result set. The result cap is 20 matches.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Control number format varies by origin** | Domestic entities use 7-digit numeric codes; foreign-qualified entities use `H` + 6 digits. A small set of legacy entities carry other letter-prefix forms (e.g. `0X10189`). Always pass the control number as-is from the register. |
| **No bulk open-data extract** | All data is read from the live eCorp portal. There is no downloadable snapshot, so both fast and authoritative requests hit the live register. |
| **Officer data lags by up to 12 months** | Officers and addresses are updated only when an entity files its annual registration. The roster may be up to one year out of date. |
| **Legal form labels** | eCorp publishes labels such as "Foreign Profit Corporation" or "Domestic Limited Liability Company". Legal form is standardized with a fixed mapping of Georgia's statutory entity types. The raw label is returned in `localName`. |
| **Officer titles** | Corporations and nonprofits list a CEO, CFO and Secretary. LLCs publish no officers. Titles are standardized with a fixed mapping, and the raw title is returned in `localName`. |
| **Registered agent is always included** | Every Georgia entity must maintain a registered agent. The agent name and address are returned in `otherKeyPersons` with the standardized role Registered Agent. Service appointment does not establish general signing authority. |
| **No shareholder or UBO register** | Georgia does not publish shareholders or beneficial owners for any entity type. Federal FinCEN beneficial ownership filings are a separate system. |
| **DBAs are filed at the county level** | Doing-business-as (trade) names are registered in individual Georgia counties and are not part of the state register. DBA-style names are not indexed for search. |
| **Paid documents require a separate order** | A Certificate of Existence and certified copies are available from the Secretary of State but require a paid order through the eCorp portal and are delivered by email. These are not available through the Topograph API. |
## Mappings
### Legal Forms
Georgia eCorp publishes entity type labels, which Topograph standardizes with a fixed mapping of Georgia's statutory entity types. Common values observed on the portal are listed below.
| eCorp Entity Type | Standardized |
| - | - |
| Domestic Profit Corporation | Corporation |
| Foreign Profit Corporation | Corporation |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Corporation | Nonprofit Organization |
| Domestic Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic Limited Liability Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Domestic Limited Liability Limited Partnership | Partnership |
| Domestic Benefit Corporation | Corporation |
| Foreign Benefit Corporation | Corporation |
A label that does not match a known Georgia entity type is returned in `localName` only, with no standardized value.
### Officer Roles
The eCorp roster lists CEO, CFO and Secretary for corporations and nonprofits. The annual-registration guide also describes General Partner and Managing Partner records for partnerships. LLCs publish no officers. Known titles use the published role catalogue; an unknown designation keeps its raw `localName`.
Officer titles identify recorded offices. Company-specific signing powers may depend on governing documents or delegated authority, which this public roster does not disclose.
| Raw Title | Standardized |
| - | - |
| CEO | Chief Executive Officer |
| CFO | Chief Financial Officer |
| Secretary | Secretary |
| General Partner | General Partner |
| Managing Partner | Managing Partner |
### Other Key Persons
Registered agents receive service of process. They appear in `otherKeyPersons` as individuals or companies, with the standardized role Registered Agent. This appointment alone does not authorize them to bind the business.
### Company Status
Status values are read directly from the eCorp portal. Common values include:
| eCorp Status | Active |
| - | - |
| Active/Owes AR | Yes |
| Active/Compliance | Yes |
| Active/Good Standing | Yes |
| Dissolved | No |
| Withdrawn | No |
| Revoked | No |
| Terminated | No |
Status is returned as both a raw `localName` from the register and a boolean `active` field.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the eCorp portal |
| Company status | Yes | Current status as published by eCorp, standardized to an `active` boolean |
| Registration date | Yes | Date of formation (domestic) or registration date (foreign), as recorded in eCorp |
| Legal address | Yes | Principal office address including street, city, state, and ZIP |
| Legal form | Yes | Standardized from the eCorp entity type label |
| Legal representatives | Yes | Recorded officers and partnership roles; title alone does not disclose signing powers |
| Other key persons | Yes | Registered agent for service of process |
| Activity codes | Yes | NAICS code where published; ISIC and NACE derived automatically |
| Shareholders | No | Not published by the Georgia register |
| UBOs | No | No state-level beneficial ownership register; federal FinCEN filings are a separate system |
| Documents | No | Certificate of Existence and certified copies require a paid order through the eCorp portal |
| Fictitious names (DBAs) | No | Registered at the county level; not part of the state register |
| Financial data | No | Not collected by the register |
For the full, up-to-date catalog of supported datapoints, documents, and sources, see the [Georgia pricing page](https://topograph.co/pricing/us-ga).
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-GA&query=Placeholder+Company" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "12345678",
"legalName": "PLACEHOLDER COMPANY INC.",
"countryCode": "US-GA",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by Control Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-GA&query=H123456" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "H123456",
"legalName": "PLACEHOLDER FOREIGN CORPORATION",
"countryCode": "US-GA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-GA", "id": "12345678", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "12345678",
"countryCode": "US-GA",
"identifiers": { "controlNumber": "12345678" },
"legalName": "PLACEHOLDER COMPANY INC.",
"registrationDate": "2010-03-15",
"status": {
"localName": "Active/Good Standing",
"active": true
},
"legalForm": {
"localName": "Domestic Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "123 Peachtree Street NW",
"city": "Atlanta",
"region": "GA",
"postalCode": "30303",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "CEO", "standardized": "Chief Executive Officer" },
"individual": { "name": { "fullName": "Jane Sample" } }
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"company": { "legalName": "Placeholder Agent Services LLC" }
}
]
}
```
# Hawaii
Source: https://docs.topograph.co/essentials/us-hawaii
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Hawaii reference is on the [Hawaii country page](https://www.topograph.co/countries/us-hi).
## Start here
This guide contains public integration notes for Hawaii. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Entity Statuses](#entity-statuses)
* [Ownership coverage](#ownership-coverage)
* [Data Availability](#data-availability)
**API access:** Hawaii is in beta. `US-HI` is accepted by `/v2/company` and `/v2/search`, but it is not yet listed in the public `countryCode` enum of the OpenAPI spec.
## Data Sources
Hawaii uses a single integration against the **Hawaii Department of Commerce and Consumer Affairs, Business Registration Division (DCCA / BREG)**, surfaced through the **Hawaii Business Express (HBE)** portal.
The register covers every entity type filed under the Hawaii Revised Statutes: domestic and foreign profit corporations, nonprofit corporations, professional corporations, sustainable business corporations, limited liability companies, general partnerships, limited partnerships, limited liability partnerships, limited liability limited partnerships, agricultural and consumer cooperatives, and the special Corporation Sole form.
* **DCCA / BREG detail page** (live, authoritative). Every profile (legal name, file number, business type, status, registration date, principal and mailing addresses, term, registered agent, and the officer / director / manager / member / general partner roster) is read directly from the register at request time. Officers are on the public record per DCCA policy and appear without any paid order. The same record carries the ownership roster for the entity types where Hawaii publishes one, so `shareholders` costs no extra call — see [Ownership coverage](#ownership-coverage).
There is no open-data bulk feed for Hawaii. The Hawaii Open Data Portal entry for "Business Name Search" links back to the live HBE web search; no downloadable dataset exists. All data is fetched live from the register.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Hawaii BREG File Number** | Up to 7 digits, no leading zeros (3 to 6 in the records we have seen), followed by a two-character suffix (one uppercase letter + one digit) | `112127D1` | Assigned by DCCA / BREG. The suffix encodes the entity type and domestic/foreign status (see table below). |
The register displays the file number with a space between the digits and the suffix (`112127 D1`). Search results, `company.id` and `identifiers.fileNumber` use the form without the space (`112127D1`, `270541C5`, `151D1`). Both forms are accepted when querying the Topograph API.
#### File Number Suffix Codes
The two-character suffix encodes both entity type and domestic vs. foreign status:
| Suffix | Entity Type |
| - | - |
| `D1` | Domestic Profit Corporation |
| `D2` | Domestic Nonprofit Corporation |
| `D9` | Domestic Corporation Sole |
| `P1` | Professional Corporation |
| `S1` | Sustainable Business Corporation |
| `F1` | Foreign Profit Corporation |
| `F2` | Foreign Nonprofit Corporation |
| `C5` | Domestic Limited Liability Company |
| `C6` | Foreign Limited Liability Company |
| `G5` | Domestic General Partnership |
| `G6` | Foreign General Partnership |
| `L5` | Domestic Limited Partnership |
| `L6` | Foreign Limited Partnership |
| `K5` | Domestic Limited Liability Partnership |
| `K6` | Foreign Limited Liability Partnership |
| `Q5` | Domestic Limited Liability Limited Partnership |
| `Q6` | Foreign Limited Liability Limited Partnership |
| `A1` | Agricultural Cooperative With Stock |
| `A2` | Agricultural Cooperative Without Stock |
| `C1` | Consumer Cooperative With Stock |
| `C2` | Consumer Cooperative Without Stock |
`Q5` / `Q6` are **limited liability limited partnerships** — limited partnerships that elected the status — not professional partnerships. The suffix therefore tells you whether ownership is published: see [Ownership coverage](#ownership-coverage) below.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `fileNumber` | Up to 7 digits + two-character suffix (compact form, no space) | `112127D1` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Aloha Holdings"` | Begins-with (case-insensitive) | Multiple results |
| By File Number | Digits + suffix, with or without a space | `112127D1` | Exact | Exact match returned first (`matchType: id`) |
Name search matches the beginning of the entity's master name. Using a more specific query string narrows the result set.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **File number suffix is load-bearing** | The two-character suffix (`D1`, `C5`, etc.) is part of the identifier and encodes the legal form. Passing a bare numeric string without the suffix returns no match. |
| **Space vs. no-space forms both work** | The portal renders file numbers with a space (`112127 D1`); the URL omits it (`112127D1`). The API accepts both. The response uses the compact form without a space (`112127D1`). |
| **Status carries the register's code** | The register renders each status as a label followed by a one-character code in parentheses, such as `Active (A)` or `Delinquent Status 1 (1)`. The string is returned as-is in `status.localName`, and `status.active` is derived from the code. Delinquent statuses (an overdue annual report) are still active. |
| **"Not in good standing" is separate from status** | An entity can have status `Active (A)` and still carry a "not in good standing" flag (for example, when the most recent annual report is delinquent). The standing flag does not change the `status` field. |
| **LLC legal-form label has a lowercase suffix** | The BREG page renders LLC types as `Domestic Limited Liability Company (llc)`. Topograph strips the `(llc)` suffix when mapping to the standardized legal form. |
| **Officer codes are combinable** | The current HBE register combines office codes with `;` (`P;D` = President + Director). Historical records may use `/` (`MGR/MEM` = Manager + Member). Each combined record is split into separate role entries in the API response. |
| **Ownership depends on the entity type** | Hawaii names owners for member-managed LLCs, general partnerships and limited liability partnerships, and for nobody else — a manager-managed LLC files only its managers and a member count, a corporation files aggregate share counts with no holder, and a limited partnership files only its general partners. Requesting `shareholders` for one of those returns an explanatory error rather than an empty list. No Hawaii filing carries an ownership percentage. UBO data is federal only (FinCEN BOI) and not public. See [Ownership coverage](#ownership-coverage). |
| **No activity codes** | The BREG does not collect NAICS, SIC, or any other industry classification code. The register captures a free-text purpose field, returned as `company.activityDescription`. |
| **Annual filings are on the public record** | Each entity shows a year-by-year filing history (Processed / Delinquent / Not Filed) on the BREG detail page. It appears on the Trade Register Extract, not as a field in the API response. |
| **Paid documents: Certificate of Good Standing and Annual Filings** | The Trade Register Extract is bundled with the company profile. Two paid documents are available separately: a Certificate of Good Standing (entities currently in good standing only) and the filed Annual Report for any year on record, ordered per year (see [pricing page](https://topograph.co/pricing/us-hi)). Both are register-issued PDFs; the annual report is a scan of the filed form. |
## Mappings
### Legal Forms
Legal form is derived from the `BUSINESS TYPE` field on the BREG detail page, a closed set of 21 entity types. The two-character file-number suffix independently encodes the same legal form.
| BREG Entity Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Profit Corporation | Corporation | `L2QV` |
| Foreign Profit Corporation | Corporation | |
| Professional Corporation | Corporation | |
| Sustainable Business Corporation | Corporation | |
| Domestic Nonprofit Corporation | Nonprofit Organization | `DX2N` |
| Foreign Nonprofit Corporation | Nonprofit Organization | |
| Domestic Corporation Sole | Other | |
| Domestic Limited Liability Company | Limited Liability Company | `VPBH` |
| Foreign Limited Liability Company | Limited Liability Company | |
| Domestic General Partnership | Partnership | |
| Foreign General Partnership | Partnership | |
| Domestic Limited Partnership | Partnership | `AQBO` |
| Foreign Limited Partnership | Partnership | |
| Domestic Limited Liability Partnership | Partnership | |
| Foreign Limited Liability Partnership | Partnership | |
| Domestic Limited Liability Limited Partnership | Partnership | |
| Foreign Limited Liability Limited Partnership | Partnership | |
| Agricultural Cooperative With Stock | Cooperative | |
| Agricultural Cooperative Without Stock | Cooperative | |
| Consumer Cooperative With Stock | Cooperative | |
| Consumer Cooperative Without Stock | Cooperative | |
The ISO 20275 column is for reference: the API does not return `iso20275Code` for Hawaii. The full legal form table, including provenance, is on the [pricing page](https://topograph.co/pricing/us-hi).
### Officer Roles
Known office codes and filed role labels are mapped to fixed role meanings. The current official title list includes Clerk and Scribe; historical vice-president ordinals (1V–9V) remain supported. The current register combines codes with `;`; historical records may use `/`. The API splits compound entries into separate records.
Other filed titles are preserved as reported. An unfamiliar title can have no `role.standardized` value.
| Office Code | Role | Notes |
| - | - | - |
| `P` | President | |
| `S` | Secretary | |
| `T` | Treasurer | |
| `D` | Director | |
| `C` | Chairman / Chairwoman of the Board | |
| `CEO` | Chief Executive Officer | |
| `CFO` | Chief Financial Officer | |
| `CO` | Comptroller / Controller | |
| `AC` | Assistant Comptroller / Controller | |
| `AS` | Assistant Secretary | |
| `AT` | Assistant Treasurer | |
| `EV` | Executive Vice President | |
| `SRV` | Senior Vice President | |
| `V` | Vice President | |
| `1V`–`9V` | 1st–9th Vice President | |
| `VC` | Vice Chairman | |
| `G` | General Partner | |
| `L` | Limited Partner | |
| `MGR` | Manager | |
| `MEM` | Member | LLC-only; not in the BREG code legend but appears in compound codes |
| `R` | Trustee | |
Managers (`MGR`) and General Partners (`G`) retain their management roles. Members (`MEM`) are Legal Representatives only for a member-managed LLC; a member of a manager-managed LLC is an other key person. Directors and board chairs are other key persons unless a separate executive office is also reported. Officer powers follow the bylaws or board directions; titles do not establish an individual signing mode. Members and partners are **additionally** returned as shareholders where Hawaii law makes the published list a complete ownership list — see [Ownership coverage](#ownership-coverage). Managers never are: state law defines a manager as a person "whether or not a member", so the title carries control, not equity. The registered agent is returned separately as an other key person and holds no statutory authority to bind the entity.
### Entity Statuses
| BREG Status | Active | Notes |
| - | - | - |
| `New (Y)` | Yes | |
| `Active (A)` | Yes | |
| `Delinquent Status 1 (1)` | Yes | Annual report overdue |
| `Delinquent Status 2 (2)` | Yes | Annual report overdue |
| `Adm. Terminated (V)` | No | Administratively terminated |
| `Terminated (T)` | No | |
| `Withdrawn (W)` | No | Foreign entity withdrawn from Hawaii |
| `Cancelled (C)` | No | |
| `Dissolved (D)` | No | Voluntarily dissolved |
| `Inv. Revoked (R)` | No | Involuntarily revoked |
| `Inv. Cancelled (X)` | No | Involuntarily cancelled |
| `Inv. Dissolved (7)` | No | Involuntarily dissolved |
| `Merged (M)` | No | |
| `Converted (9)` | No | Converted to a different entity type |
| `Expired (E)` | No | |
| `Inactive (I)` | No | |
The full status table with provenance is on the [pricing page](https://topograph.co/pricing/us-hi).
## Ownership coverage
Hawaii publishes owners only where a statute both makes the title an ownership interest **and** requires the filing to name every holder. Where it does, the owners come back on the `shareholders` datapoint at no extra charge — they are read from the same entity record as the company profile.
| Entity type | `shareholders` returns |
| - | - |
| Member-managed LLC (`C5` / `C6`) | Every member. The annual report of a member-managed company must give the name and address of **each** member, so the list is complete. A single member is reported at 100% |
| General partnership (`G5` / `G6`) | Every partner. The registration statement and every annual statement must name each partner |
| Limited liability partnership (`K5` / `K6`) | Every partner. The annual report must name each partner |
| Manager-managed LLC (`C5` / `C6`) | An explanatory error. A manager-managed company files its managers and the **number** of its members, never their names. The managers are returned under `legalRepresentatives` |
| Corporation (`D1` / `F1` / `P1` / `S1`) | An explanatory error. The annual report carries directors, officers and the total authorised and issued share counts by class — never a holder. Executive officers are returned under `legalRepresentatives`; governing-only directors are returned under `otherKeyPersons` |
| Limited partnership and LLLP (`L5` / `L6` / `Q5` / `Q6`) | An explanatory error. Only the general partners are filed; the limited partners are named in a partnership agreement that is never filed |
| Cooperative (`A1` / `A2` / `C1` / `C2`) | An explanatory error. A cooperative reports only how many members or shareholders it has |
| Non-profit corporation (`D2` / `F2`) | A not-applicable result — a non-profit has no share capital. Officers and board members are returned under `legalRepresentatives` |
**The paid Annual Filing adds no ownership detail.** The filed report lists its members by name and address and carries no percentage, share count or capital contribution — there is no such field on the form — so `shareholders` already returns everything it discloses. Order it as evidence of what was filed, not to obtain ownership data.
The filing does state the date its contents are effective from ("as of" the quarterly anchor date set by the entity's registration quarter). That date is not currently returned on the `shareholders` datapoint.
A member-managed LLC that has filed no member — a missing annual report, or a record whose management designation and filed roster disagree — returns the same explanatory error rather than an empty list. The people it has filed are still returned under `legalRepresentatives`.
**No percentages exist.** No Hawaii filing carries an ownership percentage, a share count or a capital amount for an LLC or a partnership, so `sharePercentage` is empty — with one exception: the single member of a member-managed LLC is reported at 100%, because state law makes that filed list the complete membership. Two or more owners are returned with no split. A general partnership or LLP whose public roster names only one partner is refused rather than reported as a sole owner.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name (master name on the BREG record) |
| Company status | Yes | BREG status label with its code, plus an `active` flag |
| Registration date | Yes | Initial filing date with DCCA / BREG |
| Legal address | Yes | Principal address (street, city, state, ZIP) |
| Mailing address | Partial | Used as the legal address only when no principal address is filed; not returned separately |
| Legal form | Yes | Closed 21-value BREG taxonomy with a standardized category |
| Legal representatives | Yes | Officers, directors, managers, general partners, and members filed with the entity |
| Registered agent | Yes | Returned as an other key person (name, type, and address) |
| Trade Register Extract | Yes | Register-issued PDF of the BREG detail page, bundled with the company profile at no extra charge |
| Certificate of Good Standing | Yes (paid) | Issued by DCCA / BREG for entities currently in good standing; available as a paid document (see [pricing page](https://topograph.co/pricing/us-hi)) |
| Annual filing history | No | Not returned as a field. The year-by-year filing status appears on the Trade Register Extract |
| Annual Filing (filed report PDF) | Yes (paid) | The register's own scan of a filed annual report, orderable per year for every year on record. Useful as evidence of what was filed; it carries no ownership detail beyond what `shareholders` already returns (see [pricing page](https://topograph.co/pricing/us-hi)) |
| Activity codes | No | Not collected by the BREG |
| Shareholders | Partial | Members of member-managed LLCs, and partners of general and limited liability partnerships. Never for corporations, manager-managed LLCs, limited partnerships or cooperatives — see [Ownership coverage](#ownership-coverage) |
| UBOs | No | Not published at the state level; federal FinCEN BOI records are restricted |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-HI&query=Aloha+Holdings" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "100001D1",
"legalName": "ALOHA HOLDINGS, INC.",
"countryCode": "US-HI",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by File Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-HI&query=100001D1" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "100001D1",
"legalName": "ALOHA HOLDINGS, INC.",
"countryCode": "US-HI",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-HI", "id": "100001 D1", "dataPoints": ["company", "legalRepresentatives"]}'
```
```json theme={null}
{
"company": {
"id": "100001D1",
"countryCode": "US-HI",
"identifiers": { "fileNumber": "100001D1" },
"legalName": "ALOHA HOLDINGS, INC.",
"status": {
"localName": "Active (A)",
"active": true
},
"registrationDate": "2005-06-01",
"legalForm": {
"localName": "Domestic Profit Corporation",
"englishTranslation": "Domestic Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "1 Example Street",
"city": "Honolulu",
"region": "HI",
"postalCode": "96813",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "President", "standardized": "President" },
"individual": { "name": { "fullName": "Jane K. Sample" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Director", "standardized": "Board Member" },
"individual": { "name": { "fullName": "Jane K. Sample" } }
}
]
}
```
# Idaho (US)
Source: https://docs.topograph.co/essentials/us-idaho
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Idaho (US) reference is on the [Idaho (US) country page](https://www.topograph.co/countries/us-id).
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
All entity data comes from the **Idaho Secretary of State** via the **SOSBiz** portal ([sosbiz.idaho.gov](https://sosbiz.idaho.gov)). This is the official state register for all business entities formed or qualified to do business in Idaho, including domestic and foreign corporations, LLCs, limited partnerships, nonprofits, cooperatives, and Assumed Business Names.
Every request hits the live register. There is no bulk data export or open-data feed. Only verification mode is authoritative. Prefill mode reads the same register through a lighter path to answer faster, so it can return a less complete address and legal form.
Idaho is a single-source jurisdiction. Company profile and search both
come from the live SOSBiz portal. A Trade Register Extract is included in
the document catalogue.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Idaho Entity Number** | Digits only, up to 10, without leading zeros (3 to 7 digits in the records we have seen, e.g. `481`, `586619`) | `3960192` | Primary identifier assigned by the Idaho Secretary of State. Also accepted zero-padded to 10 digits (`0003960192`), the form the register displays. |
The Entity Number is the only identifier supported for company retrieval.
To find an ID from a name, use the search endpoint first. Both the bare
form and the zero-padded 10-digit form are accepted.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | Idaho Entity Number, digits only, without leading zeros (also returned as `id`) | `3960192` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 1–200 chars | `"East Idaho Power Washing"` | Contains | Multiple results |
Name search supports contains-matching across all registered entity names.
An Entity Number typed into search is matched as free text, not as an
identifier, so results carry no `id` match type. When the Entity Number is
known, request the company profile directly.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No officers or legal representatives** | Idaho does not expose officers, directors, managers, or members through the public register. |
| **No shareholders** | Shareholder lists and LLC member names are not collected by the Idaho Secretary of State. |
| **No activity codes** | Industry classification codes (NAICS / NACE / ISIC) are not collected at the state level. |
| **Mailing address may begin with a name** | The `Mailing Address` field occasionally starts with a person's name on the first line (e.g. `JOHN SMITH / PO BOX 70 / TREMONTON, UT`). The street address begins on the second line. |
| **ABN entries have fewer fields** | Assumed Business Names often have no registered agent and no principal address. |
| **Inactive entities are fully retrievable** | Dissolved, forfeited, withdrawn, and cancelled entities remain searchable and return a complete profile. |
## Mappings
### Company Status
Status is prefixed by the Idaho SoS: `Active-*` values are active; `Inactive-*` values are not.
| Source Value | Active |
| - | - |
| Active-Good Standing | true |
| Active-Existing | true |
| Active-Current | true |
| Inactive-Administratively Dissolved | false |
| Inactive-Cancelled | false |
| Inactive-Dissolved (Admin) | false |
| Inactive-Expired | false |
| Inactive-Forfeited | false |
| Inactive-Withdrawn | false |
Any value beginning with `Active-` maps to `active: true`; any value beginning with `Inactive-` maps to `active: false`.
### Legal Forms
Idaho entity types come from the filing type field. Domestic entities may carry an ISO 20275 ELF code; foreign entities do not (they are formed in another jurisdiction).
| Idaho Filing Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Business Corporation (GBC) | Corporation | U9HL |
| Domestic Professional Service Corporation (PSC) | Corporation | None |
| Domestic Benefit Corporation | Corporation | U9HL |
| Foreign Business Corporation | Corporation | — |
| Domestic Limited Liability Company (LLC) | Limited Liability Company | RU6X |
| Domestic Professional LLC (PLLC) | Limited Liability Company | None |
| Foreign Limited Liability Company | Limited Liability Company | — |
| Domestic Limited Partnership (LP) | Partnership | `530K` |
| Foreign Limited Partnership | Partnership | — |
| Domestic General Partnership | Partnership | — |
| Domestic Limited Liability Partnership | Partnership | — |
| Domestic Nonprofit Corporation | Nonprofit Organization | EVE6 |
| Foreign Nonprofit Corporation | Nonprofit Organization | — |
| Domestic Unincorporated Nonprofit Association (UNA) | Nonprofit Organization | — |
| Domestic Cooperative Association | Cooperative | — |
| Assumed Business Name (ABN) | Other | — |
| Foreign Name Registration | Other | — |
| Reservation of Legal Entity Name | Other | — |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Legal name | Yes | |
| Entity type / legal form | Yes | Deterministically mapped |
| Status | Yes | Active/inactive derived from prefix |
| Registration date | Yes | When available in the register |
| Principal address | Yes | When available in the register |
| Mailing address | Partial | Used as the legal address only when no principal address is filed; may include a name on the first line |
| Registered agent | Yes | Name and address, returned as an other key person (`otherKeyPersons`) with the standardized role `Registered Agent` |
| Legal representatives / officers | No | Not collected by Idaho Secretary of State |
| Shareholders | No | Not collected by Idaho Secretary of State |
| UBO | No | No state-level register; federal BOI records are not public |
| Activity codes | No | Not collected at state level |
## Documents
### Trade Register Extract
A PDF of the entity's detail record from the SOSBiz register, including legal name, entity number, type, status, formation date, and all field-value pairs published by the register. Includes a capture timestamp.
| Property | Value |
| - | - |
| Format | PDF |
| Source | Idaho Secretary of State — SOSBiz portal |
| TTL | 1 day |
### Certificate of Existence / Filing
The Idaho Secretary of State offers paid certificates for registered entities (Certificate of Existence/Filing for corporations, LLCs, and other entity types; Certificate of Filing ABN for Assumed Business Names). These are not yet available through Topograph.
## Example API Responses
### Company Profile: Foreign Business Corporation
```json theme={null}
{
"company": {
"id": "3960192",
"countryCode": "US-ID",
"legalName": "AMAZON DATA SERVICES, INC.",
"status": {
"localName": "Active-Good Standing",
"active": true
},
"legalForm": {
"localName": "Foreign Business Corporation",
"englishTranslation": "Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "160 Greentree Drive Suite 101",
"city": "Dover",
"region": "DE",
"postalCode": "19904",
"countryCode": "US"
}
}
}
```
### Company Profile: Domestic LLC
```json theme={null}
{
"company": {
"id": "4318071",
"countryCode": "US-ID",
"legalName": "EAST IDAHO POWER WASHING LLC",
"status": {
"localName": "Active-Existing",
"active": true
},
"legalForm": {
"localName": "Limited Liability Company (D)",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "RU6X"
},
"legalAddress": {
"addressLine1": "123 Main St",
"city": "Idaho Falls",
"region": "ID",
"postalCode": "83401",
"countryCode": "US"
}
}
}
```
### Company Profile: Inactive Entity
```json theme={null}
{
"company": {
"id": "1405",
"countryCode": "US-ID",
"legalName": "BANK OF IDAHO FALLS",
"status": {
"localName": "Inactive-Forfeited",
"active": false
},
"legalForm": {
"localName": "General Business Corporation (D)",
"englishTranslation": "Corporation",
"standardized": "Corporation",
"iso20275Code": "U9HL"
}
}
}
```
# Illinois
Source: https://docs.topograph.co/essentials/us-illinois
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Illinois reference is on the [Illinois country page](https://www.topograph.co/countries/us-il).
## Start here
This guide contains public integration notes for Illinois. Use it for identifier formats, search behavior, and state-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
State details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Entity Statuses](#entity-statuses)
* [Data Availability](#data-availability)
## Data Sources
Illinois uses a single integration against the **Illinois Secretary of State, Department of Business Services**. The register covers approximately 3.5 million entities filed under the Illinois Business Corporation Act, the General Not-for-Profit Corporation Act, the Limited Liability Company Act, and related statutes, including domestic and foreign corporations, LLCs, professional service entities, benefit corporations, agricultural cooperatives, and not-for-profit corporations.
The Illinois Business Data Transparency Act (Public Act 102-0049, effective 2022-01-01) requires the Secretary of State to publish daily bulk distributions of the business entity database. These bulk files are the sanctioned machine-readable path; Topograph uses them as the primary data source.
* **ILSOS daily bulk distribution**. Published daily by the Secretary of State at `ilsos.gov`. Covers corporation and LLC master records, names, manager/member rosters, and registered agents. The snapshot refreshes daily; individual records may lag up to 24 hours from a filing event.
**Same data in both modes.** Prefill (`mode: "prefill"`) and verification (`mode: "verification"`) requests are both served from the daily bulk distribution and return the same data.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **ILSOS File Number** | 8 digits, leading zeros included | `08142220` | Assigned by the Illinois Secretary of State. **Illinois runs independent File Number sequences for corporations and LLCs.** The same 8-digit number can refer to two different entities (one corporation, one LLC). To target a specific entity, supply the Topograph compound ID. |
| **Topograph compound ID** | `C` or `L` prefix + 8 digits | `C08142220` | The prefix is ours, not the register's: `C` for an entity on the corporation register (including not-for-profit corporations), `L` for a limited liability company. This is the `id` of every search result and the `company.id` of every profile. Use it whenever you need to target a specific entity and avoid ambiguity. |
Search by bare 8-digit File Number returns all matching entities across both the corporation and LLC sequences. Use the compound ID (`C08142220` or `L08142220`) to resolve to a single entity. `/v2/company` refuses a bare number that matches both a corporation and an LLC. The `identifiers.entityType` field in the response confirms which family was matched.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `fileNumber` | 8 digits, leading zeros included, no prefix (`company.id` carries the `C` / `L` prefix) | `08142220` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when `fileNumber` has a unique match against Illinois registration or validation references in GLEIF and the legal name agrees.
Corporations and LLCs use separate number sequences, so a number match alone is insufficient.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Walgreen"` | Relevance-ranked match on the legal name | Multiple results |
| By File Number (bare) | 8 digits | `08142220` | Exact | Up to 2 results (one corp + one LLC if both exist) |
| By Compound ID | `C` or `L` + 8 digits | `C08142220` | Exact | Single entity |
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **File Number sequences overlap across entity families** | Illinois maintains independent File Number sequences for corporations and LLCs. Two different entities can share the same 8-digit number. Always use the Topograph compound ID (`C` or `L` prefix) when you need to unambiguously identify a single entity. |
| **Annual report freshness** | Corporations and LLCs file one annual report per year. Officer and address data in the snapshot may be up to 12 months old, reflecting the most recent annual filing. This is a structural property of the Illinois filing cadence, not a Topograph limitation. |
| **LLCs disclose managers and members** | Unlike many US states, Illinois LLCs disclose their managers and (where applicable) members in the public bulk distribution. These positions appear in `otherKeyPersons` with their filed titles and member-management context. A bulk position does not establish company-specific signing powers. |
| **Limited Partnerships and LLPs are out of scope for v1** | LPs and LLPs are available through the live portal but are not included in the daily bulk distribution. They are excluded from v1 coverage. |
| **No ownership percentages** | Illinois does not collect or publish ownership percentages for any entity type. Returned people include names and filed roles but no equity stakes. |
| **No activity codes** | The Secretary of State does not collect NAICS, NACE, or ISIC codes. A coarse 56-entry purpose code is available for corporations only and is not currently surfaced. |
| **Series LLCs** | Illinois is one of the few states that allows Series LLCs. The parent LLC is identified by its legal form (`Series Limited Liability Company`). Individual series are not returned as separate entities. |
| **State-level DBAs** | Assumed names (DBAs) registered at the state level are included in the bulk distribution and indexed for search. County-level DBA registrations are not included. |
| **Nonprofits are in scope** | Not-for-profit corporations filed under the Illinois General Not-for-Profit Corporation Act are included in the corporation bulk distribution and covered by this integration. Fundraising registration through the Illinois Charitable Trust Bureau is out of scope. |
## Mappings
### Legal Forms
Legal form is derived from the entity type code in the ILSOS bulk distribution, sourced from the published Corp and LLC data dictionaries. The full legal form table is available on the pricing page.
| Local Name | Standardized | Category |
| - | - | - |
| Domestic Corporation | Corporation | Business Corporation Act |
| Foreign Corporation | Corporation | Business Corporation Act |
| Not-For-Profit Corporation | Nonprofit Organization | Not-for-Profit Corporation Act |
| Agricultural Cooperative | Cooperative | Ag-cooperative (unique to IL) |
| Domestic Limited Liability Company | Limited Liability Company | LLC Act |
| Foreign Limited Liability Company | Limited Liability Company | LLC Act |
| Low-Profit Limited Liability Company (L3C) | Limited Liability Company | LLC Act |
| Series Limited Liability Company | Limited Liability Company | LLC Act (unique to IL) |
The full legal form table with source codes and ISO 20275 mappings (where available) is on the [Illinois pricing page](https://topograph.co/pricing/us-il).
### Entity Statuses
Status values come from the register's own status codes in the ILSOS bulk data dictionaries (Corp CORP-STATUS field and LLC LL-STATUS field). A dissolved corporation is returned as Voluntary Dissolution or Involuntary Dissolution when the register records which kind of dissolution it was, and as Dissolved otherwise.
| Status | Applies To |
| - | - |
| Goodstanding | Corps and LLCs |
| Not Good Standing | LLCs |
| Reinstated | Corps and LLCs |
| Domesticated | LLCs |
| Redomisticated | Corps |
| Intent to Dissolve | Corps |
| Unacceptable Payment | Corps |
| Registered Name Expiration | Corps |
| Registered Name Cancellation | Corps |
| Special Act Corporation | Corps |
| Ag-Coop | Corps |
| Agent Vacated | Corps and LLCs |
| Hold | LLCs |
| Bankruptcy | Corps and LLCs |
| Voluntary Dissolution | Corps and LLCs |
| Involuntary Dissolution | Corps and LLCs |
| Administratively Dissolved | Corps and LLCs |
| Dissolved | Corps |
| Withdrawn | Corps and LLCs |
| Revoked | Corps and LLCs |
| Expired | Corps |
| Void | LLCs |
| Merged/Consolidated | Corps |
| Merged | LLCs |
| Converted | Corps and LLCs |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Yes | From the register's status codes, for corporations and LLCs, in both modes |
| Registration date | Yes | ILSOS initial filing date |
| Legal address | Partial | LLCs only (records office address). Corporations publish no company address, so none is returned. |
| Legal form | Yes | Closed enum mapped to standardized categories |
| Legal representatives | Yes | Corps: president. LLCs: managers, and members holding manager authority. LP/LLP: out of scope for v1. |
| Other key persons | Yes | Corps: secretary and registered agent. LLCs: registered agent. |
| Registered agent | Yes | Returned under `otherKeyPersons` in both modes |
| Assumed names (DBAs) | Yes | State-level assumed names from the bulk distribution |
| Series LLC sub-series | No | Series LLC parents are identified by their legal form; individual series are not returned |
| Activity codes | No | Not collected by the Illinois Secretary of State |
| Shareholders | No | Not filed with the Secretary of State for any entity type |
| UBOs | No | No public beneficial ownership register at the state level |
| Trade Register Extract | No | No documents are currently offered for Illinois |
| Certificates of Good Standing | Roadmap | Paid document issued by the Secretary of State. Not currently offered through Topograph. |
| Certified copies | No | Paid documents mailed by the Secretary of State; not available through the public portal |
| Financial data | No | Not collected |
| County-level DBAs | No | County-level DBA filings are not part of the Secretary of State database |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-IL&query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "C09000001",
"legalName": "ACME MANUFACTURING, INC.",
"countryCode": "US-IL",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "IL",
"countryCode": "US"
}
}
]
```
### Search by Compound ID
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-IL&query=C09000001" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "C09000001",
"legalName": "ACME MANUFACTURING, INC.",
"countryCode": "US-IL",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-IL", "id": "C09000001", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "C09000001",
"countryCode": "US-IL",
"identifiers": { "fileNumber": "09000001" },
"legalName": "ACME MANUFACTURING, INC.",
"registrationDate": "2005-03-15",
"legalForm": {
"localName": "Domestic Corporation",
"standardized": "Corporation"
},
"status": {
"localName": "Goodstanding",
"active": true
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "President", "standardized": "President" },
"individual": {
"name": { "fullName": "Jane A. Smith" }
}
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Secretary", "standardized": "Secretary" },
"individual": {
"name": { "fullName": "Robert B. Johnson" }
}
}
]
}
```
# Indiana (US)
Source: https://docs.topograph.co/essentials/us-indiana
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Indiana (US) reference is on the [Indiana (US) country page](https://www.topograph.co/countries/us-in).
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Other Key Persons](#other-key-persons)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
All entity data comes from the **Indiana Secretary of State, Business Services Division** via the **INBiz** portal ([bsd.sos.in.gov](https://bsd.sos.in.gov/publicbusinesssearch)). This is the official state register for all business entities formed or qualified to do business in Indiana, including domestic and foreign corporations, LLCs, limited partnerships, nonprofits, and other entity types.
Every request hits the live register. There is no bulk data export or REST API. The response is always authoritative and up to date.
Indiana is a single-source country. Company profile, registered agent,
governing persons, and search all come from the live Indiana SoS portal.
The Trade Register Extract and Secretary-of-State-signed Certified Copies
are included in the document catalogue.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Indiana Business ID** | Multiple format eras (see below) | `183025-143` | Primary identifier assigned by the Indiana Secretary of State at registration |
Indiana Business IDs span several format eras depending on when the entity was formed:
| Era | Format | Example |
| - | - | - |
| Modern (2000s–present) | 13–16 digit sequential | `2001111900027` |
| Legacy numeric (1990s–2000s) | 8–12 digit numeric | `1997051343` |
| Hyphenated legacy (pre-2000) | `NNNNNN-NNN` | `183025-143` |
| Letter-separated legacy (pre-2000) | `NNNNNNANNN` | `193046A080` |
| Limited partnerships | `LPNNNNNNNN` | `LP93120064` |
The Indiana Business ID is the only identifier supported for company
retrieval. To find an ID from a name, use the search endpoint first.
Every format is accepted for search and lookup.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | Indiana Business ID (as registered) | `183025-143` | `company.identifiers`, all entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–250 chars | `"Eli Lilly and Company"` | Contains | Multiple results |
| By Business ID | ID format | `183025-143` | Exact | Exact match returned first (matchType: id); other results may follow |
Name search supports contains-matching across all registered entity names.
Business ID search locates a single entity by its exact identifier and is
the recommended path when the ID is known.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No bulk data** | Indiana does not offer bulk corporate data exports. Every lookup is resolved live against the register portal. |
| **No shareholders** | Indiana does not publish shareholder or ownership information at the state level. |
| **No activity codes** | Industry classification codes (NAICS / NACE) are not collected at the state level. |
| **Governing persons paginated** | The portal renders governing persons across multiple pages. All pages are retrieved and returned. |
| **Registered agent as OtherKeyPerson** | The registered agent is returned under `otherKeyPersons` with role `Registered Agent`. |
| **No formation jurisdiction for foreign entities** | The jurisdiction of formation is not consistently shown for foreign entities on the public portal. |
## Mappings
### Company Status
Status is read from the entity status field on the detail page.
| Source Value | Active |
| - | - |
| Active | true |
| Admin Dissolved | false |
| Cancelled | false |
| Expired | false |
| Inactive | false |
| Judicially Dissolved | false |
| Merged | false |
| Revoked | false |
| Voluntarily Dissolved | false |
| Withdrawn | false |
### Legal Forms
Indiana entity types are published in plain English on the portal. The 35 distinct values cover domestic and foreign formations across all major entity classes.
**Domestic entities:**
| Indiana Type | Standardized |
| - | - |
| Domestic For-Profit Corporation | Corporation |
| Domestic Benefit Corporation | Corporation |
| Domestic Professional Corporation | Corporation |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Domestic Limited Liability Company | Limited Liability Company |
| Domestic Master LLC | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Domestic Limited Liability Partnership | Partnership |
| Domestic Business Trust | Trust |
| Domestic Agricultural Coop | Cooperative |
Foreign entities follow the same pattern with a "Foreign" prefix.
Known governing-person titles use fixed translations and standardized values from the published role list. Compound titles keep their complete original wording. The register's governing-person list does not report company-specific signing powers, so a title does not establish sole or joint authority.
### Other Key Persons
The registered agent and formation-only incorporator appointments are returned as `OtherKeyPerson` entries. Indiana identifies whether the registered agent is an individual or a corporate registered agent. An incorporator appointment records formation work, not current general signing powers.
| Role | Standardized | Notes |
| - | - | - |
| Registered Agent | `Registered Agent` | Always present when declared on the portal |
| Incorporators | `Other` | Formation-only appointment when recorded |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Legal name | Yes | |
| Entity type / legal form | Yes | AI-standardized |
| Status | Yes | AI-enriched with `statusDetails` |
| Formation date | Yes | |
| Principal address | Yes | Geocoded with fallback to structured address |
| Governing persons | Yes | All pages fetched |
| Registered agent | Yes | Individual or corporate |
| Shareholders | No | Not published by Indiana SoS |
| UBO | No | No state-level register; federal BOI records are not public |
| Activity codes | No | Not collected at state level |
## Documents
### Trade Register Extract
A server-generated PDF of the entity's detail page. Includes the entity's legal name, entity number, type, status, formation date, principal address, registered agent, and governing persons.
| Property | Value |
| - | - |
| Format | PDF |
| Source | Indiana Secretary of State portal |
| TTL | 1 day |
### Certified Copy
A Secretary-of-State-signed PDF containing the full filing history for the entity, with a certification date, entity name, and a validation URL. Valid for 30 days from issue.
Certified copies are offered in filing-type-scoped variants. Only variants for which the entity has filings with content are advertised.
| Filing Type Variant | Available When |
| - | - |
| Certified Copy — Articles of Incorporation | Entity has filings of this type |
| Certified Copy — Business Entity Report | Entity has filings of this type |
| Certified Copy — Articles of Amendment | Entity has filings of this type |
| Property | Value |
| - | - |
| Format | PDF |
| Source | Indiana Secretary of State portal |
| TTL | 25 days |
## Retrieval Modes
Indiana company data is available in two modes at the same price. **Both return the same company details and the complete list of governing persons** — they differ only in post-processing:
| | Prefill (`mode: prefill`) | Verification (default) |
| - | - | - |
| Governing persons | Complete list | Complete list |
| Officer roles | Original titles with published values for known labels | Known labels use the same published values; unknown labels may be AI-standardized |
| Addresses (company + officers) | As filed (street, city, ZIP) | Geocoded — normalized, with `latitude` / `longitude` |
| Typical latency | Faster | Slower |
Use **prefill** for fast lookups with as-filed addresses and known role values. Use **verification** for geocoded addresses and enrichment of role labels outside the published list.
## Example API Responses
The Company Profile, Legal Representative, and Other Key Person examples below are in **verification** mode (standardized roles, geocoded addresses). See [Prefill vs Verification](#prefill-vs-verification) for the same data in prefill mode.
### Company Profile: Domestic For-Profit Corporation
```json theme={null}
{
"company": {
"id": "183025-143",
"countryCode": "US-IN",
"legalName": "ELI LILLY AND COMPANY",
"registrationDate": "1901-01-17",
"status": {
"localName": "Active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Domestic For-Profit Corporation",
"englishTranslation": "Domestic For-Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "LILLY CORPORATE CENTER",
"city": "Indianapolis",
"region": "IN",
"postalCode": "46285",
"countryCode": "US",
"latitude": 39.757,
"longitude": -86.152
}
}
}
```
### Legal Representative: Governing Person
```json theme={null}
{
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Chair, President, and Chief Executive Officer",
"englishTranslation": "Chair, President, and Chief Executive Officer",
"standardized": "Chief Executive Officer"
},
"individual": {
"name": { "fullName": "David Ricks" }
}
}
]
}
```
### Other Key Person: Registered Agent (Corporate)
```json theme={null}
{
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"legalName": "NATIONAL REGISTERED AGENTS, INC.",
"legalAddress": {
"addressLine1": "334 North Senate Avenue",
"city": "Indianapolis",
"region": "IN",
"postalCode": "46204",
"countryCode": "US"
}
}
}
]
}
```
### Prefill vs Verification
The same governing person returned in each mode. Both modes return every governing person; **prefill** keeps addresses as filed, while **verification** adds a geocoded address. Both modes use the same published role value for this known title.
```json theme={null}
{
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Chair, President, and Chief Executive Officer",
"englishTranslation": "Chair, President, and Chief Executive Officer",
"standardized": "Chief Executive Officer"
},
"individual": {
"name": { "fullName": "David Ricks" },
"residenceAddress": {
"addressLine1": "Lilly Corporate Center",
"city": "INDIANAPOLIS",
"region": "IN",
"postalCode": "46285",
"countryCode": "US"
}
}
}
]
}
```
```json theme={null}
{
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Chair, President, and Chief Executive Officer",
"englishTranslation": "Chair, President, and Chief Executive Officer",
"standardized": "Chief Executive Officer"
},
"individual": {
"name": { "fullName": "David Ricks" },
"residenceAddress": {
"city": "Indianapolis",
"region": "Marion County",
"state": "Indiana",
"countryCode": "US",
"latitude": 39.7576,
"longitude": -86.1522
}
}
}
]
}
```
The `countryCode` is parsed from the registered address — it is not assumed to be `US`. An entity with a non-US address (e.g. a foreign parent) returns that country, or no `countryCode` when it cannot be determined.
# Iowa
Source: https://docs.topograph.co/essentials/us-iowa
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Iowa reference is on the [Iowa country page](https://www.topograph.co/countries/us-ia).
## Start here
This guide contains public integration notes for Iowa. Use it for identifier formats, search behavior, and state-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Data Availability](#data-availability)
## Data Sources
Iowa has two complementary integrations against the **Iowa Secretary of State, Business Services Division**.
* **Active Iowa Business Entities open-data extract** (fast, non-authoritative). A monthly snapshot published at `data.iowa.gov`. Covers approximately 339,000 active domestic and foreign entities: legal name, entity type, registration date, principal-office address, and registered agent. Officers and directors are not included in this extract. Used for sub-second prefill lookups.
* **Iowa SoS business search portal** (authoritative). A live read from the `sos.iowa.gov` public business search. Returns authoritative entity status, the full officer roster (Name, role, Director flag, and address for each officer), the verified principal-office address, and the registered agent. Covers all entities in the Iowa register, including the approximately 265,000 dissolved, terminated, or withdrawn entities that are absent from the monthly open-data extract. The [Trade Register Extract](#data-availability) (a printed PDF of the SoS entity summary page) is bundled with this tier at no extra charge.
**Mode-based routing.** Prefill requests (`mode: "prefill"`) are served from the monthly open-data extract (fast, no live status, no officers). Verification requests (`mode: "verification"`) read the Iowa SoS portal live for authoritative status, the full officer roster, and the Trade Register Extract. Dissolved or terminated entities are only reachable through verification mode.
**Active-only open-data extract.** The monthly Iowa SoS open-data dataset covers only active entities (\~339k of approximately 600k total). Entities that have dissolved, terminated, merged, or withdrawn are removed from the feed rather than tagged. They are invisible in prefill mode and only resolvable through verification mode.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Iowa Business Entity Number** | 6 digits, numeric only, leading zeros preserved | `084726` | Assigned by the Iowa Secretary of State, Business Services Division. |
The canonical Iowa Business Entity Number is 6 digits with leading zeros. Shorter numeric input (e.g. `84726`) is zero-padded automatically to `084726`. Input that is not numeric or is longer than 6 digits is rejected.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `corpNumber` | 6 digits, zero-padded | `084726` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Hy-Vee"` | Starts-with (case-insensitive) | Multiple results, capped at 50 |
| By Iowa Business Entity Number | 6 digits | `019862` | Exact | Exact match returned first (`matchType: id`) |
**Name search anchors on the beginning of the legal name.** Use fuller query strings to narrow the result set. Inactive entities are not present in the open-data index and are surfaced through the live portal fallback. For complete coverage by name (including dissolved entities), use verification mode.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Leading zeros are part of the number** | Iowa Business Entity Numbers are 6 digits with leading zeros. Responses always return the padded form (`084726`); shorter numeric input such as `84726` is zero-padded before lookup. |
| **Prefill mode returns no officers** | The monthly open-data extract does not include officer or director information. Officers, Director flags, and per-officer addresses are available only in verification mode via the live SoS portal. |
| **Active-only extract misses \~265k entities** | The open-data dataset is an active-only snapshot. Dissolved, terminated, merged, and withdrawn entities are excluded. Verification mode is the only path to reach them. |
| **No shareholder or UBO register** | Iowa does not publish shareholders or beneficial owners for any entity type. The SoS portal has no shareholder or UBO section. |
| **No activity codes** | Industry classification codes (NAICS, NACE, ISIC) are not collected by the Iowa Business Services Division. |
| **"Doing business as" names are county-level** | DBA filings in Iowa are recorded at the county recorder level and are not aggregated in the state-level open-data dataset. Fictitious names filed with the Secretary of State appear on the live portal but are not returned as a separate datapoint. |
| **Officer Director flag** | The live SoS portal includes a separate Director (Yes/No) column on each officer record. The flag is preserved in the local role title; an office-only director is an other key person. |
## Mappings
### Legal Forms
Iowa legal form is sourced from the corporation type published in the Iowa Secretary of State open-data dataset and the live portal. The vocabulary is a closed set of 32 values drawn from the Iowa Code, covering entity types across Title XII (Business Entities) and associated chapters. Each value is mapped to a standardized Topograph category and, where available, an ISO 20275 ELF code.
The full searchable table of all 32 Iowa legal forms with standardized mappings and ISO 20275 codes is available on the [Iowa pricing page](https://topograph.co/pricing/us-ia).
| Iowa Corporation Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Limited Liability Company | Limited Liability Company | `7XPF` |
| Foreign Limited Liability Company | Limited Liability Company | |
| Domestic For-Profit Corporation | Corporation | |
| Foreign For-Profit Corporation | Corporation | |
| Revised Domestic Nonprofit Corporation (Ch. 504) | Nonprofit Organization | |
| Revised Foreign Nonprofit Corporation (Ch. 504) | Nonprofit Organization | |
| Domestic Professional LLC | Limited Liability Company | |
| Domestic Limited Liability Partnership | Partnership | `7XPF` |
| Domestic Limited Partnership | Partnership | `HPKC` |
| Domestic Cooperative | Cooperative | |
| Iowa Corporation Type | Standardized |
| - | - |
| Foreign Professional LLC | Limited Liability Company |
| Domestic Professional Corporation | Corporation |
| Foreign Professional Corporation | Corporation |
| Farm Corporation (non-registered) | Corporation |
| Revised Uniform Unincorporated Nonprofit Association | Nonprofit Organization |
| General Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic Limited Liability Limited Partnership | Partnership |
| Foreign Limited Liability Limited Partnership | Partnership |
| County General Partnership | Partnership |
| Cooperative Association, Non-Stock (Ch. 498) | Cooperative |
| Cooperative Association, Capital Stock (Ch. 497) | Cooperative |
| Cooperative Association, Value-Added | Cooperative |
| Cooperative Association, Non-Profit | Cooperative |
| Foreign Cooperative | Cooperative |
| Multiple Housing Cooperative (Ch. 499A) | Cooperative |
| Domestic Bank (Ch. 524) | Other |
| Domestic Savings & Loan Association (Ch. 534) | Other |
| Insurance Company (Ch. 508-515) | Other |
| County and City Authority | Government-Owned Entity |
| Federal Filing (not under Iowa chapter) | Other |
## Person Roles
Known titles have fixed English and standardized meanings. A combined title such as `President / Director` retains the officer meaning and the register’s director flag. Office-only directors are other key persons with standardized `Board Member`.
Ordinary members and incorporators are other key persons with standardized `Other`. Membership alone gives no agency power, and officer functions depend on bylaws or board directions. No sole or joint signing mode is inferred.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Verification only | Active / Inactive / dissolution category, read live from the SoS portal. Prefill mode (open-data extract) covers active entities only. |
| Registration date | Yes | Iowa SoS initial filing date |
| Legal address | Yes | Principal-office address (street, city, state, ZIP) |
| Legal form | Yes | Closed 32-value Iowa Code vocabulary with ISO 20275 mapping where available |
| Legal representatives | Verification only | Officer and manager titles with names, Director flags and addresses from the live portal. Office titles do not establish unrestricted signing powers. |
| Registered agent | Yes | Included in both the prefill extract and verification mode |
| Trade Register Extract | Verification only | Printed PDF of the Iowa SoS entity summary page, bundled with the verification profile at no extra charge |
| Activity codes | No | Not collected by the Iowa Business Services Division |
| Shareholders | No | Not published |
| UBOs | No | No state-level beneficial ownership register |
| Financial data | No | Not collected |
| DBA / fictitious names | No | Filed at county recorder level; not in the state open-data dataset |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-IA&query=Acme+Industries" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "084726",
"legalName": "ACME INDUSTRIES LLC",
"countryCode": "US-IA",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "IA",
"countryCode": "US"
}
}
]
```
### Search by Iowa Business Entity Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-IA&query=084726" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "084726",
"legalName": "ACME INDUSTRIES LLC",
"countryCode": "US-IA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile (prefill, fast, active entities)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-IA", "id": "084726", "dataPoints": ["company"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "084726",
"countryCode": "US-IA",
"identifiers": { "corpNumber": "084726" },
"legalName": "ACME INDUSTRIES LLC",
"registrationDate": "2005-03-15",
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Des Moines",
"region": "IA",
"postalCode": "50309",
"countryCode": "US"
}
}
}
```
### Company Profile (verification, authoritative, includes officers)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-IA", "id": "084726", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "084726",
"countryCode": "US-IA",
"identifiers": { "corpNumber": "084726" },
"legalName": "ACME INDUSTRIES LLC",
"registrationDate": "2005-03-15",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Des Moines",
"region": "IA",
"postalCode": "50309",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "President / Director"
},
"individual": {
"name": { "fullName": "Jane Smith" }
}
}
]
}
```
# Kansas
Source: https://docs.topograph.co/essentials/us-kansas
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Kansas reference is on the [Kansas country page](https://www.topograph.co/countries/us-ks).
## Start here
This guide contains public integration notes for Kansas. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Company Statuses](#company-statuses)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
Kansas uses a single integration against the **Kansas Secretary of State Business Entity Search Station** (`sos.ks.gov`), maintained by the Business Services Division. The register covers every domestic and foreign entity filed under the Kansas General Corporation Code (K.S.A. Chapter 17) and the Limited Liability Company Act (K.S.A. Chapter 17, Article 76): for-profit and not-for-profit corporations, LLCs (including series and professional variants), limited partnerships, limited liability partnerships, and business trusts.
* **Kansas Secretary of State Business Entity Search Station** (live, authoritative). The public portal is queried in real time for every request. It exposes legal name, Business ID, entity type, formation date, jurisdiction, current status, principal office address, resident agent name and address, last reporting year, next report due date, forfeiture date when applicable, and the full filing history.
**Single live source.** Kansas does not publish a bulk download or open-data feed of the business register, so every request is served from the live portal. Because that read is fast, both prefill and verification modes return the same authoritative data — there is no separate non-authoritative cache tier.
**Portal reliability.** The Kansas Secretary of State portal may be temporarily unavailable during maintenance windows or periods of high load. The `flakySource` caveat on the data block reflects this. Failed requests are not billed.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Kansas SoS Business ID** | Numeric, no dashes or spaces. 6 to 8 digits in the records we have seen, no leading zero (e.g. `602771`, `10049404`) | `6749200` | Assigned by the Kansas Secretary of State. Distinct from the Federal Employer Identification Number (FEIN). |
The Kansas Business ID is purely numeric. The portal rejects dashes, spaces, and any non-digit characters. Strip any formatting before passing the identifier to the API.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `businessId` | Numeric string, 6 to 8 digits observed | `6749200` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Garmin"` | Contains (case-insensitive) | Up to 100 results |
| By Kansas SoS Business ID | Numeric string | `1749480` | Exact | Single result (matchType: id) |
**Name search is contains-match.** Queries match anywhere in the legal name, case-insensitively. Results are capped at 100. Use a more specific query string to narrow the result set.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Numeric Business ID only** | The Kansas SoS Business ID is always a numeric string with no dashes or spaces. Non-digit characters are rejected. It is distinct from the Federal Employer Identification Number. |
| **No bulk / open-data feed** | Kansas does not publish a Socrata, CSV, or API bulk download of the business register. Every request hits the live portal. |
| **Officers not on the public detail page** | Officers and directors are filed on the Kansas annual information report (Form IFP) but are not surfaced as a structured datapoint on the public Business Entity Search Station. They are not available via the API. |
| **Resident agent is an other key person** | The resident agent name and address are returned under `otherKeyPersons`, not `legalRepresentatives`. The resident agent receives service of process but does not have authority to bind the entity. |
| **No activity codes** | Industry classification codes (NAICS / NACE / ISIC) are not collected by the Kansas Secretary of State. |
| **No shareholders or UBOs** | Shareholder lists and LLC member names are not collected by the register. Kansas does not maintain a public beneficial-ownership register. Federal FinCEN BOI records are restricted. |
| **Sole proprietorships and DBAs excluded** | Sole proprietorships, doing-business-as filings, assumed names, fictitious names, and trade names do not file with the Kansas Secretary of State and are not indexed for search. |
| **Certificate of Good Standing is a paid upgrade** | The official Kansas Certificate of Good Standing is available as a paid document (see [pricing](https://topograph.co/pricing/us-ks)). The Trade Register Extract is included with the company data at no extra charge. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type label published by the Kansas Secretary of State Business Entity Search Station. The taxonomy is a closed enum based on entity types registered under K.S.A. Chapter 17 (Kansas General Corporation Code) and K.S.A. Chapter 17, Article 76 (Limited Liability Company Act).
The full list of legal forms with ISO 20275 mappings is available on the [pricing page](https://topograph.co/pricing/us-ks). The table below shows the most common forms.
| Kansas Entity Type | Standardized | ISO 20275 |
| - | - | - |
| For-Profit Corporation | Corporation | `GCU5` |
| Professional Association | Corporation | |
| Public Benefit Corporation | Corporation | |
| Not-For-Profit Corporation | Nonprofit Organization | `FEC4` |
| Foreign For-Profit Corporation | Corporation | |
| Foreign Not-For-Profit Corporation | Nonprofit Organization | |
| Limited Liability Company | Limited Liability Company | `FBN0` |
| Series Limited Liability Company | Limited Liability Company | |
| Professional Limited Liability Company | Limited Liability Company | |
| Public Benefit Limited Liability Company | Limited Liability Company | |
| Foreign Limited Liability Company | Limited Liability Company | |
| Limited Partnership | Partnership | `XQEC` |
| Foreign Limited Partnership | Partnership | |
| Limited Liability Partnership | Partnership | |
| Foreign Limited Liability Partnership | Partnership | |
| General Partnership | Partnership | |
| Business Trust | Other | |
| Foreign Business Trust | Other | |
### Company Statuses
Status is read directly from the Kansas Secretary of State Business Entity Search Station and reflects the entity's current lifecycle state under K.S.A. Chapter 17.
| Status | Notes |
| - | - |
| Active And In Good Standing | Current on annual reports; no outstanding obligations |
| In Good Standing | Variant of the active / good-standing state |
| Active | Active without explicit good-standing qualification |
| Forfeited - Failed To Timely File AR | Annual report delinquency; entity has forfeited its rights to do business |
| Forfeited | General forfeiture state |
| Dissolved | Voluntarily or administratively dissolved |
| Cancelled | Applicable to partnerships and similar forms |
| Merged | Entity merged into another |
| Withdrawn | Foreign entity withdrew its registration |
| Inactive | No longer active; catch-all for legacy records |
## Statutory Filings
Kansas entities file an annual report confirming the entity's particulars are current. The register publishes "Next Report Due Date" and "Last Reporting Year", returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate` and `lastFiled.year`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "dueDate": "2026-08-15" },
"lastFiled": { "year": 2025 },
"source": "ks_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name as registered with the Kansas SoS |
| Company status | Yes | Live status from the Business Entity Search Station |
| Registration date | Yes | Formation date as filed with the Kansas SoS |
| Jurisdiction | Yes | State or country of domicile for foreign entities |
| Legal address | Yes | Principal office address |
| Legal form | Yes | Closed 18-value Kansas SoS taxonomy with ISO 20275 mapping where available |
| Resident agent | Yes | Returned as an other key person (name and address) |
| Legal representatives (officers) | No | Filed on the annual information report but not on the public detail page |
| Activity codes | No | Not collected by the Kansas SoS |
| Shareholders | No | Not published |
| UBOs | No | Not published |
| Trade Register Extract | Yes | Free printable record of the entity, included with the company data |
| Certificate of Good Standing | Yes | Paid document; official Kansas Certificate of Good Standing (register fee applies) |
| Financial data | No | Not collected |
| Fictitious names (DBAs) | No | Not filed with the Kansas SoS |
For the full datapoint catalog, document list, and live pricing, see the [Kansas pricing page](https://topograph.co/pricing/us-ks).
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-KS&query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-KS",
"matchReason": {
"matchType": "default"
},
"address": {
"countryCode": "US-KS"
}
}
]
```
### Search by Business ID
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-KS&query=1234567" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-KS",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-KS", "id": "1234567", "mode": "prefill", "dataPoints": ["company", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "1234567",
"countryCode": "US-KS",
"identifiers": { "businessId": "1234567" },
"legalName": "ACME HOLDINGS LLC",
"registrationDate": "2015-03-14",
"status": { "localName": "Active and in Good Standing", "active": true },
"legalForm": {
"localName": "Limited Liability Company",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "FBN0"
},
"legalAddress": {
"addressLine1": "123 Placeholder St",
"city": "TOPEKA",
"region": "KS",
"postalCode": "66612",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Resident Agent", "standardized": "Registered Agent" },
"company": {
"legalName": "SAMPLE REGISTERED AGENTS INC.",
"countryCode": "US-KS",
"legalAddress": {
"addressLine1": "456 Example Ave",
"city": "WICHITA",
"region": "KS",
"postalCode": "67202",
"countryCode": "US"
}
}
}
]
}
```
The resident agent is returned as an individual (`type: "individual"`, under `individual.name.fullName` / `individual.residenceAddress`) when the agent is a natural person, or as a company (`type: "company"`, as shown above) when it is a registered-agent service. `legalRepresentatives` is not a supported datapoint for Kansas and will be rejected if requested.
# Kentucky
Source: https://docs.topograph.co/essentials/us-kentucky
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Kentucky reference is on the [Kentucky country page](https://www.topograph.co/countries/us-ky).
## Start here
This guide contains public integration notes for Kentucky. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Status](#company-status)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
**API access:** `US-KY` is accepted by the API, but it is not yet listed in the request `countryCode` enum of the OpenAPI reference.
## Data Sources
Kentucky data is retrieved live from the **Kentucky Secretary of State, Business Filings & Records** through the public Business Entity Search portal. The register covers every domestic and foreign entity filed under Kentucky Revised Statutes Title XXIII: for-profit and nonprofit corporations, limited liability companies, limited partnerships, business trusts, cooperatives, and assumed names.
Each entity is assigned a seven-digit Organization Number with leading zeros preserved (e.g. `0061792`). The portal exposes legal name, profit/non-profit status, entity type, industry label, employee-count band, primary county, status (Active / Inactive), standing (Good / Bad), state of incorporation, formation and authority dates, last annual report date, principal office, registered agent, the current officer roster, founding officers (including the incorporator for domestic corporations), assumed names, former names, and the full filing history. Scanned images of filings submitted on or after 15 September 2004 are published as downloadable PDFs.
**Single-tier integration.** All lookups read the live register. There is no separate fast / non-authoritative mode.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Kentucky Organization Number** | 7 digits, leading zeros included, no prefix or separators | `0061792` | Primary identifier assigned by the Kentucky Secretary of State. A number sent without its leading zeros (`61792`) is padded to 7 digits. |
The Organization Number is zero-padded to exactly seven digits. One Organization Number is shared across the entity's main registration and any assumed-name (DBA) filings. Search by org number returns only the main filing. The API returns the main filing's record and never returns a DBA as a separate company. Assumed names are not included in the company data; they are listed on the Trade Register Extract.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `organizationNumber` | 7 digits, leading zeros included | `0061792` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Papa Johns"` | Starts-with (case-insensitive) | Multiple results |
| By Organization Number | 1 to 7 digits, zero-padded | `0061792` | Exact | The main filing only (`matchType: id`); assumed-name filings sharing the same org number are not returned |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use a fuller query string to narrow the result set, which is capped at 50 matches.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **One org number, many filings** | A single Organization Number is shared by the entity's main registration and every assumed-name (DBA) filing. The API returns the main legal entity only. Never use the org number as a unique filing key. |
| **Zero-padding is normalised** | Organization Numbers are always 7 digits. Input without leading zeros (`61792`) is padded, so it resolves to the same entity as `0061792`. |
| **Status has two dimensions** | The register records both a Status (`A - Active` / `I - Inactive`) and a Standing (`G - Good` / `B - Bad`). The API returns Status as the active/inactive flag. Standing is not returned in the API response; it appears only in the Trade Register Extract. |
| **No shareholder or UBO register** | Kentucky Secretary of State filings do not publish shareholder lists, capital structure, or beneficial ownership data for any entity type. Federal FinCEN beneficial ownership records are restricted and not accessible publicly. |
| **No standardised activity codes** | The register exposes a coarse industry label (e.g. "Miscellaneous Manufacturing Industries") but no NAICS, NACE, or ISIC codes. Tax IDs and EINs are also not published. |
| **Assumed names are not separate companies** | DBA / assumed-name registrations share the parent entity's Organization Number. They are not returned as independent company results, and are not included in the company data. The Trade Register Extract lists them. |
| **Founding officers appear separately** | Initial officers (the people named at formation, including the incorporator for domestic corporations) are returned as other key persons, not as current legal representatives. |
| **Filing scans start from 2004** | Scanned documents cover filings submitted on or after 15 September 2004. Earlier documents are paper records available only by request from the register. |
| **Certificate of Existence is not yet offered** | The Certificate of Existence / Authorization (KRS 14A.2-130) is not currently available through Topograph. |
## Mappings
### Legal Forms
Legal form is sourced from the Company Type field on the Kentucky SoS portal. The vocabulary uses three-letter codes with expanded display names.
| Portal Code | Display Name | Standardized | Notes |
| - | - | - | - |
| `KCO` | Kentucky Corporation | Corporation | Domestic for-profit corporation |
| `FCO` | Foreign Corporation | Corporation | Out-of-state corporation registered in KY |
| `KLC` | Kentucky Limited Liability Company | Limited Liability Company | Domestic LLC |
| `FLC` | Foreign Limited Liability Company | Limited Liability Company | Out-of-state LLC registered in KY |
| `ASN` | Assumed Name Corporation | Other | DBA filing for a corporation; same org number as the parent |
| `ASL` | Assumed Name for LLC | Other | DBA filing for an LLC; same org number as the parent |
The codelist above reflects entity types observed during integration. The Kentucky register includes additional entity types (limited partnerships, business trusts, cooperatives, nonprofits, and others). Unrecognised codes are preserved verbatim with a standardized fallback of `Other`.
### Officer Roles
Current officers are returned as legal representatives. The portal publishes a small vocabulary of titles; the titles below are mapped to a standardized Topograph role. Any other title (including `Officer`) is returned with its `localName` only.
| Portal Title | Standardized Role |
| - | - |
| President | President |
| Vice President | Vice President |
| Secretary | Secretary |
| Treasurer | Treasurer |
| Director | Director |
| Manager | Manager |
| Managing Director | Managing Director |
| Chairman | Chairman |
| Chairman of the Board | Chairman of the Board |
| Chief Executive Officer / CEO | Chief Executive Officer |
| Chief Financial Officer / CFO | Chief Financial Officer |
| Chief Operating Officer / COO | Chief Operating Officer |
| General Partner | General Partner |
| Managing Partner | Managing Partner |
| Limited Partner | Limited Partner |
| Partner | Partner |
| Authorized Signatory | Authorized Signatory |
| Owner | Owner |
| Liquidator | Liquidator |
| Administrator | Administrator |
| Receiver | Receiver |
| Officer | Not returned |
Founding officers (including the incorporator for domestic corporations) are returned as other key persons with the `Incorporator` local name, not as legal representatives. The registered agent is also returned as an other key person.
### Company Status
| Portal Value | Active Flag |
| - | - |
| `A - Active` | `true` |
| `I - Inactive` | `false` |
Standing (Good / Bad) is a separate register field. It is not returned in the API response and appears only in the Trade Register Extract.
## Statutory Filings
Kentucky entities file an annual report confirming the entity's particulars are current. The register publishes "Last Annual Report", the date the report was received, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `lastFiled.filedOn`. No forward-looking due date is published.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"lastFiled": { "filedOn": "2025-06-12" },
"source": "ky_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Yes | Active / Inactive, read from the live portal |
| Standing | Trade Register Extract only | Good / Bad, as reported by the register; not in the API response |
| Registration date | Trade Register Extract only | Date filed in Kentucky; not in the API response |
| Authority date | Trade Register Extract only (foreign) | Date the foreign entity was authorized to transact in KY; not in the API response |
| Organization date | Trade Register Extract only (domestic) | Date the domestic entity was originally organized; not in the API response |
| Legal address | Yes | Principal office address (street, city, state, ZIP) |
| Legal form | Yes | Portal Company Type, standardized |
| Legal representatives | Yes | Current officers (President, Secretary, Treasurer, Director, and other titles) |
| Other key persons | Yes | Registered agent; founding officers including the incorporator |
| Assumed names (DBAs) | Trade Register Extract only | Assumed names and their expiration dates; not in the API response |
| Former names | Trade Register Extract only | Prior legal names from amendments; not in the API response |
| Last annual report date | Yes | Date of the most recent annual report on file |
| State of incorporation | Trade Register Extract only | Not in the API response |
| Employee count band | Trade Register Extract only | Coarse bucket as published by the register; not in the API response |
| Primary county | Trade Register Extract only | Kentucky county where the principal office is located; not in the API response |
| Industry label | Yes | Returned as `activityDescription` when filed; the register does not provide a verified numeric classification or revision |
| Activity codes | No | Not published by the register in a standardized format |
| Registered agent address | Yes | Included in other key persons |
| Shareholders | No | Not published |
| UBOs | No | Not published; federal FinCEN records are restricted |
| Tax ID / EIN | No | Not exposed in the public business register |
| Financial data | No | Not collected |
| Trade Register Extract | Yes | A printable summary of the live business entity record, included at no extra charge when purchasing company data |
| Annual Report PDF | Yes | The latest Annual Report PDF, published by the register; available as a separate document |
| Certificate of Existence / Authorization | No (roadmap) | Not currently offered |
| Pre-2004 document scans | No | Paper records; must be ordered directly from the register |
## Example API Responses
### Search by Name
```bash theme={null}
curl -G "https://api.topograph.co/v2/search" \
--data-urlencode "country=US-KY" \
--data-urlencode "query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0012345",
"legalName": "ACME MANUFACTURING LLC",
"countryCode": "US-KY",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by Organization Number
```bash theme={null}
curl -G "https://api.topograph.co/v2/search" \
--data-urlencode "country=US-KY" \
--data-urlencode "query=0012345" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0012345",
"legalName": "ACME MANUFACTURING LLC",
"countryCode": "US-KY",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-KY", "id": "0012345", "dataPoints": ["company", "legalRepresentatives"]}'
```
```json theme={null}
{
"company": {
"id": "0012345",
"countryCode": "US-KY",
"identifiers": { "organizationNumber": "0012345" },
"legalName": "ACME MANUFACTURING LLC",
"status": { "localName": "A - Active", "active": true },
"legalForm": {
"localName": "Kentucky Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"city": "Louisville",
"region": "KY",
"postalCode": "40201",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"individual": { "name": { "fullName": "Jane Example" } },
"role": { "localName": "President", "standardized": "President" }
}
]
}
```
# Louisiana (US)
Source: https://docs.topograph.co/essentials/us-louisiana
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Louisiana (US) reference is on the [Louisiana (US) country page](https://www.topograph.co/countries/us-la).
## Start here
This guide contains public integration notes for Louisiana. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Entity Types](#entity-types)
* [Officer Roles](#officer-roles)
* [Status](#status)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
**API access:** `US-LA` is accepted by the API, but it is not yet listed in the request `countryCode` enum of the OpenAPI reference.
## Data Sources
Louisiana data comes from the **Louisiana Secretary of State, Commercial Division**. This is the official register of business filings for the state. It covers domestic and foreign corporations (Title 12 of the Louisiana Revised Statutes), limited liability companies, limited and general partnerships, trade names and trademarks, name reservations, and historical name records.
* **Prefill** (fast, non-authoritative). Answers from a regularly refreshed copy of the register's business-name index: legal name, Charter Number, status (active / inactive) and city. Legal representatives and registered agents come back empty in this mode, and shareholders are not available.
* **Verification** (authoritative). Each query reads live against the register and returns the legal name, Charter Number, entity type, current status with the inactivation reason when applicable, the registration date, the registered agent or agents with their address, the officer roster preserved as filed, owners for member-managed LLCs and registered partnerships, and one entity address chosen from the address types Louisiana publishes (Domicile, Mailing, Principal Business Office, Registered Office in Louisiana, Principal Business Establishment in Louisiana).
Sole proprietors and most general partnerships file at the parish (county) level and are out of scope at the state level. Trade names ("DBA") and trademarks are searchable on the same portal but are not full business entities. They appear in search results but are not returned as company profiles.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Louisiana Charter Number** | 8 digits followed by one uppercase letter (9 characters), leading zeros included | `29504510F` | No separators. The register documents this shape and requires all 9 characters for a lookup (e.g. `36528934K`, `03002150N`). |
The Charter Number is shown on every page of the CORAweb portal as `Charter Number:`. It is the single primary identifier. Louisiana does not assign a separate state-level tax ID, NAICS code, or other public identifier we expose.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `charterNumber` | 8 digits + one uppercase letter | `29504510F` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Louisiana Charter Number | 8 digits + one letter (all 9 characters) | `29504510F` | Exact | Exact match returned first (matchType: id); other results may follow |
| By name | 2–200 characters | `"Walmart"` | Substring (case-insensitive) | Up to 10 |
Name search returns up to 10 matches, each with its Charter Number. "Previous Name" and "Trade Name" rows are filtered out because they route to the same underlying entity and would duplicate the real result.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Charter Number suffix is significant** | Most active filings have a single trailing letter (e.g. `29504510F`, `36528934K`). Older records may not. The suffix is part of the identifier and must be preserved in queries. |
| **Five distinct address types** | Louisiana publishes Domicile, Mailing, Principal Business Office, Registered Office in Louisiana, and Principal Business Establishment in Louisiana. The first three reflect the entity's filing wherever incorporated; the last two are mandatory for any entity registered to do business in Louisiana. The API returns the most operationally relevant one as `legalAddress`. |
| **Inactivation carries a reason** | When an entity is `Inactive`, the register also exposes a free-form `Inactive Reason` (e.g. "Action By Secretary of State", "Revoked"). The reason is folded into the status `localName` so customers see both the state and the cause. |
| **Officer titles preserved as filed** | Louisiana files officer roles as comma-separated titles (e.g. `President, Director`, `Executive Vice-President, Secretary`). Roles are returned verbatim. LLCs typically use `Member` or `Manager` instead of the corporate vocabulary. |
| **Previous name history** | When an entity changes its legal name, the prior name(s) are kept on the public record with a change date. |
| **Owners for some entity types only** | Louisiana publishes the members of member-managed LLCs and the partners of registered partnerships. They are returned as `shareholders` in verification mode, with no ownership percentage (a sole member or sole partner is reported at 100%). Corporations and manager-managed LLCs publish no owners, so the datapoint returns an explanatory error for them. There is no beneficial-ownership register at the state level, and federal FinCEN records are restricted. |
| **No industry classification** | The Commercial Division does not collect NAICS, NACE, or ISIC codes. |
| **Apostilles are not orderable online** | Apostilled certificates require a phone order through the Commercial Division (225.925.4704). They are not part of this integration. |
## Mappings
### Entity Types
The register publishes the entity type as a label. The labels and their standardized mapping are stable.
| CORAweb Label | Standardized Form | Active in this dataset |
| - | - | - |
| Business Corporation | Corporation | Yes |
| Business Corporation (Non-Louisiana) | Corporation | Yes |
| Limited Liability Company | Limited Liability Company | Yes |
| Limited Liability Company (Non-Louisiana) | Limited Liability Company | Yes |
| Partnership | Partnership | Yes |
| Partnership (Non-Louisiana) | Partnership | Yes |
| Limited Partnership | Partnership | Yes |
| Nonprofit Corporation | Nonprofit Organization | Yes |
| Trade Name | Other (trade name) | Listed only |
| Trademark | Other (trademark) | Listed only |
| Previous Name | Other (name history) | Listed only |
The `(Non-Louisiana)` suffix flags foreign entities that are registered to do business in Louisiana but were chartered in another jurisdiction. The data model is the same. The suffix is preserved on the returned `legalForm.localName` so downstream consumers can distinguish them.
### Officer Roles
Louisiana files officer titles as free-form labels and may include multiple titles per officer (comma-separated). The most common values are listed below; less common combinations are preserved verbatim.
| Local Title | Mapped Role |
| - | - |
| President | President |
| Vice-President | Vice-President |
| Executive Vice-President | Vice-President (Executive) |
| Secretary | Secretary |
| Treasurer | Treasurer |
| Director | Board Member (other key person) |
| Officer | Officer |
| Member | Other (LLC member; authority depends on management) |
| Manager | Manager (LLC) |
When an officer holds multiple titles (e.g. `President, Director`), every title is preserved on `legalRepresentative.role.localName`. Each office is classified separately: an executive office can appear in legal representatives while a governing Director office appears in other key persons. Known labels have deterministic English and standardized meanings; unfamiliar titles retain their source text and may use AI enrichment. Corporate office powers depend on bylaws or board authorization. LLC members represent where management is reserved to members; a manager roster routes nonmanaging members to other key persons. No sole or joint signing mode is inferred.
### Status
Louisiana exposes a small set of status values. When an entity is `Inactive`, the API surfaces the cause in `status.localName` (e.g. `Inactive — Action By Secretary of State`).
| Local Status | Active |
| - | - |
| Active | Yes |
| Inactive — Action By Secretary of State | No |
| Inactive — Revoked | No |
| Inactive — Withdrawn | No |
| Inactive — Merged | No |
| Inactive — Dissolved | No |
The `Annual Report Status` (e.g. `In Good Standing`) is also published on the profile when applicable.
## Statutory Filings
Louisiana entities file an annual report confirming the entity's particulars are current. The register publishes "Last Report Filed", returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `lastFiled.filedOn`. No forward-looking due date is published.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"lastFiled": { "filedOn": "2025-04-30" },
"source": "la_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company profile | Yes | Verification: legal name, Charter Number, entity type, status with inactivation reason, registration date, and one entity address as `legalAddress`. Prefill: legal name, Charter Number, status and city. Prior names are not returned in the API response. |
| Registered agent(s) | Yes | Returned as `otherKeyPersons` with the role `registeredAgent`. Includes name and address; the appointment date is not returned. Louisiana allows multiple registered agents per entity. Verification only; empty in onboarding. |
| Legal representatives | Yes | Representing executive and management offices; governing-only directors and nonmanaging members appear in other key persons. Source titles are preserved. Verification only; empty in onboarding. |
| Shareholders | Yes (verification, some entity types) | Members of member-managed LLCs and partners of registered partnerships, with no ownership percentage (a sole owner is reported at 100%). Corporations and manager-managed LLCs return an explanatory error. |
| Ultimate beneficial owners | No | Louisiana does not maintain a public beneficial-ownership register. |
| Activity codes | No | The Commercial Division does not collect NAICS, NACE, or ISIC codes. |
| Trade Register Extract | Yes | Printable PDF of the CORAweb Commercial Search Details page, captured at request time. Included with the company profile at no extra charge. |
| Information Certificate | Yes | Official certified Trade Register Extract issued by the Secretary of State. Paid document, see below. |
| Certificate of Good Standing | Yes | Official certified document confirming the entity exists and is current on its filings and fees. Paid document, see below. |
## Documents
| Document | Format | Certified | Notes |
| - | - | - | - |
| Trade Register Extract | PDF | No | Printable rendering of the public profile, generated at request time. Included with the company profile at no extra charge. |
| Information Certificate | PDF | Yes | Official certified data snapshot (name, Charter Number, type, status, addresses, registered agent, officers), sealed by the Secretary of State as of the issue date. |
| Certificate of Good Standing | PDF | Yes | Official certificate attesting that the entity exists and is current on filings and fees, sealed by the Secretary of State as of the issue date. |
Both certified documents are issued live by the Louisiana Secretary of State and are retrievable for 120 days after issue. The Trade Register Extract is generated on-demand and reflects whatever the public profile shows at the moment of the request.
Certified documents are paid by the Secretary of State per certificate. See the live pricing page for the current rate.
## Example API Responses
Search returns the exact match first by Charter Number (other results may follow), and the profile carries the foreign-chartered Domicile address alongside the Louisiana registered office.
```json theme={null}
{
"id": "29504510F",
"countryCode": "US-LA",
"legalName": "EXAMPLE INC.",
"identifiers": {
"charterNumber": "29504510F"
},
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Business Corporation (Non-Louisiana)",
"standardized": "Corporation"
},
"registrationDate": "1971-07-14",
"legalAddress": {
"addressLine1": "1 EXAMPLE WAY",
"city": "BENTONVILLE",
"region": "AR",
"postalCode": "72716",
"countryCode": "US"
}
}
```
LA preserves multi-title officers as comma-separated `localName`s.
```json theme={null}
{
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "President, Director" },
"individual": {
"name": { "fullName": "JANE EXAMPLE" },
"residenceAddress": {
"addressLine1": "1 EXAMPLE WAY",
"city": "BENTONVILLE",
"region": "AR",
"postalCode": "72716",
"countryCode": "US"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Vice-President, Secretary" },
"individual": {
"name": { "fullName": "JOHN EXAMPLE" }
}
}
]
}
```
Louisiana allows the registered agent to be either an individual or a company. Corporate agents are returned with `type: "company"`.
```json theme={null}
{
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"legalName": "EXAMPLE AGENT SERVICES, INC.",
"countryCode": "US-LA",
"legalAddress": {
"addressLine1": "100 EXAMPLE ST.",
"city": "BATON ROUGE",
"region": "LA",
"postalCode": "70802",
"countryCode": "US"
}
}
}
]
}
```
Inactive entities carry the inactivation reason on `status.localName`.
```json theme={null}
{
"id": "36528934K",
"countryCode": "US-LA",
"legalName": "EXAMPLE LLC",
"identifiers": {
"charterNumber": "36528934K"
},
"status": {
"localName": "Inactive — Action By Secretary of State",
"active": false
},
"legalForm": {
"localName": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"registrationDate": "2007-08-28",
"legalAddress": {
"addressLine1": "100 EXAMPLE RD.",
"city": "EUNICE",
"region": "LA",
"postalCode": "70535",
"countryCode": "US"
}
}
```
All three documents are advertised unconditionally. The certified documents reflect whatever the entity's actual status is at the time of issue.
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"name": "Trade Register Extract",
"format": "pdf"
},
"certifiedTradeRegisterExtract": {
"name": "Information Certificate",
"format": "pdf"
},
"certificateOfGoodStanding": {
"name": "Certificate of Good Standing",
"format": "pdf"
}
}
}
```
# Maine (US)
Source: https://docs.topograph.co/essentials/us-maine
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Maine (US) reference is on the [Maine (US) country page](https://www.topograph.co/countries/us-me).
## Start here
This guide contains public integration notes for Maine. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction is in beta. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Other Key Persons](#other-key-persons)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
Maine uses a single integration against the **Maine Secretary of State, Division of Corporations, UCC & Commissions** via the public **Information Corporate Registry System (ICRS)** at [apps3.web.maine.gov/nei-sos-icrs/ICRS](https://apps3.web.maine.gov/nei-sos-icrs/ICRS). This is the official online register for business corporations, limited liability companies, limited partnerships, limited liability partnerships, and nonprofit corporations registered in Maine, covering both domestic entities and foreign entities qualified to do business in the state.
* **Maine SoS ICRS** (verification, primary). Every request reads live against the register. The Information Summary returns legal name, charter number, filing type, status, filing or qualification date, jurisdiction, assumed and former names, the principal home office address, and the clerk or registered agent name and address.
Every call returns the register's current state.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Charter Number** | 8 or 9 digits followed by a 1 or 2 letter entity-type suffix. A single-letter suffix is preceded by a space (`19340021 D`). A two-letter suffix follows the digits directly (`202509124DC`). | `19970058LP` | The unique, constant identifier the Maine SoS assigns to each entity. Accepted with or without the separating space. |
Both `19340021 D` and `19340021D` resolve to the same entity. The canonical form returned in API responses preserves the space for single-letter suffixes (`19340021 D`) and is flush for two-letter suffixes (`19970058LP`).
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `charterNumber` | 8-9 digits + 1-2 letter suffix | `19970058LP` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"L. L. BEAN"` | Substring (case-insensitive) | Up to 100 |
| By Charter Number | 8-9 digits + 1-2 letter suffix | `19970058LP` | Exact | Single entity |
Name searches return one row per entity-name variant: an entity appears once under its legal name and once per assumed or former name. Results are deduplicated by charter number before being returned, preferring the legal-name row.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Registration-number lookups are filtered; name searches return companies whatever their status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Charter suffix encodes entity type** | Single-letter suffixes (`D`, `F`, `N`) are written space-padded in the official register and in API responses. Two-letter suffixes (`LP`, `DC`, `FC`) are flush. The suffix is informative but the Filing Type field on the entity profile is authoritative for legal form. |
| **Domestic vs foreign** | Foreign entities (those formed outside Maine but qualified to do business in the state) carry one of the suffixes `F`, `NF`, `FC`, `LF` or `FP` and a Filing Type that ends with "doing business in Maine". They use a `qualificationDate` rather than a `registrationDate` in the source. |
| **No officers or directors** | Maine does not publish officer or director rosters on the public register. The only person returned is the clerk or registered agent, surfaced as an `otherKeyPerson` with the role "Clerk / Registered Agent". |
| **Registered agent can be a person or a company** | The agent is returned as `type: "individual"` when the name is a natural person and `type: "company"` when it is a registered-agent service (CT Corporation, Cogency, Northwest Registered Agent, etc.). The mapping is based on common corporate suffixes and service keywords. |
| **No shareholders or beneficial owners** | Shareholder and beneficial-ownership records are not collected at the state level. Federal beneficial-ownership records are restricted and not part of this dataset. |
| **No activity codes** | The Maine SoS does not collect NAICS, NACE, or ISIC industry classifications. |
| **Status is a short closed list** | `GOOD STANDING` is the only active value. Every other observed value (administratively dissolved, dissolved, merged, expired, withdrawn, authority revoked, converted, not in good standing) maps to `active: false`. New status strings introduced by the SoS are surfaced verbatim rather than rejected. |
| **Marks can appear in search** | Trademarks and service marks carry their own charter-number suffix (`M`). They are records in the SoS register but are not companies. They are not filtered out of search results and resolve with the standardized legal form `Other`. |
| **Pre-image-era filings are paper-only** | Filings indexed in the register but flagged as "Image not available" predate digital imaging. Maine offers paper retrieval for these by direct request to the Division. They are intentionally excluded from the available documents list. |
## Mappings
### Company Status
The Status field is read verbatim from the Information Summary. Only `GOOD STANDING` is treated as active. The list below covers the values observed across business corporations, LLCs, limited partnerships, and domestic and foreign nonprofit corporations.
| Local Status | English Translation | Standardized |
| - | - | - |
| GOOD STANDING | In good standing | Active |
| NOT IN GOOD STANDING | Not in good standing | Inactive |
| ADMINISTRATIVELY DISSOLVED | Administratively dissolved | Inactive |
| DISSOLVED | Dissolved | Inactive |
| MERGED | Merged | Inactive |
| EXPIRED | Expired | Inactive |
| WITHDRAWN | Withdrawn | Inactive |
| AUTHORITY REVOKED | Authority to do business revoked | Inactive |
| CONVERTED | Converted to another form | Inactive |
The list is open. A new status value introduced by the Division is returned verbatim as `status.localName`, with `active: false` unless it matches `GOOD STANDING`.
### Legal Forms
The standardized legal form is derived deterministically from the entity-type suffix on the charter number. The local name returned in the API response is the Filing Type string the Information Summary actually displays (for example `BUSINESS CORPORATION DOING BUSINESS IN MAINE` for a foreign business corporation), falling back to the table label when the field is empty.
#### Domestic entities
| Suffix | Local Name | English Translation | Standardized |
| - | - | - | - |
| `D` | Business Corporation | Business Corporation | Corporation |
| `B` | Business Corporation | Business Corporation | Corporation |
| `CP` | Business Corporation | Business Corporation | Corporation |
| `RR` | Railroad Corporation | Railroad Corporation | Corporation |
| `I` | Insurance Corporation | Insurance Corporation | Corporation |
| `DC` | Limited Liability Company | Limited Liability Company | Limited Liability Company |
| `DP` | Limited Liability Partnership | Limited Liability Partnership | Partnership |
| `LP` | Limited Partnership | Limited Partnership | Partnership |
| `ND` | Nonprofit Corporation (Title 13-B) | Nonprofit Corporation | Nonprofit Organization |
| `N` | Nonprofit Corporation (Title 13) | Nonprofit Corporation | Nonprofit Organization |
| `L` | Nonprofit Local Independent Church | Nonprofit Local Independent Church | Nonprofit Organization |
#### Foreign entities
The Filing Type for these forms ends with "doing business in Maine".
| Suffix | Local Name | English Translation | Standardized |
| - | - | - | - |
| `F` | Business Corporation (foreign) | Foreign Business Corporation | Corporation |
| `FC` | Limited Liability Company (foreign) | Foreign Limited Liability Company | Limited Liability Company |
| `FP` | Limited Liability Partnership (foreign) | Foreign Limited Liability Partnership | Partnership |
| `LF` | Limited Partnership (foreign) | Foreign Limited Partnership | Partnership |
| `NF` | Nonprofit Corporation (foreign) | Foreign Nonprofit Corporation | Nonprofit Organization |
ISO 20275 (ELF) codes are not assigned. The Legal Entity Identifier authority does not publish stable codes for Maine-specific sub-national legal forms. The standardized category above is the recommended cross-jurisdiction key.
#### Non-company suffixes
Name reservations and trademark filings carry their own charter-number suffixes and are not companies. They are not filtered out of search results, and they resolve with the standardized legal form `Other`.
| Suffix(es) | Meaning |
| - | - |
| `M` | Mark (trademark or service mark filing) |
| `RC`, `RD`, `RN`, `RP`, `LN`, `CR`, `LR`, `NR`, `PR`, `R` | Name reservation or registration of a reserved name |
### Other Key Persons
Maine publishes only one role on the public register. It appears as an `otherKeyPerson` on the company profile, not as a `legalRepresentative`.
| Local Role Name | English Translation | Notes |
| - | - | - |
| Clerk / Registered Agent | Clerk (domestic) or Registered Agent (foreign) | Service-of-process designee. Can be a natural person or a company. The address is returned for individual agents only. |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company profile | Yes | Legal name, charter number, filing type, status, registration or qualification date, jurisdiction, assumed names, former names, principal home office address. |
| Registered agent | Yes | Returned as `otherKeyPersons` with the role "Clerk / Registered Agent". Includes the name, and the address for individual agents. |
| Legal representatives | No | Officers and directors are not published on the Maine SoS public register. |
| Shareholders | No | Not collected by Maine at the state level. |
| Ultimate beneficial owners | No | Maine does not maintain a public beneficial-ownership register. |
| Activity codes | No | The Maine SoS does not collect NAICS, NACE, or ISIC codes. |
| Trade Register Extract | Yes | Printable PDF of the Maine SoS Information Summary page, captured at request time. Included with the company-data block. |
| Certificate of Existence | Yes | Official Certificate of Existence (Good Standing), Short Form, purchased from the Maine SoS and delivered as a PDF. Ordered on demand. |
| Filing copies | Yes | Uncertified copies of individual filings (annual reports, articles, amendments, restatements, mark filings, and similar) ordered on demand. |
## Documents
### Available Documents
| Document | Availability | Format | Notes |
| - | - | - | - |
| **Trade Register Extract** | Always available | PDF | Printable capture of the Maine SoS Information Summary page. Included with the company data block. |
| **Certificate of Existence** | Always available | PDF | Official Certificate of Existence (Good Standing), Short Form, issued by the Maine SoS. Ordered through the API. |
| **Annual Report (filing copy)** | Per-entity, on demand | PDF | Uncertified copy of an annual report filing, served from the SoS filings index. Listed in the available documents response when present in the register. |
| **Filing Copy (other)** | Per-entity, on demand | PDF | Uncertified copy of any other filing (articles of incorporation, amendments, restatements, mark filings, etc.). Listed in the available documents response when present in the register. |
Filings flagged "Image not available" on the register predate digital imaging and are paper-only at the Division. They are intentionally excluded from the available documents list.
Certified copies, Long Form Certificates of Existence, apostilled certificates, and written-record searches are handled by direct request to the Maine Bureau of Corporations, UCC & Commissions and are not yet offered through Topograph.
## Example API Responses
### Search by Name
```bash theme={null}
curl -G "https://api.topograph.co/v2/search" \
--data-urlencode "country=US-ME" \
--data-urlencode "query=ACME MAINE" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "20001234DC",
"legalName": "ACME MAINE HOLDINGS, LLC",
"countryCode": "US-ME",
"matchReason": { "matchType": "default" }
},
{
"id": "19850456 D",
"legalName": "ACME MAINE COMPANY",
"countryCode": "US-ME",
"matchReason": { "matchType": "default" }
}
]
```
### Search by Charter Number
```bash theme={null}
curl -G "https://api.topograph.co/v2/search" \
--data-urlencode "country=US-ME" \
--data-urlencode "query=20001234DC" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "20001234DC",
"legalName": "ACME MAINE HOLDINGS, LLC",
"countryCode": "US-ME",
"matchReason": {
"matchType": "id",
"identifier": { "charterNumber": "20001234DC" }
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-ME", "id": "20001234DC", "dataPoints": ["company", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "20001234DC",
"countryCode": "US-ME",
"identifiers": { "charterNumber": "20001234DC" },
"legalName": "ACME MAINE HOLDINGS, LLC",
"registrationDate": "2020-04-15",
"status": {
"localName": "GOOD STANDING",
"active": true
},
"legalForm": {
"localName": "LIMITED LIABILITY COMPANY",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "100 Main Street",
"city": "Portland",
"postalCode": "04101",
"region": "ME",
"countryCode": "US"
},
"commercialNames": ["ACME MAINE"]
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Clerk / Registered Agent" },
"company": {
"countryCode": "US-ME",
"legalName": "CORPORATION SERVICE COMPANY"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "19560089 D",
"countryCode": "US-ME",
"identifiers": { "charterNumber": "19560089 D" },
"legalName": "ACME FOODS OF MAINE, INC.",
"registrationDate": "1956-09-12",
"status": {
"localName": "GOOD STANDING",
"active": true
},
"legalForm": {
"localName": "BUSINESS CORPORATION",
"englishTranslation": "Business Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "1 Distribution Way",
"city": "Bangor",
"postalCode": "04401",
"region": "ME",
"countryCode": "US"
},
"legacyLegalNames": ["ACME GROCERS OF MAINE"]
},
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Clerk / Registered Agent" },
"individual": {
"name": { "fullName": "JANE ROE" },
"residenceAddress": {
"addressLine1": "12 Elm Street",
"city": "Portland",
"postalCode": "04102",
"region": "ME",
"countryCode": "US"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "20030716 F",
"countryCode": "US-ME",
"identifiers": { "charterNumber": "20030716 F" },
"legalName": "ACME GLOBAL LABORATORIES, INC.",
"registrationDate": "2003-07-16",
"status": {
"localName": "GOOD STANDING",
"active": true
},
"legalForm": {
"localName": "BUSINESS CORPORATION DOING BUSINESS IN MAINE",
"englishTranslation": "Foreign Business Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "200 Research Drive",
"city": "Boston",
"postalCode": "02118",
"region": "MA",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Clerk / Registered Agent" },
"company": {
"countryCode": "US-ME",
"legalName": "CT CORPORATION SYSTEM"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "19970058LP",
"countryCode": "US-ME",
"identifiers": { "charterNumber": "19970058LP" },
"legalName": "ACME PARTNERS, L.P.",
"registrationDate": "1997-02-10",
"status": {
"localName": "ADMINISTRATIVELY DISSOLVED",
"active": false
},
"legalForm": {
"localName": "LIMITED PARTNERSHIP",
"englishTranslation": "Limited Partnership",
"standardized": "Partnership"
},
"legalAddress": {
"addressLine1": "500 Forest Avenue",
"city": "Portland",
"postalCode": "04101",
"region": "ME",
"countryCode": "US"
}
},
"otherKeyPersons": []
}
```
```json theme={null}
{
"company": {
"id": "19800123ND",
"countryCode": "US-ME",
"identifiers": { "charterNumber": "19800123ND" },
"legalName": "ACME COMMUNITY FOUNDATION",
"registrationDate": "1980-11-04",
"status": {
"localName": "GOOD STANDING",
"active": true
},
"legalForm": {
"localName": "NON-PROFIT CORPORATION (UNDER TITLE 13-B)",
"englishTranslation": "Nonprofit Corporation",
"standardized": "Nonprofit Organization"
},
"legalAddress": {
"addressLine1": "8 Park Avenue",
"city": "Portland",
"postalCode": "04101",
"region": "ME",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Clerk / Registered Agent" },
"individual": {
"name": { "fullName": "JOHN DOE" },
"residenceAddress": {
"addressLine1": "8 Park Avenue",
"city": "Portland",
"postalCode": "04101",
"region": "ME",
"countryCode": "US"
}
}
}
]
}
```
### Available Documents
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-ME", "id": "20001234DC", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_abc123",
"name": "Trade Register Extract",
"format": "pdf"
},
"certificateOfGoodStanding": {
"id": "doc_cogs_def456",
"name": "Certificate of Existence (Good Standing)",
"format": "pdf"
},
"annualReturns": [
{
"id": "doc_ar_2024",
"name": "Annual Report — 2024-06-01",
"format": "pdf"
},
{
"id": "doc_ar_2023",
"name": "Annual Report — 2023-06-01",
"format": "pdf"
}
],
"otherDocuments": [
{
"id": "doc_other_articles",
"name": "Articles of Organization — 2020-04-15",
"format": "pdf"
},
{
"id": "doc_other_amend",
"name": "Amendment — 2022-08-12",
"format": "pdf"
}
]
}
}
```
### Order a Filing Copy
Pass a document ID returned by `availableDocuments` in the `documents` array of a company request.
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-ME", "id": "20001234DC", "documents": ["doc_ar_2024"]}'
```
Once the document has been retrieved, the company result carries it with a download URL:
```json theme={null}
{
"documents": {
"annualReturns": [
{
"id": "doc_ar_2024",
"url": "https://example.com/download/annual-report-2024.pdf"
}
]
}
}
```
# Maryland
Source: https://docs.topograph.co/essentials/us-maryland
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Maryland reference is on the [Maryland country page](https://www.topograph.co/countries/us-md).
## Start here
This guide contains public integration notes for Maryland. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Entity Status](#entity-status)
* [Data Availability](#data-availability)
**API access:** `US-MD` is accepted by the API, but it is not yet listed in the request `countryCode` enum of the OpenAPI reference.
## Data Sources
Maryland uses a single integration against the **Maryland State Department of Assessments and Taxation (SDAT)**, served through the **Maryland Business Express** public entity-detail portal.
The public detail page returns the SDAT Department ID, legal name, principal office address, resident agent name and address, current status and good-standing flag, business type and business code, formation/registration date, state of formation, stock and close-corporation classifications, mailing address, and the entity's filing history. The API response carries the Department ID, legal name, principal office address, status, business type and code, formation/registration date, and state of formation. The resident agent, stock and close-corporation classifications, and mailing address appear only on the free **Trade Register Extract** (a printable record of the public entity-detail page), which is included with every lookup at no extra charge.
**Single authoritative mode.** One live, authoritative read of the register serves both prefill and verification requests. There is no cached snapshot.
**Officers not on the public surface.** Officer, director, member, and manager rosters are not published on the Maryland Business Express public entity-detail page. They are visible only after authentication with a Maryland Business Express account or through a paid Personal Property Assessment record. The publicly-served Resident Agent (statutory service-of-process address) is included in the Trade Register Extract but is not returned as a legal representative in the API response.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **SDAT Department ID** | One letter (A-Z) followed by 8 digits | `D22958060` | Primary identifier assigned by SDAT. Case-insensitive on input; normalized to uppercase. |
The Department ID always starts with one uppercase letter followed by exactly eight digits (e.g. `D22958060`, `F04793998`, `Z25352915`, `T00371146`). SDAT documents that the letter corresponds to the entity type: `D` Maryland corporation (stock or non-stock), `F` foreign corporation, `W` Maryland LLC, `Z` foreign LLC, `M` / `P` Maryland / foreign limited partnership, `A` / `E` Maryland / foreign LLP, `B` / `S` Maryland / foreign statutory trust, `L` sole proprietorship or general partnership, `T` trade name. Trade names appear in name search results, but the register publishes no company record for them, so they cannot be retrieved with `/v2/company`. An entity that converts to another entity type receives a new Department ID.
### Identifiers in API Response
| Identifier | Format | Example | Notes |
| - | - | - | - |
| `departmentId` | Letter + 8 digits | `D22958060` | Present for all entities. Primary identifier. |
| `businessCode` | Two-digit code + label | `04 ORDINARY BUSINESS - NON-STOCK` | Secondary SDAT classification code. Not present for all entities. |
| `stateOfFormation` | Free text, as published by SDAT | Not shown | State where the entity was originally formed. Not present for all entities. |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Notes |
| - | - | - | - | - |
| By Business Name | 2-200 chars | `"Acme"` | Starts-with (case-insensitive) | Up to 50 results. |
| By Department ID | Letter + 8 digits | `D22958060` | Exact | Returns one result. |
Name search anchors on the beginning of the legal name (case-insensitive). Use a fuller query string to narrow the result set. Fictitious names (DBAs) and trade names are not indexed; search only resolves legal entity names as registered with SDAT.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Rows matched under a former company name carry no status and are always kept.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefix letter follows the entity type** | SDAT documents that the letter prefix of the Department ID corresponds to the entity type (see Company Identifiers). The full entity type is the `Business Type` field published on the detail page (e.g. "DOMESTIC LLC", "FOREIGN CORPORATION"). |
| **Officers require authentication** | Officer, director, member, and manager rosters are not part of the anonymous public detail page. They are gated behind a Maryland Business Express user account or a paid Personal Property Assessment record. |
| **Resident Agent is informational only** | The Resident Agent (name and address) is printed on the public detail page and included in the Trade Register Extract, but is not returned as a legal representative in `legalRepresentatives`. |
| **No shareholder or UBO register** | Maryland does not publish shareholders or beneficial owners for any entity type on the public register. Federal FinCEN BOI records are a separate restricted system. |
| **No activity codes** | Industry classification codes are not published on Maryland SDAT business summary records. |
| **No tax identifier on the public surface** | The SDAT Department ID is an internal entity identifier. Federal EIN and Maryland Comptroller tax accounts are not surfaced on the public business search. |
| **Certified documents are not offered yet** | Certified copies of charter filings, Certificates of Status, and the long-form Personal Property Assessment record are not offered through Topograph in v1. |
| **No public bulk extract** | SDAT does not publish a public bulk entity dataset, and the Maryland Open Data Portal does not republish entity-level data. Every lookup reads the live register. |
## Mappings
### Legal Forms
Maryland reports entity type as a free-text `Business Type` field on the SDAT entity-detail page (e.g. "CORPORATION", "DOMESTIC LLC", "FOREIGN CORPORATION", "DOMESTIC LLC", "FOREIGN LLC"). A secondary `Business Code` (e.g. "04 ORDINARY BUSINESS - NON-STOCK") further classifies the entity.
The API returns the raw SDAT Business Type in `legalForm.localName`. No standardized legal form category is returned yet.
Stock status ("STOCK" / "NONSTOCK") and close-corporation flag ("YES" / "NO") are additional qualifiers published on the detail page. They appear on the Trade Register Extract and are not returned in the API response.
### Entity Status
Maryland reports entity status as a free-text field (e.g. "Active", "Incorporated", "Forfeited", "Dissolved", "Cancelled"). The API normalizes it into a structured `status` object with a `localName` (the raw SDAT value) and an `active` boolean.
| SDAT Status | `active` |
| - | - |
| Active | `true` |
| Incorporated | `true` |
| In Good Standing | `true` |
| Forfeited | `false` |
| Dissolved | `false` |
| Cancelled | `false` |
| Terminated | `false` |
| Merged | `false` |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from SDAT |
| Company status | Yes | Normalized from SDAT free-text status + good-standing flag |
| Registration date | Yes | Date of formation/registration as published by SDAT |
| Legal address | Yes | Principal office address (street, city, state, ZIP) |
| Mailing address | No | Shown on the Trade Register Extract when published; not returned in the API response |
| Legal form | Yes | Raw SDAT Business Type in `localName`; no standardized category yet |
| Business code | Yes | Secondary SDAT classification code, when published, returned as `identifiers.businessCode` |
| State of formation | Yes | State where the entity was originally formed (relevant for foreign entities), returned as `identifiers.stateOfFormation` |
| Legal representatives | No | Not on the public detail page; requires account authentication |
| Registered agent | Informational | Resident Agent is printed on the Trade Register Extract but not modeled as a legal representative |
| Activity codes | No | Not published on SDAT business records |
| Shareholders | No | Not held by SDAT public register |
| UBOs | No | No Maryland or public federal register |
| Trade Register Extract | Yes | Free printable record of the public entity-detail page, included at no extra charge |
| Certified copies / Certificate of Status | No | Not offered through Topograph in v1 |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -G "https://api.topograph.co/v2/search" \
--data-urlencode "country=US-MD" \
--data-urlencode "query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "D12345678",
"legalName": "ACME HOLDINGS, INC.",
"countryCode": "US-MD",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by Department ID
```bash theme={null}
curl -G "https://api.topograph.co/v2/search" \
--data-urlencode "country=US-MD" \
--data-urlencode "query=D12345678" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "D12345678",
"legalName": "ACME HOLDINGS, INC.",
"countryCode": "US-MD",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MD", "id": "D12345678", "dataPoints": ["company"]}'
```
```json theme={null}
{
"company": {
"id": "D12345678",
"countryCode": "US-MD",
"identifiers": {
"departmentId": "D12345678",
"businessCode": "04 ORDINARY BUSINESS - NON-STOCK"
},
"legalName": "ACME HOLDINGS, INC.",
"registrationDate": "2010-03-15",
"legalForm": {
"localName": "CORPORATION"
},
"legalAddress": {
"addressLine1": "100 COMMERCE DRIVE",
"city": "ANNAPOLIS",
"region": "MD",
"postalCode": "21401",
"countryCode": "US"
},
"status": {
"localName": "Incorporated",
"active": true
}
}
}
```
# Massachusetts
Source: https://docs.topograph.co/essentials/us-massachusetts
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Massachusetts reference is on the [Massachusetts country page](https://www.topograph.co/countries/us-ma).
## Start here
This guide contains public integration notes for Massachusetts. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Status](#company-status)
* [Data Availability](#data-availability)
**API access:** `US-MA` is accepted by `/v2/search` and `/v2/company`, but it is not yet listed in the `countryCode` enum of the OpenAPI specification.
## Data Sources
Massachusetts uses two data channels:
* **Massachusetts Corporations Division** (company profiles, authoritative). The Secretary of the Commonwealth operates the online corporation search at `corp.sec.state.ma.us`. The live register covers every corporation, LLC, LP, LLP, professional entity, and nonprofit on file with the Commonwealth. It exposes the full entity profile: 9-digit internal ID, entity type, jurisdiction, filing date, status, addresses, registered agent, and the officer/director/manager roster from annual reports. Every company profile, in both modes, is read live from this register.
* **Massachusetts Corporations Book (DOR/DLS)** (name search only). The Massachusetts Department of Revenue, Division of Local Services publishes an annual "Corporations Book" under G.L. c.58 §2. The book lists every entity subject to MA corporate excise, with name, location (city or home state/country for foreign entities), and an M/R/D excise-class flag. It backs name search and does not serve company profiles.
**Both modes read the live register.** Prefill (`mode: "prefill"`) and verification (`mode: "verification"`) return the same authoritative data: status, registration date, legal form, principal office address, officers and registered agent. They differ only in speed and guaranteed delivery. Prefill is optimized for low latency and may be briefly unavailable under heavy load. Retry, or use verification, which always returns.
**Name search coverage.** The Corporations Book only includes entities currently subject to Massachusetts corporate excise. Dissolved, inactive, and many pass-through entities are excluded. If an entity does not appear in name search, search by its MA SoC ID, which queries the live register.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **MA SoC Entity ID** | 9 digits, leading zeros included; some trusts carry `T` followed by 8 digits (observed) | `000804945` | The Identification Number assigned by the Secretary of the Commonwealth, Corporations Division. Send it with its leading zeros. |
| **DLS identifier** | 12 lowercase hexadecimal characters | `19dcdd187b79` | Synthetic identifier returned as the `id` of name-search results, derived from the entity name and city in the annual Corporations Book. It changes when either changes in a later edition. Searching on it returns that entity. |
The MA SoC Entity ID is the canonical identifier for direct lookups. Name search returns a synthetic DLS identifier instead. See the note below on identifier promotion.
### Identifiers in API Response
| Identifier | Format | Example | Found in |
| - | - | - | - |
| `maSocId` | 9 digits, leading zeros included, or `T` + 8 digits for some trusts | `000804945` | All company profiles |
| `dlsId` | 12 lowercase hexadecimal characters | `19dcdd187b79` | The `id` of name-search results |
`dlsId` is a placeholder derived from the entity's name and location in the annual bulk publication. It carries no official register meaning. You can pass it as `id` to `/v2/company`: the entity is matched on the live register and the response carries its official `maSocId`.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match type | Expected results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Liberty Mutual"` | Full-text (case-insensitive) | Multiple results |
| By MA SoC ID | 1-9 digits (zero-padding added), or `T` followed by 8 digits for trusts | `000804945`, `804945` | Exact | Single result (`matchType: id`) |
**Name search uses the Corporations Book.** Name search covers the entities in the annual publication. Dissolved or inactive entities are not included. For entities absent from name-search results, search by MA SoC ID, which queries the live register directly.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile. Name searches draw on the state's corporate tax roll, which mostly lists active companies but can still hold entities dissolved since the last annual edition. Search results carry no status, and registration-number lookups return the company whatever its status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Identifier promotion** | Name-search results carry a synthetic `dlsId`. When you fetch the entity with `/v2/company`, the response carries the official `maSocId`. Update your records to the authoritative identifier after the first profile fetch. |
| **Annual publication lag** | The Corporations Book is published once a year. Entities incorporated after the last publication date will not appear in name-search results. Search by a known SoC ID for recently incorporated entities. |
| **Status is inferred, not a register field** | The live register does not publish a discrete status field. Status is derived from merger and inactivity signals on the corporation summary page. The two observable values are `Active` and `Merged / Inactive`. |
| **Excise-class flag is not an industry code** | The M/R/D flag in the Corporations Book (manufacturing, revoked-manufacturing, R\&D) is a Massachusetts corporate excise exemption indicator, not an industry classification. The company-register sources used here publish no NAICS, NACE, or ISIC codes. Tax classifications are not returned as `activityDescription`. |
| **Officer data comes from the annual report** | Both modes map the officer and director roster parsed from the live annual-report summary. Completeness of separate LLC manager and filing-authorized-person sections has not been verified on the current parser. |
| **Members of LLCs are generally not disclosed** | Massachusetts LLCs disclose only managers and persons authorized to validate documents in their annual reports. Members of member-managed LLCs are not disclosed unless they also hold a manager role. |
| **No shareholders or UBO register** | Massachusetts does not collect shareholder lists or beneficial-ownership data for any entity type. Federal BOI (FinCEN) is not accessible to private parties. |
| **DBAs are city-level filings** | Business certificates (doing-business-as names) are filed with the individual city or town clerk, not the state. There is no central DBA registry. |
| **Free-form officer titles** | MGL c.156D §8.40 mandates only President, Treasurer, and Secretary (or Clerk). Known statutory and observed titles map deterministically; unrecognized free-form titles use the existing parser. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type label on the Secretary of the Commonwealth Corporations Division. The vocabulary is derived from Massachusetts General Laws Title XXII (c.156D, c.156A, c.156C, c.180, c.109, c.108A). The full table with standardized categories and ISO 20275 codes is on the pricing page.
| SoC Entity Type | Standardized |
| - | - |
| Domestic Profit Corporation | Corporation |
| Foreign Profit Corporation | Corporation |
| Domestic Professional Corporation | Corporation |
| Foreign Professional Corporation | Corporation |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Corporation | Nonprofit Organization |
| Domestic Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic Limited Liability Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Foreign Corporation | Corporation |
Legal form is populated from the live register in both prefill and verification modes.
### Officer Roles
Massachusetts law (MGL c.156D §8.40 and §16.22) mandates a small set of statutory officer titles. Known statutory and observed titles map deterministically. Filed titles remain open text; unrecognized titles use the existing parser. Officer powers depend on bylaws and board authorization under MGL c.156D §8.41; a role does not establish sole or joint signing authority.
| Role | Standardized | Notes |
| - | - | - |
| President | President | Statutory officer under MGL c.156D §8.40 |
| Treasurer | Treasurer | Statutory officer under MGL c.156D §8.40 |
| Secretary | Secretary | Statutory officer under MGL c.156D §8.40 |
| Clerk | Secretary | Massachusetts-specific synonym for Secretary on for-profit corporations |
| Director | Board Member | Other Key Person; a board seat does not establish individual signing authority |
| Registered Agent | Registered Agent | Service-of-process contact under MGL c.156D §5.01; classified as Other Key Person |
President, Treasurer, Secretary, Clerk and other filed executive offices are potential Legal Representatives, subject to appointment powers. Directors, board chairs and departmental Director of Tax are returned under `otherKeyPersons`; Registered Agent remains a service contact. Known LLC manager and filing-authorized titles preserve their distinct office and limited source scope.
### Company Status
Status is inferred from signals on the corporation summary page, not from a discrete register field. Two values are possible:
| Status | Meaning |
| - | - |
| Active | No merger record and no inactivity marker detected on the SoC summary |
| Merged / Inactive | A merger record or inactivity marker is present |
## Data Availability
| Data point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Yes | Inferred from the live register summary |
| Registration date | Yes | Filing date from the live register |
| Legal address | Yes | Principal office address from the live register |
| Legal form | Yes | Entity type from the live register |
| Legal representatives | Yes | Representing officer offices from the parsed annual-report roster; governance directors are Other Key Persons |
| Other key persons | Yes | Governance roles and other nonrepresenting filed offices, alongside the registered agent |
| Registered agent | Yes | From the live register corporation detail page, returned under `otherKeyPersons` |
| Activity codes | No | Not collected by the Commonwealth |
| Shareholders | No | Not published |
| UBOs | No | Federal FinCEN BOI is not publicly accessible |
| Documents | Roadmap | Annual reports, articles of organization, and certificates are accessible on the live register; document retrieval is planned for a future release |
| Financial data | No | Not collected |
| DBAs / assumed names | No | Filed at city/town clerk level; no central registry |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MA&query=Liberty+Mutual" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "19dcdd187b79",
"legalName": "SAMPLE HOLDINGS INC.",
"countryCode": "US-MA",
"matchReason": {
"matchType": "default"
},
"address": {
"city": "BOSTON",
"region": "MA",
"countryCode": "US"
}
}
]
```
The `id` returned by name search is a `dlsId`. Pass it to `/v2/company` as is: the profile carries the official `maSocId`.
### Search by SoC ID
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MA&query=000804945" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "000804945",
"legalName": "SAMPLE HOLDINGS INC.",
"countryCode": "US-MA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MA", "id": "000804945", "dataPoints": ["company", "legalRepresentatives"], "mode": "prefill"}'
```
Prefill and verification return the same response shape and data.
```json theme={null}
{
"company": {
"id": "000804945",
"countryCode": "US-MA",
"identifiers": { "maSocId": "000804945" },
"legalName": "SAMPLE HOLDINGS INC.",
"registrationDate": "1998-03-15",
"status": { "localName": "Active", "active": true },
"legalForm": {
"localName": "Domestic Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "123 State Street",
"city": "Boston",
"region": "MA",
"postalCode": "02109",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "President", "standardized": "President" },
"individual": { "name": { "fullName": "Jane Smith" } }
}
]
}
```
# Michigan
Source: https://docs.topograph.co/essentials/us-michigan
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Michigan reference is on the [Michigan country page](https://www.topograph.co/countries/us-mi).
## Start here
This guide contains public integration notes for Michigan. Use it for identifier formats, search behavior, and state-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Entity Status](#entity-status)
* [Data Availability](#data-availability)
**API access:** `US-MI` is accepted by `/v2/search` and `/v2/company`, but it is not yet listed in the `countryCode` enum of the OpenAPI specification.
## Data Sources
Michigan uses a single integration against the **Michigan Department of Licensing and Regulatory Affairs (LARA), Corporations, Securities & Commercial Licensing Bureau (CSCL)**, via the **MiBusiness Registry** portal at `mibusinessregistry.lara.state.mi.us` (launched June 2025, replacing the legacy CID/PIN system).
The register covers every domestic and foreign profit corporation, non-profit corporation, limited liability company, limited partnership, limited liability partnership, and professional service entity filed in Michigan. Every request is resolved live. Michigan does not publish a bulk corporate data extract.
| What is returned | Source |
| - | - |
| Legal name | MiBusiness Registry entity detail |
| 9-digit Identification Number | MiBusiness Registry entity detail |
| Jurisdiction (home state for foreign entities) | Trade Register Extract only |
| Entity type (legal form) | MiBusiness Registry entity detail |
| Entity status | MiBusiness Registry entity detail |
| Prior names, annual report standing and due date | Trade Register Extract only |
| Initial filing date | MiBusiness Registry entity detail |
| Resident agent name and registered office street address | MiBusiness Registry entity detail |
| Officers (President, Secretary, Treasurer, Directors) | Most recently filed annual report (corporations only) |
| Trade Register Extract (printed entity detail) | MiBusiness Registry entity detail, included at no extra charge |
**No bulk open-data export.** LARA does not publish a corporate data extract. Every request is resolved live against the MiBusiness Registry.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Michigan LARA Identification Number** | 9 digits, no prefix or separators | `800853791` | Assigned by LARA Corporations Division. Printed on every filing and shown on the MiBusiness Registry entity detail page. Michigan assigned these 9-digit numbers in 2017, replacing the older six-character IDs. |
Pass the 9-digit identification number without any prefix or separator. The number is the same identifier shown on the entity detail page under "Identification #".
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `miIdNumber` | 9 digits, no prefix or separators | `800853791` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–100 chars | `"Acme Michigan"` | Starts-with (case-insensitive) | Multiple results |
| By Identification Number | 9 digits | `800853791` | Exact | Exact match returned first (`matchType: id`) |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use a fuller query string to narrow the result set, which is capped at 50 matches.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Officers only for corporations** | Only profit and non-profit corporations are required to disclose officers under Michigan law (MCL 450.1531 / MCL 450.2531). LLCs, limited partnerships, and LLPs do not publish member or partner information on the register. Requests for these entity types return no legal representatives. |
| **Officer data can lag up to 12 months** | Officers come from the entity's most recent annual report, filed once per year on the anniversary date. The data reflects the state at the last filing, not today. |
| **Annual report standing is separate from entity status** | The "AR Standing" field reflects whether the entity is current on its annual report filing obligation. An entity can be "Active" in status but "Overdue" on annual reports simultaneously. AR standing appears on the Trade Register Extract and is not returned in the `company` datapoint. |
| **Prior names are on the extract only** | The entity detail includes prior names. They appear on the Trade Register Extract but are not returned in the `company` datapoint. DBA-style assumed names are stored in a separate register file and are not yet surfaced. |
| **Resident agent is an Other Key Person** | The resident agent receives service of process but cannot bind the entity. It is returned under `otherKeyPersons`, not `legalRepresentatives`. |
| **No shareholder or UBO register** | Michigan does not collect shareholder lists or beneficial-ownership data for any entity type through the business register. The federal beneficial-ownership database is restricted to authorized users. |
| **No industry classification codes** | The MiBusiness Registry does not collect NAICS, NACE, or ISIC codes. |
| **No bulk data pipeline** | Every request is resolved live against the MiBusiness Registry. There is no cached open-data dataset for Michigan. |
| **Paid documents require a LARA account** | Certified copies of charter documents, annual reports, and Certificates of Good Standing are available through the LARA paid filing system. These require a MiLogin for Business account and are not yet offered through Topograph. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type label published on the MiBusiness Registry. The vocabulary follows the Michigan Business Corporation Act (MCL 450.1101), the Limited Liability Company Act (MCL 450.4101), the Nonprofit Corporation Act (MCL 450.2101), and the Revised Uniform Limited Partnership Act (MCL 449.1101). Unknown labels are classified by AI enrichment.
| MiBusiness Registry Entity Type | Standardized |
| - | - |
| Domestic Profit Corporation | Corporation |
| Foreign Profit Corporation | Corporation |
| Domestic Professional Service Corporation | Corporation |
| Foreign Professional Service Corporation | Corporation |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Corporation | Nonprofit Organization |
| Domestic Ecclesiastical Corporation | Nonprofit Organization |
| Domestic Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Domestic Professional Limited Liability Company | Limited Liability Company |
| Foreign Professional Limited Liability Company | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic Limited Liability Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Domestic Limited Liability Limited Partnership | Partnership |
| Foreign Limited Liability Limited Partnership | Partnership |
| Domestic Cooperative | Cooperative |
| Foreign Cooperative | Cooperative |
| Domestic Cooperative Association | Cooperative |
The complete legal forms table, including any labels added after this guide was written, is on the [Michigan pricing page](https://topograph.co/pricing/us-mi).
### Officer Roles
Michigan corporations are required under MCL 450.1531 (Business Corporation Act) and MCL 450.2531 (Nonprofit Corporation Act) to maintain a president, secretary, treasurer, and board of directors. The MiBusiness Registry exposes exactly these four roles.
| MiBusiness Registry Label | Standardized | Classification |
| - | - | - |
| President | President | Legal Representative |
| Secretary | Secretary | Legal Representative |
| Treasurer | Treasurer | Legal Representative |
| Director | Director | Legal Representative |
| Resident Agent | Registered Agent | Other Key Person |
The Resident Agent is classified as an Other Key Person. It only receives service of process and does not have authority to bind the entity.
### Entity Status
| MiBusiness Registry Status | Active |
| - | - |
| Active | Yes |
| Existence Ceased - Merged | No |
| Withdrawn - Certificate of Withdrawal | No |
| Converted | No |
| Dissolved - Operation of Law | No |
| Dissolved - Certificate of Dissolution | No |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Prior names | Trade Register Extract only | Not returned in the `company` datapoint |
| Entity status | Yes | See status table above |
| Annual report standing | Trade Register Extract only | Current / overdue status for annual report obligation; not returned in the `company` datapoint |
| Registration date | Yes | Initial filing date with LARA |
| Legal address | Yes | Registered office street address, or the registered office mailing address when no street address is on file |
| Legal form | Yes | Michigan entity-type vocabulary with standardized mapping |
| Legal representatives | Yes (corporations only) | President, Secretary, Treasurer, Directors from most recent annual report. LLCs, LPs, and LLPs return no legal representatives. |
| Registered agent | Yes | Resident agent name and registered office address, returned as Other Key Person |
| Activity codes | No | Not collected by the Michigan business register |
| Shareholders | No | Not published |
| UBOs | No | Not published (federal FinCEN database is restricted) |
| Assumed names (DBAs) | Roadmap | The register file exists but assumed-name data is not yet surfaced on the company profile |
| Trade Register Extract | Yes | Free printable PDF of the MiBusiness Registry entity detail page, included with the company-data request at no extra charge |
| Certified copies | No | Available through the LARA paid filing system; not yet offered through Topograph |
| Certificate of Good Standing | No | Available through the LARA paid filing system; not yet offered through Topograph |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MI&query=Acme+Michigan" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "987654321",
"legalName": "ACME MICHIGAN COMPANY",
"countryCode": "US-MI",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by Identification Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MI&query=987654321" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "987654321",
"legalName": "ACME MICHIGAN COMPANY",
"countryCode": "US-MI",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MI", "id": "987654321", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "987654321",
"countryCode": "US-MI",
"identifiers": { "miIdNumber": "987654321" },
"legalName": "EXAMPLE CORPORATION",
"registrationDate": "2005-03-15",
"legalForm": {
"localName": "Domestic Profit Corporation",
"standardized": "Corporation"
},
"status": {
"localName": "Active",
"active": true
},
"legalAddress": {
"addressLine1": "123 Example Street",
"city": "Lansing",
"region": "MI",
"postalCode": "48933",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "President",
"standardized": "President"
},
"individual": {
"name": { "fullName": "Jane Smith" }
}
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Resident Agent",
"standardized": "Registered Agent"
},
"individual": {
"name": { "fullName": "Jane Doe" }
}
}
]
}
```
# Minnesota
Source: https://docs.topograph.co/essentials/us-minnesota
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Minnesota reference is on the [Minnesota country page](https://www.topograph.co/countries/us-mn).
## Start here
This guide contains public integration notes for Minnesota. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)
**API access:** `US-MN` is accepted by `/v2/search` and `/v2/company`, but it is not yet listed in the `countryCode` enum of the OpenAPI specification.
## Data Sources
Minnesota uses a single integration against the **Minnesota Secretary of State, Minnesota Business & Lien System (MBLS)**. The register covers business corporations, nonprofit corporations, limited liability companies, limited partnerships, limited liability partnerships, cooperatives, and other entity types filed with the Secretary of State. Trademark and service mark registrations and assumed names are also present in the system.
* **MBLS public portal** (live, authoritative). Company name, file number, business type, filing status, filing date, renewal due date, registered office address, principal executive office address, registered agent, and filed managers/officers are read live from the public MBLS search and detail pages at `mblsportal.sos.mn.gov`.
**Trade Register Extract included.** Each company lookup includes a free printable extract of the MBLS business record detail page: the MBLS Business Record Details. This PDF is included at no extra charge alongside the company data.
**Certified copies and Certificates of Good Standing** are available from the Secretary of State but require an MBLS account and a paid order. These are not yet offered through Topograph. See the [pricing page](https://topograph.co/pricing/us-mn) for document availability.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Minnesota File Number** | Variable length, digits and uppercase letters, at most one internal dash. Recent filings: 12 digits in the records we have seen. Older filings: shorter, all digits or letters and digits around a dash | `631180100027`, `68758`, `1K-1056`, `886-NPA` | Assigned by the Minnesota Secretary of State (MBLS). Not unique on its own: see the warning below. Name search results carry the Filing GUID instead. |
| **MBLS Filing GUID** | 36 characters: 32 lowercase hexadecimal digits in groups of 8-4-4-4-12 separated by hyphens. UUID layout, but not UUID version rules | `e4d83ed9-ae4b-e211-bc43-001ec94ffe7f` | The `id` of every name search result. Always resolves to a single entity. |
Minnesota file numbers are alphanumeric and may contain a single internal dash (for example `1K-1056` or `886-NPA`). Letters are significant and the number is case-insensitive. Pass it in any case and the API normalizes to uppercase. Do not strip the dash.
**File number collisions.** The same numeric file number can be assigned to entities of different types. For example, a trademark registration and a business entity may both carry file number `4912`. When a file-number search returns multiple candidates that cannot be distinguished, the API returns `resource_not_found`. Use name search to locate the entity and pass the exact ID returned by search.
### Identifiers in API Response
| Identifier | Response field | Format | Found In |
| - | - | - | - |
| Minnesota File Number | `company.identifiers.fileNumber` | Digits and uppercase letters, at most one internal dash | All entities |
| MBLS Filing GUID | `company.identifiers.filingGuid` | 32 lowercase hexadecimal digits, 8-4-4-4-12 with hyphens | Returned when available. Also the `id` of name-search results, and accepted as a search input and as `id` in `/v2/company` |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when `fileNumber` has a unique match against Minnesota registration or validation references in GLEIF and the legal name agrees.
File numbers can overlap between business types, so a number match alone is insufficient.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Notes |
| - | - | - | - | - |
| By Name | 2–250 characters | `"General Mills"` | Begins-with (case-insensitive) | Results capped; use a more specific query to narrow |
| By File Number | Digits and letters, optional internal dash | `1K-1056` | Exact (normalized, case-insensitive) | Returns `matchType: id` when resolved |
| By Filing GUID | 8-4-4-4-12 hexadecimal digits | `e4d83ed9-ae4b-e211-bc43-001ec94ffe7f` | Exact (case-insensitive) | Returns `matchType: id` when resolved |
**Name search.** The MBLS portal anchors name search on the beginning of the legal name. Name search returns active entities only. To find an inactive entity, search by its file number. Each result's `id` is the MBLS Filing GUID, which you can pass straight to `/v2/company`.
**Ambiguous file numbers.** If a file number resolves to multiple entities of different types, the lookup returns `resource_not_found`. Use name search to find the correct entity, then pass its ID to `/v2/company`.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Name searches only ever return active companies. Registration-number lookups also find inactive ones, which the filter removes.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Alphanumeric file numbers with dashes** | File numbers are not always numeric. Forms like `1K-1056` and `886-NPA` are valid. The dash is load-bearing. Do not strip it. The API normalizes to uppercase. |
| **File number collisions across entity types** | The same short numeric file number can exist for multiple entity types (for example a trademark and a business entity). When ambiguous, the API returns `resource_not_found` rather than returning the wrong entity. |
| **No shareholder or UBO data** | Minnesota does not publish shareholder lists or beneficial ownership information through the Secretary of State business register. |
| **No activity codes** | The Secretary of State does not collect NAICS, NACE, or ISIC codes. Business type (domestic/foreign, entity form) is available, but industry classification is not. |
| **Assumed names live in the same system** | DBA/assumed name registrations are indexed in MBLS alongside formal entity filings. They may appear in name search results. |
| **Trademarks and service marks are also present** | Trademark and service mark registrations appear in the register and may show short numeric file numbers that collide with business entity file numbers. |
| **Registered agent may be absent** | Not all entities have a registered agent on file. The field is omitted when not present. |
| **Renewal due date is present but not status** | The detail page exposes a renewal due date and a status field. Entities whose renewal is overdue may show an inactive or dissolved status; always treat the live portal status as authoritative. |
| **Certified copies and certificates are paid** | Certificate of Good Standing / Certificate of Existence and certified copies require a paid MBLS account order and are not yet available through Topograph. |
## Mappings
### Legal Forms
Legal form is sourced from the `Business Type` field on the MBLS detail page. The MBLS uses a fixed vocabulary of entity types drawn from Minnesota business statutes. The list below covers the most common forms seen in production. The full list, with standardized and ISO 20275 mappings where available, is on the [pricing page](https://topograph.co/pricing/us-mn).
| MBLS Business Type | Standardized |
| - | - |
| Domestic Business Corporation | Corporation |
| Foreign Business Corporation | Corporation |
| Domestic Non-Profit Corporation | Nonprofit Organization |
| Foreign Non-Profit Corporation | Nonprofit Organization |
| Domestic Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic Limited Liability Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Domestic Cooperative | Cooperative |
| Foreign Cooperative | Cooperative |
| Trademark / Service Mark | Other |
| Assumed Name | Other |
Legal form is returned as `legalForm.localName` (the raw MBLS label). Standardized mapping is applied where available. For the complete enum including ISO 20275 codes, see the [pricing page](https://topograph.co/pricing/us-mn).
### Officer Roles
Officer and manager titles are sourced from the MBLS detail page and use the published role catalogue. Manager, President and Chief Executive Officer preserve the declared office context. A title alone does not disclose company-specific signing powers.
| MBLS Role | Standardized |
| - | - |
| Manager | Manager |
| President | President |
| Chief Executive Officer / CEO | Chief Executive Officer |
### Other Key Persons
Registered agents receive service of process and appear in `otherKeyPersons` with the standardized role Registered Agent. Formation, application, markholding and filing-contact records also appear in `otherKeyPersons`; these labels do not establish ongoing authority to bind the entity.
| MBLS Role | Standardized |
| - | - |
| Registered Agent | Registered Agent |
| Organizer | Other |
| Incorporator | Other |
| Applicant | Other |
| Markholder | Other |
| Filing Contact | Other |
| Individual Contact for Agent | Other |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the MBLS portal |
| Company status | Yes | Live status from the MBLS detail page (Active, Inactive, Dissolved, etc.) |
| Registration date | Yes | Filing date from the MBLS detail page |
| Renewal due date | Trade Register Extract only | Shown on the printable extract; not returned in the `company` datapoint |
| Legal address | Yes | Registered office address, or the principal executive office address when no registered office is on file |
| Legal form | Yes | MBLS business type, standardized |
| Legal representatives | Yes | Managers, presidents, CEOs, and other filed officers |
| Registered agent | Yes | Name and address when on file, returned in `otherKeyPersons` |
| Home jurisdiction | Trade Register Extract only | For foreign entities, the jurisdiction of formation; not returned in the `company` datapoint |
| Activity codes | No | Not collected by the Secretary of State |
| Shareholders | No | Not published |
| UBOs | No | No public state-level beneficial ownership register |
| Trade Register Extract | Yes | Free printable MBLS Business Record Details PDF, included with each lookup |
| Certificate of Good Standing | Roadmap | Requires a paid MBLS account order; not yet available through Topograph |
| Certified copies | Roadmap | Requires a paid MBLS account order; not yet available through Topograph |
| Financial data | No | Not collected |
For the full catalog of supported datapoints and documents, see the [pricing page](https://topograph.co/pricing/us-mn).
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MN&query=Acme+Manufacturing" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"legalName": "ACME MANUFACTURING LLC",
"countryCode": "US-MN",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by File Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MN&query=1K-1056" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1K-1056",
"legalName": "ACME HOLDINGS, INC.",
"countryCode": "US-MN",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MN", "id": "123456789012", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "123456789012",
"countryCode": "US-MN",
"identifiers": {
"fileNumber": "123456789012",
"filingGuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"legalName": "ACME MANUFACTURING LLC",
"status": {
"localName": "Active / In Good Standing",
"active": true
},
"registrationDate": "2005-03-15",
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "123 Main St",
"city": "Minneapolis",
"region": "MN",
"postalCode": "55401",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Manager",
"standardized": "Manager"
},
"individual": {
"name": { "fullName": "Jane Smith" }
}
}
]
}
```
# Mississippi
Source: https://docs.topograph.co/essentials/us-mississippi
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Mississippi reference is on the [Mississippi country page](https://www.topograph.co/countries/us-ms).
## Start here
This guide contains public integration notes for Mississippi. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Statuses](#company-statuses)
* [Data Availability](#data-availability)
**API access:** `US-MS` is accepted by `/v2/search` and `/v2/company`, but it is not yet listed in the `countryCode` enum of the OpenAPI specification.
## Data Sources
Mississippi uses a single integration against the **Mississippi Secretary of State, Business Services** portal (`corp.sos.ms.gov`). The register covers all for-profit corporations, limited liability companies, non-profit corporations, limited partnerships, limited liability partnerships, general partnerships, sole proprietorships, cooperatives, foreign business trusts, and the foreign variants of these structures registered to do business in Mississippi.
Each entity on the live portal carries a numeric Business ID as its primary identifier, together with the legal name, filing type, status, formation date, principal office address, registered agent, full officer and director roster (name, mailing address, and title), and name history.
Mississippi does not publish a bulk data extract or open-data feed. All data is fetched live from the Secretary of State public portal on each request.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Business ID** | Digits only, no separators, no leading zeros. 6 or 7 digits in the records we have seen | `104297`, `1001743` | Unique identifier assigned by the Mississippi Secretary of State. |
Use `/v2/search` to resolve a company name to its Business ID before calling `/v2/company`. The Business ID returned by search is the exact value to pass as `id` in the profile request.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `businessId` | Digits only, 6 or 7 in the records we have seen | `104297` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Delta Power"` | Starts-with (case-insensitive) | Multiple results |
| By Business ID | Numeric | `104297` | Exact (`matchType: id`) | Single result |
Name search anchors on the beginning of the legal name. The result set is capped at 50 matches. Use a more specific query string to narrow results. Each entity appears once, under its Business ID, even when it has aliases or a prior legal name. Name reservations are not returned.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Name searches are filtered by status. Registration-number lookups return the company whatever its status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Name Reservations have no Business ID** | Administrative name reservations do not receive a Business ID. They are left out of search results and cannot be profiled. |
| **Empty detail page for some dissolved entities** | A small number of dissolved entities return an empty detail page from the register. The API returns `resource_not_found` for these cases; retrying will not help. |
| **Officers holding multiple roles** | The register stores compound titles (for example "President, Chairman, Chief Executive Officer"). Topograph splits these into one entry per role in `legalRepresentatives`. |
| **Empty officer title** | Some officers appear in the register with no title at all. These records are still returned in `legalRepresentatives` with the person's name and address, and a standardized role of `Other`. |
| **No shareholder or UBO register** | Mississippi does not publish shareholders or beneficial owners for any entity type. |
| **No activity codes** | The Secretary of State does not publish NAICS, NACE, or ISIC codes on the entity detail page. |
| **Sole proprietorships included** | Unlike many US states, Mississippi publishes sole proprietorship registrations and fictitious name (DBA) registrations alongside corporate entities. |
| **Trade Register Extract is included** | The printable detail page is bundled with the company data at no extra charge. See [Documents](#data-availability) below. |
## Mappings
### Legal Forms
The Filing Type field on the portal is a closed vocabulary of 14 values. These were enumerated from live portal data by sweeping ten distinct name-search queries across the full register.
| MS Filing Type | Standardized | ISO 20275 |
| - | - | - |
| Business Corporation | Corporation | `XST3` |
| Foreign Corporation | Corporation | |
| Limited Liability Company (LLC) | Limited Liability Company | `WPCN` |
| Foreign Limited Liability Company (LLC) | Limited Liability Company | |
| Non-Profit Corporation | Nonprofit Organization | `O4NK` |
| Foreign Non-Profit Corporation | Nonprofit Organization | |
| Limited Partnership (LP) | Partnership | `NDBR` |
| Foreign Limited Partnership (LP) | Partnership | |
| Limited Liability Partnership (LLP) | Partnership | |
| General Partnership | Partnership | |
| Cooperative | Cooperative | |
| Foreign Business Trust | Trust | |
| Sole Proprietorship | Sole Proprietorship | |
| Name Reservation | Other | |
Foreign variants carry no ISO 20275 ELF code because the ELF code belongs to the jurisdiction of formation, not the state of registration. See the [pricing page](https://topograph.co/pricing/us-ms) for the full searchable table.
### Officer Roles
The register publishes officer titles as free text. The set of observed values is small and largely closed. Topograph maps each raw title to a standardized role.
| Common Register Title | Standardized | Notes |
| - | - | - |
| President | President | |
| Vice President | Vice President | |
| Secretary | Secretary | |
| Treasurer | Treasurer | |
| Director | Director | |
| Chairman | Chairman | |
| Manager | Manager | |
| Chief Executive Officer | Chief Executive Officer | |
| Chief Financial Officer | Chief Financial Officer | |
| Assistant Secretary | Other | Local title preserved in `localName` |
| Assistant Treasurer | Other | Local title preserved in `localName` |
| Incorporator | Other | Formation-time role only |
| Other | Other | |
Officers holding multiple titles are emitted as separate `legalRepresentatives` entries, one per role. The Registered Agent is returned under `otherKeyPersons` (not `legalRepresentatives`) as a service-of-process designee.
### Company Statuses
Mississippi publishes 12 distinct status values. Entities in **Good Standing** are active and in compliance. All other statuses indicate an inactive or terminated state.
| Register Status | Notes |
| - | - |
| Good Standing | Active and in compliance |
| Dissolved | Voluntarily or administratively dissolved |
| Cancelled | Registration cancelled |
| Revoked | Authority to do business revoked |
| Withdrawn | Foreign entity withdrawn from Mississippi |
| Merged | Entity merged into another entity |
| Inactive | No longer active |
| Void-Failure to File | Voided for failure to file required reports |
| Void/AFF/Void | Administrative void variant |
| Intent to Dissolve: Tax | In the process of dissolution for tax reasons |
| Name Change | Entity name changed (transitional status) |
| Reserved Name | Applies to Name Reservation filings only |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the live portal |
| Company status | Yes | One of 12 published status values (see [Company Statuses](#company-statuses) above) |
| Registration date | Yes | Effective date of filing as published on the portal |
| State of incorporation | Trade Register Extract only | State or territory where the entity was originally formed; not returned in the `company` datapoint |
| Legal address | Yes | Principal office address (street, city, state, ZIP) |
| Legal form | Yes | One of 14 Filing Type values with ISO 20275 mapping where available |
| Legal representatives | Yes | Officers and directors with name, mailing address, and role title |
| Registered agent | Yes | Agent name and address from the live portal (returned under `otherKeyPersons`) |
| Name history | Trade Register Extract only | Previous legal names and aliases; not returned in the `company` datapoint |
| Trade Register Extract | Yes | Printable detail page included at no extra charge with company data |
| Articles of Organization / Incorporation | Yes | Formation Form PDF from the register filing history, ordered separately |
| Annual Report | Yes | Annual Report PDF from the register filing history, ordered separately |
| Amendment / Other Filing | Yes | Amendments, mergers, reinstatements, and other filings from the register history, ordered separately |
| Activity codes | No | Not published by the Secretary of State |
| Shareholders | No | Not collected by the Mississippi business register |
| UBOs | No | No state beneficial-ownership register; the federal database is restricted |
| Financial data | No | Not collected |
The Trade Register Extract is a printed PDF of the current entity detail page from the Secretary of State portal, included with every company data request at no extra charge. Filed documents (Formation Form, Annual Reports, Amendments, and other filings) are ordered separately. See the [pricing page](https://topograph.co/pricing/us-ms) for the full document catalog.
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MS&query=Delta+Power" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "104297",
"legalName": "DELTA POWER COMPANY",
"countryCode": "US-MS",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by Business ID
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-MS&query=104297" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "104297",
"legalName": "DELTA POWER COMPANY",
"countryCode": "US-MS",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"countryCode": "US-MS",
"id": "104297",
"dataPoints": ["company", "legalRepresentatives"],
"mode": "verification"
}'
```
```json theme={null}
{
"company": {
"id": "104297",
"countryCode": "US-MS",
"identifiers": { "businessId": "104297" },
"legalName": "DELTA POWER COMPANY",
"registrationDate": "1982-06-15",
"legalForm": {
"localName": "Business Corporation",
"standardized": "Corporation"
},
"status": { "localName": "Good Standing", "active": true },
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Jackson",
"region": "MS",
"postalCode": "39201",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "President",
"standardized": "President"
},
"individual": {
"name": { "fullName": "Jane A. Smith" }
}
}
]
}
```
# Missouri (US)
Source: https://docs.topograph.co/essentials/us-missouri
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Missouri (US) reference is on the [Missouri (US) country page](https://www.topograph.co/countries/us-mo).
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Company Status](#company-status)
* [Data Availability](#data-availability)
This jurisdiction is in beta. Check the [live pricing page](https://topograph.co/pricing/us-mo) or contact support before relying on it in production. `US-MO` is accepted by the API but is not yet listed in the public `countryCode` enum of the OpenAPI spec.
## Data Sources
Missouri data is sourced from the **Missouri Secretary of State — Business Filings register**, the official register of every entity formed or qualified to do business in Missouri. The register returns legal name, Business Identification Number, entity type, status, formation date, domestic/foreign classification, home jurisdiction, registered agent, multiple office addresses, and a full filing history. Missouri supports verification mode only: requests using `mode: "prefill"` return a `fast_source_unavailable` error. Use `mode: "verification"` (or omit the mode to get the default).
**No bulk feed.** Missouri does not publish a bulk dataset, so every
lookup queries the register directly.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| BIN | `<1–2 letters>`, 9 characters | `F00214431` | Missouri Business Identification Number (charter number) — the public identifier on every filing. |
| BIN (older corporations) | 8 digits, no prefix, leading zeros included | `00333672` | Older for-profit corporations carry a numeric charter number with no letter prefix. |
| Topograph record id | `MOBSD-` + the register record number | `MOBSD-551157` | Returned by name search for the results whose charter number was not resolved (all results after the first few). Accepted by `/v2/company` and `/v2/search`; the response carries the charter number as `company.id`. |
| BIN (LLC) | `LC` / `FL` | `LC1026096` | `LC` for Missouri-formed LLCs, `FL` for out-of-state LLCs qualified in Missouri. |
| BIN (Non-profit) | `N` | `N00004847` | Non-profit corporations formed under Missouri non-profit corporation law. |
| BIN (Credit Union) | `H` | `H00131674` | Missouri-chartered credit unions. |
| BIN (Fictitious Name) | `X` | `X00358856` | Fictitious Name (DBA) registration — not a separate legal entity. |
### BIN prefix → entity type
| Prefix | Entity type |
| - | - |
| `F` | General Business Corporation (for-profit) |
| `LC` | Domestic Limited Liability Company |
| `FL` | Foreign Limited Liability Company qualified in Missouri |
| `N` | Nonprofit Corporation |
| `H` | Credit Union |
| `X` | Fictitious Name registration (DBA) |
| `LP` | Limited Partnership / Limited Liability Partnership |
| `K` | Bank |
| `B` | Benevolent corporation |
| `O` | Insurance company |
| none | Older General Business Corporation (8 digits, e.g. `00333672`) |
The prefix is informational and the list is not closed; the authoritative entity type is read from the entity record itself.
Name search resolves the charter number of its first few results only. The others carry a Topograph id, `MOBSD-` followed by the register's internal record number (e.g. `MOBSD-551157`). Pass it to `/v2/company` unchanged: the company comes back under its charter number (`FL0029123` for that example). A bare record number is not accepted, because it cannot be told apart from a charter number typed without its letters.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
Topograph exposes two search modes for Missouri:
* **Business Name**: 2 to 200 characters, matched with the register's default name search.
* **BIN**: exact-match lookup on the public Business Identification Number.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Registration-number lookups and the top name-search matches are filtered by status. Further name-search matches are returned whatever their status.
## Quirks & Gotchas
**No ownership filings.** Missouri does not require LLCs or corporations to
publish owner, member, manager, or officer information. The only
legal-representative record consistently published is the **registered
agent**. Officer and owner rows are populated almost exclusively for
Fictitious Name registrations.
**Registered Agent fallback.** When a foreign entity has lapsed its
registered agent, the register displays `Secretary of State` as the agent
of record. Topograph treats that value as "no agent on file" and returns
an empty `otherKeyPersons` array.
**Placeholder addresses on legacy records.** A small number of entities
filed before the SOS migrated to the current system (e.g. credit unions
chartered in the 1930s) carry the literal placeholder
`No Address to Migrate , ` in the address field. Topograph
returns the placeholder text in `legalAddress.addressLine1` and the state
code in `legalAddress.region`, and leaves `city` and `postalCode`
undefined on those records.
## Mappings
### Legal Forms
| Missouri register label | Topograph standardized form |
| - | - |
| Gen. Business - For Profit | Corporation |
| Limited Liability Company | LimitedLiabilityCompany |
| Nonprofit Corporation | NonprofitOrganization |
| Credit Union | Other |
| Fictitious Name | Other |
| Limited Partnership | Partnership |
| Limited Liability Partnership | Partnership |
| Limited Liability Limited Partnership | Partnership |
| Statutory Trust | Trust |
| Cooperative | Cooperative |
| Benefit Corporation | Corporation |
| Professional Corporation | Corporation |
### Company Status
| Missouri register label | Topograph `active` flag | Notes |
| - | - | - |
| Good Standing | `true` | Active corporation, non-profit, or credit union. |
| Active | `true` | LLC label for an in-compliance entity. |
| Fictitious Active | `true` | DBA registration is current. |
| Withdrawn | `false` | Foreign entity formally withdrew its Missouri qualification. |
| Fictitious Expired | `false` | DBA registration lapsed. |
| Admin Diss/Cancel - Report | `false` | Administratively dissolved for failure to file annual report. |
| Admin Diss/Cancel - Agent | `false` | Administratively dissolved for failure to maintain agent. |
| Inactive - Merged | `false` | Merged out of existence. |
| Inactive - Dissolved | `false` | Voluntarily dissolved. |
| Inactive - Revoked | `false` | Authority to do business revoked. |
| Inactive - Forfeited | `false` | Forfeited. |
## Data Availability
| Datapoint | Availability |
| - | - |
| `company` (core fields) | ✅ Always available. |
| `otherKeyPersons` (registered agent) | ✅ Always present except when the agent has lapsed. |
| `legalRepresentatives` | Not inferred from the Officer or Owner grids, which supply no company-specific signing powers. |
| `shareholders` | ❌ Not published by the Missouri register. |
| `ultimateBeneficialOwners` | ❌ No public beneficial-ownership data in Missouri. |
| `activityCodes` | ❌ Not published. |
| `taxId` | ❌ Not published. |
| `tradeRegisterExtract` document | ✅ Printable extract of the register's entity detail page, included with the company data. |
Named rows in the Officer and Owner grids are retained in `otherKeyPersons` as `Officer` and `Registered Owner`, respectively. The grid does not supply a more specific office title or prove authority to bind the entity.
# Montana (US)
Source: https://docs.topograph.co/essentials/us-montana
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Montana (US) reference is on the [Montana (US) country page](https://www.topograph.co/countries/us-mt).
## Start here
This guide contains public integration notes for Montana. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction is in beta. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Other Key Persons](#other-key-persons)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
Montana uses a single integration against the **Montana Secretary of State** via the public **SoS Business Search portal** at [biz.sosmt.gov/search/business](https://biz.sosmt.gov/search/business). This is the official online register for all business entities formed or qualified to do business in Montana, covering domestic and foreign corporations, limited liability companies, limited partnerships, limited liability partnerships, benefit corporations, professional corporations, nonprofit corporations, business trusts, and assumed business names.
* **Montana SoS** (prefill and verification, primary). Every request reads live against the register. Prefill mode uses a fast-response budget with fewer retry fallbacks, so on a transient register issue it may return less complete data or fail where verification would retry. Verification mode applies extra retry fallbacks for an authoritative result.
Montana does not publish a free bulk data extract. Every call returns the register's current state.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Montana SoS File Number** | One or two uppercase letters followed by 6 or 7 digits, no separator, leading zeros included | `F022568`, `C1548288`, `RN1064026` | The unique, constant identifier the Montana Secretary of State assigns to each entity at registration. State correspondence may print it with a hyphen after the letter (`D-123456`); the API returns and expects it without. |
The letter follows the entity type. In the records we have seen:
| Prefix | Entity type |
| - | - |
| `C` | Domestic Limited Liability Company |
| `D` | Domestic Corporation (profit or nonprofit) |
| `E` | Foreign Limited Liability Company |
| `F` | Foreign Corporation |
| `L` | Limited Partnership |
| `A` | Assumed Business Name |
| `RN` | Reservation of Name |
`P` and `N` are also in use. The list is not closed: accept any one or two uppercase letters followed by digits.
Entities with a `D`-prefix file number do not resolve correctly via the portal's prefill URL. These entities can still be found via name search.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `id` | Montana SoS file number | `F022568` | All entities |
| `identifiers.entityId` | Montana SoS file number | `F022568` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–250 chars | `"Walmart"` | Substring | Up to 50 |
| By File Number | 1 or 2 letters + 6 or 7 digits | `F022568` | Exact | Single entity |
Name search is case-insensitive and returns up to 50 results. File number search locates a single entity and is the recommended path when the number is known.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **D-prefix prefill limitation** | Entities with a `D`-prefix file number (domestic corporations) cannot be pre-filled via URL parameter. Use name search for these entities. |
| **No officers or directors** | The Montana SoS public portal does not expose officer or director data. Officer information is only available inside filed annual report PDFs and is not part of this integration. |
| **No shareholders or beneficial owners** | Shareholder and beneficial-ownership records are not collected at the state level. |
| **No activity codes** | The Montana SoS does not collect NAICS, NACE, or ISIC industry classifications. |
| **Registered agent detection** | The registered agent is classified as `type: "company"` when the name matches common commercial registered-agent keywords (CT Corporation, Cogency, Northwest Registered Agent, etc.) and as `type: "individual"` otherwise. |
| **Foreign entities: registrationDate is the qualification date** | For entities formed outside Montana, `registrationDate` holds the date they were authorised to do business in Montana. |
| **Previous names** | Former legal names are available in `legacyLegalNames` when the entity was previously known under a different name. |
## Mappings
### Company Status
The Status field is read verbatim from the entity detail panel. The table below covers the values observed in the register.
| Local Status | English Translation | Active |
| - | - | - |
| Active-Good Standing | Active — in good standing | Yes |
| Active-Not in Good Standing | Active — not in good standing | Yes |
| Inactive-Cancelled | Cancelled | No |
| Inactive-Withdrawn | Withdrawn | No |
| Inactive-Revoked | Revoked | No |
| Inactive Expired | Expired | No |
| Involuntary Dissolution | Involuntarily dissolved | No |
| Administrative Dissolution | Administratively dissolved | No |
| Dissolved | Voluntarily dissolved | No |
| Merged | Merged into another entity | No |
| Converted | Converted to another entity type | No |
| Cancelled Reserved Name | Reserved name cancelled | No |
| Expired Reserved Name | Reserved name expired | No |
Status values that begin with "Active" are treated as active regardless of good-standing qualification. All other values are treated as inactive.
### Legal Forms
The legal form is derived from the entity type string returned by the register.
| Local Name | English Translation | Standardized |
| - | - | - |
| Domestic Limited Liability Company | Montana Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Foreign Limited Liability Company | Limited Liability Company |
| Domestic Professional Limited Liability Company | Montana Professional Limited Liability Company | Limited Liability Company |
| Domestic Profit Corporation | Montana For-Profit Corporation | Corporation |
| Foreign Profit Corporation | Foreign For-Profit Corporation | Corporation |
| Domestic Benefit Corporation | Montana Benefit Corporation | Corporation |
| Foreign Benefit Corporation | Foreign Benefit Corporation | Corporation |
| Domestic Professional Corporation | Montana Professional Corporation | Corporation |
| Foreign Professional Corporation | Foreign Professional Corporation | Corporation |
| Domestic Nonprofit Corporation | Montana Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Corporation | Foreign Nonprofit Corporation | Nonprofit Organization |
| Domestic Limited Partnership | Montana Limited Partnership | Partnership |
| Foreign Limited Partnership | Foreign Limited Partnership | Partnership |
| Domestic Limited Liability Partnership | Montana Limited Liability Partnership | Partnership |
| Foreign Limited Liability Partnership | Foreign Limited Liability Partnership | Partnership |
| General Partnership | General Partnership | Partnership |
| Business Trust | Montana Business Trust | Trust |
| Foreign Business Trust | Foreign Business Trust | Trust |
| Assumed Business Name | Assumed Business Name (DBA) | Other |
| Reservation of Name | Reservation of Name | Other |
For entity types not in the table above, the legal form is resolved through AI enrichment and the standardized category may vary.
### Other Key Persons
Montana publishes only the registered agent on the public portal. It is returned as an `otherKeyPerson`, not as a `legalRepresentative`.
| Local Role Name | Standardized Role | Notes |
| - | - | - |
| Registered Agent | Registered Agent | Service-of-process designee. Can be a natural person or a commercial agent. |
## Statutory Filings
Montana entities file an annual report confirming the entity's particulars are current. The register publishes "AR Due Date", returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "dueDate": "2026-04-15" },
"source": "mt_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company profile | Yes | Legal name, file number, entity type, status, registration or qualification date, principal and mailing addresses, former names. |
| Registered agent | Yes | Returned as `otherKeyPersons` with the role "Registered Agent". Includes name and address. |
| Legal representatives | No | Officers and directors are not published on the Montana SoS public portal. |
| Shareholders | No | Not collected by Montana at the state level. |
| Ultimate beneficial owners | No | Montana does not maintain a public UBO register. |
| Activity codes | No | The Montana SoS does not collect NAICS, NACE, or ISIC codes. |
| Trade Register Extract | Yes | Printed PDF of the Montana SoS entity detail panel, captured at request time. Included with the company-data block. |
## Documents
### Available Documents
| Document | Availability | Format | Notes |
| - | - | - | - |
| **Trade Register Extract** | Always available | PDF | Printed capture of the Montana SoS entity detail panel. Included at no extra charge with the company-data block. |
Certificate of Existence and other official certificates require a portal account and a payment to the Montana Secretary of State. They are not yet supported through Topograph. Contact support if you need certified copies.
## Example API Responses
### Search by Name
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-MT&query=glacier" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "C1548288",
"legalName": "GLACIER BANCORP, INC.",
"countryCode": "US-MT",
"matchReason": { "matchType": "default" }
},
{
"id": "F087432",
"legalName": "GLACIER HILLS TRUCKING, INC.",
"countryCode": "US-MT",
"matchReason": { "matchType": "default" }
}
]
```
### Search by File Number
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-MT&query=F022568" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "F022568",
"legalName": "WAL-MART INC.",
"countryCode": "US-MT",
"matchReason": {
"matchType": "id",
"identifier": { "registrationNumber": "F022568" }
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MT", "id": "F022568", "dataPoints": ["company", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "F022568",
"countryCode": "US-MT",
"legalName": "WAL-MART INC.",
"registrationDate": "1991-10-07",
"status": {
"localName": "Active-Good Standing",
"active": true
},
"legalForm": {
"localName": "Foreign Profit Corporation",
"englishTranslation": "Foreign For-Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "1 CUSTOMER DR",
"city": "BENTONVILLE",
"postalCode": "72716",
"region": "AR",
"countryCode": "US"
},
"legacyLegalNames": ["WAL-MART STORES, INC."]
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"legalName": "CORPORATION SERVICE COMPANY",
"legalAddress": {
"addressLine1": "2601 PROSPECT AVE",
"city": "HELENA",
"postalCode": "59601",
"region": "MT",
"countryCode": "US"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "C1548288",
"countryCode": "US-MT",
"legalName": "GLACIER BANCORP, INC.",
"registrationDate": "2005-03-14",
"status": {
"localName": "Active-Good Standing",
"active": true
},
"legalForm": {
"localName": "Domestic Profit Corporation",
"englishTranslation": "Montana For-Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "49 COMMONS LOOP",
"city": "KALISPELL",
"postalCode": "59901",
"region": "MT",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"legalName": "CORPORATION SERVICE COMPANY",
"legalAddress": {
"addressLine1": "2601 PROSPECT AVE",
"city": "HELENA",
"postalCode": "59601",
"region": "MT",
"countryCode": "US"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "C0042771",
"countryCode": "US-MT",
"legalName": "MISSOULA HARDWARE, LLC",
"registrationDate": "1998-06-22",
"status": {
"localName": "Administrative Dissolution",
"active": false
},
"legalForm": {
"localName": "Domestic Limited Liability Company",
"englishTranslation": "Montana Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "320 N HIGGINS AVE",
"city": "MISSOULA",
"postalCode": "59801",
"region": "MT",
"countryCode": "US"
}
},
"otherKeyPersons": []
}
```
### Available Documents
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MT", "id": "F022568", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_abc123",
"name": "Trade Register Extract",
"format": "pdf"
}
}
}
```
### Order a Trade Register Extract
Pass the document ID returned by `availableDocuments` in the `documents` array of a `/v2/company` request.
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MT", "id": "F022568", "documents": ["doc_tre_abc123"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_abc123",
"name": "Trade Register Extract",
"format": "pdf",
"url": "https://blob.core.windows.net/.../trade-register-extract.pdf"
}
}
}
```
# Nebraska
Source: https://docs.topograph.co/essentials/us-nebraska
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Nebraska reference is on the [Nebraska country page](https://www.topograph.co/countries/us-ne).
## Start here
This guide contains public integration notes for Nebraska. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction is in beta. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Status](#company-status)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
**API access:** `US-NE` is accepted by the API but is not yet listed in the public `countryCode` enum of the OpenAPI spec.
## Data Sources
Nebraska uses a single integration against the **Nebraska Secretary of State, Business Services Division**, retrieved live from the public Corporate and Business Search portal at `sos.nebraska.gov`.
The register covers every domestic and foreign entity filed under the Nebraska Revised Statutes: for-profit corporations (NRS Chapter 21, Nebraska Model Business Corporation Act), limited liability companies (NRS Chapter 21 Nebraska LLC Act), nonprofit corporations (NRS Chapter 21 Article 19), limited and general partnerships and limited liability partnerships (NRS Chapter 67), cooperatives (NRS Chapter 21 Article 27), state-chartered banks (NRS Chapter 8), and insurance companies (NRS Chapter 44).
Each entity is assigned a numeric SOS Account Number that serves as the primary identifier across every lookup. The register includes both active and inactive entities and exposes the corporate officer roster (or member/manager roster for LLCs), the principal-office address, the registered agent with their service-of-process address, and the biennial-report filing history.
**Verification-only.** Nebraska does not publish a free open-data bulk extract of the business register, so all requests resolve live against the public portal. Unlike some other US states, there is no fast prefill-mode path. Requests using `mode: "prefill"` return a `fast_source_unavailable` error. Use `mode: "verification"` (or omit the mode to get the default).
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **SOS Account Number** | Digits only, no separators. 7, 8 or 10 digits in the records we have seen; leading zeros are part of the number | `10214668`, `0527041`, `2103077754` | Primary identifier assigned by the Nebraska Secretary of State, Business Services Division. Pass it exactly as a search result returns it, leading zeros included. |
Pass the SOS Account Number exactly as the register assigns it. Use `/v2/search` first to retrieve the canonical identifier, then pass it to `/v2/company`. Searching by name or partial identifier is the supported discovery path.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `accountNumber` | Digits only, 7, 8 or 10 in the records we have seen | `10214668` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 3+ chars | `"Werner Enterprises"` | Starts-with (case-insensitive) | Multiple results |
| By SOS Account Number | Numeric | `1274939` | Exact | Single result (matchType: id) |
**Minimum length.** Name searches must contain at least three characters. Searches that match too many entities are rejected by the register with a "too large" response. Use more specific query strings to narrow results.
**Trade names and trademarks appear in search results.** The Nebraska register includes Trade Name, Trademark, and Service Mark registrations alongside operating legal entities. These rows carry `Entity Type` of "Trade Name", "Trademark", or "Service Mark" and have no officer roster or registered agent. Filter by entity type if your flow requires operating legal entities only.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Verification mode only** | Nebraska has no free open-data extract, so prefill mode is not supported. All requests resolve live against the public portal. Expect longer response times than states with snapshot-backed prefill paths. |
| **Status is binary** | The public portal exposes only two status values: `Active` and `Inactive`. Lifecycle sub-events (dissolution, withdrawal, reinstatement, revocation) are visible in the Filed Documents list on the entity detail page, not as separate status values. |
| **Trade names appear in search results** | Trade Name, Trademark, and Service Mark registrations are indexed alongside operating legal entities. These are name registrations, not legal persons; they carry no officers, no registered agent, and no shareholder ledger. |
| **No shareholder or UBO register** | Nebraska does not publish shareholders or beneficial owners for any entity type. |
| **No activity codes** | Industry classification codes (NAICS, NACE, ISIC) are not collected by the Nebraska business register. |
| **LLC governance is member/manager-based** | LLCs file Members and Managers rather than Presidents, Secretaries, and Treasurers. Member and Manager titles appear in `legalRepresentatives`; the registered agent appears in `otherKeyPersons`. |
| **Officer titles are free-text** | The portal surfaces officer positions as biennial-report-filed free-text strings. Common titles (President, Secretary, Treasurer, Director, Member, Manager) are normalized deterministically. Unrecognized titles are returned in `legalRepresentatives` with the local title only and no standardized role. |
| **Biennial report cadence** | Corporations and LLCs file biennial reports in odd-numbered years. Officer data reflects the most recent biennial filing. Entities that have not yet filed their current cycle report may carry stale officer data. |
## Mappings
### Legal Forms
Legal form is read from the "Entity Type" field on each entity's detail page. The Nebraska Secretary of State uses a closed vocabulary tied to the governing statute chapter.
| NE Entity Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Domestic Corp | Domestic Corporation | Corporation | `RH6N` |
| Foreign Corp | Foreign Corporation | Corporation | `8HNT` |
| Non Profit (Dom) Corp | Domestic Nonprofit Corporation | Nonprofit Organization | `R7JP` |
| Non Profit (For) Corp | Foreign Nonprofit Corporation | Nonprofit Organization | `O256` |
| Domestic LLC | Domestic Limited Liability Company | Limited Liability Company | `8APW` |
| Foreign LLC | Foreign Limited Liability Company | Limited Liability Company | `5OET` |
| Domestic LP | Domestic Limited Partnership | Partnership | `DFPP` |
| Foreign LP | Foreign Limited Partnership | Partnership | `YWK0` |
| Domestic LLP | Domestic Limited Liability Partnership | Partnership | `YQDQ` |
| Foreign LLP | Foreign Limited Liability Partnership | Partnership | `MPFG` |
| Cooperative | Cooperative | Cooperative | N/A |
| Bank | Bank | Corporation | N/A |
| Insurance Company | Insurance Company | Corporation | `T172` |
| Trade Name | Trade Name / Fictitious Name | Other | N/A |
| Trademark | Trademark | Other | N/A |
| Service Mark | Service Mark | Other | N/A |
Trade Name, Trademark, and Service Mark entries carry no ISO 20275 code. They are name registrations, not operating legal entities. Cooperative and Bank have no active Nebraska ISO 20275 code either.
### Officer Roles
The Nebraska portal surfaces officer positions as free-text "Corporation Position" or "Member Position" strings from each entity's biennial-report filing. Common titles are normalized deterministically. Titles outside the table below are returned in `legalRepresentatives` with the local title in `role.localName` and no standardized role.
| Common Position | Standardized | Appears In |
| - | - | - |
| President, CEO, Chairman | Director | `legalRepresentatives` |
| Vice President (all variants) | Director | `legalRepresentatives` |
| Treasurer, CFO | Treasurer | `legalRepresentatives` |
| Secretary | Secretary | `legalRepresentatives` |
| Other Chief Officer titles | Director | `legalRepresentatives` |
| Member, Managing Member, Manager | Director | `legalRepresentatives` |
| Director, Board Member, Trustee | Board Member | `otherKeyPersons` |
| Registered Agent | Registered Agent | `otherKeyPersons` |
| Incorporator | Other (local title kept in `role.localName`) | `otherKeyPersons` |
| Organizer | Other (local title kept in `role.localName`) | `otherKeyPersons` |
The registered agent is returned in `otherKeyPersons` with their service-of-process address. It receives service of process and has no authority to bind the entity.
### Company Status
The Nebraska public portal exposes exactly two status values. Lifecycle sub-classifications (dissolution, withdrawal, revocation, reinstatement, merger) are not surfaced as status variants; they appear as entries in the Filed Documents list.
| NE Status | Active | Notes |
| - | - | - |
| Active | Yes | In good standing with the Nebraska Secretary of State |
| Inactive | No | Covers dissolved, forfeited, withdrawn, and suspended entities. The specific lifecycle event is recorded in the Filed Documents list. |
## Statutory Filings
Nebraska entities file a biennial report confirming the entity's particulars are current. The register publishes "Next Report Due", returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "biennial",
"next": { "dueDate": "2027-04-01" },
"source": "us_ne_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the Nebraska SoS register |
| Company status | Yes | Active or Inactive (binary; see Quirks) |
| Registration date | Yes | Original filing date with the Nebraska SoS |
| Legal address (principal office) | Yes | Street address, city, state, ZIP |
| Legal form | Yes | Closed vocabulary tied to NRS statute chapter |
| Legal representatives | Yes | Officers (corporations) or members/managers (LLCs), normalized from biennial-report filings |
| Registered agent | Yes | Returned in `otherKeyPersons` with service-of-process address |
| Activity codes | No | Not collected by the Nebraska business register |
| Shareholders | No | Not published |
| UBOs | No | Not published |
| Trade Register Extract | Yes | Printable PDF of the SoS detail page, bundled with the data request at no extra charge |
| Certificates of Good Standing | Roadmap | Paid documents sold through the Nebraska SoS portal; not yet available via the API |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-NE&query=Werner+Enterprises" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0658200",
"legalName": "WERNER ENTERPRISES, INC.",
"countryCode": "US-NE",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "NE",
"countryCode": "US"
}
}
]
```
### Search by SOS Account Number
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-NE&query=1274939" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1274939",
"legalName": "ACME HOLDINGS, INC.",
"countryCode": "US-NE",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NE", "id": "1274939", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "1274939",
"countryCode": "US-NE",
"identifiers": { "accountNumber": "1274939" },
"legalName": "ACME HOLDINGS, INC.",
"status": { "localName": "Active", "active": true },
"registrationDate": "2001-03-15",
"legalForm": {
"localName": "Domestic Corp",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "123 PLACEHOLDER DRIVE",
"city": "OMAHA",
"region": "NE",
"postalCode": "68102",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"individual": {
"name": { "fullName": "Jane Placeholder" }
},
"role": {
"localName": "PRESIDENT",
"standardized": "Director"
}
}
]
}
```
# Nevada
Source: https://docs.topograph.co/essentials/us-nevada
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Nevada reference is on the [Nevada country page](https://www.topograph.co/countries/us-nv).
## Start here
This guide contains public integration notes for Nevada. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction is in beta. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Company Statuses](#company-statuses)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
**API access:** `US-NV` is accepted by the API but is not yet listed in the public `countryCode` enum of the OpenAPI spec.
## Data Sources
Nevada uses a single integration against the **Nevada Secretary of State, SilverFlume Business Portal** (`esos.nv.gov/EntitySearch/OnlineEntitySearch`). The portal indexes every corporation, LLC, limited partnership, business trust, nonprofit, and other commercial entity registered under the Nevada Revised Statutes.
Unlike many US states, Nevada publishes the full officer roster on the free public entity page. Every officer, director, and manager reported on the most recent annual or amended list is visible without any paid tier. This means a single request powers company data, legal representatives, and the registered agent together.
Verification mode reads the register live for an authoritative result. Prefill mode returns right away from a periodic snapshot of the register, so very recent filings may not yet be reflected; an entity missing from the snapshot is read live instead.
**Nevada Business Entity Extract included.** Every company data request also delivers the printable **Nevada Business Entity Extract** (a PDF of the SilverFlume entity page) at no extra charge. No separate document purchase is needed.
## Company Identifiers
### Query Identifiers
| Identifier | Format | Example | Notes |
| - | - | - | - |
| **Entity Number** | Letter prefix, digits, a hyphen and a numeric suffix. Current numbering: `E` + 10 or 11 digits + `-` + 1 digit (`E0082262010-4`). Older entities: a letter prefix such as `C`, `LLC` or `LP`, up to 5 digits, `-` and 4 digits (`C14059-2002`) | `LLC1688-2002` | Primary identifier assigned by the Nevada Secretary of State. The register publishes no list of prefixes, so treat the set as open. |
| **NV Business ID** | `NV` followed by 11 digits, no separators | `NV20021018811` | Cross-agency identifier shared with the Nevada Department of Taxation. Accepted as an alternative search input. |
Both the Entity Number and the NV Business ID are accepted as query inputs. The Entity Number is the primary key. Pass it exactly as a search result returns it, with its letter prefix and hyphenated suffix. Stripping the prefix or suffix will not resolve correctly.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | Letter prefix, digits, `-` and a numeric suffix (`E0082262010-4`, `C14059-2002`) | `LLC1688-2002` | All entities |
| `nvBusinessId` | `NV` + 11 digits | `NV20021018811` | Most entities (not present on all records) |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2+ chars | `"Wynn"` | Snapshot match and live starts-with (case-insensitive) | Multiple results |
| By Entity Number | Letter prefix, digits, `-` and suffix | `LLC1688-2002` | Exact | Single match (`matchType: id`) |
| By NV Business ID | `NV` + 11 digits | `NV20021018811` | Exact | Single match (`matchType: id`) |
**Name search combines two result sets.** Results from the periodic register snapshot arrive first. Results from the live register, which match entities whose legal name begins with the query (a query for `"Wynn"` returns names beginning with `Wynn`), arrive later and include entities filed since the last snapshot. Use longer query strings to narrow results. An Entity Number or NV Business ID query is treated as an identifier lookup, not a name search.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Entity Number prefix is load-bearing** | Entity Numbers start with letters that are part of the number (`E`, `C`, `LLC` and `LP` in the records we have seen). Do not strip or normalise the prefix: the register treats `LLC1688-2002` and `1688-2002` as different (unresolvable) keys. |
| **SilverFlume renders type codes in the legal form label** | The portal displays entity type as `"Domestic Corporation (78)"` where `78` is an internal code. `legalForm.localName` keeps the label as the portal shows it, including the trailing code; `standardized` and `iso20275Code` are resolved from the label without the code. |
| **Name Reservation is not a legal entity** | SilverFlume can return a `Name Reservation` entry when someone has reserved a name before forming an entity. These records have no officers, no formation date, and no legal form. Querying a Name Reservation ID returns a 404. |
| **Officers reflect the most recent annual list** | Nevada requires an annual list of officers (due each anniversary month). The officers shown are from the last filed annual or amended list, which may be up to a year old. Entities in `Default` status have missed at least one annual list. |
| **No shareholders or UBO register** | Nevada does not publish ownership or beneficial ownership data for any entity type. |
| **No activity codes** | Industry classification (NAICS, SIC) is not collected by the Nevada business register. |
| **Sole proprietors are county-level** | Sole proprietors and doing-business-as filings are registered at county level and are not indexed by the state register. |
| **Compliance Hold flag** | Entities with a Compliance Hold have an outstanding obligation (typically a business licence fee) with the state. The flag is not currently returned by the API. |
## Mappings
### Legal Forms
Legal form is sourced from the `Entity Type` field on the SilverFlume entity page. The vocabulary is a closed set derived from the Nevada Revised Statutes (Chapters 78, 82, 86, 87, 87A, 88, 88A, 89, and 116). Each form is paired with a Topograph standardized category and, where a matching code exists, a GLEIF ISO 20275 ELF code for the US-NV jurisdiction.
The full 31-value table with ISO 20275 codes is available on the [pricing page](https://topograph.co/pricing/us-nv). A representative sample:
| SilverFlume Entity Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Corporation | Corporation | `8WM4` |
| Foreign Corporation | Corporation | |
| Domestic Close Corporation | Corporation | `8WM4` |
| Domestic Professional Corporation | Corporation | `8WM4` |
| Domestic Nonprofit Corporation | Nonprofit Organization | `IY8C` |
| Foreign Nonprofit Corporation | Nonprofit Organization | |
| Domestic Nonprofit Cooperative Corporation | Nonprofit Organization | `IY8C` |
| Domestic Corporation Sole | Nonprofit Organization | `IY8C` |
| Domestic Limited-Liability Company | Limited Liability Company | `MM8M` |
| Foreign Limited-Liability Company | Limited Liability Company | |
| Domestic Professional LLC | Limited Liability Company | `MM8M` |
| Domestic Restricted LLC | Limited Liability Company | `MM8M` |
| Domestic Series LLC | Limited Liability Company | `MM8M` |
| Domestic Limited Partnership | Partnership | `62L3` |
| Foreign Limited Partnership | Partnership | |
| Domestic Limited-Liability Partnership | Partnership | `7K6U` |
| Domestic Limited-Liability Limited Partnership | Partnership | `7K6U` |
| Domestic General Partnership | Partnership | |
| Domestic Business Trust | Trust | `SUEQ` |
| Domestic Real Estate Investment Trust | Trust | `SUEQ` |
| Common-Interest Community | Nonprofit Organization | |
The full enum, including all foreign variants and remaining domestic sub-forms, is on the [Nevada pricing page](https://topograph.co/pricing/us-nv).
### Company Statuses
Statuses are sourced directly from the SilverFlume `Entity Status` field. The full list of 13 values:
| Status | Active | Notes |
| - | - | - |
| Active | Yes | Entity is in good standing |
| Default | No | Missed an annual list or licence filing |
| Revoked | No | Authorisation revoked by the state |
| Permanently Revoked | No | Revocation is final and cannot be reinstated |
| Dissolved | No | Entity has been dissolved |
| Expired | No | Term-limited entity whose term has elapsed |
| Merged | No | Entity merged into another entity |
| Converted | No | Entity converted to a different legal form |
| Surrendered | No | Foreign entity has withdrawn its Nevada registration |
| Cancelled | No | Filing cancelled (e.g. limited partnership) |
| Withdrawn | No | Entity withdrew its state registration |
| Forfeited | No | Charter forfeited by the state |
| Suspended | No | Entity suspended from doing business |
## Statutory Filings
Nevada entities file an annual report confirming the entity's particulars are current. The register publishes "Annual Report Due Date", returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "dueDate": "2026-09-30" },
"source": "us_nv_sos_silverflume"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from SilverFlume |
| Company status | Yes | Closed 13-value enum including Default, Revoked, Dissolved, and Merged |
| Registration date | Yes | Formation date as published on the entity page |
| Legal address | No | Not published on the free entity page |
| Legal form | Yes | Closed enum mapped to Topograph standard + ISO 20275 where available |
| Legal representatives | Yes | Officers and managers from the most recent annual or amended list |
| Registered agent | Yes | Name and address of the registered agent |
| Activity codes | No | Not collected by the Nevada business register |
| Shareholders | No | Not published |
| UBOs | No | Not published (federal beneficial ownership data is restricted) |
| Trade Register Extract | Yes | Nevada Business Entity Extract (PDF of the SilverFlume entity page), included at no extra charge |
| Financial data | No | Not collected |
| Sole proprietors | No | Registered at county level, not indexed by the state register |
## Example API Responses
### Search by Name
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-NV&query=Wynn" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "LLC1688-2002",
"legalName": "ACME NEVADA VENTURES, LLC",
"countryCode": "US-NV",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "NV",
"countryCode": "US"
}
}
]
```
### Search by Entity Number
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-NV&query=LLC1688-2002" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "LLC1688-2002",
"legalName": "LLC1688-2002",
"countryCode": "US-NV",
"matchReason": {
"matchType": "id"
}
}
]
```
An identifier match echoes the identifier in `legalName`. The legal name is returned once the profile is fetched with `/v2/company`.
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NV", "id": "LLC1688-2002", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "LLC1688-2002",
"countryCode": "US-NV",
"identifiers": {
"entityNumber": "LLC1688-2002",
"nvBusinessId": "NV20021018811"
},
"legalName": "ACME NEVADA VENTURES, LLC",
"incorporationDate": "2002-02-14",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Domestic Limited-Liability Company",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "MM8M"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"individual": {
"name": { "fullName": "JANE PLACEHOLDER" }
},
"role": {
"localName": "Managing Member",
"standardized": "Manager"
}
}
]
}
```
# New Hampshire
Source: https://docs.topograph.co/essentials/us-new-hampshire
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date New Hampshire reference is on the [New Hampshire country page](https://www.topograph.co/countries/us-nh).
## Start here
This guide contains public integration notes for New Hampshire. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Statuses](#company-statuses)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
New Hampshire uses a single live integration against the **New Hampshire Department of State, QuickStart Business Register** (`quickstart.sos.nh.gov`). The register is the official record for every domestic and foreign for-profit and nonprofit corporation, limited liability company, limited partnership, limited liability partnership, professional limited liability company, professional association, trade name, and trademark filed in New Hampshire.
**Live-only.** The New Hampshire Department of State does not publish a free open-data feed or bulk CSV export. Per-snapshot XML extracts are available only via a paid authenticated subscription. Every lookup resolves live against the QuickStart register. There is no non-authoritative fast path.
Each entity record published by the register includes: legal name, NH Business ID, business type, current status, management style (LLC), citizenship of formation, business creation date, home-jurisdiction formation date, principal and mailing addresses, annual-report years, NAICS principal-purpose rows, the full list of officers and directors with titles and business addresses, and the registered agent with office and mailing addresses.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **NH Business ID** | Digits only, variable length, no leading zeros (5 to 7 digits in the records we have seen). Some older corporations: the letter `B` followed by 5 digits | `848218`, `39831`, `B02109` | Assigned by the Department of State at filing time, also called the Charter Number. Unique across all entity types: corporations, LLCs, limited partnerships, trade names, and trademarks share the same number space. |
The NH Business ID has no fixed length and no leading zeros. Values in our search results run from 5 to 7 digits, and some older corporations carry a legacy ID made of the letter `B` and 5 digits. Pass the ID exactly as a search result returns it.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityId` | Digits only, or `B` + 5 digits on some older corporations | `848218` | All entity types |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Granite State"` | Contains (case-insensitive) | Multiple results; capped at 50 |
| By NH Business ID | Numeric | `848218` | Exact | One result; `matchType: id` |
Name search matches anywhere in the legal name (case-insensitive). To narrow results, use a more specific query. The result set is capped at 50 matches.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No open-data snapshot** | Every request resolves live against the QuickStart register. There is no non-authoritative fast mode, and there is no open-data baseline for prefill checks. |
| **Business ID is variable length** | NH Business IDs have no fixed digit count and no leading zeros. Do not zero-pad or truncate. Pass the value exactly as returned by search. |
| **Multiple register presentation formats** | The QuickStart register may present entity records in different formats depending on the entity type. The API normalizes all formats into the same response shape. |
| **No shareholders or UBOs** | New Hampshire does not publicly disclose individual shareholders or ownership percentages. No state beneficial-ownership register exists. |
| **No FEIN** | The federal employer identification number is not disclosed through the public QuickStart register. |
| **Trade Names have no Principals grid** | Trade Name entities do not list officers. The registering owner is returned as an `otherKeyPersons` entry with role "Owner". |
| **NAICS rows may be free-text** | The register may publish free-text business purposes instead of numeric codes. Meaningful text is returned in `activityDescription`. `OTHER` is not returned as a NAICS code. |
| **Annual report years, not full dates** | The register publishes the last and next annual report year as integers, not full dates. |
| **Certificate of Good Standing is a paid upgrade** | The official New Hampshire Certificate of Good Standing carries a register fee and is ordered and delivered separately from company data. See [Data Availability](#data-availability). |
## Mappings
### Legal Forms
Legal form is sourced from the "Business Type" field on the QuickStart Business Information detail page. The vocabulary is an empirical set observed from the live register (verified May 2026).
| Business Type (QuickStart) | Standardized | ISO 20275 |
| - | - | - |
| Domestic Profit Corporation | Corporation | `6M6O` |
| Foreign Profit Corporation | Corporation | |
| Domestic Nonprofit Corporation | Nonprofit Organization | `P3LZ` |
| Foreign Nonprofit Corporation | Nonprofit Organization | |
| Domestic Limited Liability Company | Limited Liability Company | `OJ9K` |
| Foreign Limited Liability Company | Limited Liability Company | |
| Domestic Limited Partnership | Partnership | `G66U` |
| Foreign Limited Partnership | Partnership | |
| Domestic Limited Liability Partnership | Partnership | `RCNI` |
| Foreign Limited Liability Partnership | Partnership | |
| Domestic Professional Limited Liability Company | Limited Liability Company | `OJ9K` |
| Foreign Professional Limited Liability Company | Limited Liability Company | |
| Domestic Professional Association | Other | |
| Trade Name | Other | |
| Trademark | Other | |
### Officer Roles
NH QuickStart publishes officer, director, manager, member, and partner titles verbatim on the detail page. Common titles are mapped to a standardized role label; novel or unusual titles are normalized through AI enrichment.
| Raw Title (QuickStart) | Standardized | Notes |
| - | - | - |
| President | President | |
| Vice President | Vice President | |
| Secretary | Secretary | |
| Treasurer | Treasurer | |
| Director | Director | |
| Incorporator | Director | |
| Manager | Manager | LLC manager-managed entities |
| Member | Owner | LLC member-managed entities |
| Organizer | Owner | |
| Partner | Partner | General partnerships |
| General Partner | General Partner | Limited partnerships |
| Limited Partner | Limited Partner | Limited partnerships |
| Chief Executive Officer / CEO | Chief Executive Officer | |
| Chairman | Chairman | |
| Principal | Chief Executive Officer | |
The registered agent is not returned as a Legal Representative. It is returned in `otherKeyPersons`. The agent receives service of process but has no statutory authority to bind the entity.
### Company Statuses
| Status (QuickStart) | Active |
| - | - |
| Active | Yes |
| Good Standing | Yes |
| Dissolved | No |
| Administratively Dissolved | No |
| Admin Dissolution | No |
| Administratively Suspended | No |
| Expired | No |
| Merged | No |
| Non-Qualified | No |
## Statutory Filings
New Hampshire entities file an annual report confirming the entity's particulars are current. The register publishes "Next Report Year" and "Last Annual Report Year", which are years rather than dates, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.year` and `lastFiled.year`. No day or month is invented.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "year": 2026 },
"lastFiled": { "year": 2025 },
"source": "us_nh_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
For the full and current list of available datapoints, documents, and their sources, see the [pricing page](https://topograph.co/pricing/us-nh).
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name as filed |
| Company status | Yes | From the live QuickStart register |
| Registration date | Yes | Business creation date recorded by the Department of State |
| Legal address | Yes | Principal office and mailing addresses |
| Legal form | Yes | Business type with standardized category and ISO 20275 mapping where available |
| Legal representatives | Yes | Officers, directors, managers, members, and partners with titles and business addresses |
| Registered agent | Yes | Name, registered office address, and mailing address |
| NAICS codes | Conditional | Numeric codes published in the register; no code is inferred from free-text purposes |
| Activity description | Conditional | Meaningful business-purpose text published by the register |
| Activity codes (NACE / ISIC) | No | Not collected by the Department of State |
| Shareholders | No | Not publicly disclosed |
| UBOs | No | No state register; federal database is restricted |
| Trade Register Extract | Yes | Printable PDF of the QuickStart business record, included at no extra charge with every company data call |
| Certificate of Good Standing | Yes (paid) | Official New Hampshire Certificate of Good Standing, ordered through the Department of State and delivered within minutes. Carries a register fee. See the [pricing page](https://topograph.co/pricing/us-nh). |
| Articles of Incorporation / filed documents | No | Available behind the authenticated NH-Login portal; not yet integrated |
| Financial data | No | Not collected |
| Fictitious names (DBAs) | Partial | Trade names associated with an entity appear only on the Trade Register Extract PDF, not in the company datapoint. Standalone trade-name entities are separately searchable by name or NH Business ID. |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NH&query=Granite" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "848218",
"legalName": "GRANITE STATE HOLDINGS, INC.",
"countryCode": "US-NH",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by NH Business ID
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NH&query=848218" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "848218",
"legalName": "GRANITE STATE HOLDINGS, INC.",
"countryCode": "US-NH",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NH", "id": "848218", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "848218",
"countryCode": "US-NH",
"identifiers": { "entityId": "848218" },
"legalName": "GRANITE STATE HOLDINGS, INC.",
"status": {
"localName": "Active",
"active": true
},
"registrationDate": "2010-03-15",
"legalForm": {
"localName": "Domestic Profit Corporation",
"englishTranslation": "General Business Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Concord",
"region": "NH",
"postalCode": "03301",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "President",
"standardized": "President"
},
"individual": {
"name": { "fullName": "Jane A. Doe" }
}
}
]
}
```
# New Jersey
Source: https://docs.topograph.co/essentials/us-new-jersey
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date New Jersey reference is on the [New Jersey country page](https://www.topograph.co/countries/us-nj).
## Start here
This guide contains public integration notes for New Jersey. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
New Jersey uses a single integration against the **New Jersey Division of Revenue and Enterprise Services (DORES)**, within the New Jersey Department of the Treasury. The register covers every domestic and foreign corporation, limited liability company, limited partnership, and non-profit registered in New Jersey.
Two tiers of data are available:
* **Free public Business Name Search** (prefill mode). DORES publishes a free, publicly accessible Business Name Search portal that returns five fields per entity: business name, 10-digit entity ID, home city, entity type, and incorporation date. This is used for fast prefill checks and company search. No officers, members, addresses, or status are included at this tier.
* **Paid Business Entity Status Report** (verification mode). A per-entity report purchased from the DORES Business Records Service. This is the authoritative source for current entity status, principal business address, and officers and directors with roles and residence addresses. The report is retrieved live from the register for each request and used to fill in the `company` and `legalRepresentatives` data; the report PDF itself is not returned.
New Jersey publishes no open bulk data. There is no state business-entity dataset on the New Jersey Open Data portal. The free DORES public search is the only no-cost path to company data.
**Filing lag.** Filings, amendments, and annual reports submitted to DORES may take up to two business days to appear in the public portal and status report. Very recently filed or amended entities may not yet be discoverable.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **NJ Entity ID** | Exactly 10 digits, no separators; leading zeros are part of the number | `0100307257`, `0400276378`, `6444850000` | Primary identifier assigned by DORES. Used to look up filings on the portal and to purchase paid business records. |
The NJ Entity ID is always exactly 10 digits, leading zeros included. Submitting an unpadded form (e.g. `100307257` instead of `0100307257`) will be rejected. Most entity IDs we have seen start with `0`, some do not (e.g. `6444850000`); the register publishes no meaning for the leading digits.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityId` | 10 digits, numeric, leading zeros preserved | `0100307257` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-100 chars | `"Prudential"` | Starts-with (case-insensitive) | Multiple results |
| By NJ Entity ID | 10 digits | `0100307257` | Exact | Exact match returned first (`matchType: id`); other results may follow |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use fuller query strings to narrow the result set, which is capped at 50 matches.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile. Search results carry no company status, so the active-only filter has no effect. Status is available on the company profile in verification mode.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Leading zeros are load-bearing** | Entity IDs are always exactly 10 digits with leading zeros. Never strip them: the register and our API treat `0100307257` and `100307257` as different keys. |
| **Free tier returns no status** | The DORES public search returns name, ID, city, entity type, and incorporation date only. Current status (active, suspended, dissolved, revoked) is only available through the paid Business Entity Status Report. |
| **Free tier returns no officers** | Officers, LLC members, and managers are not disclosed in the free public search. They are only included when the customer opts into verification mode, which purchases a per-entity Business Entity Status Report. |
| **No shareholder or UBO register** | New Jersey does not publish shareholders or beneficial owners for any entity type. |
| **No open bulk data** | There is no business-entity open-data export from DORES. Bulk access requires a paid commercial feed agreement with the register directly. |
| **No activity codes** | NAICS, NACE, or ISIC codes are not collected by the state business register. |
| **DBA names are not in the state register** | Doing-business-as names (fictitious names) are filed at the county clerk level in New Jersey and are not part of the state register dataset. |
| **2-business-day filing lag** | Newly filed or amended records may take up to two business days to appear in the portal and status report. |
| **No documents available** | Verification mode buys the Business Entity Status Report to fill in company and legal representative data, but the report PDF is not returned as a document. Standing certificates and certified copies of charter documents are not yet available through Topograph. |
## Mappings
### Legal Forms
Legal form is derived from the entity-type abbreviations surfaced by the DORES public Business Name Search. The abbreviation is the canonical value published by the register; NJ does not publish a numeric legal-form code. Eleven distinct abbreviations were observed across broad samples.
| DORES Abbreviation | Local Name | Standardized |
| - | - | - |
| `DP` | Domestic Profit Corporation | Corporation |
| `FR` | Foreign For-Profit Corporation | Corporation |
| `DB` | Foreign Corporation (legacy) | Corporation |
| `PA` | Professional Corporation | Corporation |
| `LLC` | Domestic Limited Liability Company | Limited Liability Company |
| `FLC` | Foreign Limited Liability Company | Limited Liability Company |
| `NP` | Domestic Non-Profit Corporation | Nonprofit Organization |
| `NF` | Foreign Non-Profit Corporation | Nonprofit Organization |
| `LP` | Limited Partnership | Partnership |
| `LF` | Foreign Limited Partnership | Partnership |
| `LLP` | Domestic Limited Liability Partnership | Partnership |
ISO 20275 ELF codes are not mapped for New Jersey. GLEIF ELF coverage for US sub-national entity types is incomplete, so no ELF codes are assigned. See the pricing page for the full legal forms table.
## Statutory Filings
New Jersey entities file an annual report confirming the entity's particulars are current. The register publishes "Last Annual Report Filed" and its year, on the **paid** Business Entity Status Report, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `lastFiled.filedOn` and `lastFiled.year`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"lastFiled": { "filedOn": "2025-03-14", "year": 2025 },
"source": "nj_dores"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Person Roles
Known report titles have fixed English and standardized meanings. Directors are other key persons with standardized `Board Member`; ordinary LLC members are other key persons with standardized `Other`, since membership alone gives no agency power under New Jersey law.
Officers and managers retain their office titles. Authority depends on the entity’s governing documents and individual grants. No sole or joint signing mode is inferred, and unknown principal titles are preserved as other key persons with standardized `Other`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Verification only | Included in the paid Business Entity Status Report. Not available in prefill mode. |
| Registration date | Yes | DORES initial incorporation date |
| Legal address | Verification only | Principal business address from the paid Business Entity Status Report. Home city only in prefill mode. |
| Legal form | Yes | 11-value DORES abbreviation vocabulary with standardized mapping |
| Legal representatives | Verification only | Officer, manager and managing-member titles from the Business Entity Status Report. Titles alone do not establish individual signing powers. |
| Other key persons | Verification only | Registered agent, directors, ordinary members and nonrepresenting principals from the Business Entity Status Report. |
| Activity codes | No | Not collected by the state business register |
| Shareholders | No | Not published |
| UBOs | No | Not published (no state-level beneficial ownership register) |
| Documents | No | The Business Entity Status Report bought in verification mode is used for company and legal representative data; the PDF is not returned. Standing certificates and certified copies are not yet available through Topograph. |
| Financial data | No | Not collected |
| DBA / fictitious names | No | Filed at county clerk level, not in the state register |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NJ&query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0400123456",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-NJ",
"matchReason": {
"matchType": "default"
},
"address": {
"city": "Newark",
"region": "NJ",
"countryCode": "US"
}
}
]
```
### Search by Entity ID
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NJ&query=0400123456" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0400123456",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-NJ",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile (Prefill Mode)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NJ", "id": "0400123456", "dataPoints": ["company"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "0400123456",
"countryCode": "US-NJ",
"identifiers": { "entityId": "0400123456" },
"legalName": "ACME HOLDINGS LLC",
"registrationDate": "2005-03-14",
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"city": "Newark",
"region": "NJ",
"countryCode": "US"
}
},
"legalRepresentatives": []
}
```
### Company Profile (Verification Mode)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NJ", "id": "0400123456", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "0400123456",
"countryCode": "US-NJ",
"identifiers": { "entityId": "0400123456" },
"legalName": "ACME HOLDINGS LLC",
"status": {
"localName": "Active",
"active": true
},
"registrationDate": "2005-03-14",
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "100 Main Street",
"city": "Newark",
"region": "NJ",
"postalCode": "07102",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Member"
},
"individual": {
"name": { "fullName": "Jane Sample" },
"residenceAddress": {
"city": "Princeton",
"region": "NJ",
"countryCode": "US"
}
}
}
]
}
```
Verification mode purchases a Business Entity Status Report from the DORES Business Records Service on a per-entity basis. This is a paid upgrade. See the pricing page for current pricing.
# New Mexico
Source: https://docs.topograph.co/essentials/us-new-mexico
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date New Mexico reference is on the [New Mexico country page](https://www.topograph.co/countries/us-nm).
## Start here
This guide contains public integration notes for New Mexico. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Company Statuses](#company-statuses)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
New Mexico uses a single integration against the **New Mexico Secretary of State SOS Enterprise (SOSE)** portal at `enterprise.sos.nm.gov/search/business`. This is the official canonical source for all New Mexico business filings since the Secretary of State's 2024 migration to the SOSE platform.
* **New Mexico Secretary of State (SOSE)** (live, authoritative). The public SOSE portal publishes legal name, Business ID, entity type and sub-type, status, initial filing date, formation jurisdiction, registered agent (name and address), directors and officers with titles, and alternate business names. Data is current as filings are accepted by the Secretary of State.
New Mexico is served live from SOSE for every request. There is a single source that is both fast enough for prefill and authoritative for verification, so `mode: "prefill"` and `mode: "verification"` return the same real register data. New Mexico does not publish a free bulk export, so unlike Iowa or Pennsylvania there is no separate cached tier: both modes hit the live register.
**Reporting cadence varies by entity type.** New Mexico LLCs are exempt from periodic reporting with the Secretary of State. For-profit corporations file a biennial report; non-profit corporations file annually. Officer and director data on SOSE reflects the most recently filed report, which may lag by up to two years for corporations and indefinitely for LLCs.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **NM SOS Business ID** (most entities) | 3 to 10 digits, no separators | `2070134` | Legacy low-numbered entities have short IDs (e.g. `913`, `14902`); modern auto-assigned IDs are zero-padded to 10 digits (e.g. `0008016169`). |
| **NM SOS Business ID** (many partnerships) | Letter prefix + 10 digits | `LPD2005092001` | Prefixes in use: `LPD` / `LPF` (limited partnership, domestic / foreign), `GPD` (general partnership), `LLD` (limited liability partnership), `LLLD` / `LLLF` (limited liability limited partnership, domestic / foreign). |
| **NM SOS Business ID** (older limited partnerships) | 4 digits + `NM` | `0806NM` | Returned by name search only. The register cannot look these numbers up by ID, so they cannot be retrieved with `/v2/company`. |
Leading zeros and letter prefixes are part of the identifier. Pass the Business ID exactly as search returns it. A zero-padded ID queried without its leading zeros (`8016169` instead of `0008016169`) resolves to no match rather than the entity, so use the canonical form from the search result.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `businessId` | 3 to 10 digits, a letter prefix + 10 digits for partnerships, or 4 digits + `NM` | `2070134`, `LPD2005092001` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"TXNM"` | Contains (case-insensitive) | Multiple results |
| By Business ID | 3-10 digits, or a letter prefix + 10 digits | `2070134`, `LPD2005092001` | Exact | Single result with `matchType: id` |
**Contains search.** Name search matches anywhere in the legal name (case-insensitive). Broad queries return up to 100 matches. Use more specific strings to narrow results.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies in a procedural status (for example a pending tax clearance or appeal), not in good standing, or that have only filed a statement of intent to dissolve are kept in filtered results.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Leading zeros are load-bearing** | Numeric Business IDs range from 3 to 10 digits, with leading zeros preserved on modern entities. Never strip them: `0008016169` and `8016169` are treated as different inputs, and the unpadded form resolves to no match. Pass the ID exactly as search returns it. |
| **Partnership IDs carry letters** | Many partnerships are numbered with a letter prefix and 10 digits (e.g. `LPD2005092001`), and some older limited partnerships with 4 digits and an `NM` suffix (e.g. `0806NM`). The register cannot look the `NM`-suffixed numbers up by ID, so those entities appear in name search but cannot be retrieved with `/v2/company`. |
| **Trade register extract coverage** | The extract is available for numeric Business IDs of 7 to 10 digits. Shorter numeric IDs and partnership IDs return no available documents. |
| **No open-data bulk feed** | New Mexico does not publish a Socrata or equivalent bulk export of registered businesses. Every search and profile request is resolved live from SOSE. Prefill mode is supported and served by the same live source (there is no separate cached tier), so it returns the same authoritative data as verification. |
| **Directors and officers are free-text strings** | The SOSE drawer publishes directors and officers as multi-line text blocks, one `Name: Role` entry per line. Titles are free-form (e.g. `Director`, `Manager`, `President`, `Organizer`, `Statutory Agent`). Director and officer entries are flattened into a single `legalRepresentatives` array. |
| **Registered agent in `otherKeyPersons`** | The registered agent is returned separately under `otherKeyPersons` (role: `Registered Agent`), not in `legalRepresentatives`. The agent name and address are parsed from the SOSE drawer. |
| **No shareholder or UBO register** | New Mexico does not collect shareholder rosters or beneficial-ownership information at the state level. The federal beneficial-ownership database is restricted. |
| **NAICS not surfaced** | New Mexico collects NAICS codes at filing time but does not publish them on the public business detail page. Activity codes cannot be returned. |
| **Alternate names not returned** | SOSE may show `Other Names` and `Alternate Business Names` for an entity. These appear on the Trade Register Extract only; they are not returned in the API response and are not separately searchable. |
| **Paid Certificate of Good Standing** | A Certificate of Good Standing (equivalent to a Certificate of Existence or Certificate of Status) can be ordered through the SOSE portal. The statutory fee varies by entity type. This document is planned as a paid upgrade and is not yet available through Topograph. |
| **Free Trade Register Extract included** | A printed PDF of the SOSE business detail drawer is included at no extra charge with every company data request. This is the `tradeRegisterExtract` document. |
## Mappings
### Legal Forms
Legal form is sourced from the Entity Type field on the SOSE business detail drawer. The taxonomy was enumerated from the live SOSE search form's Entity Type filter (\~40 distinct values). Domestic types are entities formed under New Mexico law; Foreign types are entities formed elsewhere and registered to do business in New Mexico.
The full list with ISO 20275 ELF codes is on the [pricing page](https://topograph.co/pricing/us-nm). A summary of the main categories is below.
| SOSE Entity Type (examples) | Standardized | ISO 20275 |
| - | - | - |
| Domestic Limited Liability Company | Limited Liability Company | `4YOA` |
| Foreign Limited Liability Company | Limited Liability Company | |
| Domestic Profit Corporation | Corporation | `VG3S` |
| Foreign Profit Corporation | Corporation | |
| Domestic Nonprofit Corporation | Nonprofit Organization | `W0U4` |
| Foreign Nonprofit Corporation | Nonprofit Organization | |
| Domestic Profit Professional Corporation | Corporation | `VG3S` |
| Domestic Profit Professional Association | Corporation | |
| Foreign Business Trust | Trust | |
| Domestic State Bank | Other | |
| Domestic Credit Union | Other | |
| Domestic Savings and Loan | Other | |
| Domestic Federal Savings Bank | Other | |
| Domestic Insurance Company (Mutual / Stock / General) | Other | |
| Domestic Rural Electric Cooperative | Cooperative | |
| Domestic Nonprofit Cooperative Association | Cooperative | |
| Domestic Nonprofit Telephone Cooperative Association | Cooperative | |
| Domestic Nonprofit Water Users Association | Cooperative | |
| Domestic Nonprofit Marketing Cooperative Association | Cooperative | |
| Domestic Sanitary Project Associations | Other | |
| Unqualified Entity | Other | |
Specialty sub-types (bank variants, insurance variants, and cooperative sub-categories) have no broadly applicable ISO 20275 ELF code and are left without one rather than over-committing to a generic US-national code. The precise SOSE label is always preserved as `localName`.
### Company Statuses
The SOSE portal publishes 41 distinct status values. The full list is on the [pricing page](https://topograph.co/pricing/us-nm). Key groupings:
| Status Group | Examples |
| - | - |
| Active | `Active`, `Good Standing`, `Registered`, `Re-Instatement`, `Business Transacted`, `Future Effective` |
| Inactive / dissolved | `Dissolved`, `Voluntary Dissolution`, `Admin Dissolution`, `Statement Of Intent To Dissolve`, `Suspension`, `Merged`, `Merged Out of Existence`, `Converted Out of Existence`, `Cancelled`, `Withdrawn`, `Revoked`, `Revoked Final`, `Expired`, `Existence Expired`, `Forfeited`, `Abandoned` |
| Procedural | `Tax Clearance`, `Process Of Appeal`, `Bankruptcy-Receivership`, `Late-Filer`, `Non-Filer`, `NOSTAT` |
## Statutory Filings
New Mexico entities file an annual report confirming the entity's particulars are current. The register publishes "AR Due Date" on the filing-detail drawer, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "dueDate": "2026-05-15" },
"source": "us_nm_sose"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Alternate / trade names | No | Other Names and Alternate Business Names appear on the Trade Register Extract only |
| Company status | Yes | 41-value SOSE taxonomy |
| Registration date | Yes | Initial filing date |
| Formation jurisdiction | No | Shown on the Trade Register Extract only |
| Legal address | Yes | Registered office address |
| Legal form | Yes | \~40-value SOSE taxonomy with ISO 20275 mapping for main structures |
| Legal representatives | Yes | Directors and officers from the SOSE drawer; free-text titles |
| Registered agent | Yes | Name and address, surfaced under `otherKeyPersons` |
| Trade Register Extract | Yes | Printed PDF of the SOSE business detail drawer, included at no extra charge |
| Activity codes | No | NAICS collected at filing but not published on the public profile |
| Shareholders | No | Not collected by the New Mexico Secretary of State |
| UBOs | No | No state-level beneficial-ownership register; federal database is restricted |
| Certificate of Good Standing | Roadmap | Paid document (register fee varies by entity type); planned as a future paid upgrade |
| Financial data | No | Not collected |
| Tax ID / EIN | No | Not published by the New Mexico Secretary of State |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NM&query=TXNM" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "7626037",
"legalName": "Heaven Scent TXNM LLC",
"countryCode": "US-NM",
"matchReason": { "matchType": "default" }
},
{
"id": "2070134",
"legalName": "TXNM Energy, Inc.",
"countryCode": "US-NM",
"matchReason": { "matchType": "default" }
}
]
```
### Search by Business ID
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NM&query=2070134" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "2070134",
"legalName": "TXNM Energy, Inc.",
"countryCode": "US-NM",
"matchReason": {
"matchType": "id",
"identifier": { "businessId": "2070134" }
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NM", "id": "2070134", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "2070134",
"countryCode": "US-NM",
"identifiers": { "businessId": "2070134" },
"legalName": "TXNM Energy, Inc.",
"registrationDate": "2000-03-03",
"status": { "localName": "Active", "active": true },
"legalForm": {
"localName": "Domestic Profit Corporation",
"englishTranslation": "Corporation",
"standardized": "Corporation",
"iso20275Code": "VG3S"
},
"legalAddress": {
"addressLine1": "1601 N. Turner St",
"addressLine2": "Suite 420",
"city": "Hobbs",
"region": "NM",
"postalCode": "88240",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Director", "standardized": "Director" },
"individual": { "name": { "fullName": "Maureen T. Mullarkey" } }
},
{
"entityId": "person_011",
"type": "individual",
"role": { "localName": "Vice President", "standardized": "Vice President" },
"individual": { "name": { "fullName": "Becky R Teague" } }
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"company": {
"legalName": "CORPORATION SERVICE COMPANY",
"countryCode": "US-NM",
"legalAddress": {
"addressLine1": "1601 N. Turner St",
"addressLine2": "Suite 420",
"city": "Hobbs",
"region": "NM",
"postalCode": "88240",
"countryCode": "US"
}
}
}
]
}
```
# New York (US)
Source: https://docs.topograph.co/essentials/us-new-york
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date New York (US) reference is on the [New York (US) country page](https://www.topograph.co/countries/us-ny).
## Start here
This guide contains public integration notes for New York. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Company Status](#company-status)
* [Officer Roles](#officer-roles)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
New York State data comes from the **New York Department of State, Division of Corporations**.
* **NYS Open Data snapshot**. A daily refresh of the DOS business entity database published at data.ny.gov. Used for company data, company search, and former name matching. Lag is at most one day.
**Live register access is temporarily unavailable.** Both `mode: "prefill"`
and `mode: "verification"` are currently served from the daily snapshot, so a
filing made since the last daily publication is not yet reflected. Work is
underway to restore live access.
**Biennial cadence.** New York corporations file a biennial statement every
two years. Officer and CEO data can lag up to 24 months behind ground truth.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **DOS ID** | 1 to 7 digits, no leading zeros | `30059` | NY Department of State primary identifier. Most entities have 6 or 7 digits; the oldest have fewer (e.g. `3707`). |
The DOS ID is the only identifier supported for company retrieval. To find a
DOS ID from a name, use the search endpoint first.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `dosId` | 1 to 7 digits, no leading zeros | `30059` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"International Busi"` | Fuzzy | Multiple results |
| By Former Name | 2-200 chars | `"Bell Atlantic"` | Fuzzy | Multiple results |
| By Assumed Name | 2-200 chars | `"Verizon"` | Fuzzy | Multiple results |
| By DOS ID | 1-8 digits | `30059` | Exact | Exact match returned first (matchType: id); other results may follow |
**Former name search.** Entities often change legal names. Searching for a
former name (for example `"Bell Atlantic"`) will surface the current entity
(`"Verizon Communications Inc."`) via the DOS name history dataset.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile. Name searches mostly draw on the register list of active companies, but inactive companies can still appear, notably in registration-number lookups and older name matches, and are not filtered out.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No LLC officer data** | New York DOS does not collect or publish LLC member, manager, or officer information. For LLC entities the legal-representatives response will always be empty. |
| **Corporations disclose CEO only** | Biennial statements only disclose the CEO of a corporation. Directors, Vice Presidents, Secretaries, and other officers are not published by DOS. |
| **No shareholder or UBO register** | New York does not publish shareholders or beneficial owners for any entity type. |
| **No activity codes** | DOS does not collect NAICS or industry codes. The NY Department of Taxation and Finance holds NAICS for tax purposes but does not publish it openly. |
| **DBAs live at county clerks** | Assumed name (DBA) filings go to the county clerk, not DOS. A mandatory 2-newspaper-for-6-weeks publication requirement makes many small businesses skip formal DBA filing. |
| **Certified documents are paid + mail** | Certified copies of formation documents and Good Standing certificates are paid (see [pricing](https://www.topograph.co/pricing)) and delivered by mail only. No electronic download of certified copies exists. |
| **Registered agent vs SOP address** | The registered agent is returned as an other key person. The service-of-process entry is an address, not a party: for most entities the register records the entity itself there ("THE CORPORATION", "THE LLC"), meaning process is mailed to the company, so no agent is returned from it. |
## Mappings
### Company Status
Status comes from the DOS entity status field, which uses four values. The value is returned as published in `localName`.
| Source Value | Active |
| - | - |
| `Active` | `true` |
| `Inactive` | `false` |
| `Suspended` | `false` |
| `Discontinued` | `false` |
### Legal Forms
Legal form is derived from the DOS `entity_type` field. Closed vocabulary of 84 values covering domestic and foreign variants of every supported entity class. ISO 20275 ELF codes are not mapped for New York.
| DOS Entity Type | Standardized |
| - | - |
| DOMESTIC BUSINESS CORPORATION | Corporation |
| FOREIGN BUSINESS CORPORATION | Corporation |
| DOMESTIC LIMITED LIABILITY COMPANY | Limited Liability Company |
| FOREIGN LIMITED LIABILITY COMPANY | Limited Liability Company |
| DOMESTIC LIMITED PARTNERSHIP | Partnership |
| FOREIGN LIMITED PARTNERSHIP | Partnership |
| DOMESTIC REGISTERED LIMITED LIABILITY PARTNERSHIP | Partnership |
| NEW YORK REGISTERED FOREIGN LIMITED LIABILITY PARTNERSHIP | Partnership |
| DOMESTIC NOT-FOR-PROFIT CORPORATION | Nonprofit Organization |
| FOREIGN NOT-FOR-PROFIT CORPORATION | Nonprofit Organization |
| DOMESTIC PROFESSIONAL SERVICE CORPORATION | Corporation |
### Officer Roles
The supported New York sources provide two named-contact categories, mapped deterministically: CEO and Registered Agent. The CEO office does not establish unrestricted signing authority; powers depend on bylaws and board authorization under [BCL §715(g)](https://www.nysenate.gov/legislation/laws/BSC/715). Sole or joint authority is not inferred.
| DOS Role | Standardized | Notes |
| - | - | - |
| CEO | Chief Executive Officer | Biennial statement, corporations only |
| Registered Agent | Registered Agent | Statutory service-of-process contact. Available for every entity type. |
The Registered Agent is classified as an Other Key Person, not a Legal
Representative, because it has no statutory authority to bind the entity.
An agent may be a **corporate service firm** (returned under `company`) or a
**named individual** (returned under `individual`), and both are common:
large corporations typically appoint a firm, while small LLCs frequently name
their own owner, attorney, or accountant. New York publishes the agent name
without stating which it is, so we derive the distinction from the name.
Expect it to be occasionally wrong for a firm whose name carries no company
designator.
## Statutory Filings
New York entities file a biennial report confirming the entity's particulars are current. The register publishes "Next Statement Due Date". New York files a biennial **statement**, not an annual report, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
`statutoryFilings` is not returned for New York while live register access is unavailable. The daily snapshot does not carry the next statement due date.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "biennial",
"next": { "dueDate": "2027-03-31" },
"source": "ny_dos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name plus former legal names (searchable) |
| Former names | Yes | From DOS name history dataset. Indexed for search. |
| Assumed names | No | Not returned in company data. County-clerk DBAs are out of scope. |
| Company status | Yes | 4-value DOS status vocabulary |
| Registration date | Yes | DOS initial filing date |
| Legal address | Yes | A single address: principal executive office where published, otherwise the service-of-process or registered agent address. |
| Legal form | Yes | Closed DOS entity-type vocabulary; no ISO 20275 mapping |
| Authorized stock | No | Not currently available while live register access is unavailable |
| Next biennial due date | No | Not currently available while live register access is unavailable |
| Filing history | No | Not returned |
| Merger history | No | Not returned |
| Legal representatives | Yes\* | Corporations return the CEO. LLCs, LPs, and not-for-profits return none. |
| Other key persons | Yes | The registered agent, with its address. Available for LLCs, LPs and LLPs, which disclose no officers. |
| Activity codes | No | Not collected by DOS |
| Shareholders | No | Not published |
| UBOs | No | Not published (federal CTA/FinCEN is a separate system) |
| Documents | Partial | A Trade Register Extract (printable DOS entity page) comes with company data at no extra charge. Certified copies and Good Standing certificates are paid and mailed only. |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NY&query=INTERNATIONAL+BUSINESS+MACHINES" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "30059",
"legalName": "INTERNATIONAL BUSINESS MACHINES CORPORATION",
"countryCode": "US-NY",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "NY",
"countryCode": "US"
}
}
]
```
### Search by Former Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NY&query=BELL+ATLANTIC" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1898443",
"legalName": "VERIZON COMMUNICATIONS INC.",
"countryCode": "US-NY",
"matchReason": {
"matchType": "default"
}
}
]
```
### Company Profile (Prefill Mode)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NY", "id": "30059", "dataPoints": ["company", "legalRepresentatives"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "30059",
"countryCode": "US-NY",
"identifiers": { "dosId": "30059" },
"legalName": "INTERNATIONAL BUSINESS MACHINES CORPORATION",
"registrationDate": "1911-06-16",
"status": { "localName": "Active", "active": true },
"legalForm": {
"localName": "Domestic Business Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"city": "ARMONK",
"region": "NY",
"countryCode": "US"
}
},
"legalRepresentatives": []
}
```
### Company Profile (Verification Mode)
Verification mode is currently served from the same daily snapshot as prefill mode and returns the same fields.
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NY", "id": "30059", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
# North Carolina
Source: https://docs.topograph.co/essentials/us-north-carolina
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date North Carolina reference is on the [North Carolina country page](https://www.topograph.co/countries/us-nc).
## Start here
This guide contains public integration notes for North Carolina. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Legal Representatives](#legal-representatives)
* [Other Key Persons](#other-key-persons)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
All entity data comes from the **North Carolina Secretary of State, Business Registration Division** ([sosnc.gov](https://www.sosnc.gov)). This is the official register for every domestic and foreign business entity in North Carolina, covering corporations, LLCs, partnerships, nonprofits, cooperatives, banks, insurance companies, and public authorities registered under the NC General Statutes.
Every request fetches data live from the register. There is no cached or batch-synced alternative for North Carolina.
North Carolina is a single-source country. All data — company profile,
officers, registered agent, documents, and search — comes from the NC
Secretary of State Business Registration Division.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **SOS ID** | Exactly 7 digits, no separators, left-padded with zeros | `0027238`, `3395486` | Assigned by NC SOS at formation or qualification, called SOSID on sosnc.gov. Every id in the records we have seen has 7 digits. |
The SOS ID is the only identifier supported for company retrieval. To find a
SOS ID from a name, use the search endpoint first. Both zero-padded
(`0027238`) and raw (`27238`) forms are accepted; values are always
normalized to 7 digits.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `sosId` | 7 digits, zero-padded | `0027238` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | Free-text string | `"Pinecrest Technologies"` | Any-word | Multiple results |
| By SOS ID | 7 digits (with or without leading zeros) | `0027238` | Exact | Exact match returned first (matchType: id); other results may follow |
Name search uses any-word matching against the NC SOS register: results
include entities that contain any of the words in the query. Searching by
SOS ID returns the exact match first with `matchReason.matchType = "id"`;
other results may follow.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Companies whose status is not clearly active or closed (for example suspended or reserved names) are kept in filtered results.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No shareholder register** | NC SOS does not collect or publish shareholder lists for any entity type. |
| **No UBO register** | No public beneficial ownership register exists at the North Carolina state level. |
| **No activity codes** | The NC SOS does not collect NAICS, NACE, or ISIC industry codes. |
| **No EIN / federal tax ID** | The federal Employer Identification Number is not published through the NC SOS. |
| **Non-profit officers not public** | Nonprofit Corporation (Chapter 55A) profiles do not include officers. `legalRepresentatives` is always empty for these entities. |
| **Officer roles are free-text** | Officer titles come from annual reports and are not validated for consistency. Common roles are mapped deterministically; rare or novel titles are standardized using AI enrichment. |
| **Corporate registered agents** | Registered agent companies (e.g. CT Corporation System, Corporation Service Company) appear as plain text without a link on the profile page; individual registered agents have a linked profile. Both are returned correctly in `otherKeyPersons`. |
| **Annual reports excluded from filings** | The filing list omits Annual Report filings. Only formation documents and other corporate acts (amendments, mergers, conversions, etc.) are included. |
| **No Certificate of Existence in v1** | The NC Certificate of Existence (equivalent to a Certificate of Good Standing) is not yet offered through Topograph. |
| **No bulk open data** | NC SOS does not publish a free open-data business register. All reads are live. Response times are typically 15–40 seconds. |
## Mappings
### Company Status
Status is sourced directly from the NC SOS portal and mapped deterministically. No AI inference is involved.
| NC SOS Status | Active | Notes |
| - | - | - |
| `Current-Active` | Yes | Standard in-good-standing status |
| `Current-Active AR Error` | Yes | Active but annual report has a processing error |
| `Active/Not Current` | Yes | Active but annual report not yet filed for current year |
| `Active/Failure to Pay Fee` | Yes | Active but fee outstanding |
| `In Process` | Yes | Formation in progress |
| `Admin. Cancelled` | No | Administratively cancelled by SOS |
| `Applied to Withdraw` | No | Foreign entity has applied to withdraw qualification |
| `Auto Dissolve` | No | Automatically dissolved for non-compliance |
| `Consolidated` | No | Merged into another entity (consolidation) |
| `Converted` | No | Entity has converted to a different legal form |
| `Court Ordered Dissolution` | No | Judicially dissolved |
| `Dissolved` | No | Voluntarily or administratively dissolved |
| `Expired` | No | Registration term expired (certain entity types) |
| `Failure to Pay Fee` | No | Lapsed for non-payment |
| `Judicial Dissolution` | No | Dissolved by court order |
| `Merged` | No | Merged into another entity |
| `Non-domesticated` | No | Foreign entity that never completed qualification |
| `Not Registered` | No | Entity not registered with NC SOS |
| `PA Suspended` | No | Suspended under professional association rules |
| `Reserved Name` | No | Name reservation only, no active entity |
| `Revoked Licensing Board` | No | Revoked by a professional licensing board |
| `To Federal Bank` | No | Converted to federal bank charter |
| `To Foreign Insurance Co` | No | Converted to foreign insurance company |
| `Withdrawn` | No | Foreign entity has withdrawn its NC qualification |
| `Withdrawn by Merger` | No | Foreign entity withdrawn as part of a merger |
### Legal Forms
NC SOS uses a closed list of 30 entity types from the Business Registration portal. Every type is mapped deterministically to a standardized category. No AI is involved.
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Limited Liability Company | Limited Liability Company | Limited Liability Company | `X1EL` |
| Professional Limited Liability Company | Professional Limited Liability Company (PLLC) | Limited Liability Company | — |
| L3C | Low-profit Limited Liability Company (L3C) | Limited Liability Company | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Business Corporation | Business Corporation | Corporation | `1QMT` |
| Professional Corporation | Professional Corporation (PC) | Corporation | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Non-Profit Corporation | Nonprofit Corporation | Nonprofit Organization | — |
| Non-Incorporated Non-Profit | Unincorporated Nonprofit Association | Nonprofit Organization | — |
| Non-Profit Community Trust | Non-Profit Community Trust | Nonprofit Organization | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Limited Liability Partnership | Limited Liability Partnership | Partnership | `X0MP` |
| Limited Partnerships | Limited Partnership | Partnership | `ARON` |
| RLLLP | Registered Limited Liability Limited Partnership | Partnership | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Cooperative Association | Cooperative Association | Other | — |
| Cooperative 54 16 | Cooperative (GS 54-16) | Other | — |
| Electric Membership Cooperative | Electric Membership Cooperative | Cooperative | — |
| Mutual Association | Mutual Association | Other | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Bank | State-Chartered Bank | Other | `5AAO` |
| National Banking Association | National Banking Association | Other | — |
| Mutual Deposit Guaranty Association | Mutual Deposit Guaranty Association | Other | — |
| Savings & Loan Association | Savings & Loan Association | Other | — |
| State Savings Bank | State Savings Bank | Other | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Insurance Company | Insurance Company | Other | — |
| Captive Insurance | Captive Insurance Company | Other | — |
| Dental Service Corporation | Dental Service Corporation | Corporation | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Municipal | Municipal Entity | Other | — |
| Public Transportation Authority | Public Transportation Authority | Other | — |
| Railroad | Railroad | Other | — |
| County Agricultural Fair | County Agricultural Fair | Other | — |
| NC SOS Type | English Name | Standardized | ISO 20275 |
| - | - | - | - |
| Mutual Burial Association | Mutual Burial Association | Other | — |
| Non-Domestic Tobacco | Non-Domestic Tobacco Entity | Other | — |
| Other | Other | Other | — |
### Legal Representatives
Officers are sourced from the entity's annual report filings. Directors, non-executive directors, independent directors, board chairs and limited partners are other key persons when no individual grant is reported. Common role titles are mapped deterministically to standardized roles. Titles not in the deterministic set are standardized using AI enrichment; the raw title is always preserved as `localName`.
| NC SOS Role Title | Standardized Role |
| - | - |
| President | President |
| Vice President | Vice President |
| Vice-President | Vice President |
| Senior Vice President | Vice President |
| Executive Vice President | Vice President |
| First Vice President | Vice President |
| Assistant Vice President | Vice President |
| Secretary | Secretary |
| Assistant Secretary | Secretary |
| Treasurer | Treasurer |
| Assistant Treasurer | Treasurer |
| Director | Board Member |
| Executive Director | Executive Director |
| Non-Executive Director | Non-Executive Director |
| Independent Director | Independent Director |
| CEO | Chief Executive Officer |
| Chief Executive Officer | Chief Executive Officer |
| Executive Officer | Other |
| CFO | Chief Financial Officer |
| Chief Financial Officer | Chief Financial Officer |
| Chief Accounting Officer | Other |
| Corporate Controller | Other |
| Controller | Other |
| COO | Chief Operating Officer |
| Chief Operating Officer | Chief Operating Officer |
| Chief Administrative Officer | Other |
| General Counsel | General Counsel |
| Chief Legal Officer | General Counsel |
| CLO | General Counsel |
| Chairman | Chairman of the Board |
| Chairperson | Chairman of the Board |
| Chair | Chairman of the Board |
| Vice Chairman | Vice Chairman of the Board |
| Chairman of the Board | Chairman of the Board |
| Authorized Representative | Authorized Signatory |
| Authorized Signer | Authorized Signatory |
| Authorized Agent | Authorized Signatory |
| Manager | Manager |
| Managing Member | Managing Director |
| Member | Other |
| Managing Partner | Managing Partner |
| General Partner | General Partner |
| Limited Partner | Other |
| Partner | Partner |
Officer titles not in the deterministic set are standardized using AI
enrichment. The raw title is always preserved in `role.localName`. Officers
are available for Business Corporations, LLCs, and partnerships. Nonprofit
Corporations (Chapter 55A) do not expose officers on the public profile page,
so `legalRepresentatives` is always empty for these entities.
Corporate officer powers depend on bylaws or board authorization. North Carolina LLC members are managers by default unless their operating agreement provides otherwise. Titles establish the office category, and no unrestricted, sole or joint signing power is inferred.
### Other Key Persons
The registered agent is always returned as an Other Key Person, regardless of whether the agent is an individual or a corporate entity.
| Role | Standardized | Notes |
| - | - | - |
| Registered Agent | Registered Agent | Statutory service-of-process contact; required for all NC-registered entities. Can be an individual or a corporate registered agent company. |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Legal name | Yes | Current legal name from the NC SOS profile |
| Previous names | No | Not currently returned |
| Company status | Yes | Mapped from NC SOS status field (see status table above) |
| Citizenship | No | Not currently returned |
| Registration date | Yes | Date of formation or qualification in NC |
| Legal address | Yes | Principal office address, geocoded |
| Mailing address | No | Not currently returned |
| Registered office address | No | Not currently returned |
| Legal form | Yes | From NC SOS entity type (30 forms) |
| Share capital | Yes | Authorized share classes with par value, for corporations |
| Legal representatives | Yes\* | Officers from annual reports. Always empty for Nonprofit Corporations. |
| Registered agent | Yes | Returned as Other Key Person |
| Filing history (documents) | Yes | Formation documents and other corporate acts — see Documents section |
| Activity codes | No | Not collected by NC SOS |
| Shareholders | No | Not published by NC SOS for any entity type |
| UBOs | No | No public state-level UBO register |
| Federal tax ID (EIN) | No | Not published by NC SOS |
| Financial data | No | Not collected |
## Documents
### Available Documents
| Document | API Category | Availability | Format | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | Always available | PDF | Printed PDF of the entity's public profile page from NC SOS |
| **Articles of Organization / Incorporation** | `articlesOfAssociation[]` | When filed and available in NC SOS imaging | PDF | Formation filing (Articles of Organization for LLCs, Articles of Incorporation for corporations) |
| **Other NC SOS Filings** | `otherDocuments[]` | When filed and available | PDF | Amendments, mergers, conversions, registered agent changes, and other corporate acts |
Annual Report filings are excluded from the document list. The Trade Register
Extract is included in the company-data block at no extra charge; individual
filing PDFs are ordered separately. The NC Certificate of Existence is not yet
available.
Formation documents that match "Articles of Organization", "Articles of
Incorporation", "Articles of Association", or "Certificate of Formation" are
returned under `articlesOfAssociation`. All other filing types are returned
under `otherDocuments`.
## Example API Responses
All examples use placeholder data. Query with `POST /v2/company`.
### Search by Name
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-NC&query=Pinecrest+Technologies" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0012834",
"legalName": "Pinecrest Technologies, LLC",
"countryCode": "US-NC",
"matchReason": { "matchType": "default" }
}
]
```
### Search by SOS ID
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-NC&query=0012834" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0012834",
"legalName": "Pinecrest Technologies, LLC",
"countryCode": "US-NC",
"matchReason": {
"matchType": "id",
"identifier": { "sosId": "0012834" }
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NC", "id": "0012834", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "0012834",
"countryCode": "US-NC",
"identifiers": { "sosId": "0012834" },
"legalName": "Pinecrest Technologies, LLC",
"registrationDate": "2002-06-15",
"status": {
"localName": "Current-Active",
"active": true
},
"legalForm": {
"localName": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "4200 Six Forks Road",
"city": "Raleigh",
"state": "NC",
"postalCode": "27609",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Manager", "standardized": "Manager" },
"individual": { "name": { "fullName": "Jane R. Holloway" } }
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "President", "standardized": "President" },
"individual": { "name": { "fullName": "Thomas G. Kendrick" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"individual": { "name": { "fullName": "Marcus L. Duvall" } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "0019205",
"countryCode": "US-NC",
"identifiers": { "sosId": "0019205" },
"legalName": "Cape Fear Manufacturing Corporation",
"registrationDate": "1991-03-22",
"status": {
"localName": "Current-Active",
"active": true
},
"legalForm": {
"localName": "Business Corporation",
"standardized": "Corporation"
},
"capital": {
"amount": 100000,
"currency": "USD",
"formatted": "10,000,000 Common (par USD 0.01)"
},
"legalAddress": {
"addressLine1": "1 Commerce Street",
"city": "Wilmington",
"state": "NC",
"postalCode": "28401",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "President", "standardized": "President" },
"individual": { "name": { "fullName": "Robert A. Whitfield" } }
},
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Secretary", "standardized": "Secretary" },
"individual": { "name": { "fullName": "Helen F. Carmichael" } }
},
{
"entityId": "person_003",
"type": "individual",
"role": { "localName": "Treasurer", "standardized": "Treasurer" },
"individual": { "name": { "fullName": "David P. Sousa" } }
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"company": {
"legalName": "National Registered Agents, Inc.",
"countryCode": "US-NC"
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "0005417",
"countryCode": "US-NC",
"identifiers": { "sosId": "0005417" },
"legalName": "Piedmont Community Foundation",
"registrationDate": "1956-09-10",
"status": {
"localName": "Current-Active",
"active": true
},
"legalForm": {
"localName": "Non-Profit Corporation",
"standardized": "Nonprofit Organization"
},
"legalAddress": {
"addressLine1": "222 North Elm Street",
"city": "Greensboro",
"state": "NC",
"postalCode": "27401",
"countryCode": "US"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"individual": { "name": { "fullName": "Sandra K. Pryor" } }
}
]
}
```
**Note:** Nonprofit Corporation profiles do not include officers on the NC SOS public profile page. `legalRepresentatives` is always empty for Chapter 55A entities.
```json theme={null}
{
"company": {
"id": "0021176",
"countryCode": "US-NC",
"identifiers": { "sosId": "0021176" },
"legalName": "Coastal Ventures Group LLC",
"registrationDate": "2008-11-03",
"status": {
"localName": "Current-Active",
"active": true
},
"legalForm": {
"localName": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "800 Battery Park Avenue",
"city": "Asheville",
"state": "NC",
"postalCode": "28801",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": { "localName": "Manager", "standardized": "Manager" },
"individual": { "name": { "fullName": "Victor E. Larson" } }
}
],
"otherKeyPersons": [
{
"entityId": "person_002",
"type": "individual",
"role": { "localName": "Registered Agent", "standardized": "Registered Agent" },
"individual": { "name": { "fullName": "Patricia W. Nguyen" } }
}
]
}
```
```json theme={null}
{
"company": {
"id": "0007893",
"countryCode": "US-NC",
"identifiers": { "sosId": "0007893" },
"legalName": "Old Dominion Textiles, Inc.",
"registrationDate": "1975-04-01",
"status": {
"localName": "Dissolved",
"active": false
},
"legalForm": {
"localName": "Business Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "300 Industrial Drive",
"city": "Burlington",
"state": "NC",
"postalCode": "27215",
"countryCode": "US"
}
},
"legalRepresentatives": [],
"otherKeyPersons": []
}
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-NC", "id": "0012834", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_abc123",
"name": "Trade Register Extract",
"format": "pdf"
},
"articlesOfAssociation": [
{
"id": "doc_aoa_def456",
"name": "Articles of Organization",
"format": "pdf",
"date": "2002-06-15",
"description": "NC SOS filing: Articles of Organization, filed 06/15/2002"
}
],
"otherDocuments": [
{
"id": "doc_other_ghi789",
"name": "Articles of Amendment",
"format": "pdf",
"date": "2015-03-10",
"description": "NC SOS filing: Articles of Amendment, filed 03/10/2015"
}
]
}
}
```
# North Dakota
Source: https://docs.topograph.co/essentials/us-north-dakota
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date North Dakota reference is on the [North Dakota country page](https://www.topograph.co/countries/us-nd).
## Start here
This guide contains public integration notes for North Dakota. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Company Status](#company-status)
* [Data Availability](#data-availability)
## Data Sources
North Dakota uses a single live integration against the **North Dakota Secretary of State FirstStop** register at `firststop.sos.nd.gov`. The portal covers every domestic and foreign entity filed in North Dakota: for-profit and nonprofit corporations, limited liability companies, cooperative associations, insurance companies, trade names, fictitious partnership names, and reserved names.
Every request resolves live against the FirstStop register. North Dakota does not publish a free open-data feed or bulk extract; the register's Data List Requests are sold as paid subscriptions to authenticated users and are not exposed through Topograph.
The register publishes: legal name, filing type and subtype, current status, three standing flags (Annual Report, Registered Agent, Other), jurisdiction of formation, term of duration, initial filing date, principal and mailing addresses, annual-report due date, and the registered agent.
**Single authoritative mode.** All requests (both `mode: "prefill"` and `mode: "verification"`) resolve against the live FirstStop register. There is no non-authoritative fast path because no free open-data snapshot is available for North Dakota.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **SOS Control ID#** | Exactly 10 digits, no separators, left-padded with zeros. Every id in the records we have seen has 10 digits | `0000071213`, `0007382449` | Primary identifier assigned by the North Dakota Secretary of State at filing time. Unique across all filing types. |
The SOS Control ID# is zero-padded to exactly ten digits. Queries with the
unpadded form (e.g. `71213` instead of `0000071213`) are accepted. The
API left-pads to 10 digits before forwarding to the register.
### Identifiers in API Response
| Identifier | Format | Example | Notes |
| - | - | - | - |
| `entityId` | Exactly 10 digits, zero-padded | `0000071213` | SOS Control ID#, the public register identifier. |
| `ndInternalId` | Digits only, no padding | `70993` | Portal-internal identifier used by the FirstStop system, a different number from the SOS Control ID#. Returned for transparency; not a public register identifier. |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Dakota Grain"` | Substring (case-insensitive) | Multiple results, capped at 50 |
| By SOS Control ID# | 10 digits (or un-padded form) | `0000071213` | Exact | Single match returned first (`matchType: id`) |
**Substring search.** Name search matches anywhere in the legal name (case-insensitive). To narrow a large result set, use a longer or more specific query string. Results are capped at 50 matches.
### Active companies only
The register itself excludes companies that are no longer active when you search with [`activeOnly=true`](/essentials/search#active-companies-only).
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No officers or directors published** | The North Dakota register does not publish officers, directors, members, organizers, or any other party list for any entity type. The only publicly disclosed contact is the registered agent (and for trade names, the registering owner). Both are returned as `otherKeyPersons`. |
| **Registered agent may be a company** | The registered agent row can be either an individual or a company. Foreign entities often use a Commercial Registered Agent; the role label reflects this. |
| **No open-data snapshot** | There is no free bulk extract for North Dakota. Every lookup hits the live register, so latency reflects a real-time network call to the SoS portal. |
| **Three standing flags** | The register tracks three separate standing values: Annual Report, Registered Agent, and Other. These appear in the Trade Register Extract but are not surfaced as separate Topograph datapoint fields. |
| **Trade names and fictitious partnership names are indexed** | The SOS Control ID# namespace is shared across business entities, trade names, fictitious partnership names, reserved names, and trademarks. A search by name or ID may return trade names alongside corporations and LLCs. |
| **No shareholder or UBO register** | North Dakota does not publish shareholders or beneficial owners for any entity type. The federal beneficial-ownership database is a separate restricted-access system. |
| **No activity codes** | The register does not collect NAICS, NACE, or ISIC codes. |
## Mappings
### Legal Forms
Legal form is sourced from the `Filing Type` field on the FirstStop entity detail page. The vocabulary consists of 18 observed values across all entity types.
| FirstStop Filing Type | Standardized | ISO 20275 |
| - | - | - |
| Corporation - Business - Domestic | Corporation | `S745` |
| Corporation - Business - Foreign | Corporation | |
| Corporation - Nonprofit - Domestic | Nonprofit Organization | `U87X` |
| Corporation - Nonprofit - Foreign | Nonprofit Organization | |
| Corporation - Professional - Domestic | Corporation | `S745` |
| Corporation - Professional - Foreign | Corporation | |
| Corporation - Farm/Ranch - In-State | Corporation | `S745` |
| Limited Liability Company - Business - Domestic | Limited Liability Company | `GHB2` |
| Limited Liability Company - Business - Foreign | Limited Liability Company | |
| Limited Liability Company - Farm/Ranch - In-State | Limited Liability Company | `GHB2` |
| Limited Liability Company - Professional - Domestic | Limited Liability Company | `GHB2` |
| Cooperative Association - Domestic | Cooperative | |
| Cooperative Association - Foreign | Cooperative | |
| Cooperative - Mutual Aid | Cooperative | |
| Insurance Company | Other | |
| Trade Name | Other | |
| Fictitious Partnership Name | Partnership | |
| Reserved Name | Other | |
### Company Status
| FirstStop Status | Active |
| - | - |
| Active | Yes |
| Inactive - Voluntary | No |
| Inactive - Involuntary | No |
| Inactive - Expired | No |
| Inactive - Merged | No |
| Inactive - Consolidated | No |
| Inactive - Converted Out | No |
For a complete, up-to-date list of standardized values, see the [North Dakota pricing page](https://topograph.co/pricing/us-nd).
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the FirstStop register |
| Company status | Yes | Active or Inactive with reason (Voluntary, Involuntary, Expired, Merged, Consolidated, Converted Out) |
| Registration date | Yes | Initial filing date from the register |
| Legal address | Yes | Principal and mailing addresses (street, city, state, ZIP) |
| Legal form | Yes | FirstStop filing type with ISO 20275 mapping where available |
| Registered agent | Yes | Returned as `otherKeyPersons`; individual or company, with address |
| Trade name owner | Yes | Returned as `otherKeyPersons` for trade name filings only |
| Legal representatives | No | Officers, directors, and members are not published by the register |
| Activity codes | No | Not collected by the register |
| Shareholders | No | Not published |
| UBOs | No | No state beneficial-ownership register; federal system is restricted |
| Trade Register Extract | Yes | Included at no extra charge with every company data request: a printed PDF of the structured FirstStop record |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-ND&query=Dakota+Grain" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0000071213",
"legalName": "DAKOTA GRAIN COMPANY, INC.",
"countryCode": "US-ND",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "ND",
"countryCode": "US"
}
}
]
```
### Search by SOS Control ID\#
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-ND&query=0000071213" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0000071213",
"legalName": "DAKOTA GRAIN COMPANY, INC.",
"countryCode": "US-ND",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-ND", "id": "0000071213", "dataPoints": ["company", "otherKeyPersons"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "0000071213",
"countryCode": "US-ND",
"identifiers": {
"entityId": "0000071213",
"ndInternalId": "71213"
},
"legalName": "DAKOTA GRAIN COMPANY, INC.",
"registrationDate": "2006-01-11",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Corporation - Business - Domestic",
"standardized": "Corporation"
},
"legalAddress": {
"addressLine1": "100 N MAIN ST",
"city": "BISMARCK",
"region": "ND",
"postalCode": "58501",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"individual": {
"name": {
"fullName": "JOHN A PLACEHOLDER"
},
"residenceAddress": {
"addressLine1": "100 N MAIN ST",
"city": "BISMARCK",
"region": "ND",
"postalCode": "58501",
"countryCode": "US"
}
}
}
]
}
```
# Ohio
Source: https://docs.topograph.co/essentials/us-ohio
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Ohio reference is on the [Ohio country page](https://www.topograph.co/countries/us-oh).
## Start here
This guide contains public integration notes for Ohio. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Data Availability](#data-availability)
## Data Sources
Ohio uses a single integration against the **Ohio Secretary of State, Business Services** portal (`businesssearch.ohiosos.gov`).
Two channels are wired:
* **Ohio SOS Monthly Business Reports** (fast, primary). Free official TXT reports generated on the second Saturday of each month. They cover new filings, subsequent/amendment filings, and canceled or dissolved LLCs. They do not cover the full live register population. Used for prefill checks and company search.
* **Ohio SOS Business Search** (slow, authoritative). A live read from the public business search portal. Adds fields not present in the monthly reports: current status, full principal address, statutory agent details, and prior names. Verification mode reads this channel on its own, without the monthly reports.
**Mode-based routing.** Prefill requests (`mode: "prefill"`) are served from the monthly Business Reports. Verification requests (`mode: "verification"`) read the live SOS business search on its own, returning the most current status and statutory-agent data available on the portal.
**Report coverage.** The Ohio SOS monthly Business Reports cover filing events, not the full register population. Entities that have not had a filing event in the current or recent report cycles may not appear in search results. Use verification mode with a known Ohio ID for the most current data on a specific entity.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Ohio Charter / Entity Number** | Numeric for almost every entity: 4 to 7 digits, no leading zero (e.g. `1456`, `693950`). Registered trade names and a few older or special registrations carry letters: two letters + digits (e.g. `RN228652`, `FN31251`) or digits + one letter (e.g. `14276Z`). | `1067403` | Primary identifier assigned by the Ohio Secretary of State. Corresponds to the charter number on the public business search portal and in the monthly Business Reports. |
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `ohioId` | 4 to 7 digits; a few registrations carry letters (e.g. `RN228652`) | `1067403` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Nationwide"` | Name match (case-insensitive) | Multiple results |
| By Ohio Charter / Entity Number | As issued | `1067403` | Exact (`matchType: id`) | Single result or none |
**Name search.** Search combines our cached monthly-report dataset with a live query against the Ohio SOS business search, so results reflect the register's full population and match the query anywhere in the legal name (not just as a prefix). Each result set is capped at 50 matches; use fuller query strings to narrow broad searches.
**Coverage.** Because the live register is queried alongside the cache, entities that are registered with the Ohio SOS but absent from recent monthly-report cycles now appear in search results. Under heavy load the live query can briefly fall back to the cached dataset alone; searching by Ohio ID remains the most reliable lookup when you already have the identifier.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Name matches confirmed by the live register are filtered. Registration-number lookups, and name matches served only from our copy of recent filings, are returned whatever their status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Monthly reports cover filing events, not the full population** | The monthly Business Reports (which back onboarding-mode company data) are generated from filing activity rather than a full-register snapshot. This no longer limits **search** (search queries the live register alongside the cache), but onboarding-mode company lookups for an entity without a recent filing event may still be thin. Use verification mode with the `ohioId` for the most current data. |
| **Authoritative mode adds fields not in the reports** | Live status, the full principal address block, the statutory agent name and address, and prior names are only available through the live SOS business search (verification mode). Prefill mode returns only the fields present in the monthly reports: the statutory agent name (no address) and a placeholder status. |
| **No officer or director roster** | Ohio SOS does not publish a member, director, or officer list through either the monthly reports or the public business search portal. The statutory agent is returned under `otherKeyPersons` in both modes. Its local role is `Statutory Agent`, translated and standardized as `Registered Agent`. This function concerns legal notices and service of process; it does not establish general signing authority. |
| **No shareholders or UBO register** | Shareholder lists and beneficial ownership data are not published by the Ohio SOS. |
| **No activity codes** | Industry classification codes (NAICS, NACE, ISIC) were not found in the Ohio SOS public sources. |
| **No tax IDs** | Federal EIN and state tax identifiers are not disclosed by the Ohio SOS public business register. |
| **Trade Register Extract included at no extra charge** | The printable Trade Register Extract (a PDF rendering of the live SOS detail page) ships with the company-data block. It includes the entity number, legal name, type, status, filing dates, principal location, statutory agent, prior names, and filing history. |
## Mappings
### Legal Forms
Legal form is sourced from the entity type field of the Ohio Secretary of State monthly Business Reports. The vocabulary is a closed set of 10 values.
| Ohio SOS Entity Type | Standardized |
| - | - |
| Domestic For-Profit Corporation | Corporation |
| Foreign For-Profit Corporation | Corporation |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Corporation | Nonprofit Organization |
| Domestic Professional Corporation | Corporation |
| Foreign Professional Corporation | Corporation |
| Domestic Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
The full legal-form list with provenance details is on the [Ohio pricing page](https://topograph.co/pricing/us-oh).
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Verification only | Live status (Active, Cancelled, Permanently Cancelled, Held, Dead) is returned only in verification mode. Prefill mode returns a placeholder status, `Filed in Ohio SOS monthly business report` with `active: true`: it means the entity appears in a monthly report, not that it is active on the register. |
| Registration date | Yes | Filing date from the monthly Business Reports in prefill mode; effective date from the live portal in verification mode |
| Legal address | Partial | Prefill mode includes the location fields present in the reports. Verification mode adds the full principal address block from the live portal. |
| Legal form | Yes | Closed 10-value vocabulary from the Ohio SOS |
| Statutory agent | Yes | Returned under `otherKeyPersons` with local role `Statutory Agent` and standardized role `Registered Agent`. Prefill mode returns the name only; verification mode adds the address. |
| Prior names | Verification only | Prior entity names are returned in verification mode when present on the live portal. |
| Activity codes | No | Not collected by the Ohio SOS |
| Officers / directors | No | Not published by the Ohio SOS |
| Shareholders | No | Not published |
| UBOs | No | Not published (federal FinCEN is a separate system) |
| Tax IDs | No | Not disclosed by the Ohio SOS public register |
| Trade Register Extract | Yes | Included at no extra charge with the company-data block. PDF rendering of the live SOS detail page covering entity summary, statutory agent, prior names, and filings. |
| Filing document images | No (roadmap) | Individual filing PDFs available at the SOS portal are not yet offered through Topograph. |
For the full datapoint catalog, check the [Ohio pricing page](https://topograph.co/pricing/us-oh).
## Example API Responses
### Search by Name
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-OH&query=Nationwide" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567",
"legalName": "NATIONWIDE MUTUAL INSURANCE COMPANY",
"countryCode": "US-OH",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "OH",
"countryCode": "US"
}
}
]
```
### Search by Ohio ID
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-OH&query=1234567" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567",
"legalName": "NATIONWIDE MUTUAL INSURANCE COMPANY",
"countryCode": "US-OH",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile (Prefill)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-OH", "id": "1234567", "dataPoints": ["company"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "1234567",
"countryCode": "US-OH",
"identifiers": { "ohioId": "1234567" },
"legalName": "ACME MANUFACTURING LLC",
"registrationDate": "2010-03-15",
"status": {
"localName": "Filed in Ohio SOS monthly business report",
"active": true
},
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"city": "Columbus",
"region": "OH",
"countryCode": "US"
}
}
}
```
# Oklahoma
Source: https://docs.topograph.co/essentials/us-oklahoma
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Oklahoma reference is on the [Oklahoma country page](https://www.topograph.co/countries/us-ok).
## Start here
This guide contains public integration notes for Oklahoma. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)
## Data Sources
Oklahoma uses two tiers against the **Oklahoma Secretary of State, Business Services Division**. The register covers every domestic and foreign for-profit corporation, nonprofit corporation, limited liability company, limited partnership, limited liability partnership, and cooperative association formed in or qualified to do business in Oklahoma. No bulk-data extract is published for business entities; every request is resolved live against the portal.
* **Oklahoma Secretary of State public portal** (free tier). The free Entity Summary page at `sos.ok.gov/corp` exposes the legal name, current status, legal form, jurisdiction, formation date, and the registered agent for any entity. This is what the free company-data block delivers. Officer and director rosters are not visible on this surface.
* **Oklahoma Secretary of State paid Entity Detail** (paid tier). The Secretary of State charges a fee per entity to unlock the full Entity Detail view, which adds the officer/director/general-partner roster. The paid Entity Detail returns `legalRepresentatives` and non-representative principals in `otherKeyPersons`.
**Two-block model.** The free `company` + `otherKeyPersons` datapoints (registered agent) are delivered by the base company-data block. `legalRepresentatives` (officers, directors, general partners) require the separate paid Entity Detail block. See the pricing page for block pricing.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Filing Number** | 10 digits, numeric only | `3400676484` | Primary identifier assigned by the Oklahoma Secretary of State. Displayed on every entity page at sos.ok.gov/corp. |
Oklahoma Filing Numbers are 10 numeric digits. Unlike Pennsylvania's filing number they are not zero-padded: they are plain integers (e.g. `3400676484`, not `0003400676`). Pass the number exactly as it appears on the SoS portal.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `filingNumber` | 10 digits, numeric only | `3400676484` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Acme Corp"` | Starts-with (case-insensitive) | Multiple results |
| By Filing Number | 10 digits | `3400676484` | Exact (`matchType: default`) | Single match returned first |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use fuller query strings to narrow the result set, which is capped at 200 matches.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No open-data snapshot** | Oklahoma does not publish a bulk-data extract for business entities. There is no fast/non-authoritative mode. Every request hits the live portal. See the pricing page for current response times. |
| **Officers are a paid upgrade** | The free Entity Summary page does not expose officer or director data. The SoS charges a fee per entity for the full Entity Detail view that includes the PRINCIPALS table. Send the paid Entity Detail block to receive `legalRepresentatives`. |
| **No principal-office address** | The free Entity Summary shows only the registered-agent address, not the principal-office address. The paid Entity Detail block does not add it either: `company.legalAddress` is not returned for Oklahoma. |
| **Registered agent in `otherKeyPersons`** | Requests for `otherKeyPersons` alone return the registered agent with the `Registered Agent` role. When the paid principal roster fulfills the request, its `otherKeyPersons` contain non-representative principals and omit the summary-only agent. |
| **No shareholder or UBO register** | Oklahoma does not publish shareholders or beneficial owners for any entity type. |
| **No activity codes** | The Business Services Division does not collect NAICS, NACE, or ISIC codes. |
| **Legal form is free-text from the register** | The entity-type label on the SoS portal is free text (e.g. `Foreign Limited Partnership`, `Domestic Limited Liability Company`). Topograph returns it as-is in `legalForm.localName`, without a standardized category. |
| **Tradenames (DBAs) not returned** | Active commercial tradenames appear on the paid Entity Detail page, but neither block returns them. The paid Entity Detail returns `legalRepresentatives` and non-representative principals in `otherKeyPersons`. |
| **Paid Entity Detail carries a per-entity fee** | Each lookup of the paid Entity Detail block is charged a fee by the Secretary of State. This fee is incorporated into the paid block price on the pricing page. |
| **Free Trade Register Extract included** | The free company-data block includes a printable Trade Register Extract (a rendered PDF of the public Entity Summary page) at no extra charge. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type label on the Oklahoma Secretary of State Entity Summary page. The register uses a fixed vocabulary of entity types corresponding to Oklahoma statutes. Topograph returns the label as-is in `legalForm.localName`, without a standardized category.
| SoS Entity Type |
| - |
| Domestic For Profit Corporation |
| Foreign For Profit Corporation |
| Domestic Non-Profit Corporation |
| Foreign Non-Profit Corporation |
| Domestic Limited Liability Company |
| Foreign Limited Liability Company |
| Domestic Limited Partnership |
| Foreign Limited Partnership |
| Domestic Limited Liability Partnership |
| Foreign Limited Liability Partnership |
| Domestic Cooperative Association |
| Foreign Cooperative Association |
### Officer Roles
Officer and director data comes from the PRINCIPALS table on the paid Entity Detail page. Titles are reported in uppercase by the register. Topograph maps the well-known vocabulary to standardized roles. Other titles are returned with the raw title in `localName` and no standardized role. Executive offices and management functions retain their office meanings; governing-only directors, ordinary members, limited partners and formation actors are returned as `otherKeyPersons` from the Entity Detail product. Corporate officer powers depend on the bylaws or board resolution. An LLC manager’s authority depends on the governing documents and the particular act; no individual signing mode is inferred from the title.
| Common Title | Standardized | Entity Types |
| - | - | - |
| PRESIDENT | President | Corporations |
| VICE PRESIDENT | Vice President | Corporations |
| SECRETARY | Secretary | Corporations |
| TREASURER | Treasurer | Corporations |
| DIRECTOR | Board Member | Corporations |
| CHAIRMAN | Chairman of the Board | Corporations |
| CEO | Chief Executive Officer | Corporations |
| CFO | Chief Financial Officer | Corporations |
| COO | Chief Operating Officer | Corporations |
| MANAGER | Manager | LLCs |
| MANAGING MEMBER | Manager | LLCs |
| MEMBER | Other | LLCs (ownership role) |
| GENERAL PARTNER | General Partner | Limited partnerships |
| LIMITED PARTNER | Other | Limited partnerships |
| MANAGING PARTNER | Managing Partner | Partnerships |
Registered agents are returned under `otherKeyPersons`, not under `legalRepresentatives`. They hold the `Registered Agent` role and are available from the free company-data block.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes (free) | Current legal name from the Entity Summary |
| Company status | Yes (free) | Active / Inactive; read live from the portal |
| Registration date | Yes (free) | Formation date from the Entity Summary |
| Jurisdiction | Yes (free) | State of formation for foreign entities (e.g. Delaware) |
| Legal form | Yes (free) | The register's entity-type label, in `localName` only |
| Registered agent | Yes (free) | Returned as `otherKeyPersons` with the `Registered Agent` role |
| Legal address | No | Not currently returned in either tier |
| Legal representatives | Paid tier | Officers, directors, and general partners from the PRINCIPALS table |
| Tradenames (DBAs) | No | Not currently returned in either tier |
| Trade Register Extract | Yes (free, included) | Printable PDF of the public Entity Summary page, included with the company-data block at no extra charge |
| Shareholders | No | Not published by the Oklahoma business register |
| UBOs | No | No public beneficial-ownership register at the Oklahoma state level |
| Activity codes | No | Not collected by the Business Services Division |
| Financial data | No | Not collected |
| Certified copies | Roadmap | Certified documents require the Secretary of State paid filing flow and are not yet offered through Topograph |
| Certificate of Good Standing | Roadmap | Not yet offered through Topograph |
## Example API Responses
### Search by Name
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-OK&query=Acme" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567890",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-OK",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "OK",
"countryCode": "US"
}
}
]
```
### Search by Filing Number
```bash theme={null}
curl "https://api.topograph.co/v2/search?country=US-OK&query=1234567890" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "1234567890",
"legalName": "ACME HOLDINGS LLC",
"countryCode": "US-OK",
"matchReason": {
"matchType": "default"
}
}
]
```
### Company Profile (free tier)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-OK", "id": "1234567890", "dataPoints": ["company", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "1234567890",
"countryCode": "US-OK",
"identifiers": { "filingNumber": "1234567890" },
"legalName": "ACME HOLDINGS LLC",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Domestic Limited Liability Company"
},
"registrationDate": "2010-03-15"
},
"otherKeyPersons": [
{
"entityId": "person_001",
"role": { "standardized": "Registered Agent" },
"individual": {
"name": { "fullName": "ACME REGISTERED AGENT INC" },
"residenceAddress": {
"addressLine1": "123 Main St",
"city": "Oklahoma City",
"region": "OK",
"postalCode": "73102",
"countryCode": "US"
}
}
}
]
}
```
### Company Profile with Legal Representatives (paid tier)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-OK", "id": "1234567890", "dataPoints": ["company", "legalRepresentatives"]}'
```
```json theme={null}
{
"company": {
"id": "1234567890",
"countryCode": "US-OK",
"identifiers": { "filingNumber": "1234567890" },
"legalName": "ACME HOLDINGS LLC"
},
"legalRepresentatives": [
{
"entityId": "person_001",
"role": {
"localName": "MANAGER",
"standardized": "Manager"
},
"individual": {
"name": { "fullName": "JANE SMITH" }
}
}
]
}
```
# Oregon (US)
Source: https://docs.topograph.co/essentials/us-oregon
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Oregon (US) reference is on the [Oregon (US) country page](https://www.topograph.co/countries/us-or).
## Start here
This guide contains public integration notes for Oregon. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Other Key Persons](#other-key-persons)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
Oregon entity data comes from the **Oregon Secretary of State Business Registry**, which publishes two complementary public surfaces:
* **Active Businesses snapshot** (fast, prefill). A weekly refresh of every active Oregon entity, published by the Oregon Secretary of State as the "Active Businesses - ALL" open dataset on `data.oregon.gov`. Covers about 520,000 active entities. Used for prefill checks and name/identifier search.
* **Oregon Business Registry profile page** (live, verification). The authoritative entity detail page rendered by the Secretary of State at `egov.sos.state.or.us/br/`. Returns the live company profile including officers, members, registered agent, and current status. Used for verification requests and to cover inactive entities (which are absent from the open dataset).
**Mode-based routing.** Prefill requests (`mode: "prefill"`) are served from the open-data snapshot for sub-second response times. Verification requests fall through to the live profile page, which carries inactive entities and the full officer roster. Both modes are priced together as a single block.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Registry Number** | 3-9 digits. Most: 6 or 7 digits, `-` and 2 digits (`087399-14`, `1496294-95`). Some: 3-6 digits with no hyphen (`414`, `443499`) | `087399-14` | Primary identifier assigned by the Oregon Secretary of State. |
Oregon displays most Registry Numbers with a hyphen before the last two digits, and the part before the hyphen is zero-padded to six digits (`087399-14`). The open dataset stores the same number as digits only, without leading zeros (`8739914`). Both forms are accepted on input.
Responses use the hyphenated form, or plain digits for numbers under seven digits (`443499`). Some search results carry the part before the hyphen without its leading zero (`12267-11` for `012267-11`); both resolve to the same entity.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `registryNumber` | 3-9 digits, usually with `-` before the last 2 (`087399-14`); plain digits under 7 digits (`443499`) | `087399-14` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Nike"` | Contains | Multiple results |
| By Registry Number | 3-9 digits, with or without the `-` before the last 2 | `087399-14` | Exact | Exact match returned first (matchType: id); other results may follow |
Name search covers active entities only. Inactive entities (dissolved,
withdrawn, cancelled) can be found only by Registry Number, which also
queries the live registry.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Name searches only cover active companies. Registration-number lookups can also return inactive companies, which the filter removes.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Registry Number padding** | Oregon pads the part before the hyphen to six digits (`087399-14`). Numbers under seven digits in total are returned as plain digits with no hyphen, e.g. `414` (Lewis & Clark College) or `443499`. The registration year does not decide the shape: a 1907 entity carries `012267-11` and a 2001 entity carries `443499`. |
| **Active-only snapshot** | The open dataset covers active entities only. Inactive entities (dissolved, withdrawn, cancelled) resolve through the live registry path. |
| **Associated-name rows** | Each entity emits up to four rows in the snapshot, one per associated-name type (Registered Agent, Principal Place of Business, Mailing Address, Authorized Representative). Topograph folds them into one company per entity. |
| **Snapshot refresh cadence** | The "Active Businesses - ALL" dataset is refreshed weekly, typically Monday around 14:00 UTC. Brand-new filings may be a few days behind in prefill mode; verification mode reads the live registry. |
| **Activity codes not published** | Oregon does not publish industry classification codes on the public business registry. |
## Mappings
### Company Status
Status comes from the Oregon SoS entity status field on the detail page.
| Source Value | Active | Notes |
| - | - | - |
| `ACT` / Active | `true` | Entity is in good standing. |
| `INA` / Inactive | `false` | Catch-all inactive state. |
| `PEN` / Pending | `false` | Registration pending. |
| `WIT` / Withdrawn | `false` | Foreign entity withdrew its Oregon registration. |
| `CAN` / Cancelled | `false` | Registration cancelled. |
| `CON` / Converted | `false` | Entity converted. |
| `EXP` / Expired | `false` | Registration lapsed. |
| `DIS` / Dissolved | `false` | Voluntary or administrative dissolution. |
### Legal Forms
Legal form is derived from the Entity Type field. Domestic types cover entities formed under Oregon law; Foreign types cover entities formed elsewhere and registered to do business in Oregon. ISO 20275 ELF codes are assigned to domestic Oregon types from the GLEIF ELF Code List; foreign variants carry no ELF code because the code belongs to the jurisdiction of formation.
| Entity Type | Standardized | ELF Code |
| - | - | - |
| Domestic Business Corporation | Corporation | `T5ZE` |
| Foreign Business Corporation | Corporation | — |
| Domestic Professional Corporation | Corporation | — |
| Foreign Professional Corporation | Corporation | — |
| Domestic Limited Liability Company | Limited Liability Company | `QK2J` |
| Foreign Limited Liability Company | Limited Liability Company | — |
| Domestic Professional Limited Liability Company | Limited Liability Company | — |
| Foreign Professional Limited Liability Company | Limited Liability Company | — |
| Domestic Limited Partnership | Partnership | `GEE0` |
| Foreign Limited Partnership | Partnership | — |
| Domestic Limited Liability Partnership | Partnership | — |
| Foreign Limited Liability Partnership | Partnership | — |
| Domestic Nonprofit Corporation | Nonprofit Organization | `UZ83` |
| Foreign Nonprofit Corporation | Nonprofit Organization | — |
| Domestic Cooperative | Cooperative | — |
| Assumed Business Name | Other | — |
### Officer Roles
Officer titles surface on the live profile page using three-letter Oregon filing-form codes. Topograph maps them to standardized roles.
| Source Code | Local Name | Standardized |
| - | - | - |
| `PRE` | President | President |
| `VPR` | Vice President | Vice President |
| `SEC` | Secretary | Secretary |
| `TRE` | Treasurer | Treasurer |
| `DIR` | Director | Board Member |
| `MGR` | Manager | Manager |
| `PAR` | Partner | Partner |
| `GPA` | General Partner | General Partner |
| `MEM` | Member | Other |
| `INC` | Incorporator | Other |
Fixed source codes have deterministic English and standardized meanings. Directors and incorporators are returned as other key persons, as are registered agents. A member in a roster that also names a current manager is an other key person; otherwise the member retains the register's representing category. Oregon law distinguishes member-managed and manager-managed LLCs, so this category alone does not establish a person's actual signing powers. Officer duties depend on bylaws and individual grants; no sole or joint signing mode is inferred. Unknown named principal functions retain their source title as other key persons with standardized `Other`.
### Other Key Persons
| Role | Standardized | Notes |
| - | - | - |
| Registered Agent | `Registered Agent` | Statutory service-of-process contact. Returned as an `otherKeyPerson`. |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the entity detail page. |
| Company status | Yes | Active/inactive with detailed status code. |
| Registration date | Yes | Initial filing date with the Oregon Secretary of State. |
| Legal address | Yes | Principal place of business; falls back to mailing address when not separately filed. |
| Mailing address | No | Not returned as a separate field (used only as the legal address fallback). Shown on the Trade Register Extract. |
| Legal form | Yes | Entity type with domestic/foreign distinction. |
| Jurisdiction | No | Not returned in the JSON response. Shown on the Trade Register Extract. |
| Registered agent | Yes | Returned as an `otherKeyPerson`. |
| Officers and managers | Yes | Returned in verification mode (`legalRepresentatives`). |
| Name history | No | Not returned in the JSON response. Shown on the Trade Register Extract. |
| Activity codes | No | Not published by the Oregon Secretary of State. |
| Shareholders | No | Not collected by the Oregon business registry. |
| UBOs | No | No state-level beneficial-ownership register. |
## Documents
### Available Documents
| Document | Availability | Format |
| - | - | - |
| **Trade Register Extract** | Always available | PDF |
The Trade Register Extract is a printed capture of the Oregon SoS entity
detail page. It is included with the company data block at no extra charge.
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-OR&query=NIKE" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "087399-14",
"legalName": "NIKE, INC.",
"countryCode": "US-OR",
"matchReason": { "matchType": "default" }
},
{
"id": "1496294-95",
"legalName": "NIKE ALPHA FORCE LLC",
"countryCode": "US-OR",
"matchReason": { "matchType": "default" }
}
]
```
### Search by Registry Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-OR&query=087399-14" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "087399-14",
"legalName": "NIKE, INC.",
"countryCode": "US-OR",
"matchReason": {
"matchType": "id",
"identifier": { "registryNumber": "087399-14" }
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-OR", "id": "1496294-95", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "1496294-95",
"countryCode": "US-OR",
"identifiers": { "registryNumber": "1496294-95" },
"legalName": "NIKE ALPHA FORCE LLC",
"registrationDate": "2018-11-16",
"status": { "localName": "Active", "active": true },
"legalForm": {
"localName": "Foreign Limited Liability Company",
"englishTranslation": "Foreign Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "1 Bowerman Drive",
"city": "Beaverton",
"postalCode": "97005",
"region": "OR",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": { "legalName": "UNITED AGENT GROUP INC." }
}
],
"legalRepresentatives": [
{
"entityId": "company_002",
"type": "company",
"role": { "localName": "Member", "standardized": "Other" },
"company": { "legalName": "NIKE HOLDING, LLC" }
}
]
}
```
### Available Documents
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-OR", "id": "1496294-95", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_or_abc123",
"name": "Trade Register Extract",
"format": "pdf"
}
}
}
```
# Pennsylvania (US)
Source: https://docs.topograph.co/essentials/us-pennsylvania
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Pennsylvania (US) reference is on the [Pennsylvania (US) country page](https://www.topograph.co/countries/us-pa).
## Start here
This guide contains public integration notes for Pennsylvania. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
Pennsylvania is sourced from the **Pennsylvania Department of State, Bureau of Corporations and Charitable Organizations (BCCO)**. The register covers every entity filed under Title 15 of the Pennsylvania Consolidated Statutes (business corporations, nonprofit corporations, limited liability companies, limited partnerships, general partnerships including LLPs, business trusts, professional associations) and four non-Title-15 forms maintained alongside them (credit unions under 17 Pa.C.S., financial institutions under 7 Pa.C.S., municipal authorities under 53 Pa.C.S., and land banks under 68 Pa.C.S.).
* **Department of State Open Data snapshot** (fast, prefill). A weekly refresh of the BCCO database published at `data.pa.gov` under "Registered Businesses in PA Current by County Department of State". Covers 2.3M distinct filing numbers and the associated governor and officer roster (3.9M rows). Used for prefill checks, company search, and as the officer baseline in verification mode.
* **Business Filing Services portal** (live, verification). The interactive register at `file.dos.pa.gov`. Returns the current status, the principal-office address, and the annual report due date, and is the source of the printable Trade Register Extract.
**Mode-based routing.** Prefill requests (`mode: "prefill"`) are served from the open-data snapshot. Verification requests (`mode: "verification"`) read the Business Filing Services portal live and merge it with the snapshot officer list; live values take precedence on conflicts.
**Decennial-to-annual transition.** Pennsylvania repealed the decennial report regime and introduced annual reports on 2025-01-06 under Act 122 of 2022. Officer data refreshes as each entity files its first post-2025 annual report. Entities that have not yet filed a post-2025 annual report may carry officer data up to ten years old from their last decennial filing. Administrative dissolution for non-filers begins 2027.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **PA Filing Number** | 10 digits, zero-padded | `0004272272` | BCCO internal file number (15 Pa.C.S. §132). Leading zeros are significant. |
The PA filing number is zero-padded to exactly ten digits. Shorter numeric
inputs (e.g. `4272272`) are left-padded to ten digits (`0004272272`), and
responses always return the padded form. The
prefix loosely tracks registration vintage — `000xxxxxxx` is pre-1970,
`001xxxxxxx` is the current (2020s) range — but the prefix does not encode
entity type.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `filingNumber` | 10 digits, zero-padded | `0004272272` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Sheetz"` | Starts-with (case-insensitive) | Multiple results |
| By PA Filing Number | 1-10 digits | `0004272272` | Exact | Exact match returned first (matchType: id); other results may follow |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use fuller query strings to narrow the result set, which is capped at 50 matches.
### Active companies only
Search can return companies that are no longer active, but their status is not known at search time, so [`activeOnly=true`](/essentials/search#active-companies-only) has no effect. Check `company.status` on the company profile. Search results come from a register snapshot that does not carry company status, so companies that are no longer active can appear. Check the status on the company profile.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Zero-padding is load-bearing** | Filing numbers are always 10 digits with leading zeros preserved. Shorter numeric inputs are left-padded to 10 digits, so `4272272` resolves to `0004272272`. Responses always carry the padded form. |
| **Status is not in the snapshot** | The open-data dataset does not carry a current status field. The Commonwealth does not administratively dissolve non-filers before the Act 122 of 2022 penalties begin in 2027, so every row in the snapshot would read "active" and historic dissolutions are invisible. Use verification mode for the live status. |
| **No shareholder or UBO register** | Pennsylvania does not publish shareholders or beneficial owners for any entity type. |
| **No activity codes** | The BCCO does not collect NAICS, NACE, or ISIC codes. Industry classification is held by the PA Department of Revenue for tax purposes and is not released publicly. |
| **Fictitious names live separately** | Fictitious name registrations under 54 Pa.C.S. § 311 are a separate filing track and are not part of the business entity dataset. DBA-style names are therefore not indexed for search. |
| **Officer titles are free-text** | The `party_type` field carries 500+ observed variants (President, Governor, Organizer, Treasurer, Secretary, Vice President, General Partner, Incorporator, Member, plus a long tail of roles such as Pastor, Fire Chief, Chief Revenue Officer). Titles are normalized by AI enrichment. |
| **Paid documents are mailed or picked up** | The Subsistence Certificate (domestic good standing), written record search, and certified copies are paid (see [pricing](https://www.topograph.co/pricing)), ordered through the BFS portal, and delivered electronically or by mail from Harrisburg. These are not yet offered through Topograph. |
| **Annual reports are new** | The decennial-report regime was repealed in 2022. Entities now file annually (for-profit corporations by June 30, LLCs by September 30, LPs/LLPs/trusts/professional associations by December 31). First annual filing cycle ran in 2025; officer data will refresh year over year going forward. |
## Mappings
### Legal Forms
Legal form is sourced from the `typeofbusinessregistration` column of the Department of State open-data dataset. The vocabulary is a closed enum of 18 values backed by Title 15 of the Pennsylvania Consolidated Statutes (plus four forms governed by 17, 7, 53, and 68 Pa.C.S.).
| DOS Entity Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Limited Liability Company | Limited Liability Company | `9C19` |
| Foreign Limited Liability Company | Limited Liability Company | |
| Domestic Business Corporation | Corporation | `3JTE` |
| Foreign Business Corporation | Corporation | |
| Domestic Nonprofit Corporation | Nonprofit Organization | |
| Foreign Nonprofit Corporation | Nonprofit Organization | |
| Domestic Limited Partnership (LP/LLLP) | Partnership | `HSEV` |
| Foreign Limited Partnership | Partnership | |
| Domestic General Partnership (GP/LLP) | Partnership | |
| Foreign Limited Liability General Partnership | Partnership | |
| Domestic Business Trust | Trust | |
| Foreign Business Trust | Trust | |
| Domestic Professional Association | Corporation | |
| Foreign Professional Association | Corporation | |
| Authority | Other | `RPED` |
| Domestic Credit Union | Cooperative | `HV9Q` |
| Domestic Financial Institution | Other | |
| Domestic Land Bank | Other | |
### Officer Roles
The `party_type` field on the dataset is free-text with over 500 casing and punctuation variants. Topograph routes each raw value through AI role enrichment, producing a standardized role label, English translation, and (when available) an ISO 5009 Official Organizational Role code.
| Common Raw Value | Standardized | Notes |
| - | - | - |
| President | President | 15 Pa.C.S. § 1732 statutory corporation officer |
| Vice President | Vice President | |
| Secretary | Secretary | |
| Treasurer | Treasurer | |
| Governor | Director | LLC governor under 15 Pa.C.S. § 8847 |
| Organizer | AI-inferred | LLC / corporation organizer |
| Member | AI-inferred | LLC member (member-managed LLCs) |
| Managing Member | AI-inferred | LLC managing-member variant |
| General Partner | General Partner | Limited partnerships |
| Incorporator | AI-inferred | |
Governors, Organizers, Members, and General Partners are classified as Legal
Representatives. The Registered Agent only receives service of process, has
no statutory authority to bind the entity, and is not returned as a person.
## Statutory Filings
Pennsylvania entities file an annual report confirming the entity's particulars are current. The register publishes the annual report due date on the Business Filing Services record, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "dueDate": "2026-06-30" },
"source": "pa_dos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Yes | Verification mode only, read live from the Business Filing Services portal: Active, Out of Existence, Merged, Cancelled, Dissolved, Withdrawn, Consolidated, Terminated. The open-data snapshot does not carry a status field. |
| Registration date | Yes | BCCO initial filing date |
| Legal address | Yes | Street address, city, state, ZIP, county (67 Pennsylvania counties) |
| Legal form | Yes | Closed 18-value Title 15 vocabulary with ISO 20275 mapping where GLEIF publishes one |
| Legal representatives | Yes | Officers and governors with free-text titles, normalized by AI enrichment |
| Registered agent | Roadmap | Surfaced on the BFS portal detail page — not in the open-data snapshot |
| Activity codes | No | Not collected by the BCCO |
| Shareholders | No | Not published |
| UBOs | No | Not published (federal CTA / FinCEN is a separate system) |
| Documents | Yes | Trade Register Extract (printable copy of the Business Filing Services entity page), included with the company data block. The Subsistence Certificate and certified copies are not yet offered. |
| Financial data | No | Not collected |
| Fictitious names (DBAs) | No | Registered separately under 54 Pa.C.S. § 311, not part of the business entity dataset |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-PA&query=Sheetz" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0002911132",
"legalName": "SHEETZ AVIATION, INC.",
"countryCode": "US-PA",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "PA",
"countryCode": "US"
}
}
]
```
### Search by Filing Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-PA&query=0002911132" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "0002911132",
"legalName": "SHEETZ AVIATION, INC.",
"countryCode": "US-PA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-PA", "id": "0002911132", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "0002911132",
"countryCode": "US-PA",
"identifiers": { "filingNumber": "0002911132" },
"legalName": "SHEETZ AVIATION, INC.",
"registrationDate": "1999-05-20",
"legalForm": {
"localName": "Foreign Business Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"city": "Harrisburg",
"region": "PA",
"postalCode": "17101",
"countryCode": "US"
}
},
"legalRepresentatives": []
}
```
Named formation, ownership and other non-representative appointments are returned in `otherKeyPersons` with their filed titles. The live Business Filing Services record may include historical formation parties absent from the weekly snapshot. Known titles use the published catalogue; the statewide free-text vocabulary has no exhaustive published list. A title alone does not establish company-specific signing powers.
# Rhode Island (US)
Source: https://docs.topograph.co/essentials/us-rhode-island
State-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Rhode Island (US) reference is on the [Rhode Island (US) country page](https://www.topograph.co/countries/us-ri).
## Start here
This guide contains public integration notes for Rhode Island. Use it for identifier formats, search behavior, and state-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction is in preview. Check the live pricing page or contact support before relying on it in production.
State details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Entity Types](#entity-types)
* [Status Values](#status-values)
* [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)
## Data Sources
Rhode Island uses a single integration against the **Rhode Island Department of State, Business Services Corporate Database**. The register covers domestic and foreign for-profit corporations, non-profit corporations, benefit corporations, limited liability companies, limited partnerships, limited liability partnerships, and non-resident landlord registrations.
* **Rhode Island Department of State, Business Services** (verification, primary). The official public register served by the Business Portal. Each query reads live against the register and returns legal name, identification number, entity type with domestic / foreign and profit / non-profit qualifiers, date of incorporation or registration in Rhode Island, current status with revocation, withdrawal, or dissolution dates, the principal-office address, the registered-agent name and address with resignation and address-maintained flags, the statutory officers and directors of a corporation or the managers of an LLC, the corporate purpose, the NAICS code with description, registered fictitious / DBA names, prior corporate names, and merger history.
Shareholders and beneficial owners are not collected by Rhode Island at the state level. Authorized share capital is shown on the Trade Register Extract only; it is not returned in the JSON response, and the holders of those shares are not part of the register.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **RI Identification Number** | Nine-digit zero-padded numeric value, no separators | `000015908` | Assigned by the Department of State Business Services at filing. Inputs shorter than nine digits are left-padded with zeros. |
The identification number is always normalized to nine digits before search. Only digits are accepted, up to nine of them: `15908` and `000015908` resolve to the same entity.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `identificationNumber` | Nine-digit zero-padded numeric | `000015908` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2 to 200 characters | `"Hasbro"` | Begins with (case-insensitive) | Up to 50 |
| By Identification Number | 1 to 9 digits | `000015908` | Exact (after zero-padding) | Exact match returned first (matchType: id); other results may follow |
Name search returns up to 50 rows per query and is bound to currently-active entities. To resolve a known inactive entity, query by identification number instead. The identifier path covers active and inactive entities in one lookup.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones. Name searches only cover active companies and companies revoked within the last year; identification-number lookups reach every company. With the active-only filter, inactive companies are removed from both.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Identification number is zero-padded** | The canonical form is exactly nine digits, left-padded with zeros (`000015908`). Older entities are often displayed with the leading zeros elided, but the canonical form in the API response is always nine digits. |
| **No shareholder or UBO register** | Rhode Island does not publish shareholders or beneficial owners for any entity type. Federal FinCEN beneficial-ownership records are restricted and are not part of this dataset. |
| **Authorized share capital is structural** | For corporations, the register exposes the authorized share classes (class, series, par value, total authorized, total issued and outstanding) but does not identify the holders. The share classes appear on the Trade Register Extract only, not in the JSON response. LLC members are returned as `otherKeyPersons`; managers and managing members are `legalRepresentatives`. |
| **Name history is preserved** | The register tracks all prior legal names for a given entity, including the date of each change. A search by an older name resolves to the same identification number as the current name. |
| **Fictitious names / DBAs sit on the parent** | Registered fictitious or trade names (DBAs) appear on the parent entity's record rather than as standalone records. |
| **Mergers are linked** | When an entity has absorbed others through a merger, the absorbed entities are listed on the surviving record with their identification numbers. The absorbed entities' own records remain searchable and stay flagged as inactive. |
| **Purpose uses a NAICS-based code** | Each entity carries a single NAICS code with a human-readable description, plus a free-text "purpose" paragraph quoting the corporate purpose from the formation filing. The state does not collect NACE or ISIC codes; the API derives them from the NAICS code. |
| **Entity-type composite labels** | The entity-type field is a composite of the domestic / foreign qualifier, the profit / non-profit qualifier (for corporations), and the base form. Examples: `Domestic Profit Corporation`, `Foreign Limited Liability Company`, `Domestic Non-Profit Corporation`. |
## Mappings
### Entity Types
The register publishes entity types as composite labels. The standardized mapping below covers the combinations the API returns.
| Local Label | English Translation | Standardized Form | ISO 20275 |
| - | - | - | - |
| Domestic Profit Corporation | Domestic Profit Corporation | Corporation | Z54A |
| Foreign Profit Corporation | Foreign Profit Corporation | Corporation | |
| Domestic Non-Profit Corporation | Domestic Non-Profit Corporation | Nonprofit Organization | AVLE |
| Foreign Non-Profit Corporation | Foreign Non-Profit Corporation | Nonprofit Organization | |
| Domestic Limited Liability Company | Domestic Limited Liability Company | Limited Liability Company | DRSE |
| Foreign Limited Liability Company | Foreign Limited Liability Company | Limited Liability Company | |
| Domestic Limited Partnership | Domestic Limited Partnership | Partnership | FW66 |
| Foreign Limited Partnership | Foreign Limited Partnership | Partnership | |
| Domestic Limited Liability Partnership | Domestic Limited Liability Partnership | Partnership | - |
| Foreign Limited Liability Partnership | Foreign Limited Liability Partnership | Partnership | - |
| Domestic Benefit Corporation | Domestic Benefit Corporation | Corporation | QMI2 |
| Non-Resident Landlord | Non-Resident Landlord | Other | - |
### Status Values
Active is the implicit default. Inactive entities carry an explicit revocation, withdrawal, or dissolution date on the record. The API returns a normalized `status.localName` plus an `active` boolean.
| Local Status | Active |
| - | - |
| Active | Yes |
| Revoked | No |
| Withdrawn | No |
| Dissolved | No |
The Active database covers currently-effective entities plus any that were revoked within the prior year. The Inactive database holds older revocations, withdrawals, and dissolutions.
### Officer Roles
The register records officers, directors, and managers on each entity. The API surfaces them as either `legalRepresentatives` (declared current office context, with company-specific powers unverified) or `otherKeyPersons` (the registered agent, executive titles, and supporting officers). Most title strings carry a trailing department qualifier (`PRESIDENT, TOYS LICENSING & ENTERTAINMENT`, `DIRECTOR, RISK MANAGEMENT`); known full titles use exact catalogue meaning. A functional title such as `DIRECTOR, RISK MANAGEMENT` is retained as another key person rather than a board director.
| Local Role | Mapped To |
| - | - |
| President | legalRepresentatives |
| Vice-President | legalRepresentatives |
| Secretary | legalRepresentatives |
| Treasurer | legalRepresentatives |
| Director | legalRepresentatives |
| Manager (LLC) | legalRepresentatives |
| Managing Member (LLC) | legalRepresentatives |
| CEO | legalRepresentatives |
| CFO | legalRepresentatives |
| COO | legalRepresentatives |
| Member (LLC) | otherKeyPersons |
| Organizer | otherKeyPersons |
| Incorporator | otherKeyPersons |
| Assistant Secretary | otherKeyPersons |
| Assistant Treasurer | otherKeyPersons |
| EVP, SVP, VP | otherKeyPersons |
| Chief Officer titles | otherKeyPersons |
| Registered Agent | otherKeyPersons |
The registered agent is surfaced as an `otherKeyPersons` entry with `role.standardized: "Registered Agent"`. An agent marked as resigned on the register is omitted. For agents that are corporate entities (such as registered-agent services), the entry carries `type: "company"` with a `legalName`; for individual agents, the entry carries `type: "individual"` with a `fullName`.
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company profile | Yes | Legal name, identification number, entity type, dates of incorporation or registration, status with revocation / withdrawal / dissolution dates, principal-office address, corporate purpose, NAICS code with description. |
| Registered agent | Yes | Returned as `otherKeyPersons` with `role.standardized: "Registered Agent"`, with the name and full address. A resigned agent is omitted. |
| Legal representatives | Yes | Officers and directors of a corporation (President, Vice-President, Secretary, Treasurer, Director, CEO, CFO, COO) and managers / managing members of an LLC, with their addresses. |
| Other key persons | Yes | Executive roles outside the statutory officers (EVP, SVP, VP, Chief X Officer titles), assistant officers, and the registered agent. |
| Shareholders | No | Not collected by Rhode Island at the state level. Authorized share capital appears on the Trade Register Extract only, and the holders are not part of the register. |
| Ultimate beneficial owners | No | Rhode Island does not maintain a public beneficial-ownership register. |
| Activity codes | Yes | The register's single NAICS code with description, plus ISIC and NACE codes derived from it. |
| Prior names | Trade Register Extract only | The corporate name-change history, with the effective date of each change, is shown on the Trade Register Extract. It is not returned in the JSON response. |
| Fictitious / DBA names | Trade Register Extract only | Registered fictitious or trade names, with the filing date, are shown on the Trade Register Extract. They are not returned in the JSON response. |
| Mergers | Trade Register Extract only | Absorbed entities, with identification number and merger date, are shown on the Trade Register Extract. They are not returned in the JSON response. |
| Trade Register Extract | Yes | Printable PDF of the Department of State entity detail page, captured at request time. Bundled with the company-data block at no extra charge. |
| Certificate of Good Standing | Planned | The official Department of State Certificate of Good Standing is identified and documented but not yet generally available. Pricing and availability will be on the live pricing page once enabled. |
# South Carolina (US)
Source: https://docs.topograph.co/essentials/us-south-carolina
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date South Carolina (US) reference is on the [South Carolina (US) country page](https://www.topograph.co/countries/us-sc).
## Start here
This guide contains public integration notes for South Carolina. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction is in preview. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Status Values](#status-values)
* [Data Availability](#data-availability)
## Data Sources
South Carolina is sourced live from the **South Carolina Secretary of State — Business Entities Online** portal at `businessfilings.sc.gov`. The register covers every entity formed under Title 33 of the South Carolina Code of Laws — business corporations, statutory close corporations, professional corporations, nonprofit corporations, limited liability companies, limited partnerships, and limited liability partnerships. Sole proprietorships and general partnerships are not filed with the Secretary of State and are out of scope.
* **SC SoS Business Entities Online** (live, primary). Public profile carries legal name, the public Entity Id, entity type, current status, domestic/foreign flag, incorporated state, key dates (effective, expiration, term-end, dissolved), the registered agent and agent address, the full filing history, and any former names.
**No officer data at the state level.** South Carolina's Secretary of State does not collect or publish officer or director information. The SoS website directs requests for officer data to the South Carolina Department of Revenue at (844) 898-8542. The only person on file in our response is the **Registered Agent**, surfaced under `otherKeyPersons`.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **SC SoS Entity GUID** | 8-4-4-4-12 lowercase hex GUID | `e6980025-c7ec-4715-8bf0-52b5ef0c585f` | The canonical, navigable identifier used by the portal at `/Entity/Profile/`. Returned in every search result as `id`. |
The 8-digit zero-padded **Entity Id** displayed on the SoS profile page (for example `00121743`) is a human-facing identifier shown alongside the GUID. South Carolina's public search form does not accept it as input — pass the GUID to the Topograph API. The Entity Id can still be useful when reconciling against paper filings printed by the state.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `guid` | 8-4-4-4-12 lowercase hex GUID | `e6980025-c7ec-4715-8bf0-52b5ef0c585f` | All entities |
| `entityId` | 8-digit zero-padded integer | `00121743` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when the eight-digit `entityId` has a unique match against South Carolina registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-175 chars | `"BMW MANUFACTURING"` | Begins-with (case-insensitive) | Multiple results |
| By GUID | 8-4-4-4-12 hex | `e6980025-c7ec-4715-8bf0-52b5ef0c585f` | Exact | Exact match returned first (matchType: id); other results may follow |
**Begins-with search.** Name search anchors on the beginning of the legal name. The result table is capped at 50 matches; use a fuller query string to narrow the set.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Two identifiers per entity** | The portal surfaces a navigable GUID and a display-only 8-digit Entity Id. Topograph API calls use the GUID. The Entity Id is exposed under `entityId` for reconciliation with paper documents. |
| **Officers and directors are not on file** | The Secretary of State does not collect officer or director information. Only the **Registered Agent** is published, returned under `otherKeyPersons` with `role.standardized = "Registered Agent"`. |
| **No shareholder or UBO register** | South Carolina does not file shareholders or beneficial owners with the SoS for any entity type. Federal FinCEN BOI records are restricted and not exposed. |
| **No activity codes** | NAICS / NACE / ISIC codes are not collected by the SC business register. |
| **No federal EIN** | The federal employer identification number (EIN) and SC tax registrations are held by the SC Department of Revenue, not the SoS, and are not exposed through the public SoS portal. |
| **No bulk extract** | The SoS does not publish a bulk dataset, FTP feed, or open-data corporations download. The portal is the only public source — every Topograph lookup is a live query. |
| **Paid certificates not yet offered** | The Certificate of Existence (Good Standing), Certificate of Authority for foreign entities, Certificate of No Record, and certified document copies are paid orders through the SoS portal and are not yet offered through Topograph. |
| **Live profile lookups** | Every Topograph request hits the register live. Prefill and verification modes return the same live register data. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type label rendered on the SoS profile page. South Carolina does not publish a numeric codelist — the label is the canonical value.
| Local Name | Standardized | Statutory Basis (S.C. Code of Laws Title 33) |
| - | - | - |
| Corporation | Corporation | Chapters 1-20 (Business), 18 (Statutory Close), 19 (Professional) |
| Limited Liability Company | Limited Liability Company | Chapter 44 |
| Limited Partnership | Partnership | Chapter 42 |
| Nonprofit | Nonprofit Organization | Chapter 31 |
| Reservation | Other | Name reservation, not a registered entity |
Limited Liability Partnership (Title 33 Chapter 41) is administered by the SoS but does not appear in our preview sampling. If an LLP filing appears through the API, its legal form is standardized automatically.
### Status Values
| Local Status | Active | Meaning |
| - | - | - |
| `Good Standing` | `true` | Registered and current with all required filings. |
| `Dissolved` | `false` | Voluntary dissolution recorded with the SoS. |
| `Forfeited` | `false` | Charter forfeited — typically for non-payment of the annual report. |
| `Merged Out of Existence` | `false` | Entity rolled into a surviving entity through a merger filing. |
| `Reserved` | `false` | Name reservation; not a registered entity. |
## Data Availability
| Datapoint | Availability |
| - | - |
| `company` | ✅ Legal name, entity type, status, domestic/foreign flag, incorporated state, effective date. |
| `otherKeyPersons` (Registered Agent) | ✅ Agent name and agent address. Always exactly one row when present. |
| `legalRepresentatives` (officers, directors) | ❌ Not collected by the SoS. The SoS defers to the SC Department of Revenue. |
| `shareholders` | ❌ Not filed with the SoS. |
| `ultimateBeneficialOwners` | ❌ No public state register; federal FinCEN BOI is restricted. |
| `activityCodes` | ❌ Not collected by the SoS. |
| `taxId` | ❌ Federal EIN and SC tax IDs are held by the Department of Revenue. |
| Trade Register Extract (document) | ✅ Printable PDF of the SoS Entity Profile page — bundled with `company` at no additional charge. |
| Certificate of Existence / Good Standing | ❌ Available from the SoS but not yet offered through Topograph. |
| Certified copies of filings | ❌ Available from the SoS but not yet offered through Topograph. |
# South Dakota
Source: https://docs.topograph.co/essentials/us-south-dakota
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date South Dakota reference is on the [South Dakota country page](https://www.topograph.co/countries/us-sd).
## Start here
This guide contains public integration notes for South Dakota. Use it for identifier formats, search behavior, and state-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Data Availability](#data-availability)
## Data Sources
South Dakota uses a single live integration against the **South Dakota Secretary of State SoS Enterprise portal** (`sosenterprise.sd.gov`). Every request hits the register in real time. There is no open-data feed or bulk extract available for free: the register only offers a paid paper subscription for bulk database downloads, so Topograph sources data directly from the live portal.
The register covers every domestic and foreign for-profit and nonprofit corporation, LLC, limited partnership, registered limited liability partnership, financial institution (bank, trust company), and trade name filed in South Dakota.
**Two retrieval modes, same price.** Set the `mode` parameter:
* **`prefill`** — a fast base profile: legal name, entity type, current status, and filing/registration date. Non-authoritative (`authoritative: false` in the response); it does **not** include the address or registered agent.
* **`verification`** (default) — the full authoritative record: adds the principal office address, the registered agent (`otherKeyPersons`), and the bundled Trade Register Extract.
Both modes bill identically and resolve live against the register (there is no free bulk-data snapshot). Use `prefill` for a fast identity/status check and `verification` for the complete record.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Business ID** | Exactly 8 characters: two uppercase letters + six digits, leading zeros included | `FB033693` | Assigned by the South Dakota Secretary of State. |
Prefixes seen in our search results include `DL`, `NS`, `DB`, `FB`, `FL`, `FP`, `FK`, `BK`, `CH`, `DP`, `DR`, `RN`, `RS`, `DM`, `DT`, `GP` and `FN` (e.g. `DL025748`, `NS000956`, `DB007028`). The list is not closed, and the register does not publish what the letters mean, so do not infer the legal form from them.
The Business ID is exactly 8 characters. The two letters are always uppercase and the six digits keep their leading zeros. Both are part of the number: pass the ID exactly as a search result returns it.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `businessId` | Two uppercase letters + six digits, leading zeros included | `FB033693` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Acme"` | Starts-with (case-insensitive) | Multiple results |
| By Business ID | 8 characters: two letters + six digits | `FB033693` | Exact | Exact match returned first (`matchType: id`); other results may follow |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use more specific queries to narrow the result set, which is capped at 50 matches.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefix is not optional** | The two-letter prefix is part of the Business ID. Passing only the numeric portion (e.g. `033693`) is not a valid identifier and will return no results. |
| **No officers or directors** | The South Dakota register does not publish officers, directors, members, or organizers on any entity detail page. The only party disclosed publicly is the registered agent, which is returned under `otherKeyPersons`. |
| **Registered agent is not a legal representative** | The registered agent receives service of process but has no statutory authority to bind the entity. It appears under `otherKeyPersons`, not `legalRepresentatives`. |
| **No shareholder list** | South Dakota does not publish individual shareholders or owner lists for any entity type. For-profit corporations carry an authorized capital figure (share count and par value) on the register record, but it is not currently surfaced in the response, and no shareholder register exists. |
| **No activity codes** | NAICS, NACE, and ISIC codes are not collected by the South Dakota business register. |
| **Addresses are parsed** | The register records the principal office address in a compact form; Topograph parses it into structured `legalAddress` fields (and geocodes it) in verification mode. |
| **Foreign name field** | Foreign entities may carry a separate foreign-registered name on the register record. It is not currently surfaced in the API response. |
| **Term of duration** | Most entities are "Perpetual"; some carry a fixed expiration date. This is on the register record but is not currently surfaced in the API response. |
| **No open-data snapshot** | Unlike many US states, South Dakota does not publish a free bulk dataset. Every request goes to the live register portal. |
## Mappings
### Company Status
Status is read directly from the register and mapped to a Topograph standardized value.
| Register Status | Standardized | Notes |
| - | - | - |
| Good Standing | Active | All annual reports current |
| Active | Active | Used on financial-institution filings |
| Revoked (Administrative) | Closed | Annual-report lapse; administrative dissolution |
| Dissolved | Closed | Voluntary dissolution |
| Withdrawn | Closed | Foreign entity withdrew South Dakota registration |
| Merged | Closed | Entity merged into another |
| Expired | Closed | Term of duration expired |
Status values not in the table above are surfaced as-is from the register under `company.status.localName` and may be enriched by AI where the raw label maps to a known standardized category.
## Data Availability
**Prefill mode** returns only the base fields — company name, entity type / legal form, current status, and registration date. The principal office address, the registered agent, and the Trade Register Extract require **verification mode**.
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name (both modes) |
| Company status | Yes | Current status, e.g. Good Standing / Withdrawn / Revoked (both modes) |
| Legal form | Yes | Entity type as recorded by the register, e.g. `CORP`, `LLC` (both modes) |
| Registration date | Yes | Filing date with the Secretary of State (both modes) |
| Legal address | Yes | Principal office address, parsed and geocoded — **verification mode only** |
| Registered agent | Yes | Name and address, returned as `otherKeyPersons` — **verification mode only** |
| Former legal names | Yes | Prior legal names of renamed entities, returned as `legacyLegalNames` — **verification mode only** |
| Trade Register Extract | Yes | Printed PDF of the entity record, bundled at no extra charge — **verification mode only** |
| Foreign registered name | No | Present on the register record but not currently surfaced in the response |
| Mailing address | No | Present on the register record but not currently surfaced in the response |
| Jurisdiction of formation | No | Present on the register record but not currently surfaced in the response |
| Term of duration | No | Present on the register record but not currently surfaced in the response |
| Annual report due date | No | Present on the register record but not currently surfaced in the response |
| Legal representatives | No | Officers, directors, and members are not published by the South Dakota register |
| Activity codes | No | Not collected by the register |
| Shareholders | No | Not published for any entity type |
| UBOs | No | No state beneficial-ownership register; the federal database is restricted |
| Annual report PDFs | Roadmap | Referenced in the entity filing history but not yet available as downloadable documents |
| Articles of Incorporation | Roadmap | Per-filing PDFs are deferred |
| Financial data | No | Not collected by the South Dakota register |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-SD&query=Smithfield%20Packaged" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "FB033693",
"legalName": "SMITHFIELD PACKAGED MEATS CORP.",
"countryCode": "US-SD",
"matchReason": { "matchType": "default" },
"address": { "countryCode": "US-SD" }
},
{
"id": "FB038869",
"legalName": "SMITHFIELD PACKAGED MEATS SALES CORP.",
"countryCode": "US-SD",
"matchReason": { "matchType": "default" },
"address": { "countryCode": "US-SD" }
}
]
```
### Search by Business ID
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-SD&query=BK000183" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "BK000183",
"legalName": "FIRST PREMIER BANK",
"countryCode": "US-SD",
"matchReason": { "matchType": "id" },
"address": { "countryCode": "US-SD" }
}
]
```
### Company Profile — prefill mode (fast base profile)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-SD", "id": "FB196942", "dataPoints": ["company"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "FB196942",
"countryCode": "US-SD",
"identifiers": { "businessId": "FB196942" },
"legalName": "Smithfield Foods, Inc.",
"registrationDate": "2021-02-18",
"status": { "localName": "Good Standing", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "CORP" }
}
}
```
### Company Profile — verification mode (full record with registered agent)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-SD", "id": "FB033693", "dataPoints": ["company", "otherKeyPersons"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "FB033693",
"countryCode": "US-SD",
"identifiers": { "businessId": "FB033693" },
"legalName": "SMITHFIELD PACKAGED MEATS CORP.",
"legacyLegalNames": ["JOHN MORRELL & CO."],
"registrationDate": "2009-08-04",
"status": { "localName": "Good Standing", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "CORP" },
"legalAddress": {
"addressLine1": "200 Commerce Street",
"city": "Smithfield",
"postalCode": "23430",
"region": "Isle of Wight County",
"state": "Virginia",
"countryCode": "US",
"latitude": 36.98475035,
"longitude": -76.63012801121371
}
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": { "localName": "Registered Agent", "standardized": "Other" },
"company": {
"countryCode": "US",
"legalName": "C T CORPORATION SYSTEM",
"legalAddress": {
"addressLine1": "319 S COTEAU ST",
"city": "PIERRE",
"postalCode": "57501-3187",
"region": "SD",
"countryCode": "US"
}
}
}
]
}
```
# Tennessee (US)
Source: https://docs.topograph.co/essentials/us-tennessee
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Tennessee (US) reference is on the [Tennessee (US) country page](https://www.topograph.co/countries/us-tn).
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Other Key Persons](#other-key-persons)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
All entity data comes from the **Tennessee Secretary of State — Business Services Division** via the **TN CAB** portal ([tncab.tnsos.gov](https://tncab.tnsos.gov/business-entity-search)). This is the official online search system for all for-profit corporations, LLCs, nonprofit corporations, limited partnerships, and their foreign equivalents registered in Tennessee.
Every request hits the live register — there is no bulk data export or REST API. The response is always authoritative and up to date.
Tennessee is a single-source country. All data — company profile, registered
agent, and search — comes from the live TN SoS portal. The Trade Register
Extract is included at no extra charge with the company data block.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Control Number** | 9-digit zero-padded integer | `000239194` | Primary identifier assigned by TN SoS at registration |
The Control Number is the only identifier supported for company retrieval. Leading zeros may be omitted in queries — `239194` resolves the same entity as `000239194`. To find a Control Number from a name, use the search endpoint first.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `controlNumber` | `NNNNNNNNN` | `000239194` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Tennessee Energy LLC"` | Starts with | Multiple results |
| By Control Number | 1–9 digits | `000239194` | Exact | Exact match returned first (matchType: id); other results may follow |
Name search matches from the beginning of the entity name (starts-with). For
broader matches, use shorter prefixes.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No officers published** | The TN SoS public portal does not expose officer or director information for any entity type. Filing history records officer changes but they are not displayed publicly. |
| **No bulk data / REST API** | Tennessee does not offer bulk corporate data exports or a public REST API. Every lookup is resolved live against the SoS portal. |
| **No activity codes** | Industry classification codes are tracked internally by TN SoS but are not displayed on the public entity detail page. |
| **Standing fields** | The entity detail page shows three standing indicators: Annual Report, Registered Agent, and Department of Revenue. They are not currently included in the API response. |
| **Control Number zero-padding** | Control Numbers are always 9 digits in API responses. The portal displays them without leading zeros; we normalize to 9-digit form in all identifiers. |
## Mappings
### Company Status
Status comes from the TN SoS entity status field on the detail page.
| Source Value | Active | Notes |
| - | - | - |
| `Active` | `true` | Entity is in good standing |
| `Active - Dissolved` | `true` | Entity is dissolving but still active |
| `Dissolved` | `false` | Voluntary or administrative dissolution |
| `Revoked` | `false` | Revocation by the Secretary of State |
| `Withdrawn` | `false` | Foreign entity withdrew its registration |
| `Cancelled` | `false` | Registration cancelled |
| `Merged` | `false` | Entity merged into another entity |
### Legal Forms
Legal form is derived from the Entity Type field on the TN SoS portal. Domestic types cover entities formed under Tennessee law; Foreign types cover entities formed elsewhere and registered to do business in Tennessee.
| Portal Type | Standardized | ELF Code |
| - | - | - |
| For-profit Corporation | Corporation | `QJ9F` |
| Foreign For-profit Corporation | Corporation | — |
| Limited Liability Company (LLC) | Limited Liability Company | `I2XB` |
| Foreign Limited Liability Company (LLC) | Limited Liability Company | — |
| Nonprofit Corporation | Nonprofit Organization | `RD1T` |
| Foreign Nonprofit Corporation | Nonprofit Organization | — |
| Limited Partnership (LP) | Partnership | `DQUB` |
| Foreign Limited Partnership (LP) | Partnership | — |
| Reserved Name | Other | — |
### Other Key Persons
| Role | Standardized | Notes |
| - | - | - |
| Registered Agent | Registered Agent | Statutory service-of-process contact, required for all entities |
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the entity detail page |
| Company status | Yes | Register status label with an active / inactive flag |
| Registration date | Yes | Initial filing date |
| Legal address | Yes | Principal office address (registered agent address when no principal office is listed) |
| Mailing address | No | Present on the register page but not currently included in the response |
| Legal form | Yes | Entity type with domestic/foreign distinction |
| Formation jurisdiction | No | Present on the register page but not currently included in the response |
| Registered agent | Yes | Returned as Other Key Person: name, plus address for individual agents |
| Standing information | No | Present on the register page but not currently included in the response |
| Legal representatives | No | Officers are not published on the TN SoS public portal |
| Activity codes | No | Not displayed on the public entity detail page |
| Shareholders | No | Not collected by the Tennessee business register |
| UBOs | No | No state beneficial-ownership register |
## Documents
### Available Documents
| Document | Availability | Format |
| - | - | - |
| **Trade Register Extract** | Always available | PDF |
The Trade Register Extract is a printed capture of the TN SoS entity detail
page. It is included with the company data block at no extra charge.
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-TN&query=FEDEX" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "000060129",
"legalName": "FEDERAL EXPRESS CORPORATION",
"countryCode": "US-TN",
"matchReason": { "matchType": "default" }
}
]
```
### Search by Control Number
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-TN&query=000239194" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "000239194",
"legalName": "TOPOGRAPH TENNESSEE LLC",
"countryCode": "US-TN",
"matchReason": {
"matchType": "id",
"identifier": { "controlNumber": "000239194" }
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-TN", "id": "000239194", "dataPoints": ["company", "otherKeyPersons"]}'
```
```json theme={null}
{
"company": {
"id": "000239194",
"countryCode": "US-TN",
"identifiers": { "controlNumber": "000239194" },
"legalName": "TOPOGRAPH TENNESSEE LLC",
"registrationDate": "2021-03-15",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Limited Liability Company (LLC)",
"englishTranslation": "Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "123 Main Street",
"city": "Nashville",
"postalCode": "37201",
"region": "Davidson County",
"countryCode": "US",
"state": "Tennessee"
}
},
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"countryCode": "US",
"legalName": "CT Corporation System"
}
}
]
}
```
### Available Documents
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-TN", "id": "000239194", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_abc123",
"name": "Trade Register Extract",
"format": "pdf"
}
}
}
```
# Texas (US)
Source: https://docs.topograph.co/essentials/us-texas
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Texas (US) reference is on the [Texas (US) country page](https://www.topograph.co/countries/us-tx).
## Start here
This guide contains public integration notes for Texas. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Activity Codes](#activity-codes)
* [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)
* [Documents](#documents)
## Data Sources
Texas uses three data sources depending on the request mode and entity type.
**Texas Comptroller of Public Accounts** (prefill mode)
* **Franchise Tax API** (primary source). Covers entities set up for franchise tax under **Tax Code Chapter 171**: corporations, LLCs, LPs, LLPs, professional associations, and other entities doing business in Texas. \~3.4M taxpayers. Provides company name, registered office address, SOS registration status, state of formation, officer/director information, and registered agent details. Equivalent open dataset: [Active Franchise Tax Permit Holders](https://data.texas.gov/dataset/Active-Franchise-Tax-Permit-Holders/9cir-efmm).
* **Sales Tax Payer API** (fallback + establishments). Covers holders of a **sales tax permit under Tax Code Chapter 151, Subchapter F**. This includes any person or entity authorized to collect sales tax on tangible personal property, including sole traders. Provides business name, individual name (for sole traders), address, permit status, and **outlet locations** (establishments) with addresses and permit dates. Equivalent open dataset: [Active Sales Tax Permit Holders](https://data.texas.gov/Government-and-Taxes/Active-Sales-Tax-Permit-Holders/jrea-zgmq).
**Texas Secretary of State** (verification mode + documents)
The [Texas Secretary of State](https://www.sos.state.tx.us/) is the official corporate registry for entities formed or registered to do business in Texas. It is the authoritative source for entity status, filing history, registered agent, officer/director records, and assumed names. Used for verification-mode company profiles and for issuing the Information Letter document, both read from the Secretary of State's online system, SOSPortal. Covers formal entities only: sole traders are not registered with the SOS.
In prefill mode, franchise tax is tried first (richer data with officers
and registered agent). If the entity is not found there (sole traders,
entities not set up for franchise tax), it falls back to sales tax
automatically. Establishments are always fetched from the sales tax endpoint.
**Entity coverage varies by source.** Franchise tax (Chapter 171) covers
corporations, LLCs, LPs, LLPs, and professional associations. The sales tax
endpoint covers holders of a sales tax permit (Chapter 151, Subchapter F): any
person or entity selling taxable goods, including sole traders. Businesses
that only provide services (consultants, lawyers, SaaS) typically don't hold a
permit and won't appear in either source. Verification mode is limited to
formal entities registered with the Secretary of State: sole traders have no
SOS filing and are not covered.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Taxpayer Number** | 11 digits, no separators. Starts with 1 (built on the federal EIN) or 3 (assigned by the Comptroller); the last digit is a check digit | `17307175087` | Texas Comptroller's primary identifier |
| **SOS File Number** | 10 digits, zero-padded | `0003077806` | Secretary of State filing number. The Secretary of State displays it without the leading zeros (`3077806`) |
**Which identifier to use?** For **search**, use the 11-digit Taxpayer Number or the SOS File Number. For **company profile**, you must use the **11-digit Taxpayer Number** returned in the search result `id` field. The detail API only accepts this format.
**Search first, then fetch.** The SOS File Number only works for search. To retrieve company data, use the `id` from the search result (always the 11-digit Taxpayer Number). Passing an EIN or SOS File Number directly to the company profile endpoint will fail.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `taxpayerId` | 11 digits, starting with 1 or 3 | `17307175087` | All entities |
| `feiNumber` | 9 digits, no separator | `730717508` | Most entities |
| `sosFileNumber` | 10 digits, zero-padded | `0003077806` | Formal entities (Secretary of State filings) |
| `stateOfFormation` | 2-letter | `TX`, `NJ`, `DE` | Franchise tax entities, when reported (prefill mode) |
| `sosRegistrationStatus` | Text | `ACTIVE` | Franchise tax entities, when reported (prefill mode) |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when `sosFileNumber` has a unique match against Texas Secretary of State registration or validation references in GLEIF. The padded and unpadded spellings of the SOS number are equivalent for this match. Taxpayer numbers and federal EINs are excluded.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Taxpayer Number | 11 digits | `17307175087` | Exact | Exact match returned first (matchType: id); other results may follow |
| By SOS File Number | 6-10 digits, padded or not | `0003077806`, `803367205` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | 2-50 chars | `"EXXON MOBIL"` | Fuzzy | Multiple results |
**SOS File Number.** Pass it zero-padded (`0803367205`) or as the Secretary of State displays it (`803367205`); both resolve. A 9-digit input is read as an SOS File Number. Search by the Federal EIN is not supported.
**Name search is prefix-based.** Searching for `"TOPOGRAPH"` returns all
entities whose name starts with or contains that string, including
`TOPOGRAPHIC OM, INC.`, `TOPOGRAPH LLC`, etc.
### Active companies only
Search can return companies that are no longer active. [`activeOnly=true`](/essentials/search#active-companies-only) removes those whose status is known at search time; the others are kept. Lookups by taxpayer number are filtered. Name searches and file-number lookups may still include inactive companies, because most of their results carry no status.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Prefill mode is non-authoritative** | Prefill mode uses the Comptroller franchise tax system, not the official SOS corporate registry. Verification mode uses the Secretary of State directly and is authoritative. |
| **Verification mode: formal entities only** | The Secretary of State only registers formal entities (corporations, LLCs, LPs, etc.). Sole traders have no SOS filing number. Verification mode requests for sole-trader taxpayer IDs will not resolve. |
| **Company profile requires 11-digit Taxpayer Number** | The detail API only accepts the 11-digit Taxpayer Number. The 10-digit SOS File Number (e.g. `0003077806`) works for search only; an EIN does not. Always use the `id` from search results to fetch company data. |
| **No sole proprietors in franchise tax** | Sole proprietors are exempt from franchise tax. They are covered via the sales tax fallback and identified by the `IS` org type code. |
| **No legal form in Comptroller live API** | The Comptroller live API does not return entity type. In prefill mode, legal form comes from the open data `taxpayer_organizational_type` code, with name-suffix extraction as fallback. In verification mode, the SOS entity type string is used directly. |
| **Officer titles truncated (prefill mode)** | In prefill mode, titles from the Comptroller are cut to \~10 characters: `VICE PRESIDENT` becomes `VICE PRESI`. AI enrichment standardizes and completes them. In verification mode, titles come directly from the SOS Management tab and are always the full string as filed. |
| **HTML entities in titles** | Some Comptroller titles contain `&` instead of `&` (e.g., `PRES & CEO`). Decoded automatically. |
| **Leading spaces in state** | `stateOfFormation` has a leading space (e.g., ` TX`). Trimmed automatically. |
| **Missing detail for some entities** | Some entities appear in search but return "not set up for Franchise Tax" on the detail endpoint. These are entities tracked by SOS but not the Comptroller. |
| **Registered agent is not a legal representative** | Per BOC §5.206, the registered agent's only duty is to receive and forward legal process. They have no authority to act for the company. Mapped as Other Key Person. |
| **Two address types** | The Comptroller API returns both mailing address and registered office address. We use the **registered office** as `legalAddress` because it's the official address of record. |
| **Two status fields (prefill mode)** | `rightToTransactTX` = franchise tax standing only. `sosRegistrationStatus` = corporate status from SOS. We use SOS status as the company status in prefill mode. In verification mode, status is read directly from the SOS entity page. |
| **Officer data depends on report filing (prefill mode)** | In prefill mode, officer data comes from franchise tax annual reports. Entities that have never filed a report will have zero officers returned, regardless of their actual structure. This includes some large active companies that file under a different entity. Verification mode reads officers directly from the SOS Management tab and is not affected by this. |
## Mappings
### Company Status
**Prefill mode** uses `sosRegistrationStatus` from the Comptroller (which mirrors the SOS), not `rightToTransactTX` (franchise tax standing).
| Source Value | Mapped Status | Active |
| - | - | - |
| `ACTIVE` | Active | `true` |
| `INACTIVE` | Inactive | `false` |
| Other values | As-is | `false` |
**Verification mode** reads entity status directly from the Secretary of State.
| SOS Status Value | Mapped Status | Active | Notes |
| - | - | - | - |
| `In existence` | In existence | `true` | Entity is active and in good standing |
| `Forfeited existence` | Forfeited | `false` | Franchise tax delinquency |
| `Voluntarily dissolved` | Dissolved | `false` | Entity chose to dissolve |
| `Merged` | Merged | `false` | Entity was absorbed by another |
### Legal Forms
Legal form is sourced differently depending on the request mode.
**Prefill mode** uses the Comptroller's `taxpayer_organizational_type` code, a closed 2-letter set defined in the [Franchise Layout](https://data.texas.gov/dataset/Active-Franchise-Tax-Permit-Holders/9cir-efmm/about_data) record layout, fetched from the Comptroller open data API. It distinguishes domestic vs foreign entities (e.g. `CT` Texas Profit Corporation vs `CF` Foreign Profit Corporation) and covers types not detectable from names (nonprofits, associations, trusts, joint ventures). Falls back to name-suffix extraction (BOC §5.054-§5.063) when the open data lookup returns no result.
**Verification mode** uses the entity type field from the Secretary of State register directly. The SOS uses the full English description from the Texas Business Organizations Code — a closed set of 24 types organized as Domestic/Foreign pairs (e.g. "Domestic Limited Liability Company (LLC)", "Foreign For-Profit Corporation"). Source: [Texas BOC forms index](https://www.sos.state.tx.us/corp/forms_boc.shtml).
| Code | Legal Form | Standardized | ISO 20275 |
| - | - | - | - |
| CL | Texas Limited Liability Company | Limited Liability Company | `WYG5` |
| CI | Foreign Limited Liability Company | Limited Liability Company | |
| CT | Texas Profit Corporation | Corporation | `C5K7` |
| CF | Foreign Profit Corporation | Corporation | |
| CP | Texas Professional Corporation | Corporation | `9AAS` |
| CU | Foreign Professional Corporation | Corporation | |
| CN | Texas Non-Profit Corporation | Nonprofit Organization | `OGSS` |
| CM | Foreign Non-Profit Corporation | Nonprofit Organization | |
| PL | Texas Limited Partnership | Partnership | `FE1L` |
| PF | Foreign Limited Partnership | Partnership | |
| PB | Business General Partnership | Partnership | |
| AP | Texas Professional Association | Corporation | `MXWB` |
| AF | Foreign Professional Association | Corporation | |
| TR | Trust | Trust | |
| IS | Sole Proprietorship (Individual) | Sole Proprietorship | |
Domestic entities are formed under Texas law; foreign entities are registered to do business in Texas. The parenthetical abbreviation (LLC), (LP), (PLLC) is part of the official SOS display string.
| SOS Entity Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic For-Profit Corporation | Corporation | `C5K7` |
| Foreign For-Profit Corporation | Corporation | — |
| Domestic Nonprofit Corporation | Nonprofit Organization | `OGSS` |
| Foreign Nonprofit Corporation | Nonprofit Organization | |
| Domestic Professional Corporation | Corporation | `9AAS` |
| Foreign Professional Corporation | Corporation | — |
| Domestic Professional Association | Corporation | `MXWB` |
| Foreign Professional Association | Corporation | |
| Domestic Limited Liability Company (LLC) | Limited Liability Company | `WYG5` |
| Foreign Limited Liability Company (LLC) | Limited Liability Company | — |
| Domestic Professional Limited Liability Company (PLLC) | Limited Liability Company | |
| Foreign Professional Limited Liability Company (PLLC) | Limited Liability Company | |
| Domestic Limited Partnership (LP) | Partnership | `FE1L` |
| Foreign Limited Partnership (LP) | Partnership | |
| Domestic Limited Liability Partnership | Partnership | |
| Foreign Limited Liability Partnership | Partnership | |
| Domestic Real Estate Investment Trust | Trust | |
| Foreign Real Estate Investment Trust | Trust | |
| Domestic Business Trust | Trust | |
| Foreign Business Trust | Trust | |
| Domestic Cooperative Association | Nonprofit Organization | |
| Foreign Cooperative Association | Nonprofit Organization | |
| Foreign Series Limited Liability Company (LLC) | Limited Liability Company | |
| Foreign Financial Institution | Corporation | |
ISO 20275 (ELF) codes are from the [GLEIF US-TX jurisdiction list](https://www.gleif.org/en/about-lei/code-lists/iso-20275-entity-legal-forms-code-list).
### Activity Codes
NAICS codes are sourced from the Texas Comptroller open data. ISIC Rev. 5 codes are derived from NAICS through the [US Census Bureau concordance table](https://www.census.gov/naics/concordances/concordances.html) (NAICS to ISIC Rev. 4), chained with the official ISIC Rev. 4 to Rev. 5 correspondence. NACE Rev. 2.1 codes are derived from the ISIC code through a correspondence table; they are not a copy of it.
| System | Source | Example |
| - | - | - |
| NAICS | Comptroller open data (franchise or sales tax dataset) | `541330` (Engineering Services) |
| ISIC Rev. 5 | Derived from NAICS | `7110` (Architectural and engineering, and related technical consultancy activities) |
| NACE Rev. 2.1 | Derived from ISIC | `71.1` (Architectural and engineering activities and related technical consultancy) |
### Officer Roles
Both sources report the most recently filed management appointments. Known titles use the published role catalogue, including retained source abbreviations; unfamiliar titles are interpreted with their source context. A filed office does not specify a sole or joint signing rule.
| Office | Returned role and context |
| - | - |
| President / Vice President / CEO | Executive appointment, subject to bylaws and board authority |
| Manager / Managing Member | Manager when the source establishes a Texas LLC governing appointment; otherwise Other |
| General Partner / Managing Partner | Partnership representative when the source establishes a compatible Texas partnership |
| Director / Chairman | Board Member / Chairman of the Board in `otherKeyPersons` |
| Secretary / Assistant Secretary | Secretary in `otherKeyPersons` unless a separate mandate is supplied |
| CFO / COO / CTO / senior executive | C-Level Executive in `otherKeyPersons` |
| General Counsel / Member / Limited Partner / Owner / financial contact | Other in `otherKeyPersons` without an established mandate |
| Registered Agent | Registered Agent in `otherKeyPersons` |
Explicit compound offices are preserved separately, including a vice president who also serves as secretary. Incomplete abbreviations do not invent an unreported second title. Corporate holders retain their identity and available address; a US contact address does not establish domicile. For foreign entities, the governing law and source appointment determine authority. The published formation jurisdiction takes precedence over a generic LLC or partnership label. Where that jurisdiction is missing, a generic form alone does not establish Texas agency. Uncertain formatted addresses retain their source text without an assumed country; a corporate registered agent’s Texas office does not establish its formation country.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Legal name + DBA. Verification mode also returns assumed names (as `commercialNames`) from the Secretary of State record. |
| Company status | Yes | Prefill: SOS registration status from Comptroller mirror (ACTIVE / INACTIVE). Verification: status read directly from SOS (In existence, Forfeited, Dissolved, Merged). |
| Registration date | Yes | SOS effective registration date |
| Legal address | Yes | Registered office address |
| Legal form | Yes | Prefill: Comptroller organizational type code (43 types, domestic/foreign). Falls back to name-suffix extraction. Verification: Secretary of State entity type string (24 types from Texas BOC). |
| Activity codes | Yes | NAICS from Comptroller open data, with ISIC Rev. 5 derived from NAICS and NACE Rev. 2.1 derived from ISIC. Prefill mode only. |
| Share capital | No | Not provided by either source |
| Legal representatives | Yes\* | Officers with statutory authority (President, Director, etc.). Prefill: from Comptroller franchise tax reports, truncated titles, AI-enriched. Verification: from SOS Management tab, full titles. *Not available for sole traders.* |
| Other key persons | Yes\* | Treasurer, CFO, Chairman, Registered Agent, etc. Same sourcing as legal representatives by mode. *Not available for sole traders.* |
| Registered agent | Yes\* | Formal entities only. Prefill: from Comptroller. Verification: from SOS Registered Agent tab. |
| Establishments | Yes | Branch/location data from Comptroller sales tax permits, with addresses and permit dates. Prefill mode only. |
| Shareholders | No | Not available from either source |
| UBOs | No | Not available from either source |
| Documents | Yes | **Information Letter** from the Secretary of State for formal entities (corporations, LLCs, limited partnerships). **Sales Tax Permit** from the Comptroller for all entities with a sales tax permit, including sole traders. Both returned as PDF. |
| Financial data | No | Not provided |
## Documents
### Information Letter
The Information Letter is an official document issued by the Texas Secretary of State. It states the entity's name, type, jurisdiction, file number, filing date and status, the registered agent and registered office address, the assumed name certificates on file, and the managerial officials with their titles and addresses. It is the closest equivalent to a trade register extract for Texas.
| Property | Value |
| - | - |
| Available for | Formal entities only (corporations, LLCs, limited partnerships, etc.) |
| Not available for | Sole traders — they have no SOS filing number |
| Format | PDF |
| Delivery | A few minutes |
### Sales Tax Permit
The Sales Tax Permit is the official Comptroller record confirming permit status, mailing address, and all outlet locations. For sole traders it is the primary official government record confirming their business registration.
| Property | Value |
| - | - |
| Available for | All entities with an active or inactive Comptroller sales tax permit |
| Format | PDF |
| Delivery | Under 2 minutes |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-TX&query=TOPOGRAPHIC+OM" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "17307175087",
"legalName": "TOPOGRAPHIC OM, INC.",
"countryCode": "US-TX",
"matchReason": {
"matchType": "default"
},
"address": {
"postalCode": "76126",
"countryCode": "US"
}
}
]
```
### Company Profile (Prefill Mode)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-TX", "id": "17307175087", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "17307175087",
"countryCode": "US-TX",
"identifiers": {
"feiNumber": "730717508",
"taxpayerId": "17307175087",
"sosFileNumber": "0003077806",
"stateOfFormation": "OK",
"sosRegistrationStatus": "ACTIVE"
},
"legalName": "TOPOGRAPHIC OM, INC.",
"registrationDate": "1970-09-16",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Foreign Profit Corporation",
"englishTranslation": "Corporation (Foreign)",
"standardized": "Corporation",
"iso20275Code": "C5K7"
},
"activities": {
"NAICS": [
{
"code": "541330",
"description": "Engineering Services",
"isAIInferred": false
}
],
"ISIC": [
{
"code": "7110",
"description": "Architectural and engineering, and related technical consultancy activities",
"isAIInferred": false
}
],
"NACE": [
{
"code": "71.1",
"description": "Architectural and engineering activities and related technical consultancy",
"isAIInferred": false
}
]
},
"legalAddress": {
"addressLine1": "211 E. 7TH STREET SUITE 620",
"city": "AUSTIN",
"postalCode": "78701",
"region": "TX",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "PRESIDENT",
"englishTranslation": "President",
"standardized": "President"
},
"individual": {
"name": {
"fullName": "BRIAN KRAFFT"
},
"residenceAddress": {
"addressLine1": "5229 EAST VERDE CIRCLE",
"city": "BENBROOK",
"postalCode": "76126",
"region": "TX",
"countryCode": "US"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "VICE PRESI",
"englishTranslation": "Vice President",
"standardized": "Vice President"
},
"individual": {
"name": {
"fullName": "J ROBERT KEATING"
},
"residenceAddress": {
"addressLine1": "6040 LAKESIDE DRIVE",
"city": "FORT WORTH",
"postalCode": "76179",
"region": "TX",
"countryCode": "US"
}
}
},
{
"entityId": "person_003",
"type": "individual",
"role": {
"localName": "VICE PRESI",
"englishTranslation": "Vice President",
"standardized": "Vice President"
},
"individual": {
"name": {
"fullName": "WILLIAM KEATING"
},
"residenceAddress": {
"addressLine1": "903 PRINCETON AVE",
"city": "MIDLAND",
"postalCode": "79701",
"region": "TX",
"countryCode": "US"
}
}
}
],
"otherKeyPersons": [
{
"entityId": "person_004",
"type": "individual",
"role": {
"localName": "TREASURER",
"englishTranslation": "Treasurer"
},
"individual": {
"name": {
"fullName": "SHARON L KEATING"
},
"residenceAddress": {
"addressLine1": "6040 LAKESIDE DRIVE",
"city": "FORT WORTH",
"postalCode": "76179",
"region": "TX",
"countryCode": "US"
}
}
},
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Other"
},
"company": {
"countryCode": "US",
"legalName": "CORPORATION SERVICE COMPANY D/B/A CSC-LAWYERS INCO",
"legalAddress": {
"addressLine1": "211 E. 7TH STREET SUITE 620",
"city": "AUSTIN",
"postalCode": "78701",
"region": "TX",
"countryCode": "US"
}
}
},
{
"entityId": "person_004",
"type": "individual",
"role": {
"localName": "SECRETARY",
"englishTranslation": "Secretary",
"standardized": "Secretary"
},
"individual": {
"name": {
"fullName": "SHARON L KEATING"
},
"residenceAddress": {
"addressLine1": "6040 LAKESIDE DRIVE",
"city": "FORT WORTH",
"postalCode": "76179",
"region": "TX",
"countryCode": "US"
}
}
},
{
"entityId": "person_003",
"type": "individual",
"role": {
"localName": "DIRECTOR",
"englishTranslation": "Director",
"standardized": "Board Member"
},
"individual": {
"name": {
"fullName": "WILLIAM KEATING"
},
"residenceAddress": {
"addressLine1": "903 PRINCETON AVE",
"city": "MIDLAND",
"postalCode": "79701",
"region": "TX",
"countryCode": "US"
}
}
}
]
}
```
### Sole Trader (Sales Tax Fallback)
Sole traders are not in the franchise tax system. Data comes from the sales tax payer API.
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-TX", "id": "32008802830", "dataPoints": ["company", "establishments"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "32008802830",
"countryCode": "US-TX",
"identifiers": {
"taxpayerId": "32008802830"
},
"legalName": "DAVID MARTINEZ, JR",
"status": {
"localName": "Active",
"active": true
},
"legalForm": {
"localName": "Sole Proprietorship",
"englishTranslation": "Sole Proprietorship (Individual)",
"standardized": "Sole Proprietorship"
},
"activities": {
"NAICS": [
{
"code": "561740",
"description": "Carpet and Upholstery Cleaning Services",
"isAIInferred": false
}
],
"ISIC": [
{
"code": "9610",
"description": "Washing and cleaning of textile and fur products",
"isAIInferred": false
}
],
"NACE": [
{
"code": "96.10",
"description": "Washing and cleaning of textile and fur products",
"isAIInferred": false
}
]
},
"legalAddress": {
"addressLine1": "12567 SOMERSET RD",
"city": "VON ORMY",
"postalCode": "78073",
"region": "TX",
"countryCode": "US"
}
},
"establishments": [
{
"name": "CASTILLO'S ICE HOUSE",
"creationDate": "1999-12-24",
"endDate": "2008-09-01",
"active": false,
"address": {
"addressLine1": "346 E QUILL DR",
"city": "SAN ANTONIO",
"postalCode": "78228",
"region": "TX",
"countryCode": "US"
}
},
{
"name": "CARPET MASTERS",
"creationDate": "2008-05-01",
"active": true,
"address": {
"addressLine1": "346 E QUILL DR",
"city": "SAN ANTONIO",
"postalCode": "78228",
"region": "TX",
"countryCode": "US"
}
}
]
}
```
Sole traders are identified by the `IS` (Individual Sole Owner) organizational
type code from the SODA3 open data API. No officers or registered agent data
is available for sole traders.
# Utah
Source: https://docs.topograph.co/essentials/us-utah
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Utah reference is on the [Utah country page](https://www.topograph.co/countries/us-ut).
## Start here
This guide contains public integration notes for Utah. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)
## Data Sources
Utah uses a single integration against the **Utah Division of Corporations & Commercial Code (OneStop)**, operated within the Utah Department of Commerce. The register covers every domestic and foreign corporation, limited liability company, limited partnership, limited liability partnership, cooperative, statutory trust, and non-profit organization filed in Utah. The free OneStop online entity search at `businessregistration.utah.gov` returns the business name, Utah Entity Number, entity type, status, formation jurisdiction, registration and status dates, principal and mailing addresses, registered agent, and all listed principals.
**Live source only.** Utah does not publish a free machine-readable bulk export of its business register. Every search and company-data request is fulfilled live from the OneStop portal. There is no snapshot or cached open-data tier in front of it.
**Assumed names (DBAs).** Assumed name registrations are filed with the Division of Corporations but are surfaced through a separate search on the portal and are not yet linked to the primary entity record in Topograph.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Utah Entity Number** | 6 to 8 digits, a hyphen, then 4 digits (`616169-0140`, `10110445-0143`) | `616169-0140` | Assigned by the Division of Corporations. The suffix follows the entity type (see below). |
Prefer the full dashed form (e.g. `616169-0140`), which is the canonical `id` returned in responses. The digits before the hyphen alone (e.g. `616169`) are also accepted and resolve the same entity.
The four digits after the hyphen follow the entity type. In the records we have seen, `-0140` is a domestic nonprofit corporation, `-0151` an assumed name (DBA) and `-0181` a foreign limited partnership; other values such as `-0142`, `-0143` and `-0160` are in use, and the list is not closed.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityNumber` | 6 to 8 digits, hyphen, 4 digits | `616169-0140` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Zions Bank"` | Starts-with (case-insensitive) | Multiple results |
| By Utah Entity Number | Dashed or numeric prefix | `616169-0140` | Exact (matchType: id) | Single result |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). Use a fuller query string to narrow the result set, which is capped at 50 matches per call.
**Latency.** Requests are fulfilled live from the OneStop portal. Prefill mode returns company, legal representatives, and other key persons in a few seconds. Verification mode returns a fuller record and takes longer. Search returns in a few seconds.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Entity Number suffix encodes the filing type** | The dashed suffix (e.g. `-0140`) is part of the canonical identifier, and responses always return the full dashed form as the `id`. Store that form. The numeric prefix alone (e.g. `616169`) is also accepted as input and resolves the same entity. |
| **Similar portal structure to Nevada** | Utah's OneStop portal (`businessregistration.utah.gov`) follows the same search flow, result grid, and entity detail page layout as Nevada's SilverFlume portal. Integration patterns are equivalent. |
| **No free bulk export** | The Utah business register is not published as open data. There is no snapshot-backed prefill mode: both prefill and verification requests are served live from the OneStop portal. |
| **Assumed names live separately** | Assumed names ("DBA") are filed with the Division of Corporations but appear in a separate fictitious-name search track. They are not linked to the primary entity record in the current integration. |
| **Officer titles are free-form** | The OneStop detail page carries officer titles as free text. In verification mode Topograph normalizes them against the standard role taxonomy through AI enrichment; prefill mode returns the raw title. |
| **No shareholder or UBO register** | Utah does not publish shareholder lists or beneficial ownership data for any entity type. |
| **No activity codes** | Industry classification codes (NAICS, NACE, ISIC) are not collected by the Utah business register. |
| **Paid certificate requires portal login** | The Certificate of Existence / Good Standing is ordered through the OneStop portal with a Utah ID account and requires payment. It is not yet available through Topograph. The free Trade Register Extract (printed detail page) is bundled with the company data block. |
## Mappings
### Legal Forms
Utah entity type labels are read as free text from the OneStop detail page and standardized through AI enrichment. The register covers domestic and foreign variants of corporations (profit and non-profit), limited liability companies, limited partnerships, limited liability partnerships, cooperatives, statutory trusts, and assumed names (DBAs). The full closed vocabulary has not yet been fully enumerated from live data.
Legal form enum values are not yet published in the catalog. Each entity returns a `legalForm.localName` (the raw label from the register). In verification mode it also returns a `legalForm.standardized` value (AI-inferred Topograph category); prefill mode returns the raw label only. The full enum will be added to the pricing page once a broad probe run has confirmed the complete vocabulary.
| Register Label | Standardized |
| - | - |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Foreign Limited Partnership | Partnership |
| Assumed Name (DBA) | Other |
The register publishes additional entity types (domestic and foreign variants of profit corporations, LLCs, LLPs, cooperatives, statutory trusts) that will be added to the manifest as they are observed from live data.
### Officer Roles
Known principal titles have fixed English and standardized meanings in both modes. Directors, ordinary members, limited partners and incorporators are other key persons when no individual authority is recorded. Registered agents have standardized `Registered Agent`.
Officer powers depend on bylaws or board grants, and LLC membership alone gives no agency power. Titles do not establish unrestricted or sole signing powers. Unknown titles retain their source text; verification can interpret them contextually.
Officer titles are free-form text on the OneStop detail page. Known titles use the published meanings above; unknown titles retain their local text in prefill and can be interpreted contextually in verification.
| Common Title | Standardized | Notes |
| - | - | - |
| President | President | Standard corporate officer |
| Vice President | Vice President | |
| Secretary | Secretary | |
| Treasurer | Treasurer | |
| Manager | Manager | LLC manager under Utah LLC Act |
| Member | Other | LLC member (member-managed LLCs) |
| Managing Member | Manager | LLC managing-member variant |
| General Partner | General Partner | Limited partnerships |
| Registered Agent | Registered Agent | Receives service of process; returned under `otherKeyPersons`, not `legalRepresentatives` |
The full role vocabulary is open-ended. The published catalogue covers known labels, and titles outside that set keep their source text.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the OneStop detail page |
| Company status | Yes | Active / Inactive as shown on the register |
| Registration date | Yes | Formation / registration date from the OneStop detail page |
| Legal address | Yes | Company address, verification mode only. Prefill mode returns no company address |
| Legal form | Yes | Raw label from the register in both modes; normalized by AI enrichment in verification mode only |
| Legal representatives | Yes | Officers and principals from the entity detail page; titles normalized by AI enrichment in verification mode |
| Other key persons | Yes | The registered (statutory) agent, returned under `otherKeyPersons` |
| Trade Register Extract | Yes | Printed PDF of the OneStop entity detail page, included at no extra charge with the company data block |
| Activity codes | No | Not collected by the Utah business register |
| Shareholders | No | Not published by the Utah register for any entity type |
| UBOs | No | No public beneficial ownership register at the Utah state level |
| Certificate of Existence | Roadmap | Paid document ordered through the OneStop portal; not yet available through Topograph |
| Assumed names (DBAs) | Roadmap | Filed with the Division of Corporations but not yet linked to the entity record on Topograph |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-UT&query=Zions+Bank" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "123456-0100",
"legalName": "ZIONS BANCORPORATION, N.A.",
"countryCode": "US-UT",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "UT",
"countryCode": "US"
}
}
]
```
### Search by Entity Number
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-UT&query=616169-0140" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "616169-0140",
"legalName": "EXAMPLE HEALTH CARE, INC.",
"countryCode": "US-UT",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-UT", "id": "616169-0140", "dataPoints": ["company", "legalRepresentatives"]}'
```
```json theme={null}
{
"company": {
"id": "616169-0140",
"countryCode": "US-UT",
"identifiers": { "entityNumber": "616169-0140" },
"legalName": "EXAMPLE HEALTH CARE, INC.",
"registrationDate": "1970-01-01",
"legalForm": {
"localName": "Domestic Nonprofit Corporation",
"standardized": "Nonprofit Organization"
},
"legalAddress": {
"city": "Salt Lake City",
"region": "UT",
"postalCode": "84101",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "President",
"standardized": "President"
},
"individual": {
"name": { "fullName": "Jane A. Smith" }
}
}
]
}
```
All names, identifiers, and addresses in the examples above are fictional placeholders. Do not use them in production requests.
## Data Availability
For the complete list of supported datapoints, documents, pricing, and current availability status, see the live pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
# Vermont
Source: https://docs.topograph.co/essentials/us-vermont
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Vermont reference is on the [Vermont country page](https://www.topograph.co/countries/us-vt).
## Start here
This guide contains public integration notes for Vermont. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Entity Statuses](#entity-statuses)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
Vermont uses a single integration against the **Vermont Secretary of State Business Services Division**, available at `bizfilings.vermont.gov`. The portal covers every entity type filed in Vermont: domestic and foreign business corporations, nonprofit corporations, limited liability companies, limited partnerships, mutual benefit enterprises, cooperative associations, general partnerships, limited liability partnerships, unincorporated nonprofit associations, plus assumed names, reserved names, and registered names.
Filed business activity labels appear as `activityDescription` when present. A label without a numeric code is preserved as text; it does not become a NAICS code. The public profile does not identify a verified NAICS edition.
Every request resolves live against the SoS portal. Vermont publishes no open-data feed for business entities, so there is no non-authoritative fast path.
The Vermont SoS portal is the only source for Vermont entity data. The **Trade Register Extract** (a printed PDF rendered from the live structured profile) is included in the same call at no extra charge.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Record Number** | Always 6 digits, zero-padded (`074657`, `001020`, `487831`) | `074657` | Primary SoS-assigned identifier. Unique across all filing types. Accepted with or without the leading zeros; every id we return carries the 6-digit form. |
The Record Number is the identifier printed on SoS documents and shown on the portal search results page. Pass it as-is (with or without leading zeros) and Topograph will normalise it.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityId` | 6-digit zero-padded numeric string | `074657` | All entities |
| `vtIdBusiness` | UUID, 36 characters with hyphens | `79304417-fb3e-4bd0-8dda-1a005071a37a` | All entities |
`vtIdBusiness` is the register's internal key for the entity. It is returned alongside the Record Number for reference, but it is not the primary identifier and cannot be used to search or to request a company.
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name (contains) | 2–200 chars | `"Vermont Creamery"` | Contains (case-insensitive) | Multiple results |
| By Record Number | 1–6 digits | `074657` | Exact | Exact match returned first (`matchType: id`) |
**Contains search.** Name search uses a contains strategy: it matches any entity whose name includes the query string. Up to 50 results are returned. Use more specific strings to narrow the result set.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Record Number vs UUID** | The portal assigns two keys to every entity: the customer-facing Record Number (6-digit padded integer, e.g. `074657`) and an internal UUID. Topograph exposes both; use `entityId` for lookups and display, `vtIdBusiness` for reference only. |
| **Shareholders are partnership-only** | Vermont requires a partnership to name every partner when it registers, so `shareholders` is returned for general and limited partnerships. It is not available for corporations, whose annual report carries only directors and officers, nor for limited liability companies, which Vermont never requires to disclose their members — for those two the datapoint returns an explanation rather than an empty list, and the people on file come back under `legalRepresentatives` and `otherKeyPersons`. |
| **No ownership percentages, ever** | No Vermont filing states an ownership split, and no total partnership capital is published to derive one from, so a shareholding is returned without `sharePercentage`. A single partner whose class the register does not record is not returned on its own, because it cannot be shown to be the whole ownership. |
| **No UBO data** | Vermont has no state beneficial-ownership register, and the federal FinCEN database is not public. |
| **No federal tax ID (FEIN)** | The federal Employer Identification Number is not disclosed through the Vermont public business register. |
| **Filing images not available** | The filing-history timeline (annual reports, articles of amendment, registered-agent changes) is not part of the structured response; it is printed in the Trade Register Extract. The underlying filing PDF images are not exposed by the public portal API, so the Trade Register Extract is the only downloadable document today. |
| **Free-text "Other" officer title** | When an officer holds a title that does not match a standard code, the portal stores it in a free-text slot. Topograph preserves the raw value in `role.localName` when no standard mapping applies. |
| **No open-data bulk extract** | Vermont publishes no bulk dataset of registered business entities. Every request resolves live against the portal. |
| **Assumed names and reserved names are indexed** | The search index includes assumed names (`Assumed Name` entity type), reserved names, and registered names alongside standard entity filings. Search results do not carry the entity type: check `legalForm.localName` on the company profile to tell them apart. |
| **Annual report drives officer freshness** | Officer data reflects the most recent annual report filing. Entities that have not filed recently may carry older officer records. |
## Mappings
### Legal Forms
Vermont recognises 18 entity types across the search and profile endpoints. The table below lists each type with its Topograph standardized label.
| SoS Entity Type | Standardized |
| - | - |
| Domestic Business Corporation | Corporation |
| Foreign Business Corporation | Corporation |
| Domestic Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Corporation | Nonprofit Organization |
| Domestic Limited Liability Company | Limited Liability Company |
| Foreign Limited Liability Company | Limited Liability Company |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic Partnership | Partnership |
| Foreign Partnership | Partnership |
| Domestic Cooperative Association | Cooperative |
| Domestic Mutual Benefit Enterprise | Other |
| Foreign Mutual Benefit Enterprise | Other |
| Domestic Unincorporated Nonprofit Association | Nonprofit Organization |
| Foreign Unincorporated Nonprofit Association | Nonprofit Organization |
| Reserved Name | Other |
| Registered Name | Other |
| Assumed Name | Other |
Vermont also uses sub-classification election types for certain entities (Benefit Corporation, Professional, Low-Profit LLC, Blockchain-Based LLC, Worker Cooperative, etc.). These are surfaced as annotations where available.
### Officer Roles
The SoS portal carries a `titleDescription` field with a controlled set of values, plus a free-text `otherTitle` slot for non-standard titles. Topograph normalizes them to a standardized role label.
| Common Title | Standardized | Notes |
| - | - | - |
| President | President | Statutory corporation officer |
| Vice President | Vice President | |
| Secretary | Secretary | |
| Treasurer | Treasurer | |
| Director | Director | Corporation board member |
| Manager | Manager | LLC manager-managed structure |
| Managing Member | Manager | LLC managing-member variant, returned under `legalRepresentatives` |
| Member | Other | LLC member, returned under `otherKeyPersons` |
| General Partner | General Partner | Limited partnerships |
| Organizer | Other | Initial organizer, returned under `otherKeyPersons` |
| Incorporator | Other | Returned under `otherKeyPersons` |
| Other | Other | Free-text slot. The raw value is kept in `role.localName` and returned under `otherKeyPersons`, unless it matches an executive title such as President or Treasurer. |
Officers and directors surface under `legalRepresentatives`. The registered agent and organizers (plus any principal whose title does not map to an executive role) surface under `otherKeyPersons`.
### Entity Statuses
The Vermont register exposes a rich status vocabulary. The broad families are:
| Status Family | Examples |
| - | - |
| Active | Active - In Good Standing, Active - NOT In Good Standing |
| Inactive | Inactive - Voluntarily Dissolved, Inactive - Administratively Terminated, Inactive - Withdrawn, Inactive - Cancelled, Inactive - Cessated, Inactive - Dissolved, Inactive - Merged, Inactive - Revoked, Inactive - Expired |
| Pending | Pending (various sub-types) |
| Cancelled / Revoked | Cancelled, Revoked |
The register uses 37 distinct status values. Each is returned verbatim in `status.localName`, with `active: true` for every value that starts with `Active`.
## Statutory Filings
Vermont entities file an annual report confirming the entity's particulars are current. The register publishes the last report's due date and the date it was received, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `lastFiled.dueDate` and `lastFiled.filedOn`. No forward-looking due date is published.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"lastFiled": { "dueDate": "2025-03-31", "filedOn": "2025-02-11" },
"source": "us_vt_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name |
| Company status | Yes | 37-value status vocabulary from the SoS portal (Active - In Good Standing, Inactive - Voluntarily Dissolved, etc.) |
| Registration date | Yes | Date of incorporation, or the SoS-recorded effective date when no incorporation date is on file |
| Termination date | No | Not returned in the structured response |
| Legal address | Yes | One address: the physical address, otherwise the partnership address, otherwise the mailing address |
| Legal form | Yes | 18 SoS entity types, mapped to standardized labels |
| Legal representatives | Yes | Officers, directors, managers, and members with name, title, and contact address |
| Registered agent | Yes | Name and one address (physical, otherwise mailing). A commercial registered agent is identified by `role.localName` `Commercial Registered Agent` |
| Business organizers | Yes | Organizer list from the initial filing |
| Activity codes (NAICS) | Yes | Numeric NAICS codes where filed by the entity |
| Filing history | Partial | Printed in the Trade Register Extract only (annual reports, articles of amendment, registered-agent changes, etc.), not in the structured response |
| Trade Register Extract | Yes | Printed PDF rendered from the live structured Vermont profile, included at no extra charge |
| Filing images (PDFs) | No | Not exposed by the public portal API; only the filing-history timeline in the Trade Register Extract is available |
| Shareholders | Partial | Partnerships only (general and limited), without ownership percentages. Not available for corporations or LLCs — see Quirks & Gotchas |
| UBOs | No | No state beneficial-ownership register; the federal FinCEN database is restricted to authorised users |
| Tax ID (FEIN) | No | Not disclosed through the Vermont public business register |
| Financial data | No | Not collected |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-VT&query=Vermont+Creamery" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "012345",
"legalName": "VERMONT CREAMERY HOLDINGS, LLC",
"countryCode": "US-VT",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "VT",
"countryCode": "US"
}
}
]
```
### Search by Record Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-VT&query=012345" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "012345",
"legalName": "VERMONT CREAMERY HOLDINGS, LLC",
"countryCode": "US-VT",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-VT", "id": "012345", "dataPoints": ["company", "legalRepresentatives"]}'
```
```json theme={null}
{
"company": {
"id": "012345",
"countryCode": "US-VT",
"identifiers": {
"entityId": "012345",
"vtIdBusiness": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"legalName": "VERMONT CREAMERY HOLDINGS, LLC",
"registrationDate": "2010-03-15",
"status": {
"localName": "Active - In Good Standing",
"active": true
},
"legalForm": {
"localName": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"city": "Montpelier",
"region": "VT",
"postalCode": "05602",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"individual": { "name": { "fullName": "Jane A. Smith" } },
"role": {
"localName": "Manager",
"standardized": "Manager"
}
}
]
}
```
# Virginia
Source: https://docs.topograph.co/essentials/us-virginia
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Virginia reference is on the [Virginia country page](https://www.topograph.co/countries/us-va).
## Start here
This guide contains public integration notes for Virginia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)
## Data Sources
Virginia uses a single integration against the **Virginia State Corporation Commission (SCC) Clerk's Information System (CIS)** at `https://cis.scc.virginia.gov/`. The public search interface is available without authentication and covers every entity on file with the SCC.
The entity detail page returns the entity name, SCC ID, entity type, status and reason for status, formation date, Virginia qualification date, period of duration, industry code, jurisdiction, principal office address, and the current registered agent. For stock corporations, the detail page additionally publishes the officer and director roster (title, name, address, last-updated date) and total share count. For limited liability companies and limited partnerships, only the registered agent is published.
The two modes read the register differently:
* **Prefill** is served from a periodically refreshed snapshot of the Virginia business register. Entities filed or amended since the last refresh may be missing, and status may lag the live register.
* **Verification** reads the SCC Clerk's Information System live for the authoritative status, the officer and director roster, and the total share count.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **SCC ID** | 8 characters: one uppercase letter + 7 digits (`S0381378`), or 8 digits with leading zeros (`02937985`) | `02937985` | Primary identifier assigned by the Virginia SCC, shown as the Entity ID. |
The SCC ID comes in two forms: one letter followed by 7 digits (`S0381378`, `T0479784`, `F1389198`, `L0007460`, `M0093452`), or 8 digits with leading zeros kept (`02937985`, `00003145`, `11127380`). Older corporations use the 8-digit form, and so do recent registrations of every entity type.
In the records we have seen, the letter follows the filing family: `S` Virginia LLC, `T` foreign LLC, `F` foreign corporation, `L` Virginia limited partnership (and some LLCs), `M` foreign limited partnership, `J` a few LLCs. The SCC publishes no meaning for the letters, so do not rely on them for the entity type.
Always pass the full canonical form including any leading zeros or letter prefix.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityId` | 8 characters: letter + 7 digits, or 8 digits | `02937985` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Markel"` | Full-text (case-insensitive) | Multiple results |
| By SCC ID | 8 characters | `02937985` | Exact | Exact match returned first (`matchType: id`); other results may follow |
**Snapshot-first search.** Name and SCC ID search are answered from the register snapshot first. When the snapshot has no match (for example, an entity filed since the last refresh), the query runs against the live SCC search, which matches on the beginning of the legal name. Use fuller query strings to narrow the result set.
**Legal name casing.** The SCC stores LLC names in title case and stock corporation names in uppercase. Search results normalize everything to uppercase; the company profile returns the name in the casing stored by the register.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **SCC ID is alphanumeric** | The identifier is not always numeric. Domestic LLCs begin with `S`, foreign LLCs with `T`, foreign stock corporations with `F`, and limited partnerships with `M`. Older domestic corporations use a prefix-free 8-digit numeric form. Pass the full form exactly as returned by search. |
| **Leading zeros are significant** | Older domestic corporations (no letter prefix) have IDs such as `02937985` with leading zeros. These must be preserved. `02937985` and `2937985` are not equivalent. |
| **Officer disclosure varies by entity type** | Stock corporations publish officers, directors, and total share count. Limited liability companies and limited partnerships publish only the registered agent. Members, managers, and general partners are not disclosed by the Virginia register for any entity type. |
| **Prefill uses a snapshot** | The Virginia SCC does not publish the business entity register as open data. Prefill mode is served from a periodically refreshed snapshot of the register, which may lag for recently filed or amended entities. Verification mode reads the SCC live. |
| **No shareholders or UBOs** | Shareholder lists and beneficial ownership information are not published by the Virginia register for any entity type. |
| **Industry code is coarse** | The SCC publishes a single-digit industry code (for example, `35 - Insurance Agencies`) rather than NAICS, NACE, or ISIC codes. |
| **Fictitious names roll up to a parent entity** | Fictitious name registrations in Virginia are tied to a parent entity and resolved through it. They are not indexed as standalone entities. |
| **Name casing differs between search and profile** | The search grid normalizes all names to uppercase. The profile response returns the stored casing, which is uppercase for corporations and title case for LLCs. |
## Mappings
### Legal Forms
The SCC publishes an open-vocabulary entity type label on every entity. Observed values include Stock Corporation, Nonstock Corporation, Limited Liability Company, Series LLC, Limited Partnership, and their foreign equivalents. Each value surfaces verbatim as `legalForm.localName`. In verification mode it is also mapped to a standardized Topograph category.
### Officer Roles
Officer titles on stock corporation detail pages are open vocabulary (for example, President, Vice President, Secretary, Treasurer, Director). Known titles, including observed abbreviations, receive fixed standardized meanings in both modes. Verification uses AI to extract the source roster; unfamiliar titles retain their source wording and may lack a standardized role. Governing-only directors and board chairs are returned under `otherKeyPersons`. The registered agent is returned under `otherKeyPersons` with role `Registered Agent`. Officer authority depends on the bylaws or board directions; the office title does not establish an individual signing mode. It receives service of process and is disclosed for every entity type regardless of the entity's officer-disclosure ceiling.
For LLCs and limited partnerships, the registered agent is returned under `otherKeyPersons`; `legalRepresentatives` may be empty. There is no separate officer or manager disclosure for these entity types in the Virginia register.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name as stored by the SCC |
| Company status | Yes | Active or inactive, with reason for status |
| Registration / formation date | Yes | SCC initial filing date |
| Virginia qualification date | Yes | Date a foreign entity qualified to do business in Virginia |
| Legal address | Yes | Principal office address |
| Legal form | Yes | SCC entity type label with standardized mapping |
| Registered agent | Yes | Name and address of the current registered agent |
| Officers / directors | Yes (stock corps only) | Not disclosed for LLCs or limited partnerships |
| Total shares | Yes (stock corps only) | Not disclosed for other entity types |
| Activity codes | Partial | Coarse single-digit SCC industry code only; no NAICS / NACE / ISIC |
| Trade Register Extract | Yes | Printed PDF of the SCC entity detail page, included at no extra charge |
| Certificate of Good Standing | No | Ordered separately from the SCC; not yet available through Topograph |
| Shareholders | No | Not published by the Virginia register |
| UBOs | No | No public beneficial ownership register at the Virginia state level |
| Financial data | No | Not collected by the SCC |
| Tax ID (EIN) | No | Held by the Virginia Department of Taxation; not disclosed publicly |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-VA&query=Markel" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "02937985",
"legalName": "MARKEL AMERICAN INSURANCE COMPANY",
"countryCode": "US-VA",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "VA",
"countryCode": "US"
}
}
]
```
### Search by SCC ID
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-VA&query=02937985" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "02937985",
"legalName": "MARKEL AMERICAN INSURANCE COMPANY",
"countryCode": "US-VA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-VA", "id": "02937985", "dataPoints": ["company", "legalRepresentatives"]}'
```
```json theme={null}
{
"company": {
"id": "02937985",
"countryCode": "US-VA",
"identifiers": { "entityId": "02937985" },
"legalName": "SAMPLE INSURANCE COMPANY",
"registrationDate": "1988-01-15",
"legalForm": {
"localName": "Stock Corporation",
"standardized": "Corporation"
},
"status": {
"localName": "Active",
"active": true
},
"legalAddress": {
"addressLine1": "4521 Corporate Drive",
"city": "Glen Allen",
"region": "VA",
"postalCode": "23060",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"individual": { "name": { "fullName": "Jane A. Smith" } },
"role": {
"localName": "President",
"standardized": "President"
}
}
]
}
```
## Data Availability
The full list of supported datapoints, documents, modes, and sources is on the [Virginia pricing page](https://topograph.co/pricing/us-va).
# Washington
Source: https://docs.topograph.co/essentials/us-washington
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Washington reference is on the [Washington country page](https://www.topograph.co/countries/us-wa).
## Start here
This guide contains public integration notes for Washington. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Statuses](#company-statuses)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
## Data Sources
Washington uses a single live integration against the **Washington Secretary of State, Corporations and Charities Filing System (CCFS)**. The register covers every profit corporation, nonprofit corporation, social purpose corporation, LLC, limited partnership, limited liability partnership, cooperative association, and registered trust filed in Washington.
* **CCFS portal** (live, authoritative). Every request is resolved live against the CCFS register. The Washington Secretary of State no longer distributes a bulk corporate data extract (retired 2024-08-30), so there is no open-data snapshot path.
**Live-only reads.** Because no bulk dataset is available for Washington, every request (including fast prefill checks) resolves live against the CCFS register. Response times are typically 2–6 seconds when the authentication session is warm.
**Annual report freshness.** Officer data (governors, directors, LLC managers, LP general partners) is updated when each entity files its annual report, which is due once per year on the entity's anniversary date. Officer data can therefore lag up to 12 months behind the current ground truth.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **UBI (Unified Business Identifier)** | Always 9 digits, returned without separators (`600413485`, `178005030`). Accepted as 9 consecutive digits or dash-formatted (`NNN-NNN-NNN`). | `600413485` | Issued by the Washington Business Licensing Service and shared across the Secretary of State, Department of Revenue, Labor & Industries, and Employment Security. |
Both `600413485` and `600-413-485` resolve to the same entity. The register normalizes the UBI internally, but passing digits only (no dashes) is the safest format.
### Identifiers in API Response
| Identifier | Format | Example | Found in |
| - | - | - | - |
| `ubi` | 9 digits, no dashes | `600413485` | All entities |
| `fein` | The 9-digit federal EIN, as recorded on the entity profile | `911144442` | Returned when the entity profile carries a Federal Employer Identification Number. Not all entities have one. |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2–200 chars | `"Starbucks"` | Starts-with (case-insensitive) | Multiple results, up to 25 |
| By UBI | 9 digits | `600413485` | Exact | Single exact match (`matchType: id`) |
**Starts-with search.** Name search anchors on the beginning of the legal name (case-insensitive). The CCFS register indexes entities under their full legal name, including the leading article. For example, "The Boeing Company" is filed under "T" rather than "B". Use the full name or a prefix that matches the filing name.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **"THE" prefix is load-bearing** | Entities incorporated with "The" at the start of their name (e.g. "THE BOEING COMPANY") are indexed under "T", not "B". A search for `"Boeing"` returns affiliate companies before the main entity. Use the full legal name or a prefix that matches the filing. |
| **UBI spaces in the register** | The CCFS register returns UBIs in space-separated format (`"600 413 485"`). Topograph normalizes these to digits-only before returning them in the API response. |
| **No bulk / offline path** | Washington retired its bulk Corporations Data Extract on 2024-08-30. A customer-supplied list of entities cannot be resolved in bulk ahead of time. Every lookup is resolved live. |
| **Officer data freshness** | Governors, directors, LLC managers, LP general partners, and nonprofit board members are updated when the entity files its annual report (once per year). The data can be up to 12 months behind the current state. |
| **No shareholders or UBOs** | Shareholder lists and beneficial-ownership data are not collected by the Washington business register. The federal beneficial-ownership database is restricted to authorized users. |
| **No activity codes** | Industry classification codes (NAICS, NACE, ISIC) are not collected by the Secretary of State register. |
| **DBA names are not indexed** | Doing-business-as (assumed) name filings are handled by the Washington Department of Revenue Business Licensing Service, not the Secretary of State. DBA names are not returned in the corporate register response and are not searchable through Topograph. |
| **Legacy UBIs** | Entities incorporated before the UBI system was unified carry identifiers in the `177xxxxxxx` / `178xxxxxxx` range. These resolve identically on the CCFS register. |
## Mappings
### Legal Forms
Washington entity types are sourced from the **Washington Secretary of State Corporations Division** registration catalog. The entity type is returned directly from the CCFS register.
| CCFS Business Type | Standardized |
| - | - |
| Washington Profit Corporation | Corporation |
| Washington Profit Professional Service Corporation | Corporation |
| Washington Social Purpose Corporation | Corporation |
| Washington Nonprofit Corporation | Nonprofit Organization |
| Washington Nonprofit Professional Service Corporation | Nonprofit Organization |
| Washington Nonprofit Miscellaneous and Mutual Corporation | Nonprofit Organization |
| Washington Limited Liability Company | Limited Liability Company |
| Washington Professional Limited Liability Company | Limited Liability Company |
| Washington Limited Partnership | Partnership |
| Washington Limited Liability Limited Partnership | Partnership |
| Washington Limited Liability Partnership | Partnership |
| Washington Professional Limited Liability Partnership | Partnership |
| Washington General Cooperative Association | Cooperative |
| Washington Limited Cooperative Association | Cooperative |
| Massachusetts Business Trust (registered in WA) | Trust |
| CCFS Business Type | Standardized |
| - | - |
| Foreign Profit Corporation | Corporation |
| Foreign Profit Professional Service Corporation | Corporation |
| Foreign Nonprofit Corporation | Nonprofit Organization |
| Foreign Nonprofit Professional Service Corporation | Nonprofit Organization |
| Foreign Limited Liability Company | Limited Liability Company |
| Foreign Professional Limited Liability Company | Limited Liability Company |
| Foreign Limited Partnership | Partnership |
| Foreign Limited Liability Limited Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Foreign Professional Limited Liability Partnership | Partnership |
| Foreign Cooperative Association | Cooperative |
ISO 20275 ELF codes are not mapped for Washington entity types. GLEIF does not consistently cover US sub-national entity structures such as the Social Purpose Corporation or professional-service LLCs. The full legal-form catalog with standardized mappings is on the [pricing page](https://topograph.co/pricing/us-wa).
### Officer Roles
Washington uses **Governor** for the people who govern an entity. A board seat does not by itself establish personal signing authority. Corporate officer powers depend on bylaws and board authorization; LLC managers have ordinary-course agency, while members have it only in a member-managed LLC. The register's explicit LLC governing-person category supplies that context; a Member title alone does not. Sole or joint signing power is not inferred.
| CCFS Role | Standardized | Classification |
| - | - | - |
| Governor | Other | Other Key Person; Legal Representative for an explicitly identified LLC governing person |
| President | President | Legal Representative, subject to appointment powers |
| Vice President | Vice President | Legal Representative, subject to appointment powers |
| Secretary | Secretary | Legal Representative, subject to appointment powers |
| Treasurer | Treasurer | Legal Representative, subject to appointment powers |
| Chair / Chairman | Chairman of the Board | Other Key Person |
| Director | Board Member | Other Key Person |
| Manager (LLC) | Manager | Legal Representative |
| Member (LLC) | Other | Other Key Person; Legal Representative for an explicitly identified LLC governing person |
| General Partner | General Partner | Legal Representative |
| Trustee | Other | Other Key Person |
| Incorporator / formation Executor | Other | Other Key Person |
| Registered Agent | Registered Agent | Other Key Person |
Known roles and principal categories map deterministically. Filed titles remain open text; unrecognized titles preserve their local wording without an invented standardized office. Some records withhold the governor list. [Washington governing-role definitions](https://app.leg.wa.gov/RCW/default.aspx?cite=23.95.105), [officer powers](https://app.leg.wa.gov/RCW/default.aspx?cite=23B.08.410).
### Company Statuses
| Status | Description |
| - | - |
| Active | Entity is in good standing with the Secretary of State. |
| Inactive | Entity has missed an annual report filing. An administrative hold is placed; the entity has 60 days to cure before dissolution. |
| Administratively Dissolved | The entity was dissolved by the Secretary of State for failure to file annual reports or pay fees. |
| Dissolved | The entity was voluntarily dissolved by its owners. |
| Withdrawn | Foreign entity has withdrawn its registration from Washington. |
| Terminated | LP / LLP that has completed its wind-up period following dissolution. |
| Revoked | Registration has been revoked by the Secretary of State. |
## Statutory Filings
Washington entities file an annual report confirming the entity's particulars are current. The register publishes the next annual report due date on the business record, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "annual",
"next": { "dueDate": "2026-07-31" },
"source": "wa_sos"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Available | Notes |
| - | - | - |
| Company name | Yes | Current legal name from the CCFS register |
| Company status | Yes | One of: Active, Inactive, Administratively Dissolved, Dissolved, Withdrawn, Terminated, Revoked |
| Registration date | Yes | Date of initial filing with the Secretary of State |
| Legal address | Yes | Principal office street address and mailing address |
| Legal form | Yes | Entity type from the CCFS register, standardized to Topograph categories |
| Legal representatives | Yes | Corporate officers, LLC managers and source-qualified governing members, general partners; appointment powers apply and records may lag up to 12 months |
| Other key persons | Yes | Governance roles and other nonrepresenting filed offices, alongside the registered agent |
| Registered agent | Yes | Name and address, returned under `otherKeyPersons` |
| Activity codes | No | Not collected by the Secretary of State register |
| Shareholders | No | Not published by the register |
| UBOs | No | No state beneficial-ownership register; the federal database is restricted |
| DBA / assumed names | No | Filed separately with the Department of Revenue, not returned in the corporate register |
| Trade Register Extract | Yes | Included at no extra charge with the company data block: a printed PDF of the CCFS Business Information detail page |
| Certified documents | No | Certified corporate documents and Certificates of Existence are paywalled behind the Secretary of State paid filing system and are not yet offered through Topograph |
| Financial data | No | Not collected by the Secretary of State |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-WA&query=Rainier+Brewing" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "600123456",
"legalName": "RAINIER BREWING COMPANY, INC.",
"countryCode": "US-WA",
"matchReason": {
"matchType": "default"
},
"address": {
"region": "WA",
"countryCode": "US"
}
}
]
```
### Search by UBI
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-WA&query=600413485" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "600413485",
"legalName": "PLACEHOLDER TECHNOLOGY CORPORATION",
"countryCode": "US-WA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-WA", "id": "600413485", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "600413485",
"countryCode": "US-WA",
"identifiers": { "ubi": "600413485" },
"legalName": "PLACEHOLDER TECHNOLOGY CORPORATION",
"registrationDate": "1993-09-15",
"legalForm": {
"localName": "Washington Profit Corporation",
"standardized": "Corporation"
},
"status": {
"localName": "Active",
"active": true
},
"legalAddress": {
"addressLine1": "1 Placeholder Way",
"city": "Redmond",
"region": "WA",
"postalCode": "98052",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"individual": { "name": { "fullName": "Jane Doe" } },
"role": {
"localName": "President",
"standardized": "President"
}
}
]
}
```
# Washington DC (US)
Source: https://docs.topograph.co/essentials/us-washington-dc
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Washington DC (US) reference is on the [Washington DC (US) country page](https://www.topograph.co/countries/us-dc).
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Legal Representatives](#legal-representatives)
* [Other Key Persons](#other-key-persons)
* [Statutory Filings](#statutory-filings)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
Washington DC entity data comes from two complementary sources maintained by the **DC Department of Licensing and Consumer Protection (DLCP), Business and Professional Licensing Administration (BPLA)**:
* **DC DLCP Open Data CSV** (fast / prefill mode): A daily open-data export published at [opendata.dc.gov](https://opendata.dc.gov/datasets/5238c4fd99c843a1bd7679a243747a8c_0) under CC BY 4.0. Covers all \~494k domestic and foreign registered entities, refreshed every day. Entity-level fields only — no principals roster.
* **DC BOSS register API** (authoritative / verification mode): The register's own live API behind the DLCP Business and Occupational Service System at [boss.dc.gov](https://boss.dc.gov). Returns the authoritative entity status, the full roster as filed (governors, directors, organizers, incorporators and beneficial owners), the registered agent, and the entity page captured as the Trade Register Extract.
In prefill mode, data is served from the DC DLCP daily open-data snapshot.
It is typically up to 24 hours behind the live register. The roster of people
is not included in prefill mode — it is only returned in verification mode,
which reads the live register.
BOSS replaced the CorpOnline portal in August 2026. The two lanes do not share
an identical status vocabulary — see [Company Status](#company-status).
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **DC File Number** | Varies, see formats below | `L00005531281` | Assigned by DC DLCP at formation or qualification |
**DC File Number formats:**
| Format | Description | Example |
| - | - | - |
| Numeric | 1 to 6 digits, leading zeros significant | `571294`, `004285` |
| Letter + short number | One letter followed by 4 to 6 digits | `L14177`, `C013788` |
| Letter + long number | One letter followed by 10 or 11 digits, or two letters followed by 10 digits | `L00005531281`, `L0000053226`, `AC0004848765` |
| `US-DC-` prefixed | Recently registered entities: `US-DC-`, two letters, then 9 digits | `US-DC-LL082600020`, `US-DC-FN042602087` |
In the `US-DC-` form, the two letters match the entity type in the records we have seen: `LL` domestic LLC, `CO` domestic corporation, `NP` domestic nonprofit, `LP` domestic limited partnership, `ST` domestic statutory trust, `GC` and `LC` cooperative associations, and `FN` any foreign entity. In the older lettered forms the letter does not reliably give the entity type: many foreign LLCs carry a `C` number.
Pass the file number exactly as a search result returns it, including leading zeros and the `US-DC-` prefix where present. A handful of old records carry irregular values such as `951448-4164482`.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `fileNumber` | The file number as issued, in any of the formats above | `L00005531281` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | Free-text string | `"Washington Gas Light"` | Any-word | Multiple results |
| By DC File Number | Exact file number | `L00005531281` | Exact | Exact match returned first (matchType: id); other results may follow |
Search runs against the DC DLCP daily open-data extract. Name search uses any-word matching. File number lookup
returns the exact match first with `matchReason.matchType = "id"`; other
results may follow.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **No principals in prefill mode** | The DC DLCP open-data extract does not include the principals roster (governors, managers, directors). `legalRepresentatives` is not available in prefill mode: requesting it returns a failed datapoint with error code `fast_source_unavailable`. Use verification mode to retrieve the full principals list. |
| **Complex file number formats** | Several formats exist: purely numeric, one letter followed by a short or long number, and the `US-DC-` prefixed form of recently registered entities. Only the `US-DC-` form's two letters reliably match the entity type. See [Company Identifiers](#company-identifiers). |
| **No bulk open data for principals** | The open-data CSV covers entity-level fields only. The roster of people is available exclusively from the live register in verification mode. |
| **Activity codes are inferred, not published** | The DC register publishes no structured activity code — only a free-text purpose (e.g. `Natural Gas`). In verification mode that purpose is classified into ISIC Rev. 5 and NACE Rev. 2.1, returned flagged `isAIInferred`. Roughly 70% of entities receive a code; the rest state boilerplate the classifier declines rather than guesses. NAICS is not inferred. |
| **No shareholders** | DC records no ownership percentage and no ownership-vs-control flag, so an equity shareholder list cannot be derived for any entity type. |
| **Beneficial owners are named, but not quantified** | The register publishes a beneficial-owner roster, and those people are returned as Other Key Persons with the role `Beneficial Owner`. No ownership percentage accompanies them, so they are **not** returned as `shareholders` or UBOs. Federal FinCEN BOI filings are not accessible through the DC register. |
| **No EIN / federal tax ID** | The federal Employer Identification Number is not disclosed through the DC public business register. |
| **"Active - Not in Good Standing" is still active** | Entities with this status are technically still registered but have failed to meet a compliance obligation (e.g. overdue biennial report). They are returned with `active: false` by Topograph to flag the compliance gap. |
## Mappings
### Company Status
Status is drawn directly from the DC DLCP register and mapped deterministically. No AI inference is involved.
The open-data extract (prefill mode) uses exactly the 12 values below. The live register (verification mode) can additionally return `Expired` and `Active Trade Name`, so an integration should treat the list as open rather than exhaustive.
| DC DLCP Status | Active | Notes |
| - | - | - |
| `Active - In Good Standing` | Yes | Standard compliant status |
| `Active - In Good Standing - Pending Domestication` | Yes | Active while a domestication conversion is pending |
| `Active Trade Name` | Yes | A live trade-name registration (verification mode only) |
| `Active - Not in Good Standing` | No | Registered but out of compliance (overdue filing or fee) |
| `Expired` | No | Registration lapsed (verification mode only) |
| `Revoked` | No | Registration revoked by DLCP |
| `Dissolved` | No | Voluntarily or administratively dissolved |
| `Withdrawn` | No | Foreign entity has withdrawn its DC registration |
| `Merged` | No | Entity merged into another entity |
| `Inactive - Cancelled` | No | Inactive and cancelled |
| `Terminated` | No | Registration terminated |
| `Domesticated` | No | Entity domesticated to another jurisdiction |
| `Converted` | No | Entity converted to a different legal form |
| `Consolidated` | No | Merged via consolidation |
### Legal Forms
DC DLCP uses a closed list of 18 entity types. All 18 are derived from the exhaustive distinct set in the full DC DLCP open-data extract. Every entity in the register falls into exactly one of these types.
In prefill mode, `legalForm` carries the register's entity-type label in `localName` only. The standardized category and the ISO 20275 code below are added in verification mode.
| DC DLCP Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Limited Liability Company | Limited Liability Company | `2HBR` |
| Foreign Limited Liability Company | Limited Liability Company | — |
| DC DLCP Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Business Corporation | Corporation | `CNQ3` |
| Foreign Business Corporation | Corporation | — |
| Domestic Act of Congress Corporation | Corporation | — |
| Foreign Act of Congress Corporation | Corporation | — |
| DC DLCP Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Nonprofit Corporation | Nonprofit Organization | — |
| Foreign Nonprofit Corporation | Nonprofit Organization | — |
| DC DLCP Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Limited Partnership | Partnership | `74LJ` |
| Foreign Limited Partnership | Partnership | — |
| Domestic Limited Liability Partnership | Partnership | `TJ6V` |
| Foreign Limited Liability Partnership | Partnership | — |
| DC DLCP Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic General Cooperative Association | Other | — |
| Domestic Limited Cooperative Association | Other | — |
| Foreign General Cooperative Association | Other | — |
| Foreign Limited Cooperative Association | Other | — |
| DC DLCP Type | Standardized | ISO 20275 |
| - | - | - |
| Domestic Statutory Trust | Other | — |
| Foreign Statutory Trust | Other | — |
ISO 20275 ELF codes are assigned by jurisdiction of formation. Foreign
variants (e.g. "Foreign Limited Liability Company") are entities formed
outside DC and qualified to do business in the District — they carry no DC ISO
20275 code because the code belongs to their formation jurisdiction.
### Legal Representatives
The principals roster is returned in verification mode. A filed governing office is interpreted with the entity type: domestic partnership governors are general partners, with ordinary-business agency subject to the partnership's authority rules. The source does not establish sole or joint signing powers.
A governor of a corporation or cooperative is a governing board appointment. LLC membership alone does not establish agency, and an organizer or incorporator records formation activity. These appointments appear in `otherKeyPersons` when no separate mandate is supplied.
### Other Key Persons
The source preserves both governing and ownership capacities. A governor who is also a beneficial owner retains both appointments; beneficial-owner information does not imply a share percentage or create a shareholders datapoint.
| Filed office or capacity | Standardized role | Qualification |
| - | - | - |
| Governor | Board Member or Other | Entity-dependent governance; partnership context can establish General Partner |
| Director | Board Member | No individual signing mandate from a board seat alone |
| Organizer / Incorporator | Other | Formation appointment |
| Beneficial Owner / Member / Contact | Other | Ownership or administrative capacity |
| Registered Agent | Registered Agent | Service of process |
Individuals and corporate holders retain their names and available addresses. Unfamiliar titles remain visible without an assumed mandate. The prefill snapshot returns only its available service-agent data.
## Statutory Filings
Washington DC entities file a biennial report confirming the entity's particulars are current. The register publishes the date the next report is due and the date the last one was filed, returned on the cross-country [`statutoryFilings`](/essentials/compliance-signals) field as `next.dueDate` and `lastFiled.filedOn`.
```json theme={null}
{
"statutoryFilings": {
"annualFiling": {
"cadence": "biennial",
"next": {
"dueDate": "2028-04-01"
},
"lastFiled": {
"filedOn": "2026-03-18"
},
"source": "us_dc_dlcp"
}
}
}
```
US states publish no statutory accounts, so the `accounts` obligation is **absent** rather than returned empty. An empty object would read as "we looked and found nothing", which is a different claim. Placeholder cells such as `N/A` or `Inactive, Not Applicable` are dropped rather than parsed as dates, so an entity with no obligation simply has no `statutoryFilings`.
## Data Availability
| Data Point | Prefill (fast) | Verification (authoritative) | Notes |
| - | - | - | - |
| Legal name | Yes | Yes | Current legal name |
| Company status | Yes | Yes | Mapped from DC DLCP status field |
| Registration date | Yes | Yes | Effective date of formation or qualification |
| Legal address | Yes | Yes | Principal office address |
| Legal form | Yes | Yes | Entity-type label in both modes; standardized category and ISO 20275 code in verification mode only |
| Registered agent | Yes | Yes | Returned as Other Key Person; address for individual agents only in verification mode |
| Legal representatives | No | Yes | People filed with a governance title — verification mode only; can be empty where DC records none |
| Beneficial owners | No | Yes | Returned on `otherKeyPersons` with role `Beneficial Owner`, without percentages |
| Activity description | No | Yes | The entity's stated purpose as filed |
| Activity codes (ISIC / NACE) | No | Partial | Inferred from the stated purpose, flagged `isAIInferred` — \~70% of entities |
| Activity codes (NAICS) | No | No | Not published by the register, and not inferred |
| Shareholders | No | No | No ownership percentage or ownership-vs-control flag is recorded |
| UBOs | No | No | Beneficial owners are named but unquantified, so they are not returned as UBOs |
| Federal tax ID (EIN) | No | No | Not published by the DC register |
## Documents
### Available Documents
| Document | API Category | Availability | Format | Notes |
| - | - | - | - | - |
| **Trade Register Extract** | `tradeRegisterExtract` | Always available | PDF | The entity's own page on the DC BOSS register, captured as a PDF |
The Trade Register Extract is included with the company data block at no extra
charge. It is captured from the register's live entity page and carries the
register's own banner, the source URL and the capture timestamp. It covers
entity information, the biennial report status, the registered agent, the
beneficial-owner roster, and any trade name and licence records.
## Example API Responses
Every response below was captured from the live register, unedited apart from dropping internal ids. Query with `POST /v2/company`.
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-DC&query=Washington+Gas" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "L00005531281",
"legalName": "1 800 Water Damage North America, LLC",
"countryCode": "US-DC",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by DC File Number
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-DC&query=L00005531281" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "L00005531281",
"legalName": "1 800 Water Damage North America, LLC",
"countryCode": "US-DC",
"matchReason": {
"matchType": "id",
"identifier": {
"fileNumber": "L00005531281"
}
},
"address": {
"addressLine1": "185 Oakland Ave.",
"addressLine2": "Ste. 150",
"city": "Birmingham",
"postalCode": "48009",
"region": "MI",
"countryCode": "US"
}
}
]
```
### Company Profile
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-DC", "id": "L00005531281", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"]}'
```
Governors are filed with a governance title, so they are legal representatives. The registered agent is an Other Key Person.
```json theme={null}
{
"company": {
"id": "571294",
"countryCode": "US-DC",
"identifiers": {
"fileNumber": "571294"
},
"legalName": "WASHINGTON GAS LIGHT Company",
"incorporationDate": "1957-03-24",
"activityDescription": "Natural Gas",
"status": {
"localName": "Active - In Good Standing",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalForm": {
"localName": "Domestic Business Corporation",
"englishTranslation": "Domestic Business Corporation",
"standardized": "Corporation",
"iso20275Code": "CNQ3"
},
"legalAddress": {
"addressLine1": "1000 Maine Ave, SW",
"city": "Washington",
"postalCode": "20024",
"region": "DC",
"countryCode": "US"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent"
}
},
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
},
"individual": {
"name": {
"fullName": "Wendy Zelond"
}
}
},
{
"entityId": "company_002",
"type": "company",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
},
"individual": {
"name": {
"fullName": "Jimmi Duce"
}
}
},
{
"entityId": "person_003",
"type": "individual",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
},
"individual": {
"name": {
"fullName": "Colin Bonds"
}
}
},
{
"entityId": "person_004",
"type": "individual",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
},
"individual": {
"name": {
"fullName": "Donald M. Jenkins"
}
}
}
]
}
```
DC records this LLC's people as beneficial owners with no governance title, so `legalRepresentatives` is empty and the roster is on `otherKeyPersons`. This is normal for DC LLCs — read both fields.
```json theme={null}
{
"company": {
"id": "001491",
"countryCode": "US-DC",
"identifiers": {
"fileNumber": "001491"
},
"legalName": "BERNSTEIN FUND LLC",
"incorporationDate": "1991-02-10",
"activityDescription": "Real Estate Investment",
"status": {
"localName": "Active - In Good Standing",
"active": true,
"statusDetails": {
"status": "ACTIVE",
"additionalInfo": "Local status: Active - In Good Standing"
}
},
"legalForm": {
"localName": "Domestic Limited Liability Company",
"englishTranslation": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "2HBR"
},
"legalAddress": {
"addressLine1": "4800 Hampden Lane",
"addressLine2": "Suite 1200",
"city": "Bethesda",
"postalCode": "20814",
"region": "MD",
"countryCode": "US"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Beneficial Owner"
},
"individual": {
"name": {
"fullName": "Joshua B. Bernstein"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Beneficial Owner"
},
"individual": {
"name": {
"fullName": "Celia Ellen Bernstein"
}
}
},
{
"entityId": "person_003",
"type": "individual",
"role": {
"localName": "Beneficial Owner"
},
"individual": {
"name": {
"fullName": "Marianne Bernstein"
}
}
},
{
"entityId": "person_004",
"type": "individual",
"role": {
"localName": "Beneficial Owner"
},
"individual": {
"name": {
"fullName": "Nancy Gail Bernstein"
}
}
},
{
"entityId": "person_005",
"type": "individual",
"role": {
"localName": "Beneficial Owner"
},
"individual": {
"name": {
"fullName": "Elizabeth Anne Bernstein"
}
}
},
{
"entityId": "person_006",
"type": "individual",
"role": {
"localName": "Beneficial Owner"
},
"individual": {
"name": {
"fullName": "Susan Amy Bernstein"
}
}
},
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent"
}
}
]
}
```
The open-data snapshot carries entity-level fields and the registered agent only. No roster, and no activity description.
```json theme={null}
{
"company": {
"id": "571294",
"countryCode": "US-DC",
"identifiers": {
"fileNumber": "571294"
},
"legalName": "WASHINGTON GAS LIGHT Company",
"status": {
"localName": "Active - In Good Standing",
"active": true
},
"statutoryFilings": {
"annualFiling": {
"cadence": "biennial",
"next": {
"dueDate": "2027-04-01"
},
"source": "us_dc_dlcp"
}
},
"legalForm": {
"localName": "Domestic Business Corporation"
},
"legalAddress": {
"addressLine1": "1000 Maine Ave, SW",
"city": "Washington",
"postalCode": "20024",
"region": "DC",
"countryCode": "US"
}
},
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Registered Agent"
},
"individual": {
"name": {
"fullName": "CORPORATION SERVICE COMPANY"
},
"residenceAddress": {
"addressLine1": "1156 15TH STREET NW",
"city": "Washington",
"postalCode": "20005",
"region": "DC",
"countryCode": "US"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "560499",
"countryCode": "US-DC",
"identifiers": {
"fileNumber": "560499"
},
"legalName": "MARSH USA LLC",
"incorporationDate": "1956-04-26",
"activityDescription": "Insurance broker",
"status": {
"localName": "Active - In Good Standing",
"active": true,
"statusDetails": {
"status": "ACTIVE",
"additionalInfo": "Local status: Active - In Good Standing"
}
},
"legalForm": {
"localName": "Foreign Limited Liability Company",
"englishTranslation": "Foreign Limited Liability Company",
"standardized": "Limited Liability Company"
},
"legalAddress": {
"addressLine1": "1166 Avenue of the Americas",
"city": "New York",
"postalCode": "10036",
"region": "NY",
"countryCode": "US"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent"
}
},
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
},
"individual": {
"name": {
"fullName": "Claudric E Adams"
}
}
}
]
}
```
```json theme={null}
{
"company": {
"id": "000396",
"countryCode": "US-DC",
"identifiers": {
"fileNumber": "000396"
},
"legalName": "3409 CONNECTICUT AVENUE ASSOCIATES, LLC",
"incorporationDate": "1996-01-16",
"activityDescription": "PURCHASE AND MANAGEMENT OF REAL PROPERTY",
"status": {
"localName": "Dissolved",
"active": false,
"statusDetails": {
"status": "CLOSED"
}
},
"legalForm": {
"localName": "Domestic Limited Liability Company",
"englishTranslation": "Domestic Limited Liability Company",
"standardized": "Limited Liability Company",
"iso20275Code": "2HBR"
},
"legalAddress": {
"addressLine1": "3409 CONNECTICUT AVE., N.W.",
"city": "LEGACY NO DATA",
"postalCode": "20008",
"region": "DC",
"countryCode": "US"
}
},
"legalRepresentatives": [],
"otherKeyPersons": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
},
"individual": {
"name": {
"fullName": "SUSAN LIHN"
}
}
},
{
"entityId": "person_002",
"type": "individual",
"role": {
"localName": "Governor / Beneficial Owner",
"englishTranslation": "Governor / Beneficial Owner",
"standardized": "Other"
},
"individual": {
"name": {
"fullName": "jeffrey david koch"
}
}
}
]
}
```
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-DC", "id": "L00005531281", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_abc123",
"name": "Trade Register Extract",
"format": "pdf"
}
}
}
```
# West Virginia (US)
Source: https://docs.topograph.co/essentials/us-west-virginia
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date West Virginia (US) reference is on the [West Virginia (US) country page](https://www.topograph.co/countries/us-wv).
## Start here
This guide contains public integration notes for West Virginia. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Entity Types](#entity-types)
* [Status Codes](#status-codes)
* [Data Availability](#data-availability)
## Data Sources
West Virginia uses a single integration against the **West Virginia Secretary of State, Business Organization Register**. The register covers domestic and foreign corporations (for-profit, non-profit, and benefit), limited liability companies, professional LLCs, limited partnerships, general partnerships, voluntary associations, cooperatives, business trusts, and a set of administrative form types (trade names, name reservations, fictitious names, insurance companies, public corporations).
* **West Virginia Secretary of State, Business Organization Register** (verification, primary). The official public register served by the Online Data Services portal. Each query reads live against the register and returns legal name, organization number, organization type, charter type (domestic / foreign), profit / non-profit / benefit class, effective and filing dates, status with termination reason, business purpose (a NAICS-based industry code with a full description), authorized shares, capital stock and par value, the registered office and registered-agent addresses, officers and directors with their addresses, registered trade names (DBAs), mergers, amendments, and annual-report filing history.
Sole proprietors and most general partnerships are out of scope at the state level. Trade names (DBAs) and mergers appear on the parent entity's record rather than as standalone records.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **WV Organization Number** | Digits only, no leading zeros or separators; 4 to 6 digits in the records we have seen (`2011`, `20122`, `633785`) | `20122` | Assigned by the Secretary of State at filing. Also shown as "Org Id" on the portal. |
Use the organization number as it appears on the portal, digits only. Input with a prefix such as `WV-` is not accepted.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `orgNumber` | Digits only, 4 to 6 digits in the records we have seen | `20122` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 characters | `"Mountaineer Gas"` | Substring (case-insensitive) | Up to 50 |
| By WV Organization Number | Up to 10 digits | `20122` | Exact | Exact match returned first (matchType: id); other results may follow |
Name search returns up to 50 rows per query. Narrow with fuller query strings when the top of the result list looks too broad. The wildcard character `%` is also accepted (for example, `%Gas Company%`).
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Organization number is numeric** | West Virginia does not use a letter prefix on its organization number (unlike states such as Montana or Wisconsin). The plain digit string returned in the response is the canonical identifier. |
| **No shareholder or UBO register** | West Virginia does not publish shareholders or beneficial owners for any entity type. Federal FinCEN beneficial-ownership records are restricted and are not part of this dataset. |
| **LLC member and manager rosters are filed** | For LLCs, the Secretary of State records each member, manager, and organizer on the formation filing. Managers (and managing members) are surfaced as `legalRepresentatives`; members and organizers are surfaced as `otherKeyPersons` rather than as shareholders, since no ownership percentages are collected. |
| **Business purpose uses a NAICS-based code** | The "Business Purpose" field on the record is a four-digit code with a three-level description, drawn from the North American Industry Classification System. It is returned as a NAICS code, and ISIC and NACE codes are derived from it through a deterministic concordance. The state itself does not supply ISIC or NACE codes. |
| **Charter type Domestic vs Foreign** | Every entity is flagged as either Domestic (formed in West Virginia) or Foreign (formed elsewhere and registered to transact business in West Virginia). Foreign entities carry the charter state on the record. |
| **Termination reason carries the detail** | The top-level status is binary (Active / Not Active), so the termination reason is the richer signal: Dissolution by Court Order, Merger, Voluntary Dissolution, LLC Termination, Revoked (Failure to File Annual Report), Pending, and others. |
| **Certificate of Existence eligibility** | The official Certificate of Existence can only be issued for entities that are Active and in good standing on the register. Inactive, revoked, or non-compliant entities are not eligible. Pricing and availability are on the live pricing page. |
## Mappings
### Entity Types
The Secretary of State uses a fixed organization-type taxonomy. Codes and labels are stable; the live mapping to standardized legal forms is on the pricing page.
| Code | Label | Standardized Form |
| - | - | - |
| `C` | Corporation | Corporation |
| `LLC` | Limited Liability Company | Limited Liability Company |
| `PLC` | Professional Limited Liability Company | Limited Liability Company |
| `LP` | Limited Partnership | Partnership |
| `GP` | General Partnership | Partnership |
| `LLP` | Limited Liability Partnership | Partnership |
| `VA` | Voluntary Association | Other |
| `BC` | Benefit Corporation | Corporation |
| `BT` | Business Trust | Trust |
| `CA` | Cooperative Association | Cooperative |
| `UNA` | Unincorporated Non-profit Organization | Nonprofit Organization |
The register also lists administrative and regulated filing types outside this taxonomy (for example exempt entities, insurance companies, public corporations, sole proprietors, trademark holders, and fictitious names). When their label names a corporation, limited liability company, or partnership, that sets the standardized form; otherwise only the local name is returned, with no standardized form.
### Status Codes
| Code | Local Name | Active |
| - | - | - |
| `Active` | Active | Yes |
| `Not Active` | Termination reason, or `Not Active` | No |
For an inactive entity, `status.localName` holds the termination reason recorded on the register (for example Dissolution by Court Order, Merger, Voluntary Dissolution (Domestic), LLC Termination (Domestic), Revoked (Failure to File Annual Report), Pending). When the register records a termination date but no reason, `status.localName` is `Not Active`. In both cases `status.active` is `false`.
### Officer Roles
The Secretary of State records officers, directors, and other role-holders on each entity. We surface them as either `legalRepresentatives` (declared officer and management context, with company-specific powers unverified) or `otherKeyPersons` (the registered agent, LLC members, organizers, and incorporators).
| Local Role | Mapped To |
| - | - |
| President | legalRepresentatives |
| Vice-President | legalRepresentatives |
| Secretary | legalRepresentatives |
| Treasurer | legalRepresentatives |
| Director | legalRepresentatives |
| Manager | legalRepresentatives |
| Managing Member | legalRepresentatives |
| Member | otherKeyPersons |
| Organizer | otherKeyPersons |
| Incorporator | otherKeyPersons |
The registered agent (recorded on the entity as the "Notice of Process" address) is also surfaced as an `otherKeyPersons` entry with the standardized role `Registered Agent`.
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company profile | Yes | Legal name, organization number, type, charter type, profit / non-profit / benefit class, dates, status, business purpose, capital, addresses. |
| Registered agent | Yes | Returned as `otherKeyPersons` with the standardized role `Registered Agent`. Includes name and full address. |
| Legal representatives | Yes | Officers, directors, and LLC managers (President, Vice-President, Secretary, Treasurer, Director, Manager, Managing Member) are surfaced as `legalRepresentatives` with their addresses. |
| Other key persons | Yes | LLC members, organizers, incorporators, and the registered agent. |
| Shareholders | No | Not collected by West Virginia at the state level. |
| Ultimate beneficial owners | No | West Virginia does not maintain a public beneficial-ownership register. |
| Activity codes | Yes (NAICS; ISIC/NACE derived) | The NAICS-based "Business Purpose" code is returned with its description. ISIC and NACE codes are derived from it through a deterministic concordance; the state does not supply them. |
| Trade Register Extract | Yes | Printable PDF of the Secretary of State entity detail page, captured at request time. Bundled with the company-data block at no extra charge. |
| Certificate of Existence | Yes | Official PDF issued by the Secretary of State for entities that are Active and in good standing. Pricing and availability are on the live pricing page. |
# Wisconsin (US)
Source: https://docs.topograph.co/essentials/us-wisconsin
Country-specific identifiers, data sources, and integration details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Wisconsin (US) reference is on the [Wisconsin (US) country page](https://www.topograph.co/countries/us-wi).
## Start here
This guide contains public integration notes for Wisconsin. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Entity Types](#entity-types)
* [Status Codes](#status-codes)
* [Data Availability](#data-availability)
## Data Sources
Wisconsin uses a single integration against the **Wisconsin Department of Financial Institutions (WDFI) Corporate Records Search**. The register covers domestic and foreign business corporations, non-stock (non-profit) corporations, cooperatives, limited partnerships, limited liability companies, limited liability partnerships, common-law trusts, and a handful of administrative form types (name reservations, foreign registered names).
* **WDFI Corporate Records Search** (verification, primary). The official public lookup served by the Department of Financial Institutions. Each query reads live against the register and returns legal name, entity ID, entity type, registered effective date, status, registered agent name and address, and principal office address. Status date, period of existence and the chronology of filings are not returned as structured fields; they appear on the Trade Register Extract.
Sole proprietors and most general partnerships are out of scope at the state level (only general partnerships that voluntarily file a Statement of Partnership Authority appear in the register). DBA filings are handled by individual county registers of deeds and are not part of this dataset.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Wisconsin Entity ID** | 7 characters , `A######` (modern) or `#A#####` (legacy) | `K024598` | One alpha plus six numeric characters. Modern registrations follow `A######`; pre-2003 registrations may follow `#A#####`. |
Use the entity ID as it appears on the WDFI portal. Both formats are accepted. The portal is case-sensitive in display only , queries are normalized to uppercase before search.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `entityId` | 7 characters | `K024598` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Kohl's"` | Substring (case-insensitive) | Up to 250 |
| By Wisconsin Entity ID | 7 characters | `K024598` | Exact | Exact match returned first (matchType: id); other results may follow |
Name search returns at most 250 rows. Narrow with fuller query strings when the top of the result list looks too broad.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Two identifier formats** | Modern entities use `A######`; pre-2003 entities use the legacy `#A#####` form (e.g. `1J03577` for Johnson Controls, registered in 1900). Both shapes are valid and both round-trip through the search and profile endpoints. |
| **Officers and directors are not public** | Wisconsin collects officer and director rosters on the annual report, but those rosters are not part of the public search record. They are available only through a separate paid copywork order from the WDFI Online Order System and are not yet offered through Topograph. |
| **No shareholder or UBO register** | Wisconsin does not publish shareholders or beneficial owners for any entity type. Federal FinCEN beneficial-ownership records are restricted and are not part of this dataset. |
| **No activity codes** | The WDFI does not collect NAICS, NACE, or ISIC industry codes. |
| **Status comes from a closed code list** | Every entity carries one of `INC` (Incorporated/Qualified/Registered), `ORG` (Organized), `IGS` (Restored to Good Standing), `DIS` (Dissolved), or `ADS` (Administratively Dissolved). The first three are active; the last two are inactive. |
| **Principal Office may be blank** | Some entity types do not file a principal office address. When absent, the registered agent address is used as the legal address. |
| **Pre-2003 filings are paper or microfilm** | The chronology of filings goes back to formation, but pre-2003 filings are stored on microfilm or as scanned images and may take longer to retrieve through the document order system. |
| **Wisconsin Certificate of Status** | The certificate of status (good-standing certificate) is available as an official PDF issued by the WDFI. It is billed separately from the company data block; see the pricing page for the price. |
## Mappings
### Entity Types
The WDFI uses a fixed entity-type code taxonomy. The codes and labels are stable; the live mapping to standardized legal forms is on the pricing page.
| Code | Label | Standardized Form |
| - | - | - |
| 01 | Domestic Business | Corporation |
| 02 | Foreign Business Corporation | Corporation |
| 03 | Membership Cooperative | Cooperative |
| 04 | Stock Cooperative | Cooperative |
| 05 | Service Corporation | Corporation |
| 06 | Non-Stock Corporation | Nonprofit Organization |
| 07 | Domestic Limited Partnership | Partnership |
| 08 | Foreign Limited Partnership | Partnership |
| 09 | Domestic Close Corporation | Corporation |
| 10 | Service Close Corporation | Corporation |
| 11 | Miscellaneous | Other |
| 12 | Domestic Limited Liability Company | Limited Liability Company |
| 13 | Foreign LLC | Limited Liability Company |
| 14 | Domestic Limited Liability Partnership | Partnership |
| 15 | Foreign Limited Liability Partnership | Partnership |
| 16 | Foreign Non-Stock Corporation | Nonprofit Organization |
| 17 | Domestic General Partnership | Partnership |
| 18 | Foreign General Partnership | Partnership |
| 20 | Common Law Trust | Other |
| 24 | Domestic Limited Liability Partnership - Exempt | Partnership |
| 25 | Foreign Limited Liability Partnership - Exempt | Partnership |
| 90 | Foreign Registered Name | Other (name reservation) |
| 96 | Short Term Name Reservation | Other (name reservation) |
| 97 | In Process | Other (name reservation) |
| 98 | Long Term Name Reservation/Registration | Other (name reservation) |
| 99 | Short Term Name Reservation (alternate code) | Other (name reservation) |
### Status Codes
| Code | Local Name | Active |
| - | - | - |
| `INC` | Incorporated/Qualified/Registered | Yes |
| `ORG` | Organized | Yes |
| `IGS` | Restored to Good Standing | Yes |
| `DIS` | Dissolved | No |
| `ADS` | Administratively Dissolved | No |
## Data Availability
| Datapoint | Available | Notes |
| - | - | - |
| Company profile | Yes | Legal name, entity ID, entity type, registered effective date, status, principal office. |
| Registered agent | Yes | Returned as `otherKeyPersons` with the standardized role `Registered Agent`. Includes name and full address. |
| Legal representatives | No | Officers and directors are filed on the annual report and are not part of the public record. Available only through the paid copywork order, not yet integrated. |
| Shareholders | No | Not collected by Wisconsin at the state level. |
| Ultimate beneficial owners | No | Wisconsin does not maintain a public beneficial-ownership register. |
| Activity codes | No | The WDFI does not collect NAICS, NACE, or ISIC codes. |
| Trade Register Extract | Yes | Printable PDF of the WDFI entity detail page, captured at request time. Bundled with the company-data SKU at no extra charge. |
| Certificate of Status | Yes | Official PDF issued by the WDFI, billed separately. Pricing is on the live pricing page. |
# Wyoming (US)
Source: https://docs.topograph.co/essentials/us-wyoming
Country-specific identifiers, data sources, and implementation details
This guide is outdated and will be removed on 1 November 2026. The up-to-date Wyoming (US) reference is on the [Wyoming (US) country page](https://www.topograph.co/countries/us-wy).
## Start here
This guide contains public integration notes for Wyoming. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Company Status](#company-status)
* [Legal Forms](#legal-forms)
* [Legal Representatives](#legal-representatives)
* [Other Key Persons](#other-key-persons)
* [Data Availability](#data-availability)
* [Documents](#documents)
* [Example API Responses](#example-api-responses)
## Data Sources
All entity data comes from the **Wyoming Secretary of State** business register, the official **WyoBiz** filing and search system ([wyobiz.wyo.gov](https://wyobiz.wyo.gov)) for the \~200,000+ business entities registered in Wyoming.
Wyoming supports two modes on a single data block:
* **Prefill** (`mode: "prefill"`, fast, non-authoritative). Returns a quick summary built from the register's public search index: legal name, Filing ID, legal form, and status. It does not include addresses, registration date, officers, or the registered agent. Use it for fast identity resolution during prefill flows.
* **Verification** (`mode: "verification"`, the default, authoritative). Returns the full register record read live from the entity's WyoBiz detail page: everything in the prefill summary plus the registered/principal-office address, the registration date, directors and officers, and the registered agent. Use it when you need the complete, authoritative profile.
**Mode-based routing.** Prefill requests are served fast from the register's
public search index and return a non-authoritative summary. Verification requests
read the live register detail page and return the full authoritative record,
including address, directors and officers, and the registered agent.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| - | - | - | - |
| **Filing ID** | `YYYY-NNNNNNNNN` | `2004-000464709` | Wyoming Secretary of State primary identifier (year + 9-digit sequence) |
The Filing ID is the only identifier supported for company retrieval. To find
a Filing ID from a name, use the search endpoint first.
The `YYYY` prefix of the Filing ID is the year the entity registered with the
Wyoming Secretary of State (the qualification year for foreign entities), not
the entity's incorporation date. It is year-granularity only, so do not treat
it as `registrationDate`. The registration date is returned as a separate field
in verification mode.
### Identifiers in API Response
| Identifier | Format | Example | Found In |
| - | - | - | - |
| `filingId` | `YYYY-NNNNNNNNN` | `2004-000464709` | All entities |
### Legal Entity Identifier (LEI)
GLEIF is the supplementary data source for this identifier.
`company.identifiers.lei` is returned when a company identifier has a unique match against this jurisdiction's registration or validation references in GLEIF.
An [LEI (Legal Entity Identifier)](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) has 20 uppercase letters and digits, ending in two check digits.
Coverage varies by entity. The field is omitted when no unambiguous match is available. Lapsed or retired LEIs may be returned; annulled records are excluded.
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| - | - | - | - | - |
| By Name | 2-200 chars | `"Wyoming Energy Corp"` | Starts with | Multiple results |
| By Filing ID | `YYYY-NNNNNNNNN` | `2004-000464709` | Exact | Exact match returned first (matchType: id); other results may follow |
Name search matches from the beginning of the entity name (starts-with). For
broader matches, use shorter prefixes.
### Active companies only
Search can return companies that are no longer active. Each result carries the register's status, so [`activeOnly=true`](/essentials/search#active-companies-only) removes the inactive ones.
## Quirks & Gotchas
| Quirk | Details |
| - | - |
| **Wyoming is a privacy state** | Wyoming does not require LLCs to disclose members or managers in public filings. Only the organizer who filed the articles appears on the entity record. |
| **No shareholder or UBO register** | Wyoming does not publish shareholders or beneficial owners for any entity type. The federal CTA/FinCEN is a separate system. |
| **No activity codes** | The Wyoming Secretary of State does not collect NAICS or industry classification codes. |
| **Registered agent standing** | Wyoming tracks three separate standings: Tax, Registered Agent (RA), and Other. All three must be "Good" for a Certificate of Good Standing to be issued. |
| **Officers require verification mode** | Directors, officers, and the registered agent come from the entity's register detail page. They are returned in verification mode only, not in the prefill summary. |
| **Dual role labels** | Corporate officers may hold combined roles (e.g. "President / Director"). These are mapped to the primary role. |
| **Trade names and trademarks** | Trade Name and Trademark registrations appear in WyoBiz as entity types but are not legal entities. They are mapped with standardized form `Other`. |
## Mappings
### Company Status
Status comes from the WyoBiz entity status field. "Active" is the only in-good-standing state. All other statuses begin with "Inactive -" followed by a specific reason. The response includes `statusDetails` with structured fields: `status`, `closureReason`, `closureDate`, and `additionalInfo`.
| Source Value | Active | closureReason |
| - | - | - |
| `Active` | `true` | — |
| `Inactive - Dissolved` | `false` | `ADMINISTRATIVE_DISSOLUTION` |
| `Inactive - Administratively Dissolved (Tax)` | `false` | `ADMINISTRATIVE_DISSOLUTION` |
| `Inactive - Administratively Dissolved or Revoked (Tax)` | `false` | `ADMINISTRATIVE_DISSOLUTION` |
| `Inactive - Administratively Dissolved or Revoked (No Agent)` | `false` | `ADMINISTRATIVE_DISSOLUTION` |
| `Inactive - Administratively Dissolved or Revoked (Other)` | `false` | `ADMINISTRATIVE_DISSOLUTION` |
| `Inactive - Revoked (Tax)` | `false` | `ADMINISTRATIVE_DISSOLUTION` |
| `Inactive - Cancelled` | `false` | `OTHER` |
| `Inactive - Expired` | `false` | `OTHER` |
| `Inactive - Withdraw/Dissolve/Cancel` | `false` | `OTHER` |
| `Inactive - Merged` | `false` | `MERGER` |
| `Inactive - Withdrawal` | `false` | `OTHER` |
The Sub Status field ("Current" or "Archived") from WyoBiz further qualifies inactive entities. "Current" means the entity has a 2-year reinstatement window; "Archived" means it can no longer reinstate.
### Legal Forms
Legal form is derived from the WyoBiz Filing Details `Type` field. Wyoming distinguishes between domestic and foreign variants of each entity structure.
| WyoBiz Type | Standardized | ELF Code |
| - | - | - |
| Limited Liability Company (Domestic) | Limited Liability Company | `NB58` |
| Limited Liability Company (Foreign) | Limited Liability Company | |
| Profit Corporation (Domestic) | Corporation | `9GXA` |
| Profit Corporation (Foreign) | Corporation | |
| Nonprofit Corporation (Domestic) | Nonprofit Organization | `PUJR` |
| Nonprofit Corporation (Foreign) | Nonprofit Organization | |
| Limited Partnership (Domestic) | Partnership | `QR4Y` |
| Limited Partnership (Foreign) | Partnership | |
| Registered Limited Liability Partnership (Domestic) | Partnership | `71ZI` |
| Registered Limited Liability Partnership (Foreign) | Partnership | |
| Statutory Trust (Domestic) | Trust | `RDQZ` |
| Statutory Trust (Foreign) | Trust | |
| Statutory Foundation (Domestic) | Other | `1YA4` |
| Statutory Foundation (Foreign) | Other | |
| Statutory Close Corporation (Domestic) | Corporation | `9GXA` |
| Trade Name | Other | — |
| Trademark | Other | — |
### Legal Representatives
Wyoming discloses named appointments on the Filing Details page. The full entity type determines the representation context. Corporate officers may execute register filings under Wyoming Statutes 17-16-120(f) and 17-19-120(f); their title does not establish unrestricted commercial authority or a sole signature mode.
| Role | Entity context | Standardized |
| - | - | - |
| President | Corporation | President |
| President / Director | Corporation | President |
| Vice President | Corporation | Vice President |
| Vice President / Director | Corporation | Vice President |
| Secretary | Corporation | Secretary |
| Secretary / Director | Corporation | Secretary |
| Treasurer | Corporation | Treasurer |
| Treasurer / Director | Corporation | Treasurer |
| General Partner | Domestic limited partnership | General Partner |
| Partner | Domestic registered LLP | Partner |
| Trustee | Domestic statutory trust, specified certificate execution | Other |
Domestic partnership agency is subject to statutory and contractual limits. Trust certificate execution requirements differ by filing; a single signature mode is not inferred. A foreign registration does not establish the foreign formation law or an individual commercial mandate.
### Other Key Persons
| Role | Standardized | Notes |
| - | - | - |
| Director | Board Member | Board office alone does not establish individual representation |
| Incorporator | Other | Formation appointment; a current preformation signing exception is not established |
| Organizer | Other | LLC formation filer, without an evidenced current mandate |
| Manager | Other | LLC management title without a recorded representation grant |
| Limited Partner | Other | Title alone does not establish general partnership agency |
| General Partner | Other | Foreign or unqualified entity context |
| Partner | Other | Foreign or unqualified entity context |
| Trustee | Other | Foreign or unqualified trust context |
| President | C-Level Executive | Outside a qualified corporate context |
| President / Director | C-Level Executive | Outside a qualified corporate context |
| Vice President | C-Level Executive | Outside a qualified corporate context |
| Vice President / Director | C-Level Executive | Outside a qualified corporate context |
| Secretary | Secretary | Outside a qualified corporate context |
| Secretary / Director | Secretary | Outside a qualified corporate context |
| Treasurer | Other | Outside a qualified corporate context |
| Treasurer / Director | Other | Outside a qualified corporate context |
| Registered Agent | Registered Agent | Service-of-process contact |
LLC public detail records typically show formation organizers and may show managers. They do not supply a complete member register. A representative of the registered agent's organization is not assumed to hold a mandate from the subject company. Unknown appointment titles are retained as other key persons until representation evidence is available. The reference list covers existing and observed titles; WyoBiz does not publish a complete closed party classifier.
## Data Availability
Availability depends on the mode. Prefill returns a fast summary from the register's search index; verification returns the full authoritative record from the entity's register page.
| Data Point | Prefill | Verification | Notes |
| - | - | - | - |
| Company name | Yes | Yes | Current legal name |
| Filing ID | Yes | Yes | Canonical identifier |
| Legal form | Yes | Yes | Full type with domestic/foreign distinction and ISO 20275 mapping |
| Company status | Yes | Yes | Active or Inactive with specific reason |
| Registration date | No | Yes | Initial filing date |
| Legal address | No | Yes | Principal office address |
| Mailing address | No | No | Shown on the Trade Register Extract, not returned as structured data |
| Fictitious name | No | No | Not returned as structured data |
| Standings | No | No | Tax, Registered Agent, and Other standings are shown on the Trade Register Extract, not returned as structured data |
| Legal representatives | No | Yes\* | Depends on entity type — corporations have officers; LLCs may only show organizer |
| Registered agent | No | Yes | Name and address returned as Other Key Person |
| Share capital | No | No | Authorized shares and par value (corporations only) are shown on the Trade Register Extract, not returned as structured data |
| Formation jurisdiction | No | No | Shown on the Trade Register Extract, not returned as structured data |
| Activity codes | No | No | Not collected by the Wyoming Secretary of State |
| Shareholders | No | No | Not published by Wyoming at the state level |
| UBOs | No | No | No state-level beneficial-ownership register; federal FinCEN is a separate system |
| Financial data | No | No | Not collected |
## Documents
### Available Documents
| Document | Availability | Format |
| - | - | - |
| **Trade Register Extract** | Always available | PDF |
| **Certificate of Good Standing** | Conditional — entity must be Active with all standings "Good" | PDF |
The Trade Register Extract is included at no extra charge with the company data
block; it is a printed PDF of the entity's register detail page. The Certificate of
Good Standing is billed separately (see the pricing page for the price). The
Certificate of Good Standing is issued electronically by the Wyoming Secretary of
State and confirms the entity is in compliance with all state requirements (tax,
registered agent, other); it is available only for entities that are Active with
all three standings "Good".
## Example API Responses
### Search by Name
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-WY&query=ACME+ENERGY+CORP" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "2004-000464709",
"legalName": "Wyoming Energy Corporation",
"countryCode": "US-WY",
"matchReason": {
"matchType": "default"
}
}
]
```
### Search by Filing ID
```bash theme={null}
curl -X GET "https://api.topograph.co/v2/search?country=US-WY&query=2004-000464709" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "2004-000464709",
"legalName": "Wyoming Energy Corporation",
"countryCode": "US-WY",
"matchReason": {
"matchType": "id",
"identifier": { "filingId": "2004-000464709" }
}
}
]
```
### Company Profile (Prefill)
Prefill mode returns a fast, non-authoritative summary from the register's public search index: legal name, Filing ID, legal form, and status.
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-WY", "id": "2004-000464709", "dataPoints": ["company"], "mode": "prefill"}'
```
```json theme={null}
{
"company": {
"id": "2004-000464709",
"countryCode": "US-WY",
"identifiers": { "filingId": "2004-000464709" },
"legalName": "Wyoming Energy Corporation",
"status": {
"localName": "Active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Profit Corporation (Domestic)",
"englishTranslation": "Profit Corporation",
"standardized": "Corporation",
"iso20275Code": "9GXA"
}
}
}
```
### Company Profile (Verification)
Verification mode reads the live register detail page and returns the full authoritative record: everything in the prefill summary plus the registration date, the principal-office address, directors and officers, and the registered agent.
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-WY", "id": "2004-000464709", "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "2004-000464709",
"countryCode": "US-WY",
"identifiers": { "filingId": "2004-000464709" },
"legalName": "Wyoming Energy Corporation",
"registrationDate": "2004-04-12",
"status": {
"localName": "Active",
"active": true,
"statusDetails": { "status": "ACTIVE" }
},
"legalForm": {
"localName": "Profit Corporation (Domestic)",
"englishTranslation": "Profit Corporation",
"standardized": "Corporation",
"iso20275Code": "9GXA"
},
"legalAddress": {
"addressLine1": "Northwest 69th Street",
"city": "Boca Raton",
"postalCode": "33487",
"region": "Palm Beach County",
"state": "Florida",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"entityId": "person_001",
"type": "individual",
"role": {
"localName": "President / Director",
"standardized": "President"
},
"individual": {
"name": { "fullName": "Blair Merriam" }
}
}
],
"otherKeyPersons": [
{
"entityId": "company_001",
"type": "company",
"role": {
"localName": "Registered Agent",
"standardized": "Registered Agent"
},
"company": {
"countryCode": "US",
"legalName": "InCorp Services, Inc.",
"legalAddress": {
"addressLine1": "Thomes Avenue",
"city": "Cheyenne",
"postalCode": "82002",
"region": "Laramie County",
"state": "Wyoming",
"countryCode": "US"
}
}
}
]
}
```
### Available Documents
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-WY", "id": "2004-000464709", "dataPoints": ["availableDocuments"]}'
```
```json theme={null}
{
"documents": {
"tradeRegisterExtract": {
"id": "doc_tre_123",
"name": "Trade Register Extract",
"format": "pdf"
},
"certificateOfGoodStanding": {
"id": "doc_cogs_456",
"name": "Certificate of Good Standing",
"format": "pdf"
}
}
}
```
# VAT Validation
Source: https://docs.topograph.co/essentials/vat-validation
Verify EU VAT numbers and obtain legal proof for audits
## Overview
Topograph automatically validates VAT numbers for EU companies via the EU VIES (VAT Information Exchange System) service. This validation provides legally admissible proof of VAT verification for audit purposes.
## How It Works
When you request a company profile for supported EU countries, Topograph:
1. **Calculates the VAT number** from the company's registration number (e.g., SIREN in France, NIF in Spain)
2. **Performs a qualified VIES check** using Topograph's own VAT number as the requester
3. **Returns verification details** including the consultation number (legal proof)
The qualified VIES check runs on requests in verification mode, the default. A request in prefill mode can return `taxId` with `verification.status: unavailable` and no consultation number, so use verification mode when you need the legal proof.
## Response Structure
The `taxId` field is included in company profile responses:
```json theme={null}
{
"company": {
"id": "932884117",
"countryCode": "FR",
"identifiers": {
"siren": "932884117",
"VAT": "21932884117"
},
"taxId": {
"type": "eu_vat",
"value": "21932884117",
"country": "FR",
"verification": {
"status": "verified",
"verifiedAt": "2026-02-04T15:30:00.000Z",
"verifiedName": "TOPOGRAPH SAS",
"verifiedAddress": "1 RUE EXAMPLE 75001 PARIS",
"consultationNumber": "WAPIAAAAW1234567890"
}
}
}
}
```
### Fields
| Field | Description |
| - | - |
| `type` | Tax ID type. Currently `eu_vat` for EU VAT numbers |
| `value` | VAT number **without** country prefix (e.g., `21932884117` not `FR21932884117`) |
| `country` | ISO 3166-1 alpha-2 country code (e.g., `FR`, `ES`) |
| `verification.status` | Verification status: `verified`, `unverified`, or `unavailable` |
| `verification.verifiedAt` | ISO 8601 timestamp of when the verification was performed |
| `verification.verifiedName` | Company name as registered with VIES |
| `verification.verifiedAddress` | Company address as registered with VIES |
| `verification.consultationNumber` | **The legal proof** - unique identifier from VIES for audit purposes |
| `verification.source` | Authority behind the verification, when set: `vies` (intra-EU registration, carries a consultation number) or `agenzia_entrate` (Italy only, domestic VAT status, no consultation number) |
## Verification Statuses
| Status | Meaning |
| - | - |
| `verified` | VAT number is valid and registered with VIES. The company can perform EU cross-border transactions. For Italy, `verified` with `source: agenzia_entrate` means the VAT number is valid domestically but VIES did not confirm an intra-EU registration, so no consultation number is returned. |
| `unverified` | VAT number format is valid but not registered with VIES. The company may not be registered for EU trade. |
| `unavailable` | Unable to verify (VIES service unavailable, invalid format, etc.) |
## The Consultation Number
The `consultationNumber` is the critical piece for legal compliance. This is the official receipt from the EU VIES system that proves you validated the VAT number at a specific point in time.
Store the `consultationNumber` along with the `verifiedAt` timestamp in your records.
This is the legally admissible proof that you performed due diligence when validating a customer's VAT number.
## Supported Countries
### Full taxId Support (VAT in profile + VIES verification)
| Country | VAT Format | Notes |
| - | - | - |
| 🇫🇷 France | FR + 11 digits | VAT calculated from SIREN using official formula |
| 🇪🇸 Spain | ES + NIF | VAT equals NIF. Requires ROI registration for EU trade |
| 🇸🇪 Sweden | SE + 12 digits | Organisationsnummer + "01" suffix |
| 🇮🇹 Italy | IT + 11 digits | Partita IVA from Infocamere |
| 🇵🇹 Portugal | PT + 9 digits | NIF (Número de Identificação Fiscal) |
| 🇵🇱 Poland | PL + 10 digits | NIP (Numer Identyfikacji Podatkowej) |
| 🇪🇪 Estonia | EE + 9 digits | VAT from registry API |
| 🇦🇹 Austria | ATU + 8 digits | VAT via VIES reverse lookup |
| 🇧🇪 Belgium | BE + 10 digits | Enterprise Number (KBO/BCE) |
| 🇱🇺 Luxembourg | LU + 8 digits | VAT via VIES reverse lookup |
| 🇩🇰 Denmark | DK + 8 digits | CVR number |
| 🇨🇿 Czechia | CZ + 8-10 digits | IČO for companies |
| 🇷🇴 Romania | RO + 2-10 digits | CUI (Cod Unic de Înregistrare) |
| 🇭🇺 Hungary | HU + 8 digits | First 8 digits of tax number |
| 🇫🇮 Finland | FI + 8 digits | Business ID without hyphen |
| 🇭🇷 Croatia | HR + 11 digits | OIB (Osobni Identifikacijski Broj) |
| 🇧🇬 Bulgaria | BG + 9 digits | UIC. Returned only when VIES confirms the VAT registration |
| 🇳🇱 Netherlands | NL + 9 digits + B + 2 digits | VAT from the trade register, or derived from the RSIN |
### VAT Search Only (VIES reverse lookup)
For these countries, you can search by VAT number, but the `taxId` field won't appear in company profiles because the VAT is neither algorithmically derivable from the registration number nor available in the registry API.
| Country | VAT Format | Notes |
| - | - | - |
| 🇱🇻 Latvia | LV + 11 digits | Search via VIES, no taxId in profile |
| 🇨🇾 Cyprus | CY + 8 digits + 1 letter | Search via VIES, no taxId in profile |
| 🇮🇪 Ireland | IE + 7-9 characters | Search via VIES, no taxId in profile |
| 🇲🇹 Malta | MT + 8 digits | Search via VIES, no taxId in profile |
| 🇸🇰 Slovakia | SK + 10 digits | Search via VIES, no taxId in profile |
## Country-Specific Notes
### France
The French VAT number (TVA Intracommunautaire) is calculated mathematically from the SIREN:
```
Key = (12 + 3 × (SIREN mod 97)) mod 97
VAT = Key (2 digits) + SIREN (9 digits)
```
Example: SIREN `932884117` → VAT `21932884117`
### Spain
In Spain, the VAT number equals the NIF (Número de Identificación Fiscal):
* NIF: `A82511361`
* VAT: `A82511361` (same value)
Having a Spanish NIF does **not** guarantee the company is VAT-registered for EU trade.
Companies must be enrolled in the ROI (Registro de Operadores Intracomunitarios)
to perform intra-community transactions. VIES will return `unverified` for companies not in ROI.
### Sweden
Swedish VAT is derived from the Organisationsnummer with a "01" suffix:
* Organisationsnummer: `5560360793`
* VAT: `556036079301`
### Belgium
Belgian VAT equals the Enterprise Number (KBO/BCE number):
* Enterprise Number: `0644911041`
* VAT: `0644911041`
### Countries with VIES Reverse Lookup Only
For Latvia, Cyprus, Ireland, Malta, and Slovakia, the VAT number cannot be derived from the registration number and is not available in the registry API. However, you can still:
1. **Search by VAT** - Enter a VAT number to find the company via VIES reverse lookup
2. **Verify VAT** - The search returns the company name from VIES, which is then matched to the local registry
VIES reverse lookup searches by VAT number and returns the company name, which is then used to search the local registry. This may return multiple results if the company name is common.
## Searching by VAT Number
You can search for companies using their VAT number (with or without the country prefix):
```bash theme={null}
# With prefix
curl -G https://api.topograph.co/v2/search \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "country=FR" \
--data-urlencode "query=FR21932884117"
# Without prefix (11 digits for France)
curl -G https://api.topograph.co/v2/search \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "country=FR" \
--data-urlencode "query=21932884117"
```
The search will automatically extract the underlying company identifier (SIREN/NIF) and return the matching company.
## Best Practices
1. **Always store the consultation number** - This is your legal proof of verification
2. **Re-validate periodically** - VAT registrations can change; consider re-validating before significant transactions
3. **Handle `unverified` gracefully** - Not all companies are VAT-registered, especially in Spain where ROI enrollment is separate
4. **Use the `identifiers.VAT` field** - It is present when a VAT number is known or derivable for the country, and contains the VAT value without prefix. Bulgaria returns `identifiers.VAT` and `taxId` only when VIES confirms the registration, so a missing `taxId` there means no confirmed VAT registration rather than `unverified`
# Workspaces
Source: https://docs.topograph.co/essentials/workspaces
Split API usage across sub-accounts, departments, or clients for easy cost tracking and rebilling
## Overview
Workspaces let you **tag every API request** with a sub-account identifier, so you can track and rebill usage per client, department, or entity. This is especially useful for **resellers**, **multi-entity organizations**, and **platforms** that need granular cost attribution.
Each workspace has a **legal name** tied to it, perfect for invoicing and compliance. A workspace also holds its own **register credentials**, so each client can be checked under their own register account.
Track exactly how many credits each of your clients consumes
Associate each workspace with a legal name for invoicing
Pull usage reports programmatically to automate rebilling
Store each client's own register logins on their workspace
***
## How It Works
```mermaid theme={null}
flowchart LR
A[Your Platform] -->|x-topograph-workspace-id: client-a| B[Topograph API]
A -->|x-topograph-workspace-id: client-b| B
A -->|no header = default| B
B --> C[Usage tracked per workspace]
C --> D[GET /v2/workspaces/usage]
D --> E[Rebill each client]
```
Use `POST /v2/workspaces` to create a workspace with a name and legal entity name.
Pass the workspace `name` on every API call: `x-topograph-workspace-id: acme-paris`. If omitted, requests go to the default workspace.
Call `GET /v2/workspaces/usage` to get a per-workspace breakdown of credits consumed, filterable by date range.
Use the usage report to generate invoices for each client based on their actual consumption.
***
## Managing Workspaces
Every account starts with a **default** workspace. You can create additional workspaces, one per client, department, or legal entity.
### Create a Workspace
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/workspaces" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "acme-paris",
"legalName": "Acme Paris SAS"
}'
```
```json Response theme={null}
{
"id": "253299d1-e8d0-4268-945b-f175f98bc114",
"name": "acme-paris",
"legalName": "Acme Paris SAS",
"isDefault": false,
"uboEnabled": true,
"createdAt": "2026-03-09T14:00:00.000Z",
"updatedAt": "2026-03-09T14:00:00.000Z"
}
```
**`name` is the identifier you use everywhere else.** It goes in the `x-topograph-workspace-id` header and in `/v2/workspaces/{name}` paths. The UUID `id` in the response is returned for your own reference only; no endpoint takes it.
Names must be **alphanumeric with hyphens, underscores and colons** only (`^[a-zA-Z0-9_:-]+$`), max 64 characters, and `default` is reserved. Colons are allowed so a namespaced tenant key like `tenant:` can be used verbatim; other characters (spaces, `/`, `@`, `.`) are rejected.
### List Workspaces
```bash theme={null}
curl "https://api.topograph.co/v2/workspaces" \
-H "x-api-key: YOUR_API_KEY"
```
### Update a Workspace
Update the legal name, or the [UBO data access](#ubo-data-access) setting, associated with a workspace:
```bash theme={null}
curl -X PATCH "https://api.topograph.co/v2/workspaces/acme-paris" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"legalName": "Acme Paris SAS (updated)"}'
```
### Delete a Workspace
```bash theme={null}
curl -X DELETE "https://api.topograph.co/v2/workspaces/acme-paris" \
-H "x-api-key: YOUR_API_KEY"
```
You cannot delete the **default** workspace, any workspace that has existing requests associated with it, or any workspace that holds saved company batches.
***
## UBO Data Access
Every workspace can request ultimate beneficial owner (UBO) data. This is **on by default**, and controlled through the `uboEnabled` field on the workspace.
```bash theme={null}
curl -X PATCH "https://api.topograph.co/v2/workspaces/acme-paris" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"uboEnabled": false}'
```
You can set `uboEnabled` on creation too, or turn it off for an existing workspace at any time. Requesting `ultimateBeneficialOwners` from a workspace with access turned off returns `datapoint_not_supported`.
Only keep UBO data access enabled for a workspace whose legal entity is AML-obliged. UBO data carries regulatory obligations under AML law, and Topograph may revoke a workspace's UBO access if the entity attached to it is not AML-obliged.
***
## Tagging Requests
Add the `x-topograph-workspace-id` header to any data retrieval or onboarding request. Despite the header's name, its value is the workspace **`name`**, not the UUID `id`:
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-topograph-workspace-id: acme-paris" \
-H "Content-Type: application/json" \
-d '{
"id": "443061841",
"countryCode": "FR",
"dataPoints": ["company", "legalRepresentatives"]
}'
```
The header takes the workspace **name**, not the UUID `id`. If it is **omitted**, the request is automatically tagged to the **default** workspace. If the name **doesn't exist**, the API returns a `404 Not Found`; if it contains characters outside `[a-zA-Z0-9_:-]`, a `400 Bad Request`.
The workspace tag is propagated to all billing events generated by the request, so every credit consumed is attributed to the correct workspace.
### Workspace in API Responses
The workspace is **returned in every API response** inside the `request` object:
```jsonc theme={null}
{
"request": {
"requestId": "abc-123",
"companyId": "443061841",
"countryCode": "FR",
"workspace": {
"name": "acme-paris",
"legalName": "Acme Paris SAS"
},
"dataStatus": { ... }
},
"company": { ... }
}
```
### Workspace in Webhooks
When you receive a [webhook](/guides/webhooks) notification for a completed request, the workspace is included in the payload:
```jsonc theme={null}
{
"request": {
"requestId": "abc-123",
"companyId": "443061841",
"countryCode": "FR"
},
"workspace": {
"name": "acme-paris",
"legalName": "Acme Paris SAS"
},
"company": { ... }
}
```
You can use the workspace info in webhook payloads to automatically route results to the correct client or trigger per-client processing pipelines.
***
## Usage Reporting
The usage report endpoint gives you a per-workspace breakdown of all credits consumed, exactly what you need to rebill your clients.
### Get Full Report
```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/usage" \
-H "x-api-key: YOUR_API_KEY"
```
```json Response theme={null}
[
{
"workspace": {
"name": "default",
"legalName": "Your Company Inc.",
"isDefault": true
},
"totalCreditsUsed": 42.5,
"totalRequests": 85,
"breakdown": [
{ "sku": "example-company-data", "count": 50, "totalCredits": 25.0 },
{ "sku": "example-document", "count": 35, "totalCredits": 17.5 }
]
},
{
"workspace": {
"name": "acme-paris",
"legalName": "Acme Paris SAS",
"isDefault": false
},
"totalCreditsUsed": 15.0,
"totalRequests": 30,
"breakdown": [
{ "sku": "example-company-data", "count": 30, "totalCredits": 15.0 }
]
}
]
```
### Filter by Date Range
```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/usage?startDate=2026-03-01&endDate=2026-04-01" \
-H "x-api-key: YOUR_API_KEY"
```
A date is read as midnight UTC at the start of that day, so `endDate` stops where the day you pass begins. To cover all of March, pass `endDate=2026-04-01`.
### Filter by Workspace
```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris" \
-H "x-api-key: YOUR_API_KEY"
```
### Combine Filters
```bash theme={null}
curl "https://api.topograph.co/v2/workspaces/usage?workspace=acme-paris&startDate=2026-03-01&endDate=2026-04-01" \
-H "x-api-key: YOUR_API_KEY"
```
***
## Register Credentials
A few registers only serve their data to the entity performing the check, or return more of it to accounts holding elevated roles. Germany's Transparenzregister and France's INPI both work this way. For those, you store your own register login in Topograph, and you store it **on a workspace**.
```bash theme={null}
curl -X PUT "https://api.topograph.co/v2/workspaces/acme-paris/vault/de_transparenzregister" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payload": {
"email": "compliance@acme.example",
"password": "YOUR_REGISTER_PASSWORD"
}
}'
```
A request tagged `x-topograph-workspace-id: acme-paris` then runs under that login. If the workspace has no credential of its own, it falls back to the one on the **default** workspace, so you can either give every client their own register account or share a single house account across all of them.
Credentials are encrypted on write and no endpoint ever returns them back. Data fetched under a workspace's login is cached against your account alone and is never served to another customer. The cache is shared across your own workspaces, so a company fetched under one workspace's login can be reused for another of your workspaces for up to 24 hours.
Supported registers, payload shapes, rotation, and what happens when no credential is configured
***
## Use Cases
You resell Topograph to your own clients. Create one workspace per client, tag all their requests, and pull monthly usage reports to generate invoices.
```
Workspace: client-alpha -> 120 credits -> client invoice
Workspace: client-beta -> 45 credits -> client invoice
Workspace: client-gamma -> 200 credits -> client invoice
```
Your company has multiple legal entities or branches. Each entity gets its own workspace with the correct legal name, so you can allocate costs internally.
```
Workspace: default -> HQ (Paris) -> 500 credits
Workspace: london-office -> London Ltd -> 200 credits
Workspace: berlin-office -> Berlin GmbH -> 150 credits
```
You build a platform where your users trigger Topograph requests. Tag each request with the user's workspace to track per-tenant consumption and enforce usage limits.
```python theme={null}
# In your platform backend
response = requests.post(
"https://api.topograph.co/v2/company",
headers={
"x-api-key": API_KEY,
"x-topograph-workspace-id": tenant.workspace_name,
},
json={"id": company_id, "countryCode": "FR", "dataPoints": ["company", "legalRepresentatives"]}
)
```
Set up a cron job to pull usage at the end of each month and generate invoices automatically.
```python theme={null}
import requests
from datetime import datetime, timedelta, timezone
now = datetime.now(timezone.utc)
# First day of current month
start = now.replace(day=1).strftime("%Y-%m-%d")
# endDate stops at midnight UTC, so pass tomorrow to include today
end = (now + timedelta(days=1)).strftime("%Y-%m-%d")
usage = requests.get(
f"https://api.topograph.co/v2/workspaces/usage?startDate={start}&endDate={end}",
headers={"x-api-key": API_KEY}
).json()
for report in usage:
ws = report["workspace"]
credits = report["totalCreditsUsed"]
print(f"Invoice {ws['legalName']}: {credits} credits")
```
***
## API Reference
| Endpoint | Method | Description |
| - | - | - |
| [`/v2/workspaces`](/api-reference/workspaces/list-all-workspaces) | GET | List all workspaces |
| [`/v2/workspaces`](/api-reference/workspaces/create-a-new-workspace) | POST | Create a workspace |
| [`/v2/workspaces/{name}`](/api-reference/workspaces/update-a-workspace) | PATCH | Update a workspace |
| [`/v2/workspaces/{name}`](/api-reference/workspaces/delete-a-workspace) | DELETE | Delete a workspace |
| [`/v2/workspaces/usage`](/api-reference/workspaces/get-usage-report-per-workspace) | GET | Get usage report |
| [`/v2/workspaces/{name}/vault`](/api-reference/vault/list-vault-entries-on-the-workspace-metadata-only) | GET | List the workspace's [register credentials](/essentials/register-credentials) |
| [`/v2/workspaces/{name}/vault/{sourceKey}`](/api-reference/vault/create-or-replace-a-credential) | PUT | Store or rotate a register credential |
The `x-topograph-workspace-id` header is supported on [/v2/company](/api-reference/data/get-company-data-and-documents) (all modes, including `mode: "prefill"`). The legacy `/v2/onboarding` route also accepts it.
# Batches
Source: https://docs.topograph.co/guides/batches
Upload a spreadsheet of companies, match each row to its register entry, fetch the data you need and export it
**Batches** is the spreadsheet path to Topograph. Instead of calling the API
for one company at a time, you upload a file with hundreds or thousands of
companies, let Topograph find each one in its national register, review the
matches that need a human decision, fetch the data points you need, and export
a single file with the results.
It lives in the product app, in the sidebar under **Batches**. Every lookup
and every data request it makes is an ordinary request: it appears in your
request history, is billed in credits like any other request, and can be
opened on its own page.
## What a batch does
Drop a CSV or XLSX file. Topograph reads the columns and proposes which one
holds the country, the identifier, the legal name and the address. You
confirm or correct the mapping once, and the file becomes a saved batch you
can come back to at any time.
Each row is searched in its country's register, by identifier when you
have one, otherwise by legal name. Rows that resolve unambiguously are
matched on their own. Rows that need a decision wait for you in a review
queue.
Pick the data points you need (company details, legal representatives,
other key persons, establishments, shareholders, subsidiaries, ultimate
beneficial owners) and the request mode. Topograph fetches them for every
matched row, ten at a time, and keeps going while you close the tab.
Download the whole batch, or the rows you selected, as CSV or XLSX. One
row per company you imported, in the order of your file, with your mapped
inputs, the match and the data.
## Importing a file
The file needs a header row and one company per row. Any column layout works.
Topograph looks at the headers and a sample of rows to suggest which columns
are:
* **Country**: an ISO code (`FR`, `DE`), a country name, or a US state code.
A column of US states can be read as `US-AK`, `US-CA` and so on with one
checkbox. If a row has no country, a fallback country can be applied to it.
* **Identifier**: the register number, SIREN, Companies House number, EIN or
whatever your file holds. Leading zeroes are preserved.
* **Legal name**.
* **Address**: either one combined column or separate street, city, postal
code and region columns. Addresses are optional, but they are what tells two
companies with the same name apart.
Every original cell is kept in the batch and shown when you edit a row. The
export does not repeat them: it uses the fixed layout described in
[Exporting](#exporting). Multi-sheet workbooks ask which sheet to import.
Limits per batch: 50,000 rows, 100 columns, 5 MB.
## How matching works
After a search, each row lands in one of these states:
| State | Meaning | What to do |
| - | - | - |
| **Exact** | Exactly one result carries the identifier you supplied, or exactly one result has the same legal name once capitalisation, punctuation and spacing are ignored. | Nothing. Exact matches are trusted. |
| **Suggested** | One result was selected by a weaker rule: a partial identifier, a name that differs only by its legal form or word spacing, or a name-and-address comparison that accepts abbreviations, legal-form equivalents and minor typos. | Confirm it in the review dialog, or trust every suggested match at once from the **Review** menu. |
| **Ambiguous** | Several results fit, or the evidence conflicts (a different identifier, city or postal code). | Pick the right candidate, or mark the row as no match. |
| **Unmatched** | The register returned nothing, or none of the results is this company. | Search another name in the same country, or enter the identifier by hand. |
| **Reviewed** | A decision you confirmed or trusted. | It stays until you edit the row's inputs or search it again. |
The table shows the state of every row with a badge. A green check means the
match was reviewed; an amber triangle means one field, such as the postal
code, disagrees with your input.
### Reviewing
**Review** opens the rows that need a decision one after the other. Each one
shows your row and the suggested company side by side, with the evidence as
plain sentences ("Legal name agrees once the legal form is added", "Postal
code differs: 72714 vs 72715", "Address not included in this register's search
results") and the reasoning behind the suggestion one click away.
From the dialog you can confirm, mark no match, skip, search another name in
the same country, or type an identifier by hand. Keyboard shortcuts cover the
whole pass: arrow keys to pick a candidate, `N` for no match, `⌘↵` to confirm,
`S` to skip, `/` to search.
Clicking a single row in the table reviews only that row.
On a file where the suggested matches look right, use **Review → Trust
suggested matches**. It marks every unreviewed suggestion as reviewed in one
go and leaves ambiguous and unmatched rows for you.
### Fixing a row
Any row can be edited: country, identifier, legal name, address. Saving new
inputs clears the row's match and any data fetched for it, so search the row
again afterwards. Searching a row that already has a reviewed match or fetched
data asks for confirmation first.
## Getting data
**Get company data** works on the rows in view: every matched row in the
current filter, or the rows you selected. The dialog shows how many rows will
be fetched, which of them already have data, the data points to fetch, the
request mode, and the price per company for each country in the batch, with
an upper bound for the whole run before you commit.
* **Verification** mode uses authoritative sources first. It is slower and is
the right choice for KYB files.
* **Prefill** mode uses the fastest available sources first. See
[Modes](/essentials/modes).
Rows that already have data are left alone unless you tick **Fetch again**.
Each fetched row shows how much of what exists was obtained ("4 of 4
available"). Three kinds of gap are expected and never count against a row:
a data point the country does not offer, a data point that does not exist for
the company's legal form (a foundation has no shareholders), and, in
prefill mode, a data point that has no fast source, which a verification
request would fill. Hover the figure to see which apply. A row with only
expected gaps is **Ready**. A request that delivered some data points but hit
a register error on another is marked **Partial**: the data is kept and the
points to retry are named. A request that produced no data is marked
**Failed** with the register's own reason, and can be retried from the row.
**View** opens the row's request page, where the company is laid out to read.
The raw saved response stays available from the row menu.
### Listing available documents
**List available documents** is ticked by default. It is free: it records
which documents each company has ready to order, and buys nothing.
### Statistics
Open **Statistics** to see the batch the way you would report on it:
* three headline figures: companies found, data retrieved, and companies for
which everything that exists was obtained;
* **Match and data by country**: the match rate, then, for each data point,
the share of companies for which it was obtained. Open a country to see the
same figures by legal form. Sole proprietors have no shareholders, so a
country that looks incomplete is often complete form by form;
* **Documents available by country**: the share of companies with at least
one trade register extract, articles of association, financial statements or
UBO extract ready to order.
Every rate is measured against what exists to be retrieved. Data a country
does not offer shows as "–", data that does not exist for a legal form as
"n/a", and neither enters a rate; a register error always does. Successful
empty lists count as obtained. Hover any figure for its full breakdown, and
use **Copy table** to paste a table into a spreadsheet.
These figures cover the whole batch, regardless of table filters or
selection. They use each row's latest saved result, so fetching a row again
does not count it twice.
## Following progress
The filter bar has two steps. **Match** shows To review, Matched and Unmatched;
**Data** shows Not fetched, Ready and, only when they exist, Partial and
Failed. A running run shows how many rows are in flight and how many are
queued, and **Activity** lists every run of the batch with the option to stop
the rows that have not started yet.
Runs continue on our side. You can close the page, come back later and pick
up where the batch is.
## Exporting
**Export** downloads the rows in view (or your selection) as CSV or XLSX. The
file has a fixed layout, one row per imported company, in the order of your
file. The columns come in this order:
* `schema_version`, `batch_id` and `source_row`;
* your input: `input_country`, `input_identifier`, `input_legal_name`;
* the match: `matched_country`, `matched_identifier`, `matched_legal_name`,
`match_type`, `search_status`;
* the data: `data_status`, `request_id`, `requested_datapoints`, and one JSON
column per data point (`company_json`, `legal_representatives_json`,
`other_key_persons_json`, `establishments_json`, `shareholders_json`,
`subsidiaries_json`, `ultimate_beneficial_owners_json`);
* `error_code` and `error_message` for rows that could not be completed, then
`completed_at`;
* the addresses and match evidence as JSON: `input_address_json`,
`matched_address_json`, `address_assessment_json` and
`match_assessment_json`.
Structured data is exported as JSON inside the cell, so a company with three
shareholders stays one row. Identifiers are written as text, so leading zeroes
survive a round trip through a spreadsheet. Export never triggers a new
request: it writes what the batch already holds.
## Good to know
* Batches belong to a [workspace](/essentials/workspaces). Requests made from
a batch use that workspace's register credentials and appear in its history.
* Ownership graphs and document orders are not part of batches yet. Open the
request behind any row to order documents for that company.
* In a [development environment](/guides/development-environment), batches
work end to end on generated data, so you can test an import without
spending credits.
# Billing Notifications
Source: https://docs.topograph.co/guides/billing-notifications
Email and webhook alerts for low balance, high usage, and auto top-up events
Topograph can notify you about three billing events:
1. **Low balance**: your prepaid credit balance crosses a configured threshold.
2. **High usage**: your spend in a rolling window reaches a configured threshold. High usage has two independent passes, described below.
3. **Auto top-up**: an automatic recharge succeeds or fails.
Each notification can go out as an email to your account admins and as a webhook event delivered through the same webhook endpoint setup as company data events. You can independently enable or disable each channel per notification kind.
All master toggles are **off by default on new accounts**. Nothing fires until an admin enables the specific kind they want from the Billing page. Channel sub-toggles (email / webhook) start at on, so flipping a master routes through both channels with a single click.
## How notifications fire
Notifications are evaluated after billable usage changes your balance or spend window. A notification is recorded once per threshold crossing, not once per request. The tier is rearmed when you refill or usage drops below the threshold and later crosses it again.
### Global vs per-workspace high usage
High usage runs two independent passes on every reserve. Both can fire in the same evaluation, and overriding one does not affect the other:
* **Global (account aggregate)**: sums billable usage across **every workspace** over the configured global period and checks it against your global tiers. Use this to alert on total account burn regardless of which workspace drove it.
* **Per-workspace**: sums billable usage for a single workspace over the configured workspace period and checks it against workspace tiers. Account-level workspace settings act as defaults; specific workspaces can override them.
Each pass has its own master toggle, channels, period, and tier list. High usage uses formal absolute thresholds. There is no multiplier or baseline comparison.
Auto top-up notifications fire when an automatic top-up succeeds or fails.
## Channels
Every notification kind has two channels, configured independently:
* **Email**: sent to account admins.
* **Webhook**: delivered through the same endpoints you already set up for `company.updated`.
You control each channel with a boolean. A notification is sent on a given channel when the kind's master switch and the channel switch are both on. Turning both channel switches off while leaving the master on keeps the event visible in recent notification history without dispatching email or webhook alerts.
## Webhook event types
All billing webhook payloads carry a `type` and `version: "1"`. Future schema changes will emit new event types rather than mutate v1.
### `billing.low_balance.triggered`
```json theme={null}
{
"type": "billing.low_balance.triggered",
"version": "1",
"accountId": "acc_...",
"tier": "warning",
"balanceCents": 4523,
"thresholdCents": 5000,
"autoTopupEnabled": true,
"firedAt": "2026-04-14T10:23:45.000Z"
}
```
The `tier` field is one of `warning`, `critical`, or `depleted`. You can configure multiple tiers via the REST API or dashboard.
### `billing.high_usage.triggered`
The high-usage event now carries a `scope` field that tells you which pass fired:
* `scope: "workspace"` with a set `workspaceId`: the per-workspace pass fired for that workspace.
* `scope: "global"` with `workspaceId: null`: the global aggregate pass fired for the whole account.
Per-workspace example:
```json theme={null}
{
"type": "billing.high_usage.triggered",
"version": "1",
"accountId": "acc_...",
"scope": "workspace",
"workspaceId": "ws_...",
"tier": "warning",
"periodMinutes": 60,
"periodSpendCents": 2300,
"thresholdCents": 2000,
"balanceCents": 87000,
"firedAt": "2026-04-14T10:23:45.000Z"
}
```
Global aggregate example:
```json theme={null}
{
"type": "billing.high_usage.triggered",
"version": "1",
"accountId": "acc_...",
"scope": "global",
"workspaceId": null,
"tier": "critical",
"periodMinutes": 60,
"periodSpendCents": 61000,
"thresholdCents": 50000,
"balanceCents": 200000,
"firedAt": "2026-04-14T10:23:45.000Z"
}
```
Each pass starts with a default warning tier. Add or edit tiers from the dashboard or via PATCH.
Workspace overrides only affect the per-workspace pass. Setting `highUsageEnabled: false` on a workspace override stops that workspace from firing its own per-workspace notifications but does not silence the global pass. If you want to silence the global pass too, turn off `globalHighUsageEnabled` at the account level.
### `billing.auto_topup.succeeded`
```json theme={null}
{
"type": "billing.auto_topup.succeeded",
"version": "1",
"accountId": "acc_...",
"amountCents": 10000,
"previousBalanceCents": 350,
"newBalanceCents": 10350,
"thresholdCents": 5000,
"paymentIntentId": "pi_...",
"invoiceUrl": "https://...",
"firedAt": "2026-04-14T10:23:45.000Z"
}
```
`invoiceUrl` links to the hosted invoice for the top-up. It is only present when an invoice link is available.
### `billing.auto_topup.failed`
```json theme={null}
{
"type": "billing.auto_topup.failed",
"version": "1",
"accountId": "acc_...",
"attemptedAmountCents": 10000,
"currentBalanceCents": 350,
"errorMessage": "card_declined",
"paymentIntentId": null,
"autoTopupDisabled": true,
"firedAt": "2026-04-14T10:23:45.000Z"
}
```
When an auto top-up attempt fails, auto top-up is disabled to prevent retry loops. You receive this event once and then need to update your payment method to re-enable it.
## Configuration API
All endpoints are under `/v2/billing/notifications` and require your standard `x-api-key` header.
### Read the resolved config
```http theme={null}
GET /v2/billing/notifications/config
```
Returns the fully merged config: your stored overrides layered on top of the defaults. You always receive a complete shape, even if you have not configured anything yet.
A brand-new account that has never touched the config sees every master at `false` and every channel at `true`. Each kind ships with a single `warning` tier so flipping the master on immediately fires on one sensible threshold. Add more tiers (`critical`, `depleted`, extra bands) via PATCH if you want finer granularity.
```json theme={null}
{
"lowBalanceEnabled": false,
"lowBalanceEmailEnabled": true,
"lowBalanceWebhookEnabled": true,
"lowBalanceTiers": [
{ "tier": "warning", "cents": 100000 }
],
"globalHighUsageEnabled": false,
"globalHighUsageEmailEnabled": true,
"globalHighUsageWebhookEnabled": true,
"globalHighUsagePeriodMinutes": 1440,
"globalHighUsageTiers": [
{ "tier": "warning", "cents": 100000 }
],
"highUsageEnabled": false,
"highUsageEmailEnabled": true,
"highUsageWebhookEnabled": true,
"highUsagePeriodMinutes": 1440,
"highUsageTiers": [
{ "tier": "warning", "cents": 100000 }
],
"autoTopupNotificationsEnabled": false,
"autoTopupEmailEnabled": true,
"autoTopupWebhookEnabled": true
}
```
### Update the config
```http theme={null}
PATCH /v2/billing/notifications/config
Content-Type: application/json
{
"lowBalanceTiers": [
{ "tier": "warning", "cents": 10000 },
{ "tier": "critical", "cents": 2000 },
{ "tier": "depleted", "cents": 0 }
],
"highUsagePeriodMinutes": 120,
"highUsageTiers": [
{ "tier": "critical", "cents": 50000 },
{ "tier": "warning", "cents": 10000 }
],
"lowBalanceEmailEnabled": false
}
```
All fields are optional. Any field you omit keeps its persisted value. You can send just `{"lowBalanceEmailEnabled": false}` to turn off low-balance emails without touching anything else.
### List recent notification events
```http theme={null}
GET /v2/billing/notifications/recent?limit=50
```
Returns the most recent billing notification events for your account, ordered newest first. Each row includes the kind, identifier, original payload, and delivery flags for email and webhook channels.
### Workspace overrides
If you use workspaces, you can override the high-usage rules for a specific workspace. Low-balance and auto-topup stay at the account level.
```http theme={null}
GET /v2/billing/notifications/workspaces/{workspaceId}/config
PATCH /v2/billing/notifications/workspaces/{workspaceId}/config
DELETE /v2/billing/notifications/workspaces/{workspaceId}/config
```
`GET` returns both the resolved account config and the raw workspace override row, so you can see which fields are overridden and which are inherited. `PATCH` upserts an override; any null field falls back to the account config at evaluation time. `DELETE` removes the override row (the workspace then inherits everything).
Example: give workspace `ws_batch` a much higher high-usage floor so nightly backfills don't page you, while keeping everything else at the account defaults:
```http theme={null}
PATCH /v2/billing/notifications/workspaces/ws_batch/config
Content-Type: application/json
{
"highUsageTiers": [
{ "tier": "critical", "cents": 500000 },
{ "tier": "warning", "cents": 100000 }
]
}
```
## Verifying webhooks
Billing webhooks use the same webhook endpoint setup as your `company.updated` webhooks. The signature verification flow is identical:
Verify billing webhook signatures the same way you verify company data webhook signatures, then branch on the `type` field in the payload.
See the [Webhooks guide](/guides/webhooks) for the full verification walkthrough and retry semantics.
## Idempotency
Every billing notification is deduplicated at evaluation time. If the same threshold crossing is evaluated more than once, only one customer-visible notification is recorded.
Each high-usage tier sends at most one notification per configured rolling period. A tier with a 24-hour period waits at least 24 hours after its last alert before it can notify again, even if spend repeatedly crosses the threshold or a new calendar day starts. This limit applies independently to global alerts and each workspace's alerts. A higher tier can still notify during a lower tier's waiting period.
## Rearm semantics
Threshold notifications fire once when you cross a tier, then disarm. They rearm when the condition has clearly reversed:
* Low balance: when the balance recovers above the tier threshold.
* High usage: when the rolling spend falls below the tier threshold. Another alert also requires the waiting period since the previous alert to have elapsed.
This means a single balance drop will not spam you with repeated `depleted` notifications, but a refill followed by another drop can send a fresh notification.
Auto-topup notifications are event-based, not threshold-based. Each attempt is evaluated independently.
# Company Status
Source: https://docs.topograph.co/guides/company-status
How Topograph models company status across jurisdictions, from binary active/ceased to insolvency proceedings, closure reasons, and dates
## Overview
Every company in every registry has some notion of status. But registries express it very differently:
* Germany's Handelsregister records dozens of granular event codes
* Belgium's KBO has nearly 40 juridical situation codes
* Cyprus simply says "Active" or "Dissolved"
Topograph normalises all of these into a **three-layer model** so you can write one piece of logic that works across all supported countries.
```json theme={null}
"status": {
"localName": "Ouverture de faillite",
"active": false,
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"closureReason": "BANKRUPTCY",
"insolvencyStartDate": "2024-03-15"
}
}
```
***
## The Three Layers
### Layer 1: `active` (boolean)
The simplest signal. `true` means the company is legally operating; `false` means it is not. This is derived deterministically from the register. It can be omitted when the register's status cannot be classified (`statusDetails.status` is then `UNKNOWN`), so test for `active === false` rather than a falsy value.
Use this for quick filtering: *"show me only active companies"*.
### Layer 2: `localName` (string)
The raw status label from the source registry, in its original language. Examples:
| Country | Example `localName` |
| - | - |
| Belgium | `Ouverture de faillite` |
| Germany | `Konkurs` |
| Sweden | `Likvidation` |
| France | `En liquidation judiciaire` |
| Poland | `W upadłości` |
This is useful when you need to display the exact registry wording to your users.
### Layer 3: `statusDetails` (object)
The standardised, cross-country representation. Always use this layer for logic that needs to work across countries.
| Field | Type | Description |
| - | - | - |
| `status` | `CompanyStatus` | Standardised status enum (see below) |
| `closureReason` | `CompanyClosureReason` | Why the company closed, when applicable |
| `closureDate` | `string` (ISO date) | When the company was formally closed |
| `insolvencyStartDate` | `string` (ISO date) | When insolvency proceedings started |
| `additionalInfo` | `string` | Free-text context from the registry |
`statusDetails` is populated for all countries where the registry provides
sufficient data. For countries with very limited registry data (e.g. some
offshore jurisdictions), only `active` and `localName` may be present.
***
## `CompanyStatus` Values
### `ACTIVE`
The company is registered and operating. No special proceedings are in effect.
```json theme={null}
"statusDetails": {
"status": "ACTIVE"
}
```
### `UNDER_INSOLVENCY_PROCEEDING`
An insolvency or restructuring proceeding has been **opened but not yet concluded**. The company still legally exists; it has not yet been struck off the register. This covers:
* Bankruptcy proceedings opened (company is technically still alive while the liquidator works)
* Judicial reorganisation / restructuring (court-supervised debt restructuring)
* Payment suspension proceedings
The key distinction from `CLOSED`: the company has not yet been **deregistered**. It still appears on the register, but its legal situation is exceptional.
```json theme={null}
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"closureReason": "BANKRUPTCY",
"insolvencyStartDate": "2024-03-15"
}
```
Use `insolvencyStartDate` to assess how long the proceeding has been ongoing.
Proceedings that have been open for several years without closure may indicate
a complex or contested case.
### `INACTIVE_NOT_CLOSED`
The company still exists on the register but is **not currently operating**, and it has not been permanently closed. It could become active again. This covers:
* Dormant or non-trading companies
* Suspended or administratively inactive companies that can be reinstated (for example, after filing overdue accounts)
* Companies that are registered but not yet trading, or whose registration is still pending
`active` is usually `false`. The register's own wording stays in `localName`, and `additionalInfo` may add context.
```json theme={null}
"statusDetails": {
"status": "INACTIVE_NOT_CLOSED",
"additionalInfo": "Company registration is suspended"
}
```
### `PENDING_DISSOLUTION`
The company is still registered, but the register records a **process to remove it** that has not yet completed, such as a proposal to strike it off or a liquidation that is under way. The register usually still reports the company as active, so `active` is usually `true`. The status becomes `CLOSED` once the removal completes.
```json theme={null}
"statusDetails": {
"status": "PENDING_DISSOLUTION",
"additionalInfo": "Active proposal to strike off (pending dissolution)"
}
```
### `CLOSED`
The company has been **deregistered** from the registry. It no longer exists as a legal entity. Use `closureReason` and `closureDate` to understand how and when it ended.
```json theme={null}
"statusDetails": {
"status": "CLOSED",
"closureReason": "VOLUNTARY_DISSOLUTION",
"closureDate": "2023-11-01"
}
```
### `UNKNOWN`
The registry provides a status that cannot be mapped to any of the above (e.g. a cancelled registration file, data quality issues). Treat with caution. `active` may be absent in this case.
***
## `CompanyClosureReason` Values
Only present when `status` is `CLOSED` or `UNDER_INSOLVENCY_PROCEEDING`.
| Value | When used |
| - | - |
| `BANKRUPTCY` | Company went bankrupt. Covers both open proceedings and concluded cases. |
| `LIQUIDATION` | Liquidation process completed and company was struck off. |
| `VOLUNTARY_DISSOLUTION` | Shareholders or owners chose to wind down the company voluntarily. |
| `ADMINISTRATIVE_DISSOLUTION` | Registry or authorities dissolved the company (e.g. failure to file, struck off by law). |
| `COURT_ORDER` | A court ordered the dissolution (e.g. judicial dissolution for nullity, illegal activity). |
| `MERGER` | Company was absorbed into or merged with another entity. The surviving entity continues. |
| `SPLIT` | Company divided into two or more entities. The original company ceases to exist; new entities carry on. |
| `ACQUISITION` | Company was acquired and deregistered as a separate entity. |
| `OTHER` | Registry confirmed the company is closed but the reason doesn't fit any above category. |
| `UNKNOWN` | Company is closed but the reason is not available or cannot be mapped. |
### Merger vs Split
These two are often confused:
| | `MERGER` | `SPLIT` |
| - | - | - |
| Direction | Many → One | One → Many |
| What happens | Two or more companies combine | One company divides into two or more |
| Original company | Ceases to exist (absorbed) | Ceases to exist (divided) |
| Result | One surviving entity | Two or more new or existing entities |
Example:
* **Merger**: Company A + Company B → Company C (A and B are `CLOSED + MERGER`)
* **Split**: Company A → Company B + Company C (A is `CLOSED + SPLIT`, B and C are new)
***
## Example API Responses
### Active company (normal)
```json theme={null}
"status": {
"localName": "Aktiv",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
}
```
### Active company under judicial reorganisation (Belgium)
The company is legally still active (no deregistration), but a restructuring proceeding is open.
```json theme={null}
"status": {
"localName": "Sursis (réorganisation)",
"active": true,
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"insolvencyStartDate": "2024-06-01"
}
}
```
### Bankrupt company with ongoing proceedings
```json theme={null}
"status": {
"localName": "Ouverture de faillite",
"active": false,
"statusDetails": {
"status": "UNDER_INSOLVENCY_PROCEEDING",
"closureReason": "BANKRUPTCY",
"insolvencyStartDate": "2023-11-15"
}
}
```
### Company closed by voluntary dissolution
```json theme={null}
"status": {
"localName": "Dissolution anticipée",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "VOLUNTARY_DISSOLUTION",
"closureDate": "2022-04-30"
}
}
```
### Company closed after merger
```json theme={null}
"status": {
"localName": "Fusion par absorption",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "MERGER",
"closureDate": "2021-09-01"
}
}
```
### Company split into two entities
```json theme={null}
"status": {
"localName": "Scission",
"active": false,
"statusDetails": {
"status": "CLOSED",
"closureReason": "SPLIT",
"closureDate": "2023-07-15"
}
}
```
***
## Recommended Patterns
### Filter for companies you can still do business with
```javascript theme={null}
const isOperational = company.status.active === true;
```
### Detect companies in financial distress
```javascript theme={null}
const inDistress =
company.status.statusDetails?.status === 'UNDER_INSOLVENCY_PROCEEDING';
```
### Understand why a company closed
```javascript theme={null}
const { status, closureReason, closureDate } =
company.status.statusDetails ?? {};
if (status === 'CLOSED') {
switch (closureReason) {
case 'BANKRUPTCY':
// Flag for credit risk review
break;
case 'MERGER':
case 'SPLIT':
// Look up the successor entity
break;
case 'VOLUNTARY_DISSOLUTION':
// Owner choice, low risk signal
break;
}
}
```
### Show status in a UI component
```javascript theme={null}
function statusBadge(company) {
const { active, statusDetails, localName } = company.status;
if (statusDetails?.status === 'UNDER_INSOLVENCY_PROCEEDING') {
return { label: 'Insolvent', color: 'orange' };
}
if (statusDetails?.status === 'PENDING_DISSOLUTION') {
return { label: 'Pending dissolution', color: 'orange' };
}
if (statusDetails?.status === 'INACTIVE_NOT_CLOSED') {
return { label: localName, color: 'grey' };
}
if (active === false) {
return { label: localName, color: 'red' };
}
if (active === undefined) {
return { label: localName, color: 'grey' };
}
return { label: 'Active', color: 'green' };
}
```
***
## Migration from `statusDetailsBeta`
As of Week 9, 2026, `statusDetailsBeta` has been renamed to `statusDetails`. The field name is the only change; all values, types, and semantics are identical.
```diff theme={null}
- company.status.statusDetailsBeta?.status
+ company.status.statusDetails?.status
```
# Concurrency & Backfills
Source: https://docs.topograph.co/guides/concurrency-and-backfills
Manage parallel company requests and leave capacity for your live operations
Your account has a shared limit on company requests being processed at the same time. The default is **40 in-flight slots**. Contact support if you need a higher limit for a backfill or sustained traffic.
## What counts toward the limit
A standard company request uses one slot while processing. An ownership graph request uses five slots. Requests from your account share the same capacity, including prefill and verification requests.
An HTTP response does not necessarily free a slot: a company request can return with data still `in_progress`. Track outstanding work using [webhooks](/guides/webhooks) or retrieve the existing request's status. Completed requests release capacity. Work paused while waiting for external action does not hold capacity during that wait.
Development-mode requests do not consume these slots. Search and polling existing results do not start company retrievals and do not consume additional slots. API rate limits apply separately.
## Read your available capacity
Company request responses expose these headers when concurrency usage can be evaluated:
| Header | Meaning |
| - | - |
| `X-Concurrency-Limit` | Your account's current slot limit |
| `X-Concurrency-Remaining` | Available slots at the time of the check, before the new request is counted |
These values are a snapshot, not reserved capacity. Other requests can consume slots before your next call. Keep a local limit on outstanding work even when these headers are absent.
Concurrency is separate from requests per minute. The `X-RateLimit-*` headers describe the latter; raising your concurrency limit does not raise your per-minute limit.
## Handle a concurrency rejection
When your account is at capacity, a new company request receives HTTP `429` before processing starts. The response includes `Retry-After` in seconds and a body like this:
```json theme={null}
{
"statusCode": 429,
"code": "too_many_requests",
"limit": "concurrency",
"limitValue": 40,
"active": 40,
"retryAfter": 12,
"message": "Concurrency limit reached: your account is using 40 of 40 in-flight request slots. Wait for requests to complete and retry with backoff, or contact support to raise your limit."
}
```
Wait at least the `Retry-After` duration before retrying. Add a small random delay so queued requests do not all retry together. If the next attempt is also rejected, continue backing off. Use `limit: "concurrency"` to identify a concurrency rejection; HTTP `429` can also indicate a per-minute rate limit.
## Run a backfill alongside live traffic
1. Use a queue with a fixed cap on outstanding work. Sending a batch every ten minutes does not control concurrency if earlier batches are still processing.
2. Reserve capacity for normal operations. For example, with an 80-slot account limit, cap a backfill of standard company requests at 20 outstanding requests to leave headroom for live traffic.
3. Count graph requests as five slots when setting your backfill budget.
4. Wait for requests to finish before taking more work from the queue. Receiving the initial HTTP response is not enough.
5. Increase volume gradually while watching completion times and `429` responses.
For a planned backfill, share expected volumes by country and your schedule with support. Agree when to review any temporary limit increase after the backfill finishes.
# Development Environment
Source: https://docs.topograph.co/guides/development-environment
Build your integration against every country, with generated data and no charges
A **development environment** is a sandbox alongside your live account. It
answers for every country Topograph supports, returns generated data instead of
register data, and never costs real money.
It is a full environment, not a flag: its own API key, its own webhook
endpoint, its own workspaces, its own request history, and its own
**membership**. Each environment is a separate organisation with its own
member list and roles, so you can give a contractor admin access to a sandbox
without giving them anything on live. A new environment starts with no
members and is used through its API key. Invite people to its organisation,
yourself included, when they need it in the app.
It is also **physically isolated**: development environments run on their own
deployment (`sandbox.topograph.co` for the app, `api.sandbox.topograph.co`
for the API) with their own database. Nothing you do in a sandbox can touch a
live record, a real register, or a real invoice, structurally rather than by
configuration. And you do not need a production account to have one: sign up
on the sandbox, create an organisation, and you have a working environment.
Use it to build and test. Switch to your live key when you want real data.
Development environments keep working when your trial ends, when your
subscription lapses, and when your balance is empty. They cost nothing to
run, so we never close them.
## Creating one
In the product app, go to **Developer → Environments** and click **New
environment**. You get a key immediately:
```
sk_dev_kR3nQ8vYpL2mXwF7dTgHjB4c
```
Or over the sandbox API, with the key of your **default sandbox** (the
environment your main organisation gets automatically):
```bash theme={null}
curl -X POST https://api.sandbox.topograph.co/v2/environments \
-H "Content-Type: application/json" \
-H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY" \
-d '{"name": "dev-hugo"}'
```
Create as many as you need: a shared sandbox, a staging mirror, one per
developer, or one per CI run created and discarded around the job. They cost
nothing to run, so we do not cap them.
Only the key of your **default sandbox** (or an organisation admin in the
app) can create environments or list all of them. The key of an environment
created under it can only see and manage that one environment (its settings,
its key, its deletion), so a sandbox key that leaks cannot expose any other.
The live API does not manage environments: they live on the sandbox
deployment.
## Using one
Swap the key **and the base URL**: development keys are served by
`https://api.sandbox.topograph.co`, a separate deployment with its own database
and no access to any register. Everything else is identical: same endpoints, same request bodies, same
response shapes.
```bash theme={null}
curl -X POST https://api.sandbox.topograph.co/v2/company \
-H "Content-Type: application/json" \
-H "x-api-key: sk_dev_YOUR_KEY" \
-d '{"countryCode": "FR", "id": "552100554", "dataPoints": ["company", "legalRepresentatives"]}'
```
The key alone decides which environment serves the request. There is no header
to set and no flag to forget: a `sk_dev_` key can only ever reach generated
data, and a `sk_live_` key can only ever reach real data.
## What you get back
Data is generated from the country's own definitions, so it has the right
shape for the country you asked for:
* **Identifiers** in the country's real format, under the country's real keys: a French company carries a SIREN, a German one its register court, type and number. The company `id` is the one production returns (`München HRB 228960` in Germany, `krs-0000028860` in Poland), and each company has its own VAT number and EUID.
* **Legal forms** drawn from the values that country's register actually
publishes. Never a retired one.
* **Roles** from the country's own role dictionary.
* **Activity codes** in the systems that country uses.
* **Documents** exactly as the country declares them, with their real product
codes.
It is also **deterministic**: the same country and identifier always return the
same company, byte for byte. You can assert on the values in your test suite
and they will still hold next month.
Every generated field is marked with the source `generated` and the register
`topograph_development_environment`. If you ever wonder whether a payload
came from a sandbox, that is the tell.
Development traffic is stored separately from live traffic, so it never
appears in your live request history, your usage figures or your invoices.
Ordered documents come back as **real PDFs**, laid out like a register
extract and filled with the same generated company the datapoints return for
that identifier: name, people and address all agree. Every page says it is a
sandbox artefact.
## Companies you define
Generated data covers every country and every identifier, which is what makes
the sandbox broad. It is the wrong tool when you need a *specific* company: to
reproduce a bug a customer reported, to build a demo or a screenshot, or to
assert on your own matching logic. So define one:
```bash theme={null}
curl -X POST https://api.sandbox.topograph.co/v2/sandbox/companies \
-H "x-api-key: sk_dev_YOUR_KEY" -H "Content-Type: application/json" \
-d '{
"countryCode": "FR",
"company": {
"legalName": "Acme Trading SAS",
"status": { "localName": "Radiée", "active": false }
}
}'
```
The response carries the `identifier` to request it by, minted in that
country's own format:
```json theme={null}
{ "countryCode": "FR", "identifier": "418166096", "company": { … } }
```
From then on `/v2/company` with that identifier returns your company, and
`/v2/search` finds it by name or identifier alongside generated results.
**Send only what you care about.** A fixture is merged over generated data, so
pinning one field costs one field: everything you leave out (address, legal
form, incorporation date, activities) is still generated, and the record stays
complete and country-correct.
### Making a company change
`PATCH` it, and the next request returns the new version. That is what a
monitoring integration needs: a company that genuinely changes between two
fetches, rather than a synthetic event.
```bash theme={null}
curl -X PATCH https://api.sandbox.topograph.co/v2/sandbox/companies/FR/418166096 \
-H "x-api-key: sk_dev_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"company": {"legalAddress": {"city": "Lyon"}}}'
```
`GET /v2/sandbox/companies` lists what you have defined;
`DELETE /v2/sandbox/companies/{countryCode}/{identifier}` gives the identifier
back to generated data. If you pin an identifier yourself, it is stored in the
country's canonical form and validated exactly as `/v2/company` validates it,
so a fixture can never sit under an identifier the API would refuse.
## Starting from a clean slate
A CI run wants a known state. `POST /v2/sandbox/reset` clears this
environment's request history, search logs and webhook logs, and restores the
virtual wallet:
```bash theme={null}
curl -X POST https://api.sandbox.topograph.co/v2/sandbox/reset \
-H "x-api-key: sk_dev_YOUR_KEY"
```
The environment itself is untouched: same API key, same webhook endpoints, same
settings, so a job can reset between runs without re-provisioning anything.
Pass `{"keepWallet": true}` when a suite deliberately set a low balance to test
depletion and only wants the history cleared. A reset is refused with `409`
while a request is still in progress (a `DELAY_1H` sleep, say): let it finish
or cancel it first.
## Coverage is honest
A development environment will not invent data a country cannot deliver. Ask
for a datapoint a country does not support and you get the same error you would
get in production:
```bash theme={null}
# Country has no beneficial-ownership source → same error as live
curl -X POST https://api.sandbox.topograph.co/v2/company \
-H "x-api-key: sk_dev_YOUR_KEY" \
-d '{"countryCode": "XX", "id": "123", "dataPoints": ["ultimateBeneficialOwners"]}'
```
That is deliberate. A sandbox that answered everything would let you ship an
integration that breaks the first time it runs for real.
The **ownership graph** (`graph`) is not served in a development environment.
Traversal fans out across real registers, so rather than half-serve it we
decline it. Everything else (search, all company datapoints, documents,
webhooks) is available.
## Test identifiers
Magic identifiers work in **every** country here, so you can exercise your
error handling against country-correct data. If you are coming from the
[TEST country](/guides/test-country): its error identifiers, `DELAY_*` tokens
and `GRAPH_SIMPLE`, `GRAPH_CHAIN` and `GRAPH_UBO` work here too, and
`GRAPH_EMPTY` is `GRAPH_NONE`. `GRAPH_CIRCULAR`, `GRAPH_WIDE`, `GRAPH_MIXED`
and `GRAPH_DEEP` exist only in `TEST`; here they return the simple structure.
### Errors
**Every error code the live API can return has an identifier**: the code in
upper case. Whatever branch your error handling has, you can reach it:
| Identifier | Result |
| - | - |
| `RESOURCE_NOT_FOUND` | `resource_not_found` (404) |
| `INVALID_REQUEST` | `invalid_request` (400) |
| `PROCESSING_FAILED` | `processing_failed` (422) |
| `SERVICE_UNAVAILABLE` | `service_unavailable` (503) |
| `SOURCE_UNAVAILABLE` | The register behind the datapoint is down |
| `INSUFFICIENT_FUNDS` | The refusal a depleted wallet produces |
| `BALANCE_NEGATIVE` | The refusal a wallet below zero produces |
| `ONBOARDING_TIMEOUT` | Fast source missed the prefill deadline |
| `NO_DATA_AVAILABLE` | Sources answered but held no data |
| `NO_DOCUMENT_AVAILABLE` | The register has no such document on file |
| `DATAPOINT_NOT_SUPPORTED` | The country does not offer this datapoint |
| `DATAPOINT_NOT_APPLICABLE` | Datapoint does not exist for this legal form |
| `FAST_SOURCE_UNAVAILABLE` | No fast source for the datapoint in prefill mode |
| `AUTHORITATIVE_SOURCE_UNAVAILABLE` | No authoritative source for the datapoint in verification mode |
| `MANUAL_DOCUMENT_TIMEOUT` | The document could not be obtained within the expected timeframe |
| `ACCOUNT_CONFIGURATION_REQUIRED` | The account needs configuration first, such as register credentials |
| `BUDGET_EXCEEDED` | The request hit its configured budget ceiling |
| `REQUEST_CANCELLED` | The request was cancelled mid-flight |
| `PROCESSING_INTERRUPTED` | Processing was interrupted before completion |
| `PARTIAL_FAIL` | Data delivered even though one source failed. The public status stays `succeeded` (source-level imperfection is never surfaced), so this checks your handler treats a delivered response the same either way |
Messages, HTTP statuses and retryability come from the same registry the live
API uses, so what you handle here is exactly what you will handle there.
`RATE_LIMITED` is the one exception, and it is worth knowing why: rate limiting
happens before a request reaches the data pipeline, so it is not a data error
at all. Use it as the identifier (or the search query) with your `sk_dev_` key
and you get a genuine `429` with `Retry-After` and the `X-RateLimit-*` headers,
produced by the same guard that throttles real traffic, which is what your
retry and backoff code needs to see.
### Delivery delays
| Identifier | Delivered after |
| - | - |
| `DELAY_1M` | 1 minute |
| `DELAY_10M` | 10 minutes |
| `DELAY_1H` | 1 hour |
| `DELAY_10H` | 10 hours |
### Company status
Generated companies are active. These pin the branch a KYB flow exists to
handle, the decline:
| Identifier | Company returned |
| - | - |
| `DISSOLVED` | `status.active: false`, standardized status `CLOSED` |
| `INACTIVE` | On the register but not operating (`INACTIVE_NOT_CLOSED`) |
### Data shapes that break integrations
Generated companies are complete, mid-length and Latin-alphabet. Real registers
are not, and that gap is where integrations fail in production. These pin the
shapes worth testing against:
| Identifier | What comes back |
| - | - |
| `SPARSE` | Valid but minimal: every optional field absent (no address, legal form, capital, activities). The thin record your code must not assume away |
| `UNICODE` | Accented, Cyrillic, CJK and RTL names, people and cities, for encoding, collation, and column rendering |
| `LONG_NAMES` | A 300-character legal name, past what most UI columns and a few `varchar(255)` schemas survive |
| `MANY_RESULTS` | Search fills the whole page, for pagination and "too many matches, refine your query" |
### Search results and match reasons
A sandbox search returns a **realistic result set**, not a single row: the
query itself first, then plausible neighbours carrying identifiers in that
country's own format. Every row resolves: follow any of them into
`/v2/company` and you get the company the row promised.
Match reasons are inferred the way live infers them: an identifier resolves
`id` (1:1, with the matched identifier attached), a name matches
`exactLegalName`, near-misses come back as `partialId`, the rest `default`;
and results arrive ranked `id` > `exactLegalName` > `partialId` > `default`.
To drive one branch of your resolution logic directly, pin it:
| Query | Result set |
| - | - |
| `MATCH_ID` | First result reports an `id` (1:1) match |
| `MATCH_EXACT` | First result reports `exactLegalName` |
| `MATCH_PARTIAL` | First result reports `partialId` |
| `MATCH_DEFAULT` | First result reports `default` |
| `SINGLE_RESULT` | Exactly one result, the auto-select branch |
| `NO_RESULTS` | Empty set, the "nothing found, offer manual entry" branch |
### Ownership structures
| Identifier prefix | Structure |
| - | - |
| `GRAPH_SIMPLE` | Individual shareholders |
| `GRAPH_CHAIN` | A corporate shareholder, with an individual behind it |
| `GRAPH_UBO` | A single beneficial owner with majority control |
| `GRAPH_NONE` | No shareholders and no beneficial owners on file |
All of these accept a suffix, so you can keep several in-flight requests apart
in your own logs: `RESOURCE_NOT_FOUND-042`, `DELAY_1H_A`, `GRAPH_CHAIN_007`.
They also compose where it makes sense: `RESOURCE_NOT_FOUND_DELAY_1M` fails
after a minute, which is the case your timeout-plus-error handling needs.
Test identifiers are deliberately not any country's identifier format, so a development environment accepts them where live would reject the shape.
An ordinary malformed identifier is still rejected in the sandbox exactly as in production, so you cannot ship code that sends ids production refuses.
A bare German register number such as `228960`, for one, fails every datapoint with `invalid_request` in both. Pass the `id` search returns.
### Global search
[Global search](/guides/global-search) answers from generated data too. It reads the legal form in the name and returns candidates in the countries that use it, each one resolvable with `/v2/company` in the same environment. A name that only points at countries Topograph does not cover ends `not_found` with `country_not_covered`, and an input like "Undisclosed shareholders" is rejected as `not_a_legal_entity`, exactly as in production.
## Response times
By default a development environment answers **instantly**, which is what a CI
suite wants. Use a `DELAY_*` identifier when you need to exercise polling,
timeouts or a loading state.
You can also switch on **Simulate real response times** for an environment.
Each datapoint then waits around that country's published latency for it,
with a little natural variation from request to request, and with **different
datapoints landing at different moments**, exactly as a real request streams
in. If your integration blocks on the whole response instead of consuming the
stream, this is the setting that will show you.
For tests that assert on timing, set a **fixed response time** instead: every
answer then takes exactly that many milliseconds, no jitter. The `DELAY_*`
identifiers keep working in every mode.
Both are settable in the app, and over the sandbox API with your default
sandbox key, so a CI job can configure the environment it is about to use:
```bash theme={null}
# realistic, jittered timings
curl -X POST https://api.sandbox.topograph.co/v2/environments/ci/settings \
-H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY" -H "Content-Type: application/json" \
-d '{"simulateLatency": true}'
# or an exact 2.5s for every answer
curl -X POST https://api.sandbox.topograph.co/v2/environments/ci/settings \
-H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY" -H "Content-Type: application/json" \
-d '{"fixedLatencyMs": 2500}'
# back to instant
curl -X POST https://api.sandbox.topograph.co/v2/environments/ci/settings \
-H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY" -H "Content-Type: application/json" \
-d '{"fixedLatencyMs": null, "simulateLatency": false}'
```
## Webhooks
Each environment has its own webhook application, its own endpoints **and its
own signing secret**, configured independently of live. Point development
deliveries at a tunnel on your laptop and your live endpoint never sees them;
the two streams cannot interleave, because they are different applications.
To configure one: switch to the environment in the app, open **Webhooks**, and
the portal you see belongs to that environment (the page names which one you
are editing). Add your endpoint and copy its signing secret from there.
Two extra affordances for development deliveries:
* Every development request webhook carries `"environment": "development"` at
the top level, so a handler receiving both streams at one URL can tell
generated data from real without comparing signing secrets. Monitoring
events triggered on demand (below) are identical to production payloads and
carry no such marker.
* The `DELAY_*` identifiers exercise the full async path: create a request
with `DELAY_1M` and your endpoint receives the completion webhook a real
minute later, exactly as a slow register would deliver it.
### Monitoring events on demand
Monitoring is the one part of the product you cannot rehearse while building:
a real `monitor.notification` arrives when a register changes, on the daily
check's schedule, days of waiting for an event that may never come. A
development environment lets you deliver the genuine event now.
Create the monitor first, exactly as you would in production
(`POST /v2/monitors`), then trigger an event for it:
```bash theme={null}
curl -X POST https://api.sandbox.topograph.co/v2/sandbox/monitor-webhook \
-H "x-api-key: sk_dev_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"monitorId": "YOUR_MONITOR_ID", "changeCategories": ["status", "address"]}'
```
The response is the exact payload delivered to your endpoint. It carries your
own monitor id and the metadata you set at monitor creation, built by the same
code the daily monitoring workflow uses, indistinguishable from a real
notification.
| Body | Event delivered |
| - | - |
| `{"monitorId": "…"}` | `monitor.notification`, category `other` |
| `{"monitorId": "…", "changeCategories": ["status","ownership"]}` | `monitor.notification` with those categories |
| `{"monitorId": "…", "changeCategories": ["disappeared"], "monitorHasBeenDeactivated": true}` | the company-disappeared case |
| `{"monitorId": "…", "event": "monitor.datapoint_blocked", "datapoint": "ultimateBeneficialOwners"}` | credential gate closes |
| `{"monitorId": "…", "event": "monitor.datapoint_unblocked", "datapoint": "ultimateBeneficialOwners"}` | credential gate reopens |
The monitor itself is never modified: no change is recorded, nothing is
deactivated, and the next scheduled check is unaffected. Live accounts get a
`403` here: a production notification means a register really changed.
Everything else that is configured per account works the same way: workspaces,
API key rotation, request history. A development environment has its own.
## Billing that behaves like the real thing
A development environment has its own wallet, funded with **virtual credits**.
Every request bills the **real catalog price** against it, so the balance
depletes exactly as a live wallet would: you see genuine prices on every
event, and your integration exercises real billing behaviour.
The difference is that the credits cost nothing and the wallet refills itself:
whenever a request would leave it below **10,000 credits**, it tops back up to
**20,000** automatically. It can never run dry, never blocks a test suite, and
never touches a card.
To test what happens when a wallet DOES run dry, take control of it:
```bash theme={null}
curl -X PUT https://api.sandbox.topograph.co/v2/sandbox/wallet \
-H "x-api-key: sk_dev_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"balanceInCreditCents": 120, "autoRefill": false}'
```
With the auto-refill off, requests deplete the balance for real and the one
that no longer fits fails with a genuine `insufficient_funds`, the same
refusal, from the same billing path, your live integration would see. Set any
balance and `"autoRefill": true` to go back to normal. (`GET` on the same
route reads the current state; the `INSUFFICIENT_FUNDS` identifier is the
quicker option when you only need the error branch.)
**Usage → Development environments** shows what each sandbox has spent. Because
the prices are real, that figure is also your live-bill estimate: run the
integration end to end here and read off what production will cost.
## Creating and discarding programmatically
Create an environment from **Developer** in the app (from the live app it is
created on the sandbox deployment and you are taken straight to it), or over
the sandbox API with the key of your **default sandbox** (the environment your
main organisation gets automatically; its key is on the same page). In the
app, only an organisation admin can create, rotate or delete one. A new
environment starts with no members: environments have their own members, so
invite whoever needs it.
```bash theme={null}
# create
curl -X POST https://api.sandbox.topograph.co/v2/environments \
-H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY" -H "Content-Type: application/json" \
-d '{"name": "ci"}'
# list (keys included)
curl https://api.sandbox.topograph.co/v2/environments -H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY"
# discard
curl -X DELETE https://api.sandbox.topograph.co/v2/environments/ci \
-H "x-api-key: sk_dev_YOUR_DEFAULT_SANDBOX_KEY"
```
Deleting an environment kills its key immediately: the next request with it
returns `401`, and its request history is no longer reachable, so export what
you need first. The name becomes available again for a new environment.
Development keys are prefixed `sk_dev_`. Keys issued before that prefix
existed start with `sk_test_` and keep working unchanged.
Managing environments keeps working when your trial ends or a subscription
lapses, and so does every environment you already have. A sandbox costs
nothing to run, so losing one mid-integration would make no sense. Live data
access is unaffected by this: a lapsed `sk_live_` key still cannot fetch real
register data.
# Global Search
Source: https://docs.topograph.co/guides/global-search
Find a company from its name when you do not know its country
Global search is in alpha. The request and response shapes may still change, and so may the wording of explanations and the list of reason kinds.
Every `/v2/search` call needs a country. Often you do not have one: a shareholder listed in a foreign filing, a counterparty on an invoice, a holding company whose stated domicile is not where it is incorporated. Or you know the country but not the state: an American company, any of fifty registers.
`POST /v2/search/global` takes what you know in one line of text and returns candidates across every country Topograph covers, or only the [countries you choose](#searching-only-some-countries), best first. Each candidate has the country and registration number you pass to [`/v2/company`](/essentials/retrieve_company), whether it is a strong or a possible match, and a one-sentence explanation of why it matched. When the search can stand behind one of them, that candidate is [`selected`](#the-company-selected).
## Quick example
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search/global" \
-H "x-api-key: $TOPOGRAPH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "Bamberger GmbH, Wien" }'
```
```json theme={null}
{
"id": "global-search-1791216000000-k3x9qa",
"status": "resolved",
"summary": "Found in Austria: Bamberger GmbH (370916s).",
"likelyCountryCode": "AT",
"query": {
"name": "Bamberger GmbH",
"legalForm": "GmbH",
"address": "Wien"
},
"candidates": [
{
"selected": true,
"match": "strong",
"countryCode": "AT",
"id": "370916s",
"legalName": "Bamberger GmbH",
"address": { "city": "Wien", "countryCode": "AT" },
"isActive": true,
"explanation": {
"summary": "The register in Austria lists it under exactly that name; the address you gave points to Austria; the legal form \"GmbH\" is used in Austria.",
"reasons": [
{ "kind": "register_match", "countryCode": "AT", "text": "The register in Austria lists it under exactly that name" },
{ "kind": "address", "countryCode": "AT", "text": "The address you gave points to Austria" },
{ "kind": "legal_form", "countryCode": "AT", "text": "The legal form \"GmbH\" is used in Austria" }
]
}
}
],
"usage": { "priceCents": 50, "durationMs": 4180 }
}
```
The selected candidate is the company, ready for a company request:
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: $TOPOGRAPH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "countryCode": "AT", "id": "370916s", "dataPoints": ["company"] }'
```
## Sending what you know
Put everything you know in `query`, separated by commas. The name comes first; everything after it is read for what it says about the company.
| You write | Read as |
| - | - |
| `Bamberger GmbH, Wien` | address `Wien` |
| `MFG Investments EOOD, from a UK filing` | the name came from a United Kingdom filing |
| `Altria Group Inc., Richmond VA, altria.com` | address `Richmond VA`, website `altria.com` |
| `Metinvest B.V., Netherlands` | a company in the Netherlands |
| `Acme Holding, HRB 12345` | identifier `HRB 12345` |
| `96950066U5XAAIRCPA78` | the company this LEI designates |
| `Приватна компанія Метінвест Б.В. (Metinvest B.V.)` | name with its Latin alias |
What was understood comes back in `query`, so you can check the search read your input as you meant it:
| Field | Meaning |
| - | - |
| `name` | The company name. |
| `latinName` | Its Latin spelling, when the name is in another script. |
| `legalForm` | The legal form the name carries. |
| `address` | The address part. |
| `identifier` | A registration, VAT or LEI number. |
| `website` | A website. A national domain is a country signal. |
| `mentionedCountries` | Countries your text names as where the company is. A belief the search weighs, not a filter. |
| `sourceCountry` | The country of the filing the name came from. A weak signal: a foreign holder's stated domicile is often not where it is incorporated. |
Add `"activeOnly": true` to leave out companies the search sees as inactive (an indicative status, see [Candidates](#candidates)).
## Searching only some countries
`countries` limits the search to the countries you name. Nothing outside them is searched or returned.
```json theme={null}
{ "query": "Red Tail Ventures LLC", "countries": ["US"] }
```
| You send | Searched |
| - | - |
| `["US"]` | Every US state, and nothing else |
| `["US-DE", "US-NY"]` | Delaware and New York |
| `["CA"]` | Every Canadian jurisdiction: the federal register (`CA-FED`) and the provinces and territories (`CA-ON`, `CA-QC`, ...) |
| `["DE", "AT", "CH"]` | Germany, Austria and Switzerland |
`US` stands for every state, and `CA` for every Canadian jurisdiction we cover. When the state is not known, the search looks for it in public sources first, then asks the state registers: the usual incorporation states first (Delaware, New York, Nevada, Wyoming, Florida, Texas), then almost every other state.
A Canadian company is returned once, in the jurisdiction it is incorporated in. A federal corporation registered in a province as an extra-provincial corporation is found in both registers; when the two records share a Business Number, or the provincial record names the federal one, the search returns the federal (`CA-FED`) candidate and lists the provincial registration as an `other_registration` reason. New Brunswick and Nunavut are not covered yet.
`countries` is a filter. A country named in `query` is not: it says where you think the company is, and the search can still look elsewhere.
When nothing is found in the countries you named and the evidence places the company elsewhere (a `GmbH` searched in the United States only), the search ends `not_found` with the reason `outside_countries`, and `likelyCountryCode` names the country it points to. The same happens, without any search, for an LEI registered outside them.
### Searching by LEI
An LEI names one entity, and the LEI record says where it is registered. Send the LEI alone as `query`, or next to a name (`La Banque Postale, 96950066U5XAAIRCPA78`), and the search goes straight to that register: no other country is searched.
```json theme={null}
{ "query": "96950066U5XAAIRCPA78" }
```
The candidate carries the reason `identifier`, "The LEI you gave belongs to a company registered in France". When the LEI belongs to a company registered in a country Topograph does not cover, the search ends `not_found` with `country_not_covered`, and `likelyCountryCode` names that country.
## How it decides
The search works through cheap signals first and stops as soon as one candidate is a strong match.
1. **The name.** The legal form and the wording of the name point to the jurisdictions that use them: `EOOD` is Bulgarian, `S.p.A.` Italian, `GmbH` German, Austrian or Swiss. `Ltd` is most often British, but an American-sounding `Ltd` is weighed toward the United States. `LLC` and `Inc.` point to the United States, and the state still has to be found. Scanning noise such as `S.a r.1.` is corrected.
2. **The rest of your query**, as above: an address, an identifier, a website, a country.
3. **Topograph's company data**, checked once across all countries.
4. **The web**, only when the name and Topograph's data are not enough, or the company is American and its state is unknown. A source page is kept as evidence.
5. **The registers.** Live searches in the most likely countries, three at a time, with one rephrased retry when a register returns nothing. The search stops once a register returns the exact name and no other country is a serious contender.
For a US company with no known state, the usual incorporation states are tried first (Delaware, New York, Nevada, Wyoming, Florida, Texas). Then the search moves on through the other states, up to almost every state, six at a time and fastest registers first.
**When you give an address**, it decides a lot. If the address names a country or a US state, that register is asked first, before any web search. When it returns the company under that name at the address you gave, or nearby, the search stops there and no other country is searched. When a register holds several companies with the same name, they are ranked by the distance between their registered address and yours, and each explanation says how far it is ("Its registered address is 3 km from Richmond").
A search runs at most 15 register and web searches, plus up to 40 state registers for a US company with no known state, within 100 seconds.
## Reading the answer
`status` is the first thing to check.
| `status` | Meaning | What to do |
| - | - | - |
| `resolved` | One strong match, and no plausible rival. | Use the candidate with `selected: true`. |
| `ambiguous` | Several plausible candidates (the same name exists in Germany and Austria, or twice in one register with nothing to tell them apart), or one candidate that is not strong enough on its own. | Show the candidates to a person, or add what you know to the query and search again. |
| `not_found` | Nothing acceptable. | Read `reason`. |
`summary` says the same thing in one sentence you can show a user.
On `not_found`, `reason` says why:
| `reason` | Meaning |
| - | - |
| `not_a_legal_entity` | The input names a class of holders ("Undisclosed shareholders", "Employees"), a trust or a nominee account. Nothing was searched. |
| `no_country_signal` | Nothing in the query, Topograph's data or public sources pointed at a country. |
| `country_not_covered` | The evidence points to a register Topograph does not cover. |
| `no_register_match` | The likely countries were searched and none returned the company. |
| `outside_countries` | You limited the search with `countries`, nothing was found there, and the evidence places the company in another country. |
| `search_limit_reached` | The search limit was reached before every likely country was tried. |
| `timeout` | The time limit was reached. |
`likelyCountryCode` names the country the evidence settled on, even when the company could not be confirmed, its register is not covered, or it is outside `countries`. A Cayman Islands fund still gets its country.
`id` identifies the search. Quote it when you contact support about one.
### The company: `selected`
The candidate with `selected: true` is the one you can use without a person checking it. At most one candidate is selected, always the first, and only when `status` is `resolved`. The search selects a candidate only for a strong match with no plausible rival: no candidate of that name in another country, and no other company of the same name in the same register that the evidence cannot tell apart. Two `Topograph SAS` in France and no address to separate them is `ambiguous`, not a guess.
Take the selected candidate rather than picking from `candidates` yourself: the decision is the search's own, made on evidence the response does not all carry.
```ts theme={null}
const result = await response.json();
const company = result.candidates.find((c) => c.selected);
if (company) {
await getCompany(company.countryCode, company.id);
} else {
showToReviewer(result.candidates, result.summary);
}
```
### Candidates
Candidates come best first. Each carries `countryCode`, `id`, `legalName`, its registered `address` and `isActive`, `selected`, and a `match`: `strong` when the evidence points to this company, `possible` when it needs a second look. Several candidates can be `strong` (the same name in Germany and Austria) while none is selected.
`isActive` is indicative only. It is the status the search saw, from a register's search results or from Topograph's company data, which can lag the register, so it may be out of date, and it is absent when unknown. `activeOnly` filters on the same indicative status. Before relying on a company's status, request `company` from `/v2/company` and read [`company.status`](/guides/company-status). `explanation.summary` says why it matched in one or two sentences, and `explanation.reasons` lists the reasons one by one, each with a `text` you can show as is:
| `kind` | Meaning |
| - | - |
| `register_match` | The register returned the company. |
| `public_source` | A public page states where it is registered, with its `url`. |
| `identifier` | The identifier you gave has this country's format, or the LEI you gave belongs to a company registered there. |
| `address_match` | The register address matches the address you gave. |
| `distance` | How far the registered address is from the address you gave. |
| `address` | The address you gave points to this country. |
| `legal_form` | The legal form in the name is used in this country. |
| `source_filing` | The name came from a filing in this country. |
| `country_hint` | Your query names this country. |
| `website` | The website domain points to this country. |
| `company_data` | Topograph's company data lists it under that name. |
| `other_registration` | The same company is also registered in another register, under the number given in `text`: a Canadian corporation registered in a province other than its own. When that register publishes neither the home number nor a Business Number, the link rests on the name alone and `text` says a registration with the same name was found. That registration is not listed as a candidate of its own. |
## Streaming
With `"stream": true` and the `Accept: text/event-stream` header, the endpoint sends Server-Sent Events while the search runs:
* `progress`: the search so far, as `{ revision, activity, candidates, query }`. `activity` lists what the search is doing right now, as sentences you can show ("Asking the register in Austria"); several registers are often asked at once. Its wording is for display and may change. `candidates` are the ones found so far; none is selected before `complete`. A new event is sent every time something changes.
* `complete`: the final response, same shape as the non-streaming answer.
* `error`: `{ error: { code, message } }`.
```ts theme={null}
const response = await fetch('https://api.topograph.co/v2/search/global', {
method: 'POST',
headers: {
'x-api-key': process.env.TOPOGRAPH_API_KEY!,
'Content-Type': 'application/json',
Accept: 'text/event-stream',
},
body: JSON.stringify({ query: 'Altria Group Inc., Richmond VA', stream: true }),
});
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += value;
const frames = buffer.split('\n\n');
buffer = frames.pop() ?? '';
for (const frame of frames) {
const event = frame.match(/^event: (.*)$/m)?.[1];
const data = JSON.parse(frame.match(/^data: (.*)$/m)?.[1] ?? '{}');
if (event === 'progress') console.log(data.activity.join(' · '));
if (event === 'complete') console.log(data.status, data.summary);
if (event === 'error') console.error(data.error.code, data.error.message);
}
}
```
Streaming is the better choice for anything a person watches: candidates appear as each register answers, and a long search never runs into an HTTP timeout.
## Billing
A search is billed only when it succeeds, that is when `status` is `resolved`. Ambiguous and not-found searches, inputs rejected as not a legal entity, failures and timeouts are not billed. `usage.priceCents` shows what the search was charged. The current price is on the [pricing page](https://topograph.co/pricing).
## Limits and errors
Each account can run 60 global searches per minute and 5 at the same time.
| HTTP | `error.code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | `query` is missing or empty, `countries` is empty or holds a code that is not a country, or the request still sends the removed `name` or `hints`. |
| 402 | `insufficient_funds` | The account cannot pay for a search. |
| 429 | `rate_limited` | Too many searches this minute, or too many running at once. Wait `retryAfterSeconds`. |
| 503 | `search_timeout` | The search outlived the request. Use streaming, or add what you know to the query. |
## Development environments
With an `sk_dev_` key, global search answers from generated data: candidates in the countries the name's legal form points to, each resolvable with `/v2/company` in the same environment. Coverage is honoured, so a name that only points at uncovered countries ends `not_found` with `country_not_covered`, as it would live. A `countries` filter is honoured too: nothing outside it is generated, and `US` lands on a state. Nothing is billed.
## In the app
The same search is in the app under **Global search** in the sidebar: one text box, a choice between every country, the United States only or a list of countries, the search progressing live, and the candidates with their explanations.
Click a candidate, or **Get data**, to pick the datapoints and order the company exactly as from the country search.
# KYB Onboarding Best Practices
Source: https://docs.topograph.co/guides/kyb-onboarding
Build fast, reliable KYB onboarding flows that maximize conversion and minimize fraud risk
When a business signs up to use your product, every second of friction matters. The difference between a 30-second form and a 3-minute form can cut your conversion rate in half. Yet KYB compliance requires you to collect detailed company information: legal name, registration number, address, legal representatives, beneficial owners.
The best onboarding experiences solve this tension with forms that are pre-filled using data from public company registers. Your customer selects their company from a search, and you use this info to fill in the rest. Less typing, fewer errors, more conversion.
But register data comes with challenges. Fetching it can be slow, expensive, and unreliable. This guide explains how to navigate these trade-offs to build an onboarding flow that converts.
## The Fundamental Trade-off
Company registers are authoritative sources of truth, but they were not designed for real-time API access. When you query a register directly, you might wait seconds or sometimes minutes for a response. Some registers go down regularly. Pricing also varies by country and by data type.
These constraints are especially problematic during onboarding. Your prospect is sitting there, waiting. Each second of delay increases the chance they will drop. And since many prospects will not convert anyway, spending heavily on everyone who starts your signup process does not make economic sense.
The solution is to use different data at different stages of your flow:
**Early in onboarding**, when you're not sure whether the prospect will convert, use fast and affordable data. Accept that it might be slightly stale or incomplete—you'll verify it later.
**After qualification**, when the customer has demonstrated real intent, invest in authoritative verification. Query the register directly, fetch official company documents, and cross-check everything.
This staged approach gives you the best of both worlds: a fast, high-conversion onboarding experience that meets your compliance requirements.
## Start with Company Search
Before you can prefill anything, you need to know which company your customer represents. This means search.
Most onboarding flows already collect the customer's country early on—to adapt the experience, determine pricing, or define the service area. Use this to scope your search. A country-scoped search is faster and returns more relevant results.
When your customer starts typing their company name, you want results to appear immediately. Use [streaming search](/essentials/search) to display results as they arrive from different sources. In countries with multiple search sources, your customer can see initial results quickly while additional sources continue to respond.
Search on Topograph is free and typically returns results in less than 5 seconds. The goal is to make company selection feel effortless.
## Prefill with Fast Company Data
Once your customer selects their company, you need to retrieve profile data to populate your forms. This is where the trade-off materializes.
If you query the register directly, you might have to wait 5-30 seconds for a response. In some countries, the register might be down entirely. Meanwhile your customer is staring at a loading spinner, wondering if something broke. Many will leave.
The [`/v2/company` endpoint with `mode: "prefill"`](/essentials/modes) solves this problem. It is designed specifically for the onboarding use case:
* **Speed**: Each requested datapoint has a 10-second deadline. A datapoint that misses it fails with `onboarding_timeout` instead of keeping your customer waiting.
* **Fail fast**: A datapoint with no fast source in that country fails immediately with `fast_source_unavailable`.
* **Block-based pricing**: Each data block has country-specific pricing, with 24-hour deduplication
To achieve this, we make trade-offs. The data might come from a cached source rather than a live register query. In countries where register access is expensive, we might use alternative data sources. Datapoints that no fast source can deliver are not silently left out: they fail with `fast_source_unavailable`, so you know to fetch them later in verification mode. See [Modes](/essentials/modes) for the details.
These trade-offs are acceptable during onboarding because you are not making final compliance decisions yet. You are just trying to reduce friction and collect initial information. The verification comes later, when the customer has proven they are serious.
Importantly, trade-offs does not mean low-quality: we always favour official sources and when we do cache data, we still refresh it quite often.
Even if we offer a fast response, consider adding a lightweight UI step between launching the API request for data
request and displaying your forms, e.g. phone verification or email confirmation. This
gives the data a moment to load while the customer does something useful,
making the experience seamless.
## Check what Documents Exist
While you're fetching onboarding data, also check which official documents are available in the register for the company of interest. This request runs in parallel and is free.
Knowing what documents are available helps you plan the rest of the flow:
* Documents that exist in the register can be retrieved automatically for verification
* Documents that don't exist will need to be uploaded by your customer
This avoids the frustrating experience of asking customers to upload documents you could have fetched yourself.
## Apply an Early Filter
With the onboarding data in hand, you can make an initial assessment: can you actually work with this company?
Check the basics:
* Is the company active, or has it been dissolved?
* Does the industry or legal form fit your product requirements?
* Are there any obvious red flags in the company structure?
Reject early if the answers require it; this saves everyone time. There's no point putting a prospect through additional verification steps if you already know you can't serve them.
Early rejection also protects your unit economics. Each step past this point costs money: verification data, document retrieval, manual review. Don't spend on companies that will never become customers.
## Verify against Data from the Register
This step is critical. Everything up to this point has been about speed and
conversion. Now you need to verify that the information is correct.
The data your customer provided might not match reality. They could be impersonating a different company. They might have provided outdated information. Or, in rare cases, the cached data from the onboarding endpoint you used for pre-filling might have changed since last refresh.
At this stage, the customer has demonstrated real intent. They've filled out your forms, passed your initial filter, and progressed through your onboarding flow. Now it's worth investing in authoritative data.
The [verification data endpoint](/essentials/retrieve_company) provides comprehensive, verified data:
* **Authoritative data**: Fetched from public company registers. A result fetched for the same company in the last 24 hours can be reused.
* **Complete data**: Automatically enriched with information extracted from available company documents
* **Cross-checked**: Data verified against register documents (beta feature—contact us to enable)
This endpoint can be slower and may use different billable blocks than prefill mode. That is the trade-off for authoritative data. At this stage of your flow, it is usually the right trade-off to make.
Build this as an asynchronous step. Submit the verification request, then let the customer continue while it processes in the background. Use webhooks to receive the results when they're ready.
## Complete with Document Verification
The final layer of verification is cross-checking data against official documents from the register:
* **Financial statements** reveal the company's financial health and disclosures
* **Register extracts** confirm registration details and legal representatives
* **Articles of association** show company structure and governance rules
* **UBO extracts** confirm beneficial ownership declarations
Why should you fetch these documents from the register, rather than ask your customer to upload them? To name two of the many reasons: (1) the individual filling the form does not necessarily know where the right documents are or have access to them and (2) because documents can be forged, but register responses cannot. When you retrieve a document directly from the official source, you know it's authentic.
See our [document retrieval guide](/essentials/document-guide) for details on how document fetching works.
## Putting it Together
The complete flow balances speed with thoroughness:
| Stage | What happens | Why |
| - | - | - |
| **Search** | Customer finds their company | Fast, free, reduces friction |
| **Fast company data** | Prefill forms with company info | Fast and affordable -- optimized for conversion |
| **Available documents** | Check what's in the register | Plan the verification step |
| **First filter** | Assess basic fit with your process | Save costs on unqualified leads |
| **Verification data** | Verify against register data | Authoritative data for compliance |
| **Document verification** | Cross-check against official documents | Prevent document fraud and improve UX |
The key insight is that different stages have different requirements. Early on, speed and cost matter more. Later, accuracy and authority matter most. By choosing the right data for each stage, you get better conversion and strong compliance.
## The Flow
```mermaid theme={null}
flowchart TD
Start([Customer enters onboarding]) --> Search[Company search]
Search --> Select[Customer selects company]
Select --> Parallel{Parallel requests}
Parallel --> Onboarding[Fast company data]
Parallel --> AvailDocs[Available documents]
Onboarding --> Prefill[Prefill forms]
Prefill --> Filter{First filter: qualified?}
Filter --> |No| Reject([Early rejection])
Filter --> |Yes| Verify[Verification data]
AvailDocs --> DocList[Know which docs exist]
Verify --> Documents[Document retrieval and verification]
DocList --> Documents
Documents --> Complete([Onboarding complete])
style Start fill:#e1f5ff
style Complete fill:#d4edda
style Reject fill:#f8d7da
style Filter fill:#fff3cd
```
## Next steps
Implement company search with results streaming
Cheap, fast data for onboarding flows
Live data verification from public registers
Official company documents for verification
# Use Topograph from your AI agent
Source: https://docs.topograph.co/guides/mcp
Connect Claude, ChatGPT, Cursor, VS Code and other AI agents to the Topograph MCP to look up companies in official business registers.
**Early access**
MCP access is an early-access feature, available only to subscribed clients with active API access. Functionality and availability may change without notice.
MCP access does not modify, extend, or reduce the terms governing the relationship between Topograph and the client, as defined in the signed Terms and Conditions and Data Processing Agreement.
The client is solely responsible for the choice of AI agent and for its use. Topograph provides data as returned by its MCP server and is not responsible for how the agent interprets, summarises, or presents that data.
The Topograph MCP lets an AI agent query company data the way your application does through the API. Ask "who are the directors of this company?" or "who owns it?" in plain English, and the agent searches the register, picks the right company, and fetches only what you asked for.
It is a remote [Model Context Protocol](https://modelcontextprotocol.io) server at `https://mcp.topograph.co/mcp`. Sign in with your Topograph account, or connect with an API key. Requests are billed exactly like the API: same prices, same wallet. Requests you make while signed in also show up in your request history in the app.
Building an integration rather than looking up companies? The [Topograph Wizard](/guides/topograph-mcp) gives your coding agent live coverage, pricing, docs and code samples. It is free to use. The Claude Code plugin installs both servers.
## Using agents responsibly
When your agent calls the MCP, Topograph returns the results to the client you connected. Results can include personal data about directors, shareholders and beneficial owners. Your chosen agent platform and model provider may process and retain that data.
Before connecting, review your provider's data handling, retention and access settings. You are responsible for choosing and configuring your agent, supervising its requests, and ensuring that sharing the returned data with your provider is appropriate for your use.
AI summaries can misinterpret or omit returned data. Check the underlying results and official documents before making KYB or compliance decisions. You remain responsible for those decisions.
## Connect your agent
The app lists every client below, with copy buttons and one-click links, on the [AI agents page](https://app.topograph.co/agents) (**AI agents** in the sidebar). That page also shows your MCP spending this month.
Works in Claude on the web, Claude Desktop, Cowork and the mobile apps.
[Add Topograph to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Topograph\&connectorUrl=https%3A%2F%2Fmcp.topograph.co%2Fmcp) opens the form already filled in. To do it by hand:
Open **Settings > Connectors > Add custom connector**.
Name: `Topograph`. URL: `https://mcp.topograph.co/mcp`.
Click **Connect** and sign in with your Topograph account. Choose the organisation Claude should act for.
On Team and Enterprise plans, an owner may need to add the connector for the organisation first.
Add the server, then run `/mcp` in Claude Code to sign in:
```bash theme={null}
claude mcp add --transport http topograph https://mcp.topograph.co/mcp
```
To use an API key instead of signing in:
```bash theme={null}
export TOPOGRAPH_API_KEY="sk_live_..."
claude mcp add --transport http topograph https://mcp.topograph.co/mcp \
--header "Authorization: Bearer $TOPOGRAPH_API_KEY"
```
Or install the Topograph plugin. It adds this server, the [Topograph Wizard](/guides/topograph-mcp), a `/topograph:lookup` command and skills that teach Claude to search first and check the price before it pays:
```
/plugin marketplace add getsemaphore/topograph-mcp-library
/plugin install topograph@topograph
```
Open **Settings > Apps & Connectors > Advanced settings** and enable **Developer mode**.
Click **Create**. Name it `Topograph`, set the URL to `https://mcp.topograph.co/mcp` and the authentication to **OAuth**.
Sign in with your Topograph account and choose the organisation.
Developer mode is available on the plans where ChatGPT supports custom connectors. Workspace admins may need to allow it.
[Add Topograph to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=topograph\&config=eyJ1cmwiOiJodHRwczovL21jcC50b3BvZ3JhcGguY28vbWNwIn0%3D) installs it in one click. Or add it to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"topograph": {
"url": "https://mcp.topograph.co/mcp"
}
}
}
```
To use an API key, add a header that reads it from your environment:
```json theme={null}
{
"mcpServers": {
"topograph": {
"url": "https://mcp.topograph.co/mcp",
"headers": { "Authorization": "Bearer ${env:TOPOGRAPH_API_KEY}" }
}
}
}
```
[Add Topograph to VS Code](vscode:mcp/install?%7B%22name%22%3A%22topograph%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.topograph.co%2Fmcp%22%7D) installs it in one click. Or from a terminal:
```bash theme={null}
code --add-mcp '{"name":"topograph","type":"http","url":"https://mcp.topograph.co/mcp"}'
```
VS Code asks you to sign in the first time the agent uses a Topograph tool.
```bash theme={null}
gemini mcp add --transport http topograph https://mcp.topograph.co/mcp
```
Gemini CLI opens the Topograph sign-in the first time it connects.
Agents you build on a model provider's API connect with an API key.
```json Anthropic Messages API theme={null}
{
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.topograph.co/mcp",
"name": "topograph",
"authorization_token": ""
}
],
"tools": [
{ "type": "mcp_toolset", "mcp_server_name": "topograph" }
]
}
```
```json OpenAI Responses API theme={null}
{
"tools": [
{
"type": "mcp",
"server_label": "topograph",
"server_url": "https://mcp.topograph.co/mcp",
"headers": { "Authorization": "Bearer " },
"require_approval": "always"
}
]
}
```
The Anthropic MCP connector is in beta: send the `anthropic-beta: mcp-client-2025-11-20` header with the request. Keep approvals on for paid tools, or set a low `max_cost_credits` in your prompts, so an unattended agent cannot spend without a check.
## Authentication
There are two ways to connect. Both act for one organisation and its wallet.
**Sign in (OAuth).** The default for chat apps and editors. The first time the agent connects, your browser opens the Topograph sign-in. You then choose which organisation (environment) the agent acts for and approve what it may do:
| Permission | Allows |
| - | - |
| `data:read` | The free tools: search in one country, coverage, prices, cost estimates, document lists, your requests and monitors |
| `data:spend` | The paid tools: company data, document orders and worldwide search |
| `monitors:write` | Starting and stopping monitoring |
Anyone in an organisation can connect and spend through the MCP, within the monthly cap described below. To switch organisation, disconnect and connect again.
**API key.** For agents you build yourself, or when you prefer not to sign in. Send the key as `Authorization: Bearer ` (preferred) or `x-api-key: `. Use the API key of a live environment (`sk_live_...`). Keys are on **Settings & More > Developer** in the [app](https://app.topograph.co).
MCP access is available only to subscribed clients with active API access.
## Tools
The agent picks the tools itself. You do not need to name them, but knowing what they do helps you read what it did.
### Free tools
| Tool | What it returns |
| - | - |
| `search_companies` | Companies in one country matching a name, registration number or LEI, each with the identifier the other tools take. |
| `get_country_coverage` | What Topograph covers in a country: datapoints, documents, identifier formats, prices, typical speed and beta status. |
| `get_pricing` | Your prices for one country: every data block and document with the price you pay, including contract prices. |
| `estimate_cost` | The price of a set of datapoints, and optionally documents, before running it. |
| `list_documents` | The official documents available for a company, each with its price and expected delivery time. |
| `get_request` | The status and results of a previous request: what has arrived so far and what is still pending. |
| `get_document` | A fresh download link for a document you already retrieved (valid for about 15 minutes), with its metadata. |
| `list_requests` | Every request on the account (API, app and MCP), newest first, searchable by company name or identifier. |
| `get_account` | Your balance, environment (live or sandbox), workspaces, and your MCP spending this month against the cap. |
| `list_monitors` | The companies you monitor. |
### Paid tools
| Tool | What it returns |
| - | - |
| `get_company` | The company profile and any of: legal representatives, other key persons, establishments, shareholders, subsidiaries, ultimate beneficial owners, available documents. Billed like the same datapoints on the API. |
| `get_graph` | An authoritative ownership graph, bounded by the approved spending limit. Requires a live environment. |
| `continue_graph` | Expands selected company nodes where a previous graph stopped, under a newly approved limit. |
| `order_documents` | Buys documents from `list_documents` and returns them, or a request to follow when delivery takes longer. |
| `search_companies_worldwide` | Finds a company when you do not know its country, or across several countries. Billed per search, only when it resolves to one good match. In beta, like [global search](/guides/global-search). |
`get_company` takes a mode, as the API does. `verification` (the default) reads the authoritative register live and is what compliance work needs. `onboarding` is faster and cheaper but not suitable for compliance records. See [Verification vs onboarding mode](/essentials/modes).
For ownership exploration, call `get_graph` with `country`, `company_id` and a user-approved `max_cost_credits`. The total depends on the companies discovered, so the limit is a ceiling rather than an exact quote. Traversal uses verification mode and stops at the budget or the service's depth and node limits.
To expand a branch, call `continue_graph` with the returned `main_request_id` as `request_id`, the exact `node_ids` of selected `budget_truncated` companies, and a newly approved `max_cost_credits`. Poll the continuation's `request_id` while it is in progress. Then call `get_request` on `main_request_id` to retrieve the merged graph. Previously purchased company data is deduplicated across the request tree. Use `response_format: "full"` when the summary truncates the node list.
### Monitoring tools
| Tool | What it does |
| - | - |
| `create_monitor` | Starts daily monitoring of a company, within your monitoring plan. Changes are delivered to your [webhooks](/essentials/monitoring). |
| `delete_monitor` | Stops monitoring a company. |
## How paid calls work
Paid and monitoring tools are marked as actions that change something, so Claude, ChatGPT and most editors ask you to confirm before they run. Free tools run without asking.
Every paid call is bounded and priced in the open:
* **A ceiling per call.** `get_company` takes `max_cost_credits`. A call that would cost more is refused instead of run. It works like `maxBudget` on the API.
* **Documents are ordered at a quoted price.** `order_documents` requires `expected_total_credits`, the total the agent showed you. If the price changed since, the order is refused and nothing is charged.
* **Every result shows its cost.** Each tool result states what that call cost, so the agent can tell you.
A good agent searches for free, estimates the cost for free, tells you the price, and only then runs the paid call. The Claude Code plugin and the tool descriptions teach this order.
### Monthly cap
Each person can spend up to **1,000 credits per calendar month** through the MCP. The cap counts purchases made through the MCP only; your API usage is not affected. For an API key, the cap applies to the key.
When a call would go over the cap, it is refused with a message that says when the cap resets: midnight UTC on the first day of the next month. `get_account` and the [AI agents page](https://app.topograph.co/agents) show what you have spent this month.
Development environments are not capped and never cost real money.
## Long-running requests
Some registers answer in seconds, some take minutes. `get_company` waits about 30 seconds (an agent can ask for up to 50 with `wait_seconds`). If everything has arrived, you get the full result. Otherwise you get what has arrived so far, the datapoints still pending, and a `request_id`.
Ask the agent to check again later. It calls `get_request` with the `request_id`, which is free. Calling `get_company` again would start, and bill, a new request.
Some documents are delivered manually by the register and take hours or days. The order returns a `request_id` straight away; the document appears in `get_request` once it arrives. See [Manual delivery](/essentials/manual-delivery).
## Register data is third-party content
Company names, addresses, activity descriptions and documents come from registers and the companies that file with them. Topograph returns them as published.
Your agent should treat everything in a result as data to report, not as instructions to follow. A company name that says "ignore your previous instructions" is still just a company name. Keep confirmations on for paid tools so that nothing in a result can lead to a purchase without you seeing it.
## Sandbox
Build and test against a [development environment](/guides/development-environment) first. Its MCP server is:
```
https://mcp.sandbox.topograph.co/mcp
```
Connect with the development environment's API key (`sk_dev_...`). Every tool works as it does in live, but results are generated data, requests cost only virtual credits, and there is no monthly cap.
## Example prompts
```text theme={null}
"Find the French company Doctolib and show me its legal representatives."
"Who are the ultimate beneficial owners of ASML Holding N.V.? Tell me the
price before you fetch anything."
"Is 'Bamberger GmbH' in Vienna still active? Use onboarding mode, I just
want a quick check."
"List the official documents available for Companies House number 00445790
and their prices. Don't order anything yet."
"Order the trade register extract for SIREN 552100554 if it costs less
than 5 credits."
"What did I spend through the MCP this month, and what were my last
five lookups?"
"Start monitoring the three companies we just looked up."
```
## Troubleshooting
The server could not identify you. With an API key, check that it is sent as `Authorization: Bearer ` and has not been rotated. With sign-in, the session may have expired: disconnect and connect again (in Claude Code, run `/mcp`). A development key (`sk_dev_...`) only works on the sandbox server, and a live key only on `https://mcp.topograph.co/mcp`.
You are identified but not allowed to do this. Either the organisation does not have active API access and a subscription, or you did not grant the permission the tool needs. For example, paid tools need `data:spend`. Reconnect and approve the permission, or ask an admin of your organisation.
The call would take your MCP spending this month over the cap. The message says when it resets. Nothing was charged, and free tools keep working.
Cursor prefers OAuth when a server advertises it, which Topograph does, so it can skip the header you configured. Just sign in when Cursor asks; it acts with the same access.
The register had not answered within the wait (about 30 seconds by default). Ask the agent to check the request again; it uses `get_request`, which is free.
Some clients let you approve a tool permanently. Review your client's tool permissions and set Topograph's paid tools back to "ask". With your own agent, keep `require_approval` on and pass `max_cost_credits`.
## Related
* [Topograph Wizard](/guides/topograph-mcp): the integration helper for coding agents
* [Verification vs onboarding mode](/essentials/modes)
* [Coverage and pricing](/essentials/coverage-and-pricing)
* [Development environments](/guides/development-environment)
* [Monitoring](/essentials/monitoring)
# Migrating to the Data Product Model
Source: https://docs.topograph.co/guides/migration-data-product-model
Move from companyProfile and /v2/onboarding to granular datapoints on /v2/company
Historically, `/v2/company` accepted a single catch-all datapoint called `companyProfile` and onboarding ran on its own `/v2/onboarding` endpoint. That model hid what you were actually buying (one `companyProfile` meant different things in different countries) and forced prefill and verification down two separate code paths.
The Data Product Model replaces `companyProfile` with explicit, named datapoints and folds `/v2/onboarding` into `/v2/company` as a `mode`. You now ask for exactly the sections you need, the billing and response shape match what you requested, and both retrieval modes share the same endpoint.
Both legacy shapes still work. This guide shows you how to move over.
## The datapoints
A request to `POST /v2/company` takes a `dataPoints` array. Each entry is one of the values below. Availability varies by country (see each [country guide](https://www.topograph.co/countries/fr)).
| Datapoint | What you get |
| - | - |
| `company` | Core registration record: legal name, registration number, legal form, status, incorporation date, registered address, share capital, activity codes, tax IDs. |
| `legalRepresentatives` | Directors, managers, and officers with signing authority. |
| `otherKeyPersons` | Non-signing roles the register exposes separately: auditors, supervisory board members, commissaires aux comptes, etc. |
| `establishments` | Branches and secondary locations with their own address and local registration number. |
| `subsidiaries` | Companies this company holds shares in. |
| `shareholders` | Direct shareholders and their ownership percentages, as declared at the register. |
| `ultimateBeneficialOwners` | UBO declarations: natural persons with ultimate control, ownership chain, and control type. |
| `availableDocuments` | List of official documents the register exposes for this company. Always free. Use the returned IDs in a follow-up `documents` request. |
| `graph` | Ownership and control network: nodes (companies, people) and edges (shareholding, subsidiaries, officer roles). Budget-capped with `graphMaxBudget`. |
`company`, `legalRepresentatives`, `otherKeyPersons`, `establishments`, and `subsidiaries` are the datapoints introduced by the Data Product Model. `shareholders`, `ultimateBeneficialOwners`, `availableDocuments`, and `graph` pre-date it and have always been callable by name.
### What `companyProfile` means
`companyProfile` is a legacy alias. It stands for **`company` + `legalRepresentatives` + `otherKeyPersons` + `establishments`**, on a best-effort basis.
**Best-effort** means: each of the four expanded datapoints is included only if the country has a block covering it in the mode you requested. If a datapoint has no compatible block, it is silently dropped from the expansion. You are never billed for datapoints the country cannot deliver.
Concretely:
| Country | Verification block covers | `companyProfile` expansion in verification |
| - | - | - |
| FR, GB, BE, CZ | all 4 | all 4 |
| EE | company, legalReps, otherKeyPersons, shareholders | company, legalReps, otherKeyPersons (establishments dropped) |
| DK | company, legalReps, establishments, shareholders | company, legalReps, establishments (otherKeyPersons dropped) |
| DE | company, legalReps, otherKeyPersons | company, legalReps, otherKeyPersons (establishments dropped) |
| IT | company, legalReps, plus establishments in a separate block | company, legalReps, establishments (otherKeyPersons dropped) |
| ES, AT, CY | company, legalReps | company, legalReps only |
The same rule applies in prefill mode: the expansion is filtered against the country's fast block. For Italy this means `companyProfile` in prefill mode includes only `company`: the fast block covers nothing else, so `legalRepresentatives`, `otherKeyPersons` and `establishments` are all dropped.
Billing is one block per resolved bundle. Expansion never adds a separate catalog item.
## Replace `companyProfile`
Swap `companyProfile` for the datapoints you actually need.
```json theme={null}
// Before
{ "dataPoints": ["companyProfile"] }
// After (equivalent on countries whose block covers all four)
{ "dataPoints": ["company", "legalRepresentatives", "otherKeyPersons", "establishments"] }
// After (when you only need the basics)
{ "dataPoints": ["company", "legalRepresentatives"] }
```
Pick the names you consume:
* `company` alone if you only need the registration record.
* `company` + `legalRepresentatives` for the classic KYB pair.
* Add `otherKeyPersons` when your compliance checks cover auditors or board members without signing authority.
* Add `establishments` when you need branch offices.
* Add `shareholders` / `ultimateBeneficialOwners` for ownership checks.
Explicit names make your billing predictable and your response shape visible to the reader of the code.
### Do not mix legacy and new names
Within one request, you must pick one vocabulary:
* Legal: `["companyProfile"]`, `["companyProfile", "shareholders"]`, `["companyProfile", "ultimateBeneficialOwners", "availableDocuments"]`
* Legal: `["company", "legalRepresentatives"]`, `["company", "shareholders", "ultimateBeneficialOwners"]`
* **Rejected with HTTP 400**: `["companyProfile", "company"]`, `["companyProfile", "legalRepresentatives"]`, `["companyProfile", "otherKeyPersons"]`, `["companyProfile", "establishments"]`, `["companyProfile", "subsidiaries"]`
The rule is: `companyProfile` cannot appear alongside any of the five new names (`company`, `legalRepresentatives`, `otherKeyPersons`, `establishments`, `subsidiaries`). Shared datapoints (`shareholders`, `ultimateBeneficialOwners`, `availableDocuments`, `graph`) can be combined with either vocabulary.
### The response echoes your vocabulary
`dataStatus.dataPoints` uses the exact keys you sent. Send `companyProfile`, get `companyProfile` back. Send `company` + `legalRepresentatives`, get them back separately. The internal best-effort expansion is not visible in `dataStatus`.
```json theme={null}
// Request: { "dataPoints": ["companyProfile"] }
{
"dataStatus": {
"dataPoints": {
"companyProfile": { "status": "succeeded" }
}
}
}
// Request: { "dataPoints": ["company", "legalRepresentatives"] }
{
"dataStatus": {
"dataPoints": {
"company": { "status": "succeeded" },
"legalRepresentatives": { "status": "succeeded" }
}
}
}
```
This is why existing integrations keep working unchanged.
The response body itself contains whatever sections the country's block produced. For a country whose block covers all four company-level datapoints, a `companyProfile` request returns `company`, `legalRepresentatives`, `otherKeyPersons`, and `establishments` fields in the body. Request them explicitly (new vocabulary) to make that shape obvious in your code.
## Replace `/v2/onboarding`
`/v2/onboarding` is deprecated. Use `/v2/company` with `mode: "prefill"` instead.
```bash theme={null}
# Before
curl -X POST https://api.topograph.co/v2/onboarding \
-H 'x-api-key: ' \
-d '{
"countryCode": "DE",
"id": "HRB123456"
}'
# After
curl -X POST https://api.topograph.co/v2/company \
-H 'x-api-key: ' \
-d '{
"countryCode": "DE",
"id": "HRB123456",
"dataPoints": ["company"],
"mode": "prefill"
}'
```
`/v2/onboarding` requests only `company` in prefill mode and reports its status under `dataStatus.dataPoints.company`, so the request above is the like-for-like replacement.
Two wins from the move:
1. You pick the datapoints. The old endpoint only returns `company`. On `/v2/company` you can add `legalRepresentatives`, `shareholders`, `ultimateBeneficialOwners`, or anything else and still run in prefill mode.
2. One codebase, one response shape. Verification and prefill share the endpoint, the DTO, and the `dataStatus` format. Read [Verification vs Prefill Mode](/essentials/modes) for the source-selection and deadline behavior.
Prefill mode enforces a hard 10-second deadline per datapoint and only uses fast sources. Datapoints that have no fast source fail with `fast_source_unavailable`. See [Verification vs Prefill Mode](/essentials/modes).
## Compatibility summary
| Legacy shape | Status | Replacement |
| - | - | - |
| `dataPoints: ["companyProfile"]` | Works (best-effort alias for the 4 company-level datapoints) | Explicit list: `["company", "legalRepresentatives", "otherKeyPersons", "establishments"]` |
| `POST /v2/onboarding` | Deprecated | `POST /v2/company` with `mode: "prefill"` |
| Deprecated `fast: true` flag | Works | `mode: "prefill"` |
| Deprecated `authoritative: true` flag | Works | omit `mode` or pass `mode: "verification"` |
New integrations should start with the new vocabulary and `/v2/company`. Existing integrations can stay on `companyProfile` and `/v2/onboarding` as long as needed, and migrate opportunistically.
## Next steps
Full `/v2/company` request and response reference.
Source selection, deadlines, and `authoritative` flag.
End-to-end flow combining search, prefill mode, and verification.
How datapoints map to billable blocks and the 24-hour dedup window.
# Register Data Complexity
Source: https://docs.topograph.co/guides/register-data-complexity
Why register data is difficult to work with and how we handle it
If you've worked with company data before, you know the struggle. You expect an API that returns data in JSON format in 200 milliseconds.
Instead, you get the **reality of public company registers worldwide**:
* **Infrastructure from the 90s** or earlier
* **Files instead of APIs**: PDFs, XML dumps, or worse
* **Frequent downtime**: maintenance windows, random outages
* **Inconsistent data models**: every country defines "company" differently
This guide explains the complexity of the underlying data sources and how Topograph hides it so you can focus on your product.
## The "Wild West" of Register Data
There is no global standard for company data. Every jurisdiction operates independently, with its own rules, formats, and technical capabilities.
### 1. Live vs. non-live sources
Not all registers are online databases that you can query in real-time.
| Source Type | Reality |
| - | - |
| **Modern API** | JSON/XML API, reasonable uptime |
| **Legacy Database** | SOAP endpoints, IP whitelisting, VPN requirements |
| **Bulk Files** | Daily/monthly dumps (CSV, XML) |
| **Complex Websites** | Flaky navigation, dynamic content |
**The Topograph solution:** a single, uniform API regardless of the underlying source.
### 2. The Speed Spectrum
Response times vary wildly depending on the source:
* **Fast (1-5s)**: Modern registers with direct API access
* **Slow (10s+)**: Registers that require website navigation, or have slow infrastructure
* **Very slow (minutes to hours)**: Registers that deliver documents asynchronously
**The Topograph solution:** a single asynchronous endpoint with webhook delivery.
### 3. Register Instability
Registers frequently experience temporary outages and disruptions:
* **Scheduled Maintenance**: Many public systems go offline for hours every night or weekend
* **Unplanned Outages**: Legacy systems crash under load
* **Rate Limiting**: Strict limits on how many queries you can make
**The Topograph solution:** advanced retry strategies. For verification data, we prefer to deliver data late (up to one hour of retries) rather than not deliver at all. For onboarding data, we prioritize speed over completeness and fail fast if the register is slow.
### 4. Always evolving registers
Registers constantly change: website revamping, API update, change in authentication methods, modifications of data formats. With integrations across dozens of countries and US states, breaking changes happen frequently and simultaneously.
**The Topograph solution:** continuous monitoring and agile development processes. We detect breaking changes early and rapidly adapt our integrations, aiming to resolve issues within **24 business hours** of detection.
### 5. Barriers to Data Access
Many registers have procedural barriers:
* **Business verification**: some countries only allow registered businesses to access data
* **Signed contracts**: some registers require bilateral agreements
* **Physical presence**: a few national registers require a local legal entity to access
* **Manual approval**: access requests may take weeks or months to be granted
**The Topograph solution:** we build relationships and agreements everywhere possible.
### 6. The PDF Problem
In many countries, the data you need is locked inside PDF documents:
* **Financials**: annual accounts are often scanned images
* **Shareholders**: listed only in meeting minutes or notary deeds
* **Statutes**: legal documents describing the company structure
**The Topograph solution:** structured JSON extracted from documents.
### 7. Cost Variability
Government pricing for public company data varies wildly:
* **Free**: UK, France, and several others
* **Moderate**: many company profiles and documents in mature digital registers.
* **Expensive or variable**: documents and extracts whose price depends on the register, delivery method, or document size.
Some registers also require annual subscriptions, upfront deposits (often thousands of euros), or restrict access to registered businesses.
**The Topograph solution:** Block-based pricing with clear included documents, 24-hour deduplication, and no hidden fees.
## Summary
| Challenge | Reality | With Topograph |
| - | - | - |
| **Integration** | Build 50+ different connectors | One unified API |
| **Data Format** | XML, SOAP, PDF, CSV, HTML | Standardized JSON |
| **Uptime** | Handle every outage yourself | Built-in reliability |
| **Maintenance** | Constant updates as registers change | Zero maintenance |
| **Cost** | Subscriptions, deposits, variable pricing | Block-based pricing with deduplication |
We handle the complexity of public registers worldwide so you can focus on your product.
# Reliability & Errors
Source: https://docs.topograph.co/guides/reliability-and-errors
Understanding retry strategies, error handling, and the speed vs. robustness trade-off
Working with global company registers means dealing with instability. Registers have maintenance windows, rate limits, and unexpected downtime.
Topograph abstracts this complexity, but our approach to reliability differs depending on which endpoint you use. We make deliberate trade-offs between **speed** and **robustness**.
Monitor real-time system status at
[status.topograph.co](https://status.topograph.co/).
## The speed vs. robustness trade-off
Same endpoint (**`POST /v2/company`**), different behavior by **mode**:
| Mode | Priority | Strategy | Retry behavior |
| - | - | - | - |
| **`mode: "prefill"`** | **Speed** | Fail fast | Strict short timeouts. Minimal retries—if the register is slow, we return quickly rather than wait. |
| **Verification (default)** | **Robustness** | Deliver eventually | Longer retries—up to **1 hour** for transient register outages. |
The legacy **`POST /v2/onboarding`** route follows the same fast-path strategy but is deprecated; prefer `mode: "prefill"`. See [Data retrieval modes](/essentials/modes).
## Retry strategies
### Prefill mode (`mode: "prefill"`)
Designed for real-time user flows where latency matters most.
* **Timeout**: Hard **10-second deadline per datapoint**. Datapoints that do not finish in time fail with error code `onboarding_timeout`. Any partial data that arrived before the deadline is still returned.
* **Retries**: Minimal. We do not retry transient register errors that would delay the response significantly.
* **Priority**: Speed over completeness. Retry without `mode: "prefill"` if you need the datapoint the slow way.
### Verification mode (default `POST /v2/company`)
Designed for back-office processes where data completeness is critical.
* **Timeout**: Long. We accept that some requests might take minutes if the register is struggling
* **Retries**: Exponential backoff strategies. For scheduled register maintenance or temporary outages, we may retry for up to **1 hour**
* **Priority**: Eventual success over immediate failure
Because verification requests can be long-running, we strongly recommend using
**webhooks** to receive results asynchronously.
## Error handling
Errors come back at two levels. An HTTP error status means the request itself was refused. Once a `POST /v2/company` request is accepted, a problem with one datapoint or document does not change the HTTP status: the response is still `200` or `201`, and the item is marked `failed` in `request.dataStatus` with an `error.code`.
### HTTP status codes
When a request is refused, the body's `error.code` uses the same vocabulary as the item-level codes below.
| Code | Error | Description | Action |
| - | - | - | - |
| `400` | Bad Request | Invalid parameters, data points or identifier format | Fix your request payload |
| `401` | Unauthorized | Invalid or missing API key | Check your credentials |
| `404` | Not Found | Unknown `requestId` on `GET /v2/company/{requestId}` | Check the request ID |
| `406` | Not Acceptable | Country not supported by search | Check [coverage and pricing](/essentials/coverage-and-pricing) |
| `429` | Too Many Requests | You hit your rate limit | Slow down your requests |
| `500` | Internal Error | Server-side issue | Contact support if persistent |
| `503` | Service Unavailable | A search could not reach the register or took too long | Retry the search later |
### Datapoint and document error codes
These appear in `request.dataStatus` on the response and in `company.updated` webhooks. Each failed item carries a `code`, a human-readable `message` you can show your own users, `retryable`, and, when retryable, `retryAfterSeconds`:
```json theme={null}
"shareholders": {
"status": "failed",
"error": {
"code": "source_unavailable",
"message": "The 'handelsregister' register is temporarily unavailable. Please try again later.",
"source": "handelsregister",
"retryable": true,
"retryAfterSeconds": 300
}
}
```
Every `error.code` is listed below with its fixed `retryable` flag and the recommended minimum wait before you resubmit. The same list is the `PublicErrorCode` enum in the [API reference](/api-reference/data/get-company-data-and-documents), with the same description on every value, so a generated client can switch on it. Failed items are never charged.
| `error.code` | `retryable` | `retryAfterSeconds` | Meaning | What to do |
| - | - | - | - | - |
| `service_unavailable` | `true` | 300 | Topograph could not complete the lookup because of a temporary problem on its side. | Resubmit the same request after `retryAfterSeconds`, doubling the delay on each further failure (cap at one hour). |
| `source_unavailable` | `true` | 300 | The register behind this datapoint is down, rate limiting or timing out; `error.source` names it when known. | Resubmit the same request after `retryAfterSeconds`, doubling the delay on each further failure (cap at one hour). |
| `processing_failed` | `true` | 900 | The register answered, but Topograph could not process the response; the team is alerted automatically. | Resubmit the same request after `retryAfterSeconds`, doubling the delay on each further failure (cap at one hour). |
| `request_cancelled` | `true` | 0 | The request was cancelled before this item completed. | Resubmit the same request right away. |
| `processing_interrupted` | `true` | 0 | Processing was interrupted before this item completed; no verdict was reached. | Resubmit the same request right away. |
| `resource_not_found` | `false` | n/a | No company exists in the register under this identifier. | Nothing to retry: the same request returns the same answer. Treat it as a final result. |
| `invalid_request` | `false` | n/a | The request is malformed: an unknown datapoint, a badly formatted identifier or an invalid parameter. | Correct the request before resending it; resent unchanged, it fails the same way. |
| `insufficient_funds` | `false` | n/a | The wallet balance does not cover the price of this request. | Top up the wallet, then resubmit. |
| `datapoint_not_supported` | `false` | n/a | Topograph does not return this datapoint for this country, in any mode. | Nothing to retry: the same request returns the same answer. Treat it as a final result. |
| `fast_source_unavailable` | `false` | n/a | The datapoint exists for this country, but not in prefill mode. | Resubmit without `mode: "prefill"`. |
| `authoritative_source_unavailable` | `false` | n/a | The datapoint exists for this country, but only from a non-authoritative source, which verification mode does not use. | Resubmit with `mode: "prefill"`. |
| `onboarding_timeout` | `false` | n/a | The datapoint did not finish within the prefill-mode deadline. | Resubmit without `mode: "prefill"`. |
| `no_data_available` | `false` | n/a | The register answered, but holds no data for this company and datapoint. | Nothing to retry: the same request returns the same answer. Treat it as a final result. |
| `no_document_available` | `false` | n/a | The requested document is not available for this company; failed document orders are not charged. | Nothing to retry: the same request returns the same answer. Treat it as a final result. |
| `manual_document_timeout` | `false` | n/a | A manually fulfilled document was not delivered within the expected timeframe. | Contact [support@topograph.co](mailto:support@topograph.co) with the request id. |
| `datapoint_not_applicable` | `false` | n/a | The datapoint does not exist for this entity's legal form, for example the shareholders of a sole trader. | Nothing to retry: the same request returns the same answer. Treat it as a final result. |
| `account_configuration_required` | `false` | n/a | The data source needs account-specific credentials that are not configured on your account. | Store the credentials on your account (see Register credentials), then resubmit. |
| `budget_exceeded` | `false` | n/a | The quoted price exceeds the budget cap set on the request. | Raise or remove the budget cap on the request, then resubmit. |
| `balance_negative` | `false` | n/a | The wallet balance is below zero; every request is refused until it is topped up. | Top up the wallet, then resubmit. |
`retryable: false` means the same request returns the same answer: do not retry it, and do not alert on the codes that are a legitimate "nothing to report" (see [Retrieve a company](/essentials/retrieve_company#not-every-failed-is-an-outage)). Switch on `error.code` or on `error.retryable`, never on `error.message`; messages change, codes and flags are stable.
### Retrying a retryable item
Five codes are retryable: `service_unavailable`, `source_unavailable`, `processing_failed`, `request_cancelled` and `processing_interrupted`. For those:
1. **A retry is a new `POST /v2/company`** with the same body, or with only the failed datapoints. Polling `GET /v2/company/{requestId}` reads the existing result; it never re-runs a failed item.
2. **Wait at least `retryAfterSeconds`** before the first retry. Double the delay on each further failure, add a little jitter so queued retries do not all fire together, and cap the delay at one hour.
3. **Give up after 24 hours.** Check [status.topograph.co](https://status.topograph.co/) for an ongoing incident, and contact support with the `requestId` if nothing is posted there.
The delay is guidance about how long the cause usually lasts, not a promise that it is fixed by then. In verification mode (the default) we have already retried the register for up to an hour before returning `source_unavailable`, so a quick retry rarely helps. In prefill mode the failure is fail-fast: resubmitting without `mode: "prefill"` is usually the better move.
HTTP `429` is different: it carries a `Retry-After` header, and [Concurrency & Backfills](/guides/concurrency-and-backfills) explains how to retry it while keeping capacity for live traffic.
### Handling "in progress" status
For the verification endpoint, data retrieval is asynchronous. You will initially receive a `200 OK` response with data status set to `in_progress`.
```json theme={null}
{
"request": {
"dataStatus": {
"dataPoints": {
"company": {
"status": "in_progress"
}
}
}
}
}
```
**Do not treat this as an error.** It means we have accepted your request and are working on it (including handling any necessary retries). Wait for the webhook.
Most datapoints resolve within the retry windows described above. A small number are [manually delivered](/essentials/manual-delivery) and typically take 1–3 business days. These stay `in_progress` during that time and do not hold a concurrency slot.
### Handling register instability
If you receive a `failed` status in your webhook payload with `code: "source_unavailable"`:
1. **Prefill mode**: This is usually final for that request. Ask the user to enter details manually, or resubmit without `mode: "prefill"`.
2. **Verification mode**: We tried for up to 1 hour and still could not reach the register, often a prolonged outage (for example weekend maintenance). Resubmit after `retryAfterSeconds`, backing off as described above.
## Breaking changes in a register
Registries occasionally introduce breaking changes such as new API versions, schema modifications, authentication updates, or structural changes to their data formats. These changes can temporarily disrupt data retrieval until we adapt our integration.
### Our response strategy
We maintain **strong monitoring** and **agile development processes** to detect and respond to registry changes quickly:
* **24-hour recovery target**: We aim to resolve breaking changes from registries within **24 business hours** of detection
* **Proactive monitoring**: Our systems continuously monitor register responses and API behavior to detect anomalies early
* **Rapid adaptation**: When breaking changes occur, our team prioritizes fixes to restore service as quickly as possible
### What this means for you
* **Temporary disruptions**: If a register has a breaking change, you may see more datapoints fail with `source_unavailable` until we adapt. Note that you never pay for failed requests!
* **Automatic recovery**: Once we've updated our integration, service will resume automatically, no action required on your end
* **Status updates**: Check [status.topograph.co](https://status.topograph.co/) for real-time updates during incidents.
If you experience persistent errors for a specific country, please contact support so we can assist in the most efficient way.
# Data Standardization
Source: https://docs.topograph.co/guides/standardization
How we map local register data to clean international standards
Every country has its own way of describing companies. A "limited liability company" is a "GmbH" in Germany, an "SARL" in France, and an "S.r.l." in Italy. Standard activity codes vary, from NACE (EU) to SIC (UK) to ISIC (Global).
Topograph standardizes this kind of datapoints so you can build one integration that works everywhere. This standardization is crucial because it enables you to:
* **Build consistent logic** across countries without country-specific conditionals
* **Compare companies** from different jurisdictions using the same classification systems
* **Integrate with downstream systems** that expect standardized formats
* **Reduce complexity** in your codebase by handling variations at the API level
**Prefill mode varies by country**: with [`POST /v2/company`](/essentials/retrieve_company)
and [`mode: "prefill"`](/essentials/modes), the depth of standardization depends on the
country. Some countries return the same standardized legal forms, roles and statuses as
verification mode. Others return only the register's local values for some of these fields, for
example a legal form without its ISO 20275 code or a role without its ISO 5009 code. Activity
codes are usually standardized in both modes. Use default verification mode (omit `mode` or use
`mode: "verification"`) when you need fully standardized data.
## 1. Legal Forms
Understanding a company's legal structure is fundamental to risk assessment, compliance, and business relationships. Different legal forms carry different liability implications, regulatory requirements, and governance structures. However, each country uses its own terminology and classification system, making cross-border comparisons difficult.
We map thousands of local legal forms to both a standardized English translation and an **ISO 20275 code**. The ISO 20275 standard (Entity Legal Forms) provides a globally recognized classification system maintained by GLEIF (Global Legal Entity Identifier Foundation). This enables precise identification and comparison of legal entity types across jurisdictions.
**How we do it**: We use AI-powered translation and semantic matching against the official ISO 20275 code list. We are on **version 1.6**, published 19 February 2026, which contains 3,599 entity legal forms across 200 jurisdictions in 130 countries. When available, we also perform vector similarity search against the GLEIF-maintained database to find the most accurate ISO code match.
**Example: Germany**
* **Local**: "Gesellschaft mit beschränkter Haftung"
* **ISO 20275**: `2HBR`
* **Standardized**: `Limited Liability Company`
The ISO 20275 standard is maintained by GLEIF and provides a comprehensive,
internationally recognized classification system. Learn more about [ISO 20275
Entity Legal Forms Code
List](https://www.gleif.org/en/lei-data/code-lists/iso-20275-entity-legal-forms-code-list).
## 2. Roles
Identifying who has legal authority to represent a company is critical for due diligence, contract execution, and compliance checks. However, role titles vary dramatically across languages and legal systems. What's called a "Manager" in one country might be a "Gérant" in France or a "Geschäftsführer" in Germany, each with subtly different legal powers.
We map these diverse role titles to a standardized English classification and, for legal representatives, assign an **ISO 5009 code**. ISO 5009 (Official Organizational Roles) provides a standardized way to identify organizational roles within legal entities, enabling consistent role-based analysis across jurisdictions.
**How we do it**: We use AI to translate role titles to English and classify them into standardized categories. For legal representatives, we perform semantic matching against the ISO 5009 code list, which is contextually aware of both the role title and the company's legal form (ISO 20275 code), ensuring accurate role classification. We are on **ISO 5009 version 1.0.0**, published June 2023 — the only edition GLEIF has released.
An ISO 5009 code identifies a role **within a specific legal form**, so the same
job title carries a different code depending on the company it is held in. The
examples below are each scoped to that country's private limited company:
| Local Title | Country | Legal form (ISO 20275) | Standardized Role | ISO 5009 Code |
| - | - | - | - | - |
| Gérant | France | SARL (`V9QP`) | Manager | `4BIJAS` |
| Geschäftsführer | Germany | GmbH (`2HBR`) | Managing Director | `O3E52H` |
| Amministratore Unico | Italy | S.r.l. (`OV32`) | Sole Director | `IGKI9C` |
Because coverage is scoped this way, a legal form GLEIF has no role rows for
returns a role with no `iso5009Code`. That is an honest gap rather than a
near-miss from a neighbouring legal form.
ISO 5009 codes provide standardized role identification within legal entities.
The standard is maintained by GLEIF and enables consistent role-based
analysis. Learn more about [ISO 5009 Official Organizational Roles Code
List](https://www.gleif.org/en/lei-data/code-lists/iso-5009-official-organizational-roles-code-list).
## 3. Activity Codes (Activity Mapping)
Economic activity classification is essential for industry analysis, market research, regulatory compliance, and risk assessment. However, countries use different classification systems: Italy uses ATECO, the UK uses SIC, Germany uses WZ codes, and France uses NAF/APE codes. Even within the EU, while NACE is the standard, local implementations vary.
We map these diverse local activity codes to international standards: **ISIC Rev.5** (the global standard) and **NACE Rev.2.1** (the European standard). This enables you to compare companies across borders, perform industry-level analysis, and integrate with systems that expect standardized activity codes.
### Mapping Process
Topograph uses AI to standardize the activity sector of companies through a two-step process, prioritizing **precision over recall**.
#### Step 1: Local Classifications → ISIC Rev.5
We use AI to map local activity codes to ISIC Rev.5.
**Priority order:**
1. **Local Classification Codes** (Primary source)
* Country-specific codes (e.g., ATECO for Italy)
* Sector-specific codes (e.g., SIC, RAE, SAE)
* Official business register classifications
2. **Activity Descriptions** (Fallback source)
* Free-text activity descriptions when no local codes are available
**Process:** AI analyzes the activity code and description together to find the most semantically similar ISIC code. We favour accurate matches over complete coverage.
#### Step 2: ISIC Rev.5 → NACE Rev.2.1
Formal mapping from ISIC to NACE. NACE Rev.2.1 is the European implementation of ISIC Rev.5, so the two share the same structure and the correspondence is deterministic.
* **100% coverage** of ISIC Rev.5 classes
* **Deterministic correspondence**, derived from the official UNSD and Eurostat structures
* Register-native NACE codes are upconverted to NACE Rev.2.1 from the official Eurostat transition table
### Both standards, always together
When an activity can be placed in the current standardized classifications, the response carries `ISIC` and `NACE`, using the official ISIC Rev. 5 to NACE Rev. 2.1 correspondence where available. The register's own code is retained under its national key. An unknown revision or an unsupported correspondence can leave only the native code; no standardized class is invented.
These are absent only when the source register exposes no activity data at all for the company, or
when none of the codes it holds can be placed honestly in the standards:
* a NACE Rev. 2 class whose Rev. 2.1 successors scatter across unrelated divisions, with no activity
description to choose between them (see
[When you need the register's own NACE class](#when-you-need-the-registers-own-nace-class));
* in Croatia, a code stamped NKD 1994, which predates Croatia's NACE alignment and so cannot be
crosswalked from;
* in Latvia, a pre-2008 NACE Rev. 1 or Rev. 1.1 code that cannot be placed in Rev. 2.
In each case the register's own code is still published under its own key. See
[Where two revisions run side by side](#where-two-revisions-run-side-by-side).
### Which version of each classification?
Two revisions are fixed platform-wide, for every country and every source:
| Key | Standard | Revision |
| - | - | - |
| `ISIC` | UN ISIC | **Rev. 5** |
| `NACE` | Eurostat NACE | **Rev. 2.1** |
These never vary by country. A register that publishes NACE Rev. 2 is upconverted to Rev. 2.1
using the official Eurostat transition correspondence before we publish it, so `activities.NACE`
is Rev. 2.1 even where the source is not.
Every other key is the register's **own** national code, published exactly as the register records
it. We do not restate, renumber, or re-version those.
#### Revision-explicit keys
Each classification and revision has one canonical response key. `ISIC` means Rev. 5 and `NACE` means Rev. 2.1. National keys name their revision when the source establishes it, such as `SIC_2007` for UK SIC.
```json theme={null}
"activities": {
"NACE": [{ "code": "62.10", "description": "Computer programming activities" }],
"ISIC": [{ "code": "621", "description": "Computer programming activities" }]
}
```
Source aliases are merged into the canonical key, keeping distinct codes and deduplicating repeated codes. For editions resolved per record, bare keys contain only unresolved records; they do not repeat the revision-key arrays.
Earlier responses could return several spellings for the same classification. Current responses return only the canonical key. Update consumers of earlier spellings using the table below. See [alternate spellings](/essentials/activity-codes#alternate-spellings).
| Earlier or source key | Current response key | Country | Classification and revision |
| - | - | - | - |
| `ISIC_REV5` | `ISIC` | all | International Standard Industrial Classification, Rev. 5 |
| `NACE_REV21` | `NACE` | all | NACE, Rev. 2.1 |
| `ISAT` | `ISAT_2008` | Iceland | ÍSAT 2008, including the register’s national subclass digit |
| `KD` | `KD_BIH_2010` | Bosnia and Herzegovina | KD BiH 2010, the register’s NACE Rev. 2 harmonisation |
| `NACE_BEL` | `NACE_BEL_2003` / `NACE_BEL_2008` / `NACE_BEL_2025` | Belgium | NACE-BEL, per the version the register stamped |
| `WZ2008` | `WZ_2008` | Germany | Klassifikation der Wirtschaftszweige 2008 |
| `WZ2025` | `WZ_2025` | Germany | Klassifikation der Wirtschaftszweige 2025 |
| `DBR` | `DB25` | Denmark | Dansk Branchekode 2025 |
| `CNAE` | `CNAE_2009` | Spain | CNAE-2009 |
| `EMTAK` | `EMTAK_2008` / `EMTAK_2025` | Estonia | EMTAK, per the edition stamped on each assignment |
| `TOL` | `TOL_1995` / `TOL_2002` / `TOL_2008` / `TOL_2025` | Finland | Toimialaluokitus, per the edition the register stamped on the company's code |
| `NAFREV2` / `NAFRev2` | `NAF_REV2` | France | NAF rév. 2 (code APE) |
| — | `NACE_REV2` | France, Latvia, Malta, Ireland, Estonia | NACE Rev. 2 — the register's own class, see [When you need the register's own NACE class](#when-you-need-the-registers-own-nace-class) |
| — | `NACE_REV1` / `NACE_REV11` | Latvia | NACE Rev. 1 / Rev. 1.1 — the register's own pre-2008 class, per the revision it stamped |
| — | `NAF_2025` | France | NAF 2025 (INSEE's implementation of NACE Rev. 2.1), the code INSEE has assigned the company — provisional until 2027-01-01, see [France](https://www.topograph.co/countries/fr#activity-code-mapping) |
| `SIC` | `SIC_2007` | United Kingdom | UK SIC 2007 |
| `KAD` | `KAD_2025` | Greece | ΚΑΔ 2025 |
| `NKD` | `NKD_1994` / `NKD_2007` / `NKD_2025` | Croatia | NKD, per the revision the entry was filed under |
| `TEÁOR` | `TEAOR_2008` / `TEAOR_2025` | Hungary | TEÁOR, per the nomenclature the extract stamps on each entry |
| `ATECO` | `ATECO_2007` | Italy | ATECO 2007 (aggiornamento 2022) |
| `ATECO2025` | `ATECO_2025` | Italy | ATECO 2025 |
| `CAEN` | `CAEN_REV2` / `CAEN_REV3` | Romania | CAEN, per the revision stamped on each assignment |
| `CAEM-1.1` | `CAEM_REV11` | Moldova | CAEM Rev. 1.1 |
| `CAEM-2` | `CAEM_REV2` | Moldova | CAEM Rev. 2 |
| `SBI_2025` | `SBI` | Netherlands | No guaranteed edition; current active registrations use 2025, but historical and deregistered records can retain 2008 |
| `CAE` | `CAE_REV3` | Portugal | CAE Rev. 3 |
| `OKVED` | `OKVED_REV2` | Russia | OKVED Rev. 2 (ОК 029-2014) |
| — | `SNI_2025` | Sweden | SNI 2025 (Statistics Sweden's implementation of NACE Rev. 2.1) |
| `KVED` | `KVED_2010` | Ukraine | KVED-2010 |
`SBI` does not guarantee an edition. Check historical and deregistered records against the register before assigning a year.
These are the revisions the **registers** serve, which is not always the revision the national
statistics office has most recently adopted. The two routinely disagree, in both directions: a
register can serve an older revision for years after a new one is published, and sometimes the
register moves first. The Dutch Handelsregister converted every active registration to SBI 2025
in September 2025 while CBS is still phasing SBI 2025 into its own statistics through 2029.
#### Where two revisions run side by side
Belgium, Estonia, Croatia, Hungary, Romania and Latvia stamp each activity record with the revision it was filed
under, so a single company can carry codes from more than one. Rather than average that into one
answer, you get a key per revision:
* **Belgium.** The register's activity file marks every row `2003`, `2008` or `2025`, so the codes
arrive under `NACE_BEL_2003`, `NACE_BEL_2008` or `NACE_BEL_2025` accordingly.
* **Estonia.** RIK stamps each assignment with its EMTAK edition. EMTAK 2025 feeds standardized `NACE` directly; explicitly labelled EMTAK 2008 also preserves the declared class under `NACE_REV2` before transition. Unknown or conflicting editions retain native `EMTAK` and `NACE_EE`, without a guessed standardized class.
* **Romania.** ONRC assignments stamped Rev. 2 or Rev. 3 retain their national codes under `CAEN_REV2` or `CAEN_REV3`. Only recognized revisions feed the corresponding formal NACE transition.
* **Croatia.** The court register stamps each business-scope entry, giving `NKD_1994`, `NKD_2007`
or `NKD_2025`. A company filed across revisions returns one key for each. NKD 2007 and NKD 2025
are Croatia's NACE Rev. 2 and Rev. 2.1 transpositions, so both also feed `NACE`; codes stamped
NKD 1994 predate that alignment and are excluded, since reading one as Rev. 2 would produce a
class the register never declared.
* **Hungary.** The company extract stamps every activity `'08` (TEÁOR'08, the NACE Rev. 2
implementation) or `'25` (TEÁOR'25, the Rev. 2.1 one), so the codes arrive under `TEAOR_2008` or
`TEAOR_2025`. Only the `'08` entries are transitioned on their way into `NACE`.
* **Latvia.** The Enterprise Register stamps every NACE code `1`, `1.1` or `2`. Rev. 2 codes arrive
under `NACE_REV2` and are transitioned into `NACE`. Pre-2008 codes arrive under `NACE_REV1` or
`NACE_REV11` exactly as declared; where a model can place one in Rev. 2 it also reaches `NACE`,
marked `isAIInferred: true`, and where it cannot, the register's own code is still there rather
than dropped.
* **Malta.** The Business Registry records one area of activity per entity, from its own NACE Rev. 2
list. It arrives under `NACE_REV2` as declared and is transitioned into `NACE`.
#### Where we do not state a revision
The following keys have no revision-explicit sibling. The response does not identify their edition, so do not assign a revision from the key alone:
| Key | Country | Why |
| - | - | - |
| `CAE_QC` | Canada, Quebec | The register’s own economic activity codes, without an edition marker on the enterprise record. These are distinct from Portuguese CAE. |
| `NAICS` | US states | Each state records the NAICS vintage current when the entity registered and does not publish which one. The code is passed through exactly as the state holds it. |
| `NACE_SK` | Slovakia | Retains the register’s activity assignment when its code-list marker does not establish a recognized NACE edition. |
| `SSIC` | Singapore | The retrieved ACRA company dataset does not identify the edition on each record; native assignments are retained without asserting a revision. |
| `PKD` | Poland | The registers publish PKD codes without stating the revision, and PKD 2007 and PKD 2025 overlap in code shape. |
| `CAEN` | Romania | CAEN preserves older or unstamped assignments; recognized Rev. 2 and Rev. 3 stamps publish only `CAEN_REV2` or `CAEN_REV3`. |
| `NACE_EE` | Estonia | The original source NACE string, retained across editions, including unknown or unstamped legacy records. |
| `NKID` | Bulgaria | Recording an NKID code is optional and it is never retroactively migrated, so a filed code may be КИД-2003, КИД-2008 or КИД-2025 depending only on when the company last amended it. |
| `NAF` | any | Emitted by our AI profile parser rather than read from a French register, so the key does not fix a revision. France's own register code is `NAF_REV2`. |
| `RNA` | France | The associations register's nomenclature des objets sociaux describes association purposes. We publish no revision identifier; label it as RNA without a year. |
Country-specific revision keys are published on the [pricing page](https://topograph.co/pricing) and in `/v2/catalog` under `activityCodes.responseKeys`. That field lists declared canonical classification keys, rather than every possible response key, such as unstamped and association-purpose classifications. See the [activity-code page](/essentials/activity-codes#alternate-spellings) for spelling compatibility.
If you need one revision you can rely on across every country without tracking national
transitions, read `ISIC` or `NACE`. The national keys are there for round-tripping
back to the register, not for cross-border comparison.
### One code in, one code out
**We never publish an activity the register did not declare.** You get one standardized class per
declared code — never a list of candidates we could not choose between.
This matters because classification systems do not line up one-to-one. When a company's declared
class maps to several classes in the target standard, the true one is unknowable from the code
alone. Rather than return all of them, we return the most precise class the correspondence actually
supports:
| The declared code maps to | What you get |
| - | - |
| Exactly one class in the target standard | That class |
| Several classes in the same group | Their shared group (for example `64.2` rather than guessing `64.21` or `64.22`) |
| Several classes across different groups or divisions | Their shared division (for example `47`) |
| Classes scattered across unrelated divisions | No standardized code — the register's own local code only |
A shorter code is not missing data: `64.2` means the register told us the company is a holding
company but not which kind. It is the most specific statement the source supports. The register's
own code is always published in full alongside it.
The one exception is when the register also publishes a free-text activity description. That is
independent evidence about the actual trade, so we use it to pick the precise class — and mark the
result `isAIInferred: true` so you can tell it apart from a formal mapping.
#### When you need the register's own NACE class
Upconverting to Rev. 2.1 is the right default, but it has a hard limit: **Rev. 2.1 deleted some
Rev. 2 classes**. `86.90` has no Rev. 2.1 class of its own, so the most precise standardized answer
is the group `86.9`; for 17 further classes the successors scatter across unrelated divisions and
there is no honest Rev. 2.1 code at all, so `activities.NACE` is absent.
Where the register itself publishes NACE Rev. 2, we also publish that class verbatim under
**`NACE_REV2`**. Today that includes France, Latvia, Malta, Ireland and Estonia’s explicitly labelled EMTAK 2008 assignments. In France, NAF rév. 2 *is* the French implementation of NACE
Rev. 2 — an APE code's first four digits are the Rev. 2 class, the trailing letter a French
subdivision below it — so the key is present on every French company whose APE code we hold:
```json theme={null}
"activities": {
"NAF_REV2": [{ "code": "8690F", "description": "Activités de santé humaine non classées ailleurs" }],
"NACE_REV2": [{ "code": "86.90", "description": "Other human health activities" }],
"NACE": [{ "code": "86.9", "description": "Other human health activities" }]
}
```
Read `NACE_REV2` when you need a 4-digit class for every company and can accept the older revision;
read `NACE` when you need one revision you can compare across countries. They are
different revisions of the same classification, so never mix them in one field: `86.90` is not a
NACE Rev. 2.1 code and `86.9` is not a Rev. 2 class.
#### The register's own answer beats any table
Where the register itself publishes the company's class in the target revision, we read that and convert
nothing. France is the worked case: INSEE assigns every active company its **NAF 2025** code — the French
implementation of NACE Rev. 2.1, i.e. a Rev. 2.1 class with one French letter appended — and publishes it in
Sirene ahead of the 2027 cutover. A code-level correspondence can only say where a *code* went; INSEE says
where the *company* went, and the two differ whenever INSEE recoded the company on its actual activity
(a consultancy filed as `62.02A` that INSEE recoded to `73.12Y`, media representation). So for France,
`NACE` is the first four digits of the NAF 2025 code, the code itself is published under `NAF_2025`, and the
rules below only apply to the small population INSEE has not assigned one (units still coded in
pre-2008 nomenclatures, almost all ceased).
#### National sub-classes are used as evidence
Some registers publish a code that is *finer* than the standard class it sits in. France's APE/NAF
code is the clearest case: `8690F` is the NACE Rev. 2 class `86.90` plus a French sub-class letter,
and the letter says something the class does not.
Where the national statistics office publishes an official correspondence for those sub-classes, we
resolve through it rather than through the class. So `6420Z` returns NACE `64.21` (INSEE maps that
sub-class to a single Rev. 2.1 class) instead of the group `64.2` the bare class `64.20` would give.
The sub-class is only preferred when it names exactly one class; when it straddles several, the
class-level answer stands. Both codes are always published, so you can see the reasoning:
`activities.NAF_REV2` holds the register's own code and `activities.NACE` the standardized class.
If you previously filtered or de-duplicated `activities.NACE` and `activities.ISIC` yourself to
work around long lists, that logic is no longer needed. Counts are now proportional to what the
register declared: a company with three declared activities returns three NACE and three ISIC
codes, not several dozen.
### The main activity
Many registers designate one activity as the company's **main** (primary, prevailing) activity —
Belgium's `MAIN` classification, Poland's *działalność przeważająca*, Croatia's *pretežita
djelatnost*, Hungary's *főtevékenység*, and others — and some registers publish only the main
activity in the first place (France's APE code, Finland's main business line).
Where the register makes that distinction, the corresponding activity item carries
`isMainActivity: true`, and every code derived from it (NACE, ISIC, local crosswalks) inherits the
flag. At most one code per classification carries it, so
`activities.NACE.find(a => a.isMainActivity)` is a safe way to pick one code per company.
Where activity codes are AI-inferred from a free-text activity description, the single best-match
code is flagged as the main activity and is marked `isAIInferred: true` alongside, so a
register-declared main activity is always distinguishable from an inferred one.
Absence of `isMainActivity` means the register does not say — not that the code is secondary. Do
not rely on array order to identify the main activity; the flag is the only guaranteed signal.
### Example: Italy
Italy's register publishes a company's ATECO 2025 code together with its NACE class. ATECO 2025 is
Italy's implementation of NACE Rev. 2.1, so the NACE class is published as the register declared it,
and ISIC Rev. 5 is derived from it through the official correspondence. No AI step is involved, so
the ISIC code is `isAIInferred: false`, and the main-activity flag carries over to every derived
code. Each classification appears under its canonical key.
### API Response
```json theme={null}
{
"activities": {
"ATECO_2025": [
{ "code": "01.11", "description": "Growing of cereals", "isMainActivity": true }
],
"NACE": [
{ "code": "01.11", "description": "Growing of cereals", "isMainActivity": true }
],
"ISIC": [
{
"code": "0111",
"description": "Growing of cereals (except rice), leguminous crops and oil seeds",
"isAIInferred": false,
"isMainActivity": true
}
]
}
}
```
## 4. Addresses
Addresses are critical for verification, communication, and compliance (especially for KYC/AML requirements), but registries store them as unstructured text strings in various formats. Parsing addresses correctly is challenging because formats vary by country, and components like street numbers, postal codes, and administrative divisions are positioned differently.
We parse and structure unstructured address strings into standardized component parts, enabling you to validate addresses, perform geocoding, and integrate with address validation services without writing country-specific parsing logic.
**How we do it**: We use pattern recognition and country-specific parsing rules to extract address components, then normalize them according to international standards. Country codes follow ISO 3166-1 alpha-2 format for consistency.
* Street
* House Number
* Postal Code
* City
* Country (ISO 3166-1 alpha-2)
## 5. Status
Company status information is crucial for risk assessment. You need to know if a company is active, dissolved, in liquidation, or bankrupt before entering into business relationships. However, registries use different terminology and status codes, and some countries have complex status hierarchies that don't map cleanly to simple active/inactive states.
We normalize company status to a simple active/inactive boolean plus a standardized status enum, a closure reason, and key dates. This makes it easy to filter and reason about company status across jurisdictions without learning each country's specific status terminology.
**How we do it**: We map local status codes and descriptions to a three-layer model (boolean `active`, raw `localName`, and standardized `statusDetails`), preserving the original status information while providing a clean cross-country view.
* **`active`**: `true` / `false` (omitted when the register's status cannot be classified)
* **`statusDetails.status`**: `ACTIVE`, `UNDER_INSOLVENCY_PROCEEDING`, `INACTIVE_NOT_CLOSED`, `PENDING_DISSOLUTION`, `CLOSED`, `UNKNOWN`
* **`statusDetails.closureReason`** (when closed or under insolvency): `BANKRUPTCY`, `LIQUIDATION`, `VOLUNTARY_DISSOLUTION`, `ADMINISTRATIVE_DISSOLUTION`, `COURT_ORDER`, `MERGER`, `SPLIT`, `ACQUISITION`, `OTHER`, `UNKNOWN`
See the [Company Status guide](/guides/company-status) for the full model and usage patterns.
# Test Country (deprecated)
Source: https://docs.topograph.co/guides/test-country
Superseded by development environments
**Deprecated.** Use a [development environment](/guides/development-environment)
instead. It covers what `TEST` covers, except the `graph` datapoint, and does
it for **every country we support**, with that country's real identifier
formats, legal forms, roles and document catalog, so what you build against
behaves like the country you will actually query, not like a placeholder. It
understands the error, delay, `GRAPH_SIMPLE`, `GRAPH_CHAIN` and `GRAPH_UBO`
identifiers documented below (`GRAPH_EMPTY` becomes `GRAPH_NONE`; the
circular, wide, mixed and deep structures exist only in `TEST`), plus many
more, and it never costs real money: requests bill real prices against a free
virtual wallet.
`TEST` keeps working and is not going away without notice. New integrations
should not start here.
The `TEST` country allows you to test your integration without making real requests to external registries. It returns predictable mock data instantly.
## Basic Usage
Use country code `TEST` with any company ID. Special IDs trigger specific behaviors:
```bash theme={null}
curl -X POST https://api.topograph.co/v2/company \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"countryCode": "TEST", "id": "SUCCESS-12345", "dataPoints": ["company", "legalRepresentatives"]}'
```
## Search
Search returns your query plus example test IDs you can use:
```bash theme={null}
curl -G https://api.topograph.co/v2/search \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "country=TEST" \
--data-urlencode "query=my-company"
```
## Test Company IDs
### Success Cases
Any ID that doesn't match an error pattern returns a valid company:
| Company ID | Description |
| - | - |
| Any valid ID | Returns a complete company response |
### Error Cases
Use these IDs to test every error response your integration needs to handle:
| Company ID | Error Code | Message | HTTP Status |
| - | - | - | - |
| `RESOURCE_NOT_FOUND` | `resource_not_found` | The requested resource was not found. Please verify the identifier and try again. | 404 |
| `INVALID_REQUEST` | `invalid_request` | Invalid request. Please check the request parameters and try again. | 400 |
| `PROCESSING_FAILED` | `processing_failed` | Unable to process the request. Please try again later. | 422 |
| `SERVICE_UNAVAILABLE` | `service_unavailable` | Service temporarily unavailable. Please try again in a few moments. | 503 |
These error IDs work across all request types: company data, available documents, and document downloads. Use them as the `id` to trigger errors on any datapoint or document retrieval.
### Delivery Delays
By default the `TEST` country responds instantly. To test how your integration handles slow requests, such as polling, timeouts, and loading states, use an ID containing a `DELAY_` token. The request stays pending for the given duration, then returns successful data.
| Company ID | Delivery delay |
| - | - |
| `DELAY_1M` | 1 minute |
| `DELAY_10M` | 10 minutes |
| `DELAY_1H` | 1 hour |
| `DELAY_10H` | 10 hours |
The delay applies to both company data and document downloads. Each request to the `TEST` country runs independently, so the same ID triggers the full delay every time, including on repeated and concurrent requests. You can still add a `-` or `_` separated suffix such as `DELAY_1M-001` to label requests in your own logs.
The token also combines with the `GRAPH_` prefixes below. `GRAPH_CHAIN_DELAY_1M` delays every company resolved in the ownership graph. Use the shorter durations (`1M`, `10M`) for graph IDs, since the delay applies to each company in the chain.
### Documents
All test companies return a free "Trade Register Extract" document.
### Graph/Ownership Testing
IDs starting with `GRAPH_` return specific ownership structures:
| Company ID | Description |
| - | - |
| `GRAPH_SIMPLE_001` | 2 individual shareholders (30%, 20%) |
| `GRAPH_CHAIN_001` | Company → Company → Individual chain |
| `GRAPH_UBO_001` | Clear UBO structure (51%, 25%, 24%) |
| `GRAPH_CIRCULAR_001` | Circular ownership (A owns B owns A) |
| `GRAPH_WIDE_001` | 5 individual shareholders (15% each) |
| `GRAPH_MIXED_001` | 2 individuals + 2 company shareholders |
| `GRAPH_DEEP_001` | Deep chain up to 3 levels |
| `GRAPH_EMPTY_001` | Company with no shareholders |
These IDs work with the `shareholders`, `ultimateBeneficialOwners`, and `graph` data points:
* `shareholders` returns the direct shareholders of the company.
* `ultimateBeneficialOwners` returns the individual shareholders holding 25% or more. For `GRAPH_UBO_001` this is the 51% and 25% holders; the 24% holder is excluded.
* `graph` returns the full ownership tree, recursing through company shareholders and flagging beneficial owners on the individual nodes.
# Topograph Wizard
Source: https://docs.topograph.co/guides/topograph-mcp
Give Claude Code, Cursor and other AI coding agents live Topograph coverage, pricing, docs and code samples while they build your integration.
**Beta.** The Topograph Wizard is in beta. Tools and behaviour may change during this period.
Company data is complex: dozens of countries and US states, each with its own registers, identifiers, modes and data quirks. The Topograph Wizard plugs into your AI coding agent (Claude Code, Cursor, or any MCP-aware editor) so it pulls live coverage, pricing and integration methodology on demand. Ask questions in plain English, get grounded answers, and ship your integration in an afternoon.
The Wizard is an integration helper. It reads the public catalog and documentation and never runs a billed request. To look up actual companies from your agent, use the [Topograph MCP](/guides/mcp) instead.
**Two commands and you're in.** In Claude Code:
```
/plugin marketplace add getsemaphore/topograph-mcp-library
/plugin install topograph@topograph
```
The plugin installs both servers: the Wizard and the [Topograph MCP](/guides/mcp) for company data. Run `/mcp` and sign in with Topograph the first time.
The Wizard's address is `https://mcp.topograph.co/wizard`. It used to be called the Designer MCP, at `https://api.topograph.co/designer-mcp`; that address keeps working, so existing setups need no change.
## What you can ask
These prompts work today and call the right tools and rules under the hood:
```text Sample prompts theme={null}
"Does France have UBO data? What about Italy and the UK?"
"How do I authenticate? Walk me through getting an API key
and making my first call."
"What's the difference between prefill mode and verification
mode, and when do I use each?"
"What does Topograph cover in Germany for company + UBOs,
and what response fields will I get back?"
"Write me a Node.js example that searches a French company,
then fetches its profile with progressive results."
"How do I handle webhooks for /v2/company? Which event tells
me a request is fully done?"
"I'm a fintech reselling Topograph KYB to my customers. How
do I attribute usage per end-client for rebilling?"
"How do I test my integration end-to-end without hitting real
registers?"
"What's the canonical KYB onboarding flow with Topograph,
from signup search to compliance record?"
"How do I cap a single /v2/company request so a deep
ownership graph stays within a known bound?"
```
Each answer is grounded in live data from the Topograph catalog and the canonical integration rules, not in training data that may be months out of date.
## Why it's better than reading docs
Coverage, identifiers, datapoints, legal forms, roles, and pricing are pulled live from the catalog. You'll never get an answer based on stale documentation.
The Wizard ships with the canonical patterns: search-first identifier resolution, prefill vs verification phasing, webhook terminal detection, budget caps, and more.
Example snippets are derived from the OpenAPI spec. No hallucinated endpoint paths, no fabricated request shapes.
Your agent works alongside your existing code: pull data, write the integration, run it, iterate. No copy-pasting from a docs tab.
## Country-specific integration data
Call `get_country` with the country code (for example, `{"cc":"FR"}`) to retrieve its public manifest. The same manifest is available through the `topograph://countries/FR` resource. Use it when mapping a country into your own model; use `get_openapi` with `path: "/v2/company"` and `includeSchemas: true` for the company API response schema. Country-specific manifest fields include:
* `identifiers`: accepted identifiers, their formats and examples, whether they are primary or searchable, and the matching `company.identifiers` response key when Topograph returns one.
* `activityCodes`: `responseKeys` lists revision-specific `company.activities` keys with their versions, `isLatest`, and `supersedes`. `unversionedKeys` lists keys whose revision is unknown, with a reason. Legacy aliases are not enumerated here.
* `enums`: maintained country enum sets: `legalForms`, `legalFormsOnboarding`, `roles`, `companyStatuses`, `registerCourts` (local courts or offices), and `registerTypes` (register sections).
* `complianceSignals`: register-reported compliance flags and statutory-filing fields available for the country.
* `registers` and `dataBlocks`: public register descriptions, supported datapoints, entity types, modes, and their applicability notes.
* `countryDocuments`: document types and names, including `subType` and `appliesTo` where supplied. `subType` matches the response item's `subType`. `otherDocuments` lists additional document names and descriptions.
* `developmentStatus` and `availableOnRequest`: integration maturity and capabilities available on request, where listed.
* `performance`: indicative search, datapoint, and document timings. Datapoint timings describe source speed, not end-to-end request turnaround.
Each enum set contains `values` and `sources`. Legal forms and roles include `code`, `source` (the code system), `localName`, `standardized`, and optionally `englishName`. Legal forms may include `iso20275Code` and `isDiscontinued`. Roles include `isLegalRepresentative` and `isOtherKeyPerson`, and may include `iso5009Mappings` with `oorCode`, `elfCode`, and optional `legalBasis`. A role can have several ISO mappings depending on the legal form; match `elfCode` to the legal form's `iso20275Code` where available.
`companyStatuses.values` contains strings. `registerCourts.values` contains `localName`, which can form part of a registration identifier. `registerTypes.values` contains `code`, `localName`, and optionally `englishName` and `scope`. Identifier `appliesTo` and `activityCodes.local[].appliesTo` describe the entity types to which an entry applies; when omitted, the entry applies to all covered entity types.
In `complianceSignals`, `flags.values[].kind` identifies a `company.complianceFlags` entry. `reportsNegative: true` means the register can explicitly report `active: false`; absence is not the same as a negative result. `statutoryFilings.values[].kind` identifies an entry in `company.statutoryFilings`, and `fields` lists relative paths such as `lastFiled.filedOn`. Optional `cadence` and `note` explain its filing cycle and limitations.
Data-block modes describe `fast`, `authoritative`, datapoint subsets, caveats, and routing notes. Their source references identify entries in `registers`; consult per-datapoint details and routings as well as defaults. A `cached` flag describes a non-authoritative cached mode, not a freshness guarantee. A block's `requiredCredential` identifies the public register credential `sourceKey` and whether it is mandatory for that fetch or enhances completeness. See [register credentials](/essentials/register-credentials) for setup and fallback behavior.
`legalForms` describes verification values. When `legalFormsOnboarding` is absent, use `legalForms` for all modes. When present, it supplies the prefill-specific values. Read the provenance in `sources` for scope and completeness: some sets contain observed values rather than an exhaustive closed list.
```text theme={null}
"For France, list the identifiers and response keys, activity-code keys,
legal forms, company roles, and company statuses I need to map."
```
An absent optional field does not by itself prove the underlying company data is unavailable. For example, an identifier without `key` may be accepted for lookup but not echoed in `company.identifiers`. Consult the field-specific meaning and country coverage. `list_countries` only returns summaries, and `find_data` does not search enum values or identifier keys; use `get_country` for these mappings.
## When the Wizard earns its keep
Use it when you would otherwise be context-switching to docs:
* Onboarding a country you've never integrated before
* Sizing volume against country coverage and capability
* Designing async delivery (webhooks vs polling, terminal-event detection)
* Picking the right datapoint mix for KYB vs onboarding flows
* Debugging "why am I getting this error / why is this datapoint missing?"
* Reviewing an existing integration against the canonical methodology
* Writing tests against a development environment (or the deprecated TEST country)
For one-off questions, the regular docs are still the right tool. For real integration work, the Wizard is faster.
## What's inside
Tools your agent will call:
* `list_countries`, `get_country`, `find_data`: live country and capability catalog.
* `get_pricing`: public per-country prices for any data block.
* `search_docs`, `get_doc`: search and fetch documentation pages.
* `get_openapi`: endpoint definitions straight from the OpenAPI spec.
* `example_snippet`: copy-paste snippets in curl, Node, Python, or Go.
* `whoami`, `my_pricing_simulations`, `personalized_quote`: pricing simulator quotes tied to your Topograph login.
Built-in integration rules your agent reads:
* Onboarding methodology: the five-step KYB flow from search to audit.
* Search-first resolution: turning fuzzy user input into a canonical company ID.
* Prefill vs verification mode: picking the right one per call.
* Webhooks: signed delivery, progressive payloads, terminal-event detection.
* Workspaces: required for resellers, end-client attribution and rebilling.
* Budgets: `maxBudget`, `profileMaxBudget`, `graphMaxBudget`.
* TEST country (deprecated): magic identifiers for deterministic testing.
* Data blocks, documents, common pitfalls, and country coverage matrix.
## Install: other clients
If your client supports HTTP MCP servers and OAuth discovery, point it at the endpoint directly:
```json theme={null}
{
"mcpServers": {
"topograph-wizard": {
"type": "http",
"url": "https://mcp.topograph.co/wizard"
}
}
}
```
In Claude Code without the plugin:
```bash theme={null}
claude mcp add --transport http topograph-wizard https://mcp.topograph.co/wizard
```
Your client will prompt you to sign in with Topograph the first time it queries the Wizard. Any Topograph login works, and no API key is needed: the Wizard only reads the public catalog and your own pricing simulations. Your application still calls the Topograph API with its own API key, and the [Topograph MCP](/guides/mcp) uses your organisation's access when your agent looks up companies.
## Public repository
The plugin, with both the Wizard and the Topograph MCP, is published from the public marketplace repository:
[github.com/getsemaphore/topograph-mcp-library](https://github.com/getsemaphore/topograph-mcp-library)
The source is mirrored from Topograph's monorepo on every release.
## Related
* [Use Topograph from your AI agent](/guides/mcp): the Topograph MCP for company data
* [Quickstart](/quickstart)
* [Coverage and pricing](/essentials/coverage-and-pricing)
* [Verification vs prefill mode](/essentials/modes)
* [Webhooks](/guides/webhooks)
* [Workspaces](/essentials/workspaces)
* [Development environments](/guides/development-environment) (the TEST country is deprecated)
Country manifests include `complianceSignals.flags.values`: covered compliance flag keys, country-specific descriptions, source registers, reported fields, negative-answer semantics, and request paths (`providedBy`). Search flag keys or their descriptions with `find_data`. `get_pricing` includes country coverage and filters covered flags to the requested catalog item when a SKU is supplied. Country resources and `get_country` expose the same country-owned metadata.
# Webhooks
Source: https://docs.topograph.co/guides/webhooks
Securely receiving asynchronous updates for company data and monitoring
Topograph uses webhooks to notify you about asynchronous events:
1. **Data Retrieval**: When company data or documents are ready (verification data).
2. **Monitoring**: When a monitored company changes (Monitoring API), or when a monitored datapoint is paused or resumed because of register credentials.
3. **Billing**: Low balance, high usage and auto top-up events. See [Billing notifications](/guides/billing-notifications).
## Configuration
You configure webhooks in the [Topograph Dashboard](https://app.topograph.co) under **Settings & More > Webhooks**.
## Verification (Security)
You should verify every webhook to ensure it actually came from us.
### 1. Get your signing secret
You can find your endpoint's signing secret (starting with `whsec_`) in the Dashboard.
### 2. Verify the signature
We include headers in every request to allow verification:
* `svix-id`: Unique message ID
* `svix-timestamp`: Timestamp
* `svix-signature`: The signature itself
Use a standard webhook signature verification library or your own HMAC verification code to verify these headers.
```javascript theme={null}
const secret = 'whsec_...';
const headers = req.headers;
const payload = req.body;
const evt = verifyWebhookSignature(payload, headers, secret);
```
## Event Types
### `company.updated`
Sent when company data is retrieved or updated. Webhooks are sent progressively as data becomes available - you may receive multiple webhooks for the same request as different data points complete. The payload matches the response you get by calling `GET /v2/company/{requestId}`, plus an added `type` field.
```json theme={null}
{
"type": "company.updated",
"request": {
"companyId": "932884117",
"countryCode": "FR",
"requestId": "86c082a6-c9a0-4243-87d8-7ae18f0ee13a",
"version": 7,
"dataStatus": {
"dataPoints": {
"company": { "status": "succeeded", "authoritative": true },
"availableDocuments": { "status": "in_progress" }
}
}
},
"company": {
"id": "932884117",
"countryCode": "FR",
"legalName": "TOPOGRAPH",
"status": {
"localName": "Immatriculée",
"active": true,
"statusDetails": {
"status": "ACTIVE"
}
},
"legalAddress": {
"addressLine1": "123 Rue Example",
"city": "Paris",
"postalCode": "75001",
"countryCode": "FR"
}
},
"documents": {
"tradeRegisterExtract": {
"id": "1c932de4-4610-5506-b48d-4e62529d58e8",
"name": "Extrait Kbis",
"format": "pdf",
"url": "https://..."
}
}
}
```
**Key fields:**
| Field | Description |
| - | - |
| `type` | Event type identifier (`company.updated`) |
| `request.requestId` | Unique identifier to correlate webhooks with your original request |
| `request.version` | Monotonic snapshot version for this `requestId`. A higher value is a newer snapshot. Use it to discard stale, out-of-order deliveries (see [Ordering and duplicate delivery](#ordering-and-duplicate-delivery)). |
| `request.metadata` | The key-value pairs you provided when creating the request, echoed back so you can map the webhook to your internal records |
| `request.dataStatus` | Status of each data point (`succeeded`, `in_progress`, `enriching`, `failed`). `enriching` means the datapoint is in progress with an intermediate AI enrichment result available. |
| `company` | Core company information |
| `ultimateBeneficialOwners` | Array of beneficial owners (when available) |
| `legalRepresentatives` | Array of legal representatives (when available) |
| `shareholders` | Array of shareholders (when available) |
| `documents` | Retrieved documents with signed download URLs |
### `monitor.notification`
Sent when a monitored company changes status or details.
```json theme={null}
{
"type": "monitor.notification",
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T14:23:45.678Z",
"changeCategories": ["status", "address"],
"monitorHasBeenDeactivated": false,
"metadata": {
"caseId": "case-12345"
}
}
```
`metadata` echoes the key-value pairs you set when creating the monitor (`POST /v2/monitors`). Use it to map the notification back to your internal records. The field is only present when the monitor has metadata.
**Change categories:**
* `status` - Company status changed (active, dissolved, etc.)
* `address` - Legal address changed
* `ownership` - Shareholders or UBOs changed
* `financial` - Capital or financial information changed
* `legalRepresentatives` - Legal representatives or directors changed
* `other` - Other changes detected
* `disappeared` - Company no longer found in register
**Testing it:** the portal's sample payload carries no real monitor id and no metadata, so it can't exercise an integration that routes on either. To receive a genuine event on demand, use **Send Test Notification** on a monitor's page in the dashboard, or `POST /v2/monitors/{monitorId}/test-notification`. See [Monitoring](/essentials/monitoring#step-4-test-your-integration).
### `monitor.datapoint_blocked` and `monitor.datapoint_unblocked`
Sent when a monitored datapoint that needs your own [register credentials](/essentials/register-credentials) stops being checked because the credentials are missing (`monitor.datapoint_blocked`), and again when it resumes after you configure them (`monitor.datapoint_unblocked`). Each fires once per transition, not on every recheck.
```json theme={null}
{
"type": "monitor.datapoint_blocked",
"monitorId": "clh3k9n0x000008l63vog8wkp",
"companyId": "932884117",
"countryCode": "FR",
"timestamp": "2025-09-26T14:23:45.678Z",
"datapoint": "ultimateBeneficialOwners",
"status": "blocked_missing_credentials",
"message": "ultimateBeneficialOwners requires account-specific credentials that have not been configured. ...",
"metadata": {
"caseId": "case-12345"
}
}
```
`status` is `blocked_missing_credentials` on `monitor.datapoint_blocked` and `active` on `monitor.datapoint_unblocked`. `metadata` follows the same rule as for `monitor.notification`.
## Ordering and duplicate delivery
Webhooks for the same `requestId` are **not guaranteed to arrive in order**, and the same event can be delivered more than once due to retries. A `company.updated` that fails on its first delivery is retried later and can land after a newer one that succeeded immediately. Two rules keep your data correct:
1. **Each payload is a full snapshot**, identical to what `GET /v2/company/{requestId}` returned at the time it was sent. Merge it into your store per data point. Do not blindly replace your record based on arrival order, or a late `in_progress` delivery can overwrite newer data.
2. **Use `request.version` to reject stale updates.** It increases every time the snapshot changes for a `requestId`. Track the highest `version` you have applied per `requestId` and ignore any webhook whose `version` is lower than or equal to it. The late `in_progress` delivery carries a lower `version` than the final one, so this drops it.
`request.version` is scoped to a single `requestId`. Do not compare it across different requests.
## Retry Policy
If your server returns an error (non-2xx status) or times out, we will retry delivery with exponential backoff.
* **First retry**: Immediate
* **Subsequent retries**: Increasing delays (seconds, minutes, hours)
* **Duration**: We retry for up to 3 days
Ensure your webhook endpoint is idempotent and responds quickly (return 200 OK immediately, process later).
# Introduction
Source: https://docs.topograph.co/introduction
The unified API for KYB prefill and verification
## What is Topograph?
Topograph turns the complexity of public company registers into a standardized, developer-friendly API. We help you build fast KYB (Know Your Business) onboarding flows and rigorous verification processes without dealing with fragmented company data across jurisdictions.
Best practices for building onboarding flows with high conversion rates.
Find live country coverage, pricing, sources, identifiers, and available documents.
## The Onboarding Flow
We provide search, `POST /v2/company` (verification or prefill mode), documents, and monitoring so you can cover each step of a modern KYB flow without juggling multiple APIs.
```mermaid theme={null}
flowchart LR
Search[Search] --> Onboard[Onboard]
Onboard --> Verify[Verify]
Verify --> Monitor[Monitor]
```
### 1. Search
Let users find their company instantly.
Search by name or registration number and stream results for instant UI feedback. We handle multiple search sources per country seamlessly.
### 2. Onboard
Prefill forms to maximize conversion.
Use `/v2/company` with `mode: "prefill"` for fast, cost-effective company data to prefill forms, with a 10-second deadline per datapoint. Country pricing pages publish measured speed figures where enough traffic exists.
### 3. Verify
Perform rigorous compliance checks.
Live, authoritative data fetched directly from public registers for final KYB checks.
Download official PDFs (extracts, statutes, financials) sourced directly from public registers.
### 4. Monitor
Keep your data up to date.
Receive webhook notifications when a company's records change in the public register–status, address, representatives, etc.
## Key Capabilities
Beyond the core onboarding flow, Topograph solves the hard problems of international company data:
We map local specifics to international standards: ISO 20275 for legal forms, ISO 5009 for roles, and ISIC/NACE for activity codes.
Public registers are unreliable. Understand retries, timeouts, in-progress results, and how to recover from failures.
(Beta) Extract structured financial data from financial statements PDF, automatically.
Use the live pricing pages as the source of truth for country support, sources, pricing, and documents.
## Getting Started
Sign up at [app.topograph.co](https://app.topograph.co) to receive credentials.
Follow the [Quickstart Guide](/quickstart) to make your first API request in minutes.
# Quickstart
Source: https://docs.topograph.co/quickstart
Make your first request to the Topograph API in minutes
This guide gets you from an API key to your first company data response. You will authenticate, search for a company, create an asynchronous request, and retrieve the result.
**Building with an AI coding agent?** Install the Topograph plugin. Its [Topograph Wizard](/guides/topograph-mcp) gives Claude Code live country coverage, pricing and integration rules while it writes your integration, and the [Topograph MCP](/guides/mcp) lets it look up real companies with your account. Other editors and chat apps can connect to either server directly.
```
/plugin marketplace add getsemaphore/topograph-mcp-library
/plugin install topograph@topograph
```
## 1. Get your API Key
You'll need an API key to authenticate your requests.
1. Sign up or log in to the [Topograph Dashboard](https://app.topograph.co).
2. Open **Settings & More > Developer**. Only organisation admins can see API keys.
3. Reveal and copy the API key of your live environment. Each environment has one key, and you can copy it again at any time from this page.
4. If a key leaks, rotate it from the same page. Rotation invalidates the previous key immediately.
Want to integrate without real data or real charges? Create a [development environment](/guides/development-environment) from the same page. It has its own API key.
## 2. Search for a Company
The entry point to Topograph is usually a search. Let's find BNP Paribas in France.
```bash theme={null}
curl --request GET \
--url 'https://api.topograph.co/v2/search?country=FR&query=BNP%20Paribas' \
--header 'x-api-key: '
```
This returns matching companies. Pick the company you want and copy its `id`. The `id` returned by search is the value to pass to other Topograph endpoints.
Country-specific identifier formats vary. Use the [coverage and pricing page](/essentials/coverage-and-pricing) to find the live country catalog, accepted identifiers, and available sources before building a country-specific flow.
## 3. Create a Data Request
Now use that `id` to create a request for company data. The `/v2/company` endpoint is asynchronous: it starts retrieval and returns a `requestId` you use to poll or correlate webhooks.
```bash theme={null}
curl --request POST \
--url https://api.topograph.co/v2/company \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"countryCode": "FR",
"id": "552032534",
"dataPoints": ["company", "legalRepresentatives"]
}'
```
The response contains a `requestId` and a `dataStatus` object. Some datapoints may already be `succeeded`, while others are still `in_progress`. The first response is not necessarily complete.
```json theme={null}
{
"request": {
"requestId": "253299d1-e8d0-4268-945b-f175f98bc114",
"dataStatus": {
"dataPoints": {
"company": { "status": "succeeded" },
"legalRepresentatives": { "status": "in_progress" }
}
}
},
"company": {
"id": "552032534",
"countryCode": "FR",
"legalName": "BNP PARIBAS",
"identifiers": {
"siren": "552032534"
}
}
}
```
Retrieval time depends on the country and datapoint. Most resolve in seconds, some take minutes. A small number of datapoints are [manually delivered](/essentials/manual-delivery) and typically take 1–3 business days. The `manual` flag on `GET /v2/catalog` tells you which ones before you order.
## 4. Pick the right mode
`/v2/company` supports two modes:
| Mode | Use it for | What to expect |
| - | - | - |
| Verification (default) | Compliance checks and final KYB decisions | Authoritative data from official sources. Slower, but optimized for completeness. |
| Prefill | Form prefill and early screening | Fast data with a short per-datapoint deadline. Some countries use non-authoritative fast sources. |
For the full tradeoff, read [Verification vs prefill mode](/essentials/modes).
## 5. Retrieve the results
Use the `requestId` from step 3 to poll for the complete data. Polling is free: requests made with a `requestId` are never rebilled.
```bash theme={null}
curl --request GET \
--url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114 \
--header 'x-api-key: '
```
Poll every 3 seconds until all data points in `dataStatus` show `succeeded` or `failed`. Once resolved, the response contains the full verified data: legal name, address, company status, legal representatives, and more.
Polling works well for getting started. In production, set up [webhooks](/guides/webhooks) instead so Topograph pushes completed data to your server automatically.
## 6. Explore more features
Now that you have the basics, explore what else you can do:
Build a KYB flow with high conversion rates
Retrieve high-quality, detailed data, including UBOs and company documents
Find live country coverage, sources, pricing, identifiers, and available documents
Explore all endpoints and parameters
Let Claude, ChatGPT, Cursor and other AI agents look up companies in official registers
Give your coding agent live coverage, pricing, docs and code samples while it writes your integration