The first three requests: search, read a company, list its officers
Answer in brief
Most company data integrations start with three requests. Search by the start of a name or by a business ID, read the chosen company by its permanent ID and confirm its registry identifiers, then list its current officers. Your code chooses the candidate, because search results carry no relevance score.
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
Request 1: search
GET /v1/search
Search takes the start of a company name or a business ID (q, 3 to 64
characters), optionally narrowed by address_country or jurisdiction:
base=https://api.companyregistryapi.com
curl "$base/v1/search?q=example&address_country=FI&limit=5"
The documentation’s sample response, for a fictional company:
{
"object": "list",
"query": "example",
"address_countries": ["FI"],
"data": [
{
"id": "co_014d2pf2dbsqqg28t5cy4tqkff",
"object": "company",
"lifecycle": { "status": "active" },
"name": "Example Robotics Oy",
"country_code": "FI",
"company_status": { "local_name": "active", "category": "active" },
"company_type": "private_limited_company"
}
],
"next_cursor": null,
"attribution": "Powered by Coragrid"
}
Search results carry the permanent id but no registry identifiers. A live
call returns what the connected registers hold for that prefix, which may be
an empty list.
Request 2: read the company and confirm it
GET /v1/companies/{company_id}
id="<an id from your search results>"
curl "$base/v1/companies/$id"
The record is in data. Only id, object and lifecycle are required;
other fields appear when the register publishes them. The docs’ abridged
sample includes:
{
"data": {
"id": "co_014d2pf2dbsqqg28t5cy4tqkff",
"lifecycle": { "status": "active" },
"name": "Example Robotics Oy",
"legal_form": "Osakeyhtiö",
"as_of_date": "2026-07-15",
"identifiers": [
{
"scheme": "national_registry_number",
"value": "1234567-8",
"country_scope": "FI",
"role": "root",
"status": "active"
}
]
},
"attribution": "Powered by Coragrid"
}
Confirm the candidate before you store its ID:
import requests
BASE = "https://api.companyregistryapi.com"
def find_by_number(number, country, scheme="national_registry_number"):
"""Search by a business ID, then confirm it in the company's identifiers."""
page = requests.get(
f"{BASE}/v1/search",
params={"q": number, "jurisdiction": country, "limit": 25},
timeout=10,
).json()
for candidate in page["data"]:
url = f"{BASE}/v1/companies/{candidate['id']}"
company = requests.get(url, timeout=10).json()["data"]
for entry in company.get("identifiers", []):
if (
entry["value"] == number
and entry.get("scheme") == scheme
and entry.get("country_scope") == country
and entry.get("status") != "ended"
):
return company
return None
The same digits can be another kind of number, such as a tax number, so the
scheme is part of the match. An entry whose status is ended is a former
number, never a current one.
Request 3: list current officers
GET /v1/companies/{company_id}/officers
const base = "https://api.companyregistryapi.com";
const response = await fetch(`${base}/v1/companies/${id}/officers`);
const page = await response.json();
for (const officer of page.data) {
console.log(officer.roles ?? [], officer.source.system);
}
if (page.has_more) console.log("The register lists more officers.");
What the response carries, from the docs and the OpenAPI document:
| Field | Meaning |
|---|---|
data |
Up to 100 current officers, where the register publishes them |
data[].roles |
Role titles as the register states them; absent when it states none |
data[].appointed_on |
Appointment date, where the register states it |
data[].source |
The publishing system, with its url and observed_at when known |
has_more |
Whether the register lists more current officers than returned |
company_id, requested_company_id |
The canonical company, and the ID you asked for when it redirected |
Officer names are personal data from public records. Show them only where your product needs them, with their source.
Then add the patterns
These three calls work as written until something goes wrong. Before you ship, add handling for 429 and Retry-After, problem details and, if you list many results, cursor pagination.
Questions and answers
Why not take the first search result?
Results come in registry name order with no relevance score, so the first result is only the alphabetically first match. Confirm the registry number, scheme and jurisdiction in the company read before you store the ID.
I already have the registry number. Do I still search?
Yes, but search by the number itself, which the API accepts as q. Then read the company and confirm the number appears in identifiers with the scheme and jurisdiction you expect and a status other than ended.
Why are officers a separate call?
The company read returns registry facts; officers come from a separate endpoint so you only fetch them when you need them. Each officer names the system that published it.
Sources for this entry
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com OpenAPI document
- CompanyRegistryAPI.com: Free Company Registry API
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
- CompanyRegistryAPI.com free API (Profile)
- Identifiers and jurisdictions (Guide)
- Officers and their sources (Guide)
- Pagination with cursors (Guide)
- Best company data API (Category 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 first three requests: search, read a company, list its officers.” Content reviewed . https://bestcompanydataapi.com/first-three-requests