---
title: "The free register API in practice | Official Register Data"
description: "A walk through CompanyRegistryAPI.com's free API: prefix search, confirming the registry number, lifecycle, 429s and attribution."
url: https://bestcompanydatafromofficialregisters.com/free-register-api-in-practice
---

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

# The free register API in practice

[Getting the data](https://bestcompanydatafromofficialregisters.com/topics/getting-the-data)

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

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

```bash
curl "https://api.companyregistryapi.com/v1/search?q=example&address_country=FI&limit=5"
```

- `q` is the start of a company name or a business ID, 3 to 64 characters.
- `address_country` filters by address country (ISO 3166-1 alpha-2); `jurisdiction` filters 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_cursor` for 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

```bash
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

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

```bash
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

1. [CompanyRegistryAPI.com API docs](https://companyregistryapi.com/api) Coragrid. The free API's base URL, endpoints, rate limit, record fields, registry 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, how current it is and how the data may be used. Retrieved 17 November 2026.
3. [About CompanyRegistryAPI.com](https://companyregistryapi.com/about) Coragrid. Where the product's records come from, what Coragrid keeps with each fact, what the product does not do with the data, and the free API terms. 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://bestcompanydatafromofficialregisters.com/sources)

## Continue reading

- [Guide to company data from official registers](https://bestcompanydatafromofficialregisters.com/best-company-data-from-official-registers) (Category guide)
- [CompanyRegistryAPI.com](https://bestcompanydatafromofficialregisters.com/companyregistryapi) (Profile)
- [One API across registers](https://bestcompanydatafromofficialregisters.com/one-api-across-registers) (Guide)
- [Reading a register record](https://bestcompanydatafromofficialregisters.com/reading-a-register-record) (Guide)
- [Matching across registers](https://bestcompanydatafromofficialregisters.com/matching-companies-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.

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

## Cite this entry

Best Company Data from Official Registers. “The free register API in practice.” Content reviewed 17 November 2026. [https://bestcompanydatafromofficialregisters.com/free-register-api-in-practice](https://bestcompanydatafromofficialregisters.com/free-register-api-in-practice)

## Featured product: CompanyRegistryAPI.com

- **What it is:** Free company lookup website and keyless JSON API
- **Documented service:** Registry facts as the register published them, with the date it was last observed, and current officers with their sources, as JSON
- **Official destination:** [companyregistryapi.com](https://companyregistryapi.com/)
- **Operator:** Coragrid
- **Source status:** Described from its own pages; same publisher as this site

* [Read the CompanyRegistryAPI.com profile](https://bestcompanydatafromofficialregisters.com/companyregistryapi)
* [How this site chooses](https://bestcompanydatafromofficialregisters.com/methodology)
