Store permanent IDs, not names or registry numbers
Answer in brief
Key each company in your database by the API's permanent ID, not by its name or registry number. Names change and repeat, registry numbers are unique only inside one register and can be retired, and companies merge and split. A permanent ID that stays valid through those events, with lifecycle states for them, keeps one row per company.
Disclosure. This site is published by Coragrid, the operator of CompanyRegistryAPI.com, and promotes it. “Best” is our editorial choice, not a measured ranking. Other products are described only from their own official pages. How we choose
What goes wrong with names and numbers
| Key | Breaks when |
|---|---|
| Company name | The company is renamed, or two companies share a name |
| Registry number | Another register uses the same number, or the number ends after a re-registration |
| VAT number | The company is not VAT-registered, or the number changes |
| Your own row ID | Fine inside your system, but you still need a stable link to the source |
What a permanent ID gives you
CompanyRegistryAPI.com gives every company an ID starting with co_, from
Coragrid. Its docs describe the ID as opaque, permanent and never reassigned,
even when the name or a registry number changes, and independent of registry
numbers and database keys. It is the id of every search result and the
{company_id} in the company and officers paths.
A table keyed by permanent ID
create table company (
provider_id text primary key, -- 'co_...' as returned, never parsed
name text, -- display only; may change
country_code text,
as_of_date date,
fetched_at timestamptz not null
);
create table company_identifier (
provider_id text not null references company (provider_id),
scheme text not null, -- national_registry_number, lei, ...
value text not null,
country_scope text not null default '', -- '' for globally unique schemes
status text, -- active, ended, suspended, unknown
primary key (provider_id, scheme, country_scope, value)
);
Look companies up by identifier through the second table; join on the ID. The jurisdiction is part of the key: a company registered in two jurisdictions can hold the same number under the same scheme in both.
Store it as returned
- Keep the full string, case and prefix included.
- Do not derive anything from its characters.
- Validate shape only lightly, if at all: the API itself rejects a malformed
ID with
400invalid_request.
Keep it valid through lifecycle changes
A permanent ID can lead to a record that has been redirected or split. Before
you update a stored row, read lifecycle:
redirected: readlifecycle.canonical_idand point your row at it.split: choose amonglifecycle.successor_ids.tombstonedorrestricted: keep the row and flag it.
See status and lifecycle for the loop.
Migrating a table keyed by numbers
- Add a nullable
provider_idcolumn. - For each row, search by the registry number, read the candidates, and
confirm the number with its scheme and jurisdiction in
identifiers. - Write the confirmed ID; leave ambiguous rows for review.
- Spread the job under the rate limit: at 50 lookups a minute, 3,000 rows take about an hour, plus one read per candidate.
- Switch joins to
provider_id, then keep the number as an identifier row.
Keep your own key too
If you may ever use more than one provider, keep your own internal key per company and map each provider’s permanent ID to it. Switching provider is then a new mapping, not a rewrite.
Questions and answers
Can I parse or shorten the permanent ID?
No. CompanyRegistryAPI.com describes its company ID as opaque, permanent and never reassigned, and asks you to store it as returned.
What happens to the ID when companies merge?
The record may be redirected. The ID you stored stays valid, and lifecycle.canonical_id names the record to read and store from then on.
Will the IDs still work if I move to the paid Coragrid API?
Yes, according to the product's pages. The free API uses the same permanent IDs and field names as the Coragrid public API, so stored IDs stay valid and need no data migration.
Sources for this entry
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com Company Data API
- CompanyRegistryAPI.com Get an API key
Each source supports only what its publisher says about its own product or data. Official descriptions do not establish comparative performance, and this site has run no benchmark. All sources
Continue reading
- Permanent ID (Definition)
- Status and lifecycle (Guide)
- Identifiers and jurisdictions (Guide)
- From a free API to a keyed platform (Guide)
- Best company data API (Category guide)
- CompanyRegistryAPI.com free API (Profile)
How the related websites connect
This is one of 3 coordinated reference sites published by Coragrid. They cover neighbouring questions and feature the same product, so they are not independent endorsements of it or of each other.
Cite this entry
Best Company Data API. “Store permanent IDs, not names or registry numbers.” Content reviewed . https://bestcompanydataapi.com/store-permanent-ids