Company identifiers and jurisdiction codes in APIs
Answer in brief
A registry number only identifies a company inside one register, so an API must give it with its scheme and its jurisdiction. Jurisdictions are written as ISO 3166 codes, FI for a country or CA-QC for a subdivision. To match a company, compare value, scheme and jurisdiction together, and check whether the number is current or ended.
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
Numbers need a scheme and a place
The same number can exist in two registers, and one company can carry several numbers: a registry number, a VAT number, a tax number, an LEI. An identifier is therefore three things together:
| Part | Example | Why |
|---|---|---|
| Scheme | national_registry_number |
Which numbering system |
| Value | 1234567-8 |
As the source publishes it |
| Jurisdiction | FI |
Which register’s numbering |
How CompanyRegistryAPI.com lists them
A company read lists identifiers, strongest first. Each entry has a scheme
and a value; country_scope gives the registration jurisdiction in ISO
3166-1 alpha-2 or ISO 3166-2 form. The docs list these schemes:
| Scheme | Meaning |
|---|---|
national_registry_number |
A number a company register assigns |
lei |
Legal Entity Identifier, ISO 17442; globally unique, no country_scope |
eu_vat_number |
An EU VAT number, with its country_scope |
vat_number |
A VAT number of another scheme, with its country_scope |
tin |
A tax identification number, with its country_scope |
Where the source states the registration behind a number, an entry also has
role (root for the number the record was created from, alias for
others), status (active, ended, suspended or unknown), and
valid_from and valid_to at the source’s precision (2016, 2016-04 or
2016-04-28). An ended entry is a former number; a suspended one is still
current. The docs say to match on status, not on position.
Matching an identifier safely
def holds_number(company, value, scheme, jurisdiction):
for entry in company.get("identifiers", []):
if (
entry["scheme"] == scheme
and entry["value"] == value
and (entry.get("country_scope") or "") == jurisdiction
and entry.get("status") != "ended"
):
return True
return False
Compare the jurisdiction exactly. A country and one of its subdivisions are
separate numbering systems, so a number registered under CA-QC does not
confirm the same number under CA:
quebec = {"identifiers": [{
"scheme": "national_registry_number", "value": "1234567890",
"country_scope": "CA-QC", "status": "active",
}]}
scheme = "national_registry_number"
holds_number(quebec, "1234567890", scheme, "CA-QC") # True
holds_number(quebec, "1234567890", scheme, "CA") # False
For a globally unique scheme such as lei, which has no country_scope, pass
an empty jurisdiction.
Compare the value as the source publishes it. If your users type numbers in another format, normalise their input to the register’s format for that jurisdiction, not the other way round.
Jurisdiction codes
ISO 3166 gives two-letter country codes (part 1, such as FI) and subdivision
codes (part 2, such as CA-QC for Quebec). Registers below country level, such
as provincial or state registers, need the subdivision form.
The CompanyRegistryAPI.com search has two filters:
address_country: ISO 3166-1 alpha-2, matched against where the company’s address is.jurisdiction: ISO 3166-1 alpha-2 or ISO 3166-2, matched against the registry identifiers; a country code also matches its subdivisions.
base=https://api.companyregistryapi.com
curl "$base/v1/search?q=example&jurisdiction=CA-QC"
The filter is wider than holds_number on purpose: jurisdiction=CA also
returns companies registered in a subdivision. Treat what search returns as
candidates, and confirm each one against the exact jurisdiction you expect.
The record’s own registration jurisdiction is the country_scope of the first
scoped entry in identifiers, and it can differ from country_code, the
address country.
Other conventions
OpenCorporates’ API reference writes a country as its lowercase two-letter
code (gb, es) and a state or province as an underscore form of the ISO
3166-2 code (us_mi). Write one conversion function per provider and keep
ISO 3166 as your internal form.
What to store
Store the provider’s permanent company ID as the key, and identifiers as rows with scheme, value, jurisdiction, status and the date you read them. The permanent IDs guide explains why the number is not the key.
Questions and answers
What is the difference between address country and jurisdiction?
The address country is where the company's address is; the jurisdiction is where its identifiers are registered. CompanyRegistryAPI.com notes that the two can differ, and offers a separate filter for each.
Does an LEI have a jurisdiction?
No. An LEI is globally unique under ISO 17442, so CompanyRegistryAPI.com lists it under the scheme lei without a country_scope.
Why do OpenCorporates' jurisdiction codes look different?
OpenCorporates documents lowercase two-letter country codes and an underscore form of ISO 3166-2 for states and provinces, such as us_mi. Convert between conventions in one function when you use several APIs.
Sources for this entry
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com Company Data API
- OpenCorporates API Reference
- The Legal Entity Identifier (LEI)
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
- Jurisdiction code (Definition)
- ISO 3166 (Definition)
- Legal Entity Identifier (LEI) (Definition)
- Store permanent IDs (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. “Company identifiers and jurisdiction codes in APIs.” Content reviewed . https://bestcompanydataapi.com/identifiers-and-jurisdictions