The company data model behind an API
About this topic
Company data APIs return a record per legal entity, but registers publish different fields, numbers repeat across countries and companies merge or split. Model the record around a permanent ID, keep identifiers with their scheme and jurisdiction, read status apart from record lifecycle, and keep provenance next to every fact you store.
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 this topic covers
The guides walk through a company record field by field: what a register may leave out, how identifiers and jurisdiction codes work, how status differs from lifecycle, where officers data comes from, how provenance and observation times are expressed, and why you store permanent IDs.
Field names used here
Field names in these guides are those of the CompanyRegistryAPI.com API docs
(id, lifecycle, company_status, identifiers, as_of_date). Other
APIs name the same ideas differently; the concepts carry over.
Entries in this topic
-
Guide
Company records and missing fields
What a company record from a company data API contains, why fields differ by register, and how to model absent, unknown and restricted values in your code.
-
Guide
Identifiers and jurisdictions
How company data APIs express registry numbers, LEIs, VAT numbers and jurisdictions with ISO 3166 codes, and how to match an identifier safely.
-
Guide
Status and lifecycle
Why company data APIs separate a company's register status from its record lifecycle, and how to handle redirected, split and removed records.
-
Guide
Officers and their sources
How company data APIs return current officers, what each source field means, and how to handle officers as personal data in your product.
-
Guide
Provenance and observation times
How company data APIs say where a fact came from and when it was observed, which provenance fields to store, and how to show freshness to users.
-
Guide
Store permanent IDs
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.
Definitions in this topic
-
Glossary
ISO 3166
The international standard for codes of countries (part 1, such as FI) and their subdivisions (part 2, such as CA-QC), used by company data APIs.
-
Glossary
Jurisdiction code
A code naming the place whose register issued a company's number, written as ISO 3166 country or subdivision codes such as FI or CA-QC.
-
Glossary
Legal Entity Identifier (LEI)
A unique 20-character alphanumeric code for a legal entity, based on the ISO 17442 standard and administered by GLEIF.
-
Glossary
Permanent ID
An identifier a data service gives a company that stays valid through renames, mergers and splits, unlike names and registry numbers.
Questions and answers
Why does my company table need more than a name and a number?
Because names change, registry numbers are only unique inside one register, and the same company can carry several numbers. A permanent ID plus identifiers with scheme and jurisdiction keeps one row per company.
Should I copy every field the API returns?
No. Store the fields your product uses, the permanent ID and the observation time, and read the rest from the API when you need it.
Sources for this entry
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
- Store permanent IDs (Guide)
- Identifiers and jurisdictions (Guide)
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. “The company data model behind an API.” Content reviewed . https://bestcompanydataapi.com/topics/data-model