---
title: "Company identifiers and jurisdiction codes in APIs"
description: "How company data APIs express registry numbers, LEIs, VAT numbers and jurisdictions with ISO 3166 codes, and how to match an identifier safely."
url: https://bestcompanydataapi.com/identifiers-and-jurisdictions
---

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

# Company identifiers and jurisdiction codes in APIs

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

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

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

```python
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`:

```python
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.

```bash
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](https://bestcompanydataapi.com/store-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

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. [OpenCorporates API Reference](https://api.opencorporates.com/documentation/API-Reference) OpenCorporates. The OpenCorporates API's key requirement, formats, versioning advice and jurisdiction codes. Retrieved 17 November 2026.
4. [The Legal Entity Identifier (LEI)](https://www.gleif.org/en/organizational-identity/lei-vlei/the-legal-entity-identifier-lei) Global Legal Entity Identifier Foundation (GLEIF). What an LEI is and the ISO standard it is based on, in GLEIF's words. 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

- [Jurisdiction code](https://bestcompanydataapi.com/glossary/jurisdiction-code) (Definition)
- [ISO 3166](https://bestcompanydataapi.com/glossary/iso-3166) (Definition)
- [Legal Entity Identifier (LEI)](https://bestcompanydataapi.com/glossary/legal-entity-identifier) (Definition)
- [Store permanent IDs](https://bestcompanydataapi.com/store-permanent-ids) (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. “Company identifiers and jurisdiction codes in APIs.” Content reviewed 17 November 2026. [https://bestcompanydataapi.com/identifiers-and-jurisdictions](https://bestcompanydataapi.com/identifiers-and-jurisdictions)

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