COMPANY PROFILE REST · RECOMMENDED
Resolve the entity, then retrieve its profile.
The CompanyProof profile flow has a stable, versioned top-level envelope. Resolve a legal entity first, keep the returned opaque id, then request the consolidated profile. An active evaluation or paid entitlement and a cp_live_… key are required; test keys never call live company-data services.
- 01Resolve the legal entity
POST /v2/companies/searchwith a name, registration number, VAT/tax ID or ticker and country. Check jurisdiction and identifiers before selecting a fuzzy name match. - 02Retrieve the profile envelope
GET /v2/companies/{id}/profilereturnscompany_id,profile, optionalenrichmentandsection_status. - 03Validate availability
On a successful
200,section_status.profileisavailable. Checksection_status.enrichmentindependently; it may beunavailable.
identifier_typeenumnoname (default), registration_number, vat_tax_id or ticker.
identifierstringyesThe company name or identifier to resolve.
countrystringyesUppercase ISO 3166-1 alpha-2 jurisdiction code.
subdivisionstringnoISO-style country-state code matching country, for example US-CA. Supported only for US, CA and CN.
city_or_statestring[]noUp to 10 non-empty city or state filters, each no longer than 100 characters.
limitintegernoNumber of matches, from 1 to 10. Defaults to 8.
{
"identifier_type": "ticker",
"identifier": "ACME",
"country": "US",
"subdivision": "US-CA",
"city_or_state": ["San Francisco"],
"limit": 5
}{
"companies": [
{
"id": "company_123",
"name": "ACME HOLDINGS LIMITED",
"registration_number": "12345678",
"vat_tax_id": "US123456789",
"ticker": "ACME",
"country": "US",
"country_name": "United States",
"state": "California",
"jurisdiction": "US-CA",
"status": "Active",
"legal_form": "Corporation",
"incorporation_date": "2020-01-15",
"website": "https://acme.example",
"logo_url": null,
"evidence": {
"source_name": "National company register",
"source_url": "https://register.example/company/12345678",
"source_category": "Government Registry",
"source_comment": "Official legal-entity record",
"source_record_id": "12345678",
"retrieved_at": "2026-09-02T10:42:11.000Z"
}
}
]
}A search match returns id, name, registration_number, vat_tax_id, ticker, country, country_name, state, jurisdiction, status, legal_form, incorporation_date, website, nullable logo_url and the evidence provenance object. Evidence contains source_name, nullable source_url, nullable source_updated_at (the source’s own update date, never the retrieval time), source_category, source_comment, source_record_id and retrieved_at. No match is a successful 200 with { "companies": [] }. Search has no cursor, offset or pagination contract; request at most limit: 10.
const headers = {
"Authorization": "Bearer " + process.env.COMPANYPROOF_API_KEY,
"Content-Type": "application/json"
};
const registrationNumber = process.env.COMPANY_REGISTRATION_NUMBER;
const companyCountry = process.env.COMPANY_COUNTRY;
if (!registrationNumber || !/^[A-Z]{2}$/.test(companyCountry || "")) {
throw new Error("Set COMPANY_REGISTRATION_NUMBER and a two-letter COMPANY_COUNTRY");
}
// 1. Resolve the legal entity.
const searchResponse = await fetch(
"https://companyproof.ai/v2/companies/search",
{
method: "POST",
headers,
body: JSON.stringify({
identifier_type: "registration_number",
identifier: registrationNumber,
country: companyCountry
})
}
);
const matches = await searchResponse.json();
const match = matches.companies?.find(
company => company.registration_number === registrationNumber
);
if (!searchResponse.ok || !match?.id) {
throw new Error("Company could not be resolved");
}
// 2. Retrieve the consolidated legal company profile.
const profileResponse = await fetch(
`https://companyproof.ai/v2/companies/${match.id}/profile`,
{ headers }
);
const profile = await profileResponse.json();
if (!profileResponse.ok) throw new Error("Profile retrieval failed");
if (profile.section_status.profile !== "available") {
throw new Error("The core profile is unavailable");
}
if (profile.section_status.enrichment !== "available") {
console.warn("Optional enrichment is unavailable");
}
// The stable envelope is profile.profile + profile.enrichment + section_status.
const companyProfile = profile.profile;
const officers = companyProfile.officers?.error
? []
: (companyProfile.officers?.data ?? companyProfile.officers ?? []);{
"company_id": "company_123",
"profile": {
"lite": {
"basic": {
"name": "ACME HOLDINGS LIMITED",
"status": "Active",
"source": { "name": "Illustrative company registry", "url": null, "retrieved_at": "2026-08-29T10:42:11.000Z" }
}
},
"officers": { "data": [], "source": {} },
"shareholders": {
"error": { "status_code": 403, "message": "This module is unavailable for the selected record." }
},
"group_structures_full": { "data": [], "source": {} },
"financial": { "data": { "years": [], "groups": [] }, "source": {} }
},
"enrichment": {},
"section_status": {
"profile": "available",
"enrichment": "available"
}
}liteLegal identity
Name, registration and VAT/tax identifiers, status, incorporation, legal form and registered address.
officersOfficers
Directors and officers, roles, appointment dates, work status and returned registry addresses.
shareholdersShareholders
Returned holders, ownership percentages when available, share classes, quantities and values.
group_structures_fullCorporate hierarchy
Parent and subsidiary relationships. Treat modelled relationships differently from registry-sourced facts.
financialFinancial statements
Multi-year filings, balance-sheet and income-statement data, cash flow, KPIs and ratios.
enrichmentProfile enrichment
Industry, SIC, size, brands, company contacts and social links when available.
The top-level envelope is stable, but module coverage varies by jurisdiction. Every known nested fact is optional unless its schema marks it required, and an optional value may be absent or null; lists may be empty. Officers and shareholders can be a direct array or a { data, total_pages, total_results, source } wrapper. Financial and group modules can likewise be direct or wrapped. A module-level { error: { status_code: 403, detail, message } } means the account is not entitled to that module; 404 means no source record is available. Both are embedded in an otherwise successful profile 200, so branch per module rather than treating the whole response as failed.
When provenance is enabled, lite and officer facts are grouped into source-bearing basic, address, contact, officer and appointment objects. A returned source can contain category, comment, id, name, nullable url and nullable retrieved_at. Module errors can also include structured access metadata such as permission, permission_name, module, module_name, app and app_name. Preserve provenance alongside the fact it qualifies.
Registry-derived facts, enriched contact fields and modelled corporate relationships do not have the same evidential weight. Preserve each returned source category and never label an enriched or modelled field as registry-verified. Returned shareholders and hierarchy are not, by themselves, a calculated UBO determination or a sanctions-screening result.
Officer birth month/year, address, email and phone can be personal data even when obtained from a public or enriched source. Process these fields only for a documented lawful business purpose and legal basis; apply data minimisation, role-based access, security, retention/deletion and data-rights procedures. Do not use CompanyProof as the sole basis for a legal or similarly significant decision about a person, or for unlawful discrimination, harassment, surveillance or identity exploitation. Your order, applicable law and the Acceptable Use Policy remain controlling.