Company data API checklist: 30 questions before you integrate
Answer in brief
Before you integrate a company data API, answer about 30 questions from its documentation, in five groups covering access and limits, search, the data model, errors and pagination, and terms and operations. Each answer should carry a link to where the docs say it. A question the documentation cannot answer is a risk to record, not a detail to skip.
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
How to use it
Copy the block below into your ticket or design document. Answer each line with a value and a link to the documentation that states it. Leave nothing blank: write “not documented” where the docs are silent.
Access and limits
- [ ] How does the API authenticate: none, API key, OAuth or another scheme?
- [ ] How is the credential sent: header, Basic auth username, query string?
- [ ] What is the rate limit: number, window, and per what (key, user, address)?
- [ ] What does the API return over the limit: status, headers, body?
- [ ] Is there a Retry-After header, and in seconds or as a date?
- [ ] Are browser calls allowed (CORS), and for which methods?
- [ ] Is there a free tier, and what exactly does it include?
Search
- [ ] Which search modes exist: prefix, exact identifier, fuzzy, description?
- [ ] What is the minimum and maximum query length?
- [ ] How are results ordered: relevance score, registry order, something else?
- [ ] Which filters exist: country, jurisdiction, status, legal form?
- [ ] Do search results carry identifiers, or only the full record?
Data model
- [ ] Does each company have a permanent ID that survives renames and mergers?
- [ ] Are registry numbers given with scheme and jurisdiction?
- [ ] How is status expressed: register wording, a normalised category, both?
- [ ] How are merged, split or removed records represented?
- [ ] Does each fact carry its source and an observation time?
- [ ] Are unpublished fields absent, null, or filled with estimates?
- [ ] Where do officers come from, and do they carry their source?
- [ ] Is coverage documented per country, and how far does that statement go?
Errors and pagination
- [ ] Is there one error format (for example RFC 9457 problem details)?
- [ ] Are error codes stable strings your code can branch on?
- [ ] Which errors are documented as retryable?
- [ ] How does pagination work: cursor, page number, offset?
- [ ] What is the maximum page size, and how deep can you page?
- [ ] What happens when a cursor expires?
Terms and operations
- [ ] Is there a published OpenAPI document, and is it current?
- [ ] What may you do with the data, and what is forbidden?
- [ ] What attribution must you show, and where?
- [ ] Is the service provided "as is", and can it change or be withdrawn?
- [ ] Is there a status page, a changelog or a versioning policy?
A worked example
Here is how the free CompanyRegistryAPI.com API answers a few of the lines, from its API docs and About page:
| Question | Answer from the docs |
|---|---|
| Authentication | None |
| Rate limit | 60 requests per minute per client address, bursts up to the same number |
| Over the limit | 429 with a Retry-After header |
| CORS | Browser requests from any origin are allowed for GET |
| Search modes | Start of a name or a business ID, 3 to 64 characters, registry name order |
| Errors | RFC 9457 problem documents with a stable code |
| Pagination | Opaque next_cursor; cursors expire, restart on 400 |
| Attribution | “Powered by Coragrid” wherever you display the data |
| Warranty | Provided as is, without warranty; may change or be withdrawn |
The publisher of this site operates that API. Fill the same table for every candidate and compare the rows against your own requirements, not against each other.
What the checklist will not tell you
Documentation describes intent, not behaviour under your load. After the
checklist, run a short spike: one search, one read, one invalid request and a
handled 429. The first three requests guide gives
the calls.
Questions and answers
Do I need to answer every question on the checklist?
No, but record every unanswered one with a reason. "Not documented" and "not relevant to us" are different findings, and the first is a risk you are accepting.
Can I run the checklist without an account?
For most APIs you can answer the documentation questions without one. Testing the error and limit behaviour needs a working credential, or a keyless API such as the free CompanyRegistryAPI.com API.
How do I keep the checklist results useful later?
Store the filled-in copy next to the integration code, with the date and the documentation links, so whoever revisits the choice can see what was true when it was made.
Sources for this entry
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
- Best company data API (Category guide)
- How to choose a company data API (Selection guide)
- Reading an OpenAPI document (Guide)
- Terms, attribution and "as is" (Guide)
- CompanyRegistryAPI.com 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.
Cite this entry
Best Company Data API. “Company data API checklist: 30 questions before you integrate.” Content reviewed . https://bestcompanydataapi.com/company-data-api-checklist