The free register API in practice
Answer in brief
Using CompanyRegistryAPI.com's free API well takes five steps. Search by the start of a name or a business ID, choose the candidate yourself, read the company record and confirm the registry number, scheme and jurisdiction, store the permanent ID with the as-of date, and check lifecycle before you update stored data. Respect the 60-requests-a-minute limit and show "Powered by Coragrid".
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
This walk-through uses the free API of CompanyRegistryAPI.com, the product this site recommends and its publisher operates. Every behaviour described here is from the product’s own API docs. The company in the examples is the fictional one from those docs.
1. Search by the start of a name or a number
curl "https://api.companyregistryapi.com/v1/search?q=example&address_country=FI&limit=5"
qis the start of a company name or a business ID, 3 to 64 characters.address_countryfilters by address country (ISO 3166-1 alpha-2);jurisdictionfilters by where the identifiers are registered, and a country code also matches its subdivisions.- Results come in registry name order with no relevance score, up to 25 per
page, with
next_cursorfor the next page. Cursors expire; on a 400, restart from the first page.
Search by number when you have one: it is the most exact query.
2. Choose the candidate yourself
Search results carry the company ID, name, country, status and type, but no registry identifiers. Your code, or a person, picks the candidate that matches what you already know.
3. Read the record and confirm the number
curl "https://api.companyregistryapi.com/v1/companies/<company_id>"
In data.identifiers, confirm the expected number, scheme and
country_scope. Entries come strongest first; role is root for the
number the record was created from; status is active, ended, suspended or
unknown. An ended number is a former number. If the number you expected is
not there, you have the wrong company.
4. Store the ID with its date
import requests
company = requests.get(
"https://api.companyregistryapi.com/v1/companies/<company_id>"
).json()["data"]
# Read the register's wording whether the status arrives as an object or as
# plain text.
status = company.get("company_status")
status_local = status.get("local_name") if isinstance(status, dict) else status
record = {
"company_id": company["id"], # opaque, permanent, never reassigned
"name": company.get("name"), # as the register publishes it
"status_local": status_local,
"as_of": company.get("as_of_date"), # when the register was last observed
"identifiers": company.get("identifiers", []),
}
Store the ID exactly as returned. Keep as_of_date with every value you
copy, and use .get(): the docs say only id, object and lifecycle are
required, and a field the register does not publish is absent.
5. Check lifecycle before you update
When you refresh a stored company, read lifecycle.status first:
lifecycle.status |
What to do |
|---|---|
active |
Update from this record |
redirected |
Read the record at lifecycle.canonical_id instead |
split |
Choose among lifecycle.successor_ids |
tombstoned |
The record was removed; keep your history, stop updating |
restricted |
The record is withheld; note it in your file |
Officers
curl "https://api.companyregistryapi.com/v1/companies/<company_id>/officers"
Current officers where the register publishes them, up to 100 per call, with
has_more when the register lists more. Each names its publishing system,
with URL and observation time when known. Officer data is personal data;
store it only for a purpose you can state.
Errors and limits
Errors are RFC 9457 problem documents with a stable code:
invalid_request (400), not_found (404), rate_limited (429),
upstream_error (502), upstream_busy and upstream_unavailable (503).
The limit is 60 requests per minute per client address. On 429 and on
upstream_busy, wait for the seconds in Retry-After.
Attribution and use
Show “Powered by Coragrid” wherever you display the data. You may use the data in your own operations, products and services, but not present it as an official register extract. The service is provided as is and may change.
Questions and answers
Why did my search return nothing for a company I know exists?
Search matches the start of a name or business ID, so try the registered name's first word or the number. If it still returns nothing, the company may be in a register Coragrid has not connected; the product says an empty result is not evidence that a company does not exist.
What happens when I exceed the rate limit?
The API answers 429 with the problem code rate_limited and a Retry-After header. Wait that many seconds before retrying, and cache results you have already read.
Sources for this entry
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com Company Data API
- About CompanyRegistryAPI.com
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
- Guide to company data from official registers (Category guide)
- CompanyRegistryAPI.com (Profile)
- One API across registers (Guide)
- Reading a register record (Guide)
- Matching across registers (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 from Official Registers. “The free register API in practice.” Content reviewed . https://bestcompanydatafromofficialregisters.com/free-register-api-in-practice