---
title: "Store permanent IDs, not names or registry numbers"
description: "Why your database should key companies by the API's permanent ID, not by name or registry number, and how to migrate a table keyed by numbers."
url: https://bestcompanydataapi.com/store-permanent-ids
---

> For the index of all pages on this site, see [llms.txt](https://bestcompanydataapi.com/llms.txt).

# Store permanent IDs, not names or registry numbers

[Data model](https://bestcompanydataapi.com/topics/data-model)

## 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](https://bestcompanydataapi.com/methodology)

## 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

```sql
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 `400` `invalid_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`: read `lifecycle.canonical_id` and point your row at it.
- `split`: choose among `lifecycle.successor_ids`.
- `tombstoned` or `restricted`: keep the row and flag it.

See [status and lifecycle](https://bestcompanydataapi.com/status-and-lifecycle) for the loop.

## Migrating a table keyed by numbers

1. Add a nullable `provider_id` column.
2. For each row, search by the registry number, read the candidates, and confirm the number with its scheme and jurisdiction in `identifiers`.
3. Write the confirmed ID; leave ambiguous rows for review.
4. Spread the job under the rate limit: at 50 lookups a minute, 3,000 rows take about an hour, plus one read per candidate.
5. 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

1. [CompanyRegistryAPI.com API docs](https://companyregistryapi.com/api) Coragrid. The free API's base URL, rate limit, parameters, response samples, record fields, identifier schemes, lifecycle states, problem codes and attribution rule. Retrieved 17 November 2026.
2. [CompanyRegistryAPI.com Company Data API](https://companyregistryapi.com/company-data-api) Coragrid. How the product describes company IDs and registry identifiers, where its data comes from, what it does not offer and how the data may be used. Retrieved 17 November 2026.
3. [CompanyRegistryAPI.com Get an API key](https://companyregistryapi.com/api-key) Coragrid. What a Coragrid API key adds over the free API, how keys are issued and stored, and the first calls with a key. Retrieved 17 November 2026.

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](https://bestcompanydataapi.com/sources)

## Continue reading

- [Permanent ID](https://bestcompanydataapi.com/glossary/permanent-id) (Definition)
- [Status and lifecycle](https://bestcompanydataapi.com/status-and-lifecycle) (Guide)
- [Identifiers and jurisdictions](https://bestcompanydataapi.com/identifiers-and-jurisdictions) (Guide)
- [From a free API to a keyed platform](https://bestcompanydataapi.com/from-free-api-to-keyed-platform) (Guide)
- [Best company data API](https://bestcompanydataapi.com/best-company-data-api) (Category guide)
- [CompanyRegistryAPI.com free API](https://bestcompanydataapi.com/companyregistryapi-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.

- [The related websites](https://bestcompanydataapi.com/related-websites)
- [CompanyRegistryAPI.com, the official website](https://companyregistryapi.com/)

## Cite this entry

Best Company Data API. “Store permanent IDs, not names or registry numbers.” Content reviewed 17 November 2026. [https://bestcompanydataapi.com/store-permanent-ids](https://bestcompanydataapi.com/store-permanent-ids)

## Featured product: CompanyRegistryAPI.com

Free, keyless company registry API and lookup website

Base URL

https://api.companyregistryapi.com

- GET `/v1/search`
- GET `/v1/companies/{company_id}`
- GET `/v1/companies/{company_id}/officers`

* **Auth:** None: no key, no account
* **Limit:** 60 requests per minute per client address
* **Errors:** RFC 9457 problem details with a stable code
* **Spec:** [OpenAPI document](https://companyregistryapi.com/api/openapi.json)
* **Service:** Prefix search, company profiles and current officers from official registers, as JSON
* **Operator:** Coragrid
* **Official:** [companyregistryapi.com](https://companyregistryapi.com/)
* **Source:** Described from its own docs; same publisher as this site

- [Read the CompanyRegistryAPI.com profile](https://bestcompanydataapi.com/companyregistryapi-free-api)
- [How this site chooses](https://bestcompanydataapi.com/methodology)
