---
title: "First three requests: search, company, officers"
description: "The three calls every company data integration starts with, as cURL, JavaScript and Python against the free keyless CompanyRegistryAPI.com API."
url: https://bestcompanydataapi.com/first-three-requests
---

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

# The first three requests: search, read a company, list its officers

[Integration patterns](https://bestcompanydataapi.com/topics/integration)

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

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

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

```json
{
  "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}`

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

```json
{
  "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:

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

```javascript
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](https://bestcompanydataapi.com/handling-429-and-retry-after), [problem details](https://bestcompanydataapi.com/problem-details-and-error-codes) and, if you list many results, [cursor pagination](https://bestcompanydataapi.com/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

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 OpenAPI document](https://companyregistryapi.com/api/openapi.json) Coragrid. The free API as an OpenAPI 3.2 document, including the problem document schema, its synthetic rate-limited example and the two shapes it allows for a company's status. Retrieved 17 November 2026.
3. [CompanyRegistryAPI.com: Free Company Registry API](https://companyregistryapi.com/) Coragrid. What the product is, its key features, the country-level coverage list and the first calls in cURL, JavaScript and Python. 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

- [CompanyRegistryAPI.com free API](https://bestcompanydataapi.com/companyregistryapi-free-api) (Profile)
- [Identifiers and jurisdictions](https://bestcompanydataapi.com/identifiers-and-jurisdictions) (Guide)
- [Officers and their sources](https://bestcompanydataapi.com/officers-and-their-sources) (Guide)
- [Pagination with cursors](https://bestcompanydataapi.com/cursor-pagination) (Guide)
- [Best company data API](https://bestcompanydataapi.com/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.

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

## Cite this entry

Best Company Data API. “The first three requests: search, read a company, list its officers.” Content reviewed 17 November 2026. [https://bestcompanydataapi.com/first-three-requests](https://bestcompanydataapi.com/first-three-requests)

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