CormorantDocs
Menu

The company/v1 record

GET /v1/schemas/company serves the JSON Schema (2020-12) of the record; this page explains it. The OpenAPI document describes every field too.

Claims and provenance#

Every value is a claim of one source: the value, the source, observed_at (first seen), confirmed_at (last time the source still said so), valid_from / valid_to, confidence and the raw document (document_ref with sha256 and body_url). Claims are never overwritten: when a source reports a different value, the old claim is closed (valid_to) and a new one opened. So the record can show what changed and when (GET /v1/companies/{id}/history).

For each field the record shows the resolved value: the claim of the source with the highest precedence (official register > official gazette > GLEIF > regulatory filings > crosswalks > commercial sources), then the field's preferred sources within that class, then the more recent one. The legal name is stricter: it is the official national register's primary entry in its official form and language (in Switzerland Zefix, then the UID register), ties go by source name rather than by time, so refreshing GLEIF after the register (or the other way round) never changes it. Other sources' forms are in names.alternates ({name, source}), language versions in names.translations (with source). provenance names the claim behind each field and flags conflict when another source currently says something else; quality.conflicts lists those values. include=claims returns every current claim; sources= restricts the record to some sources.

Fields#

Field Content
id cmp_<ulid>, stable; merged records redirect (redirected_from)
identifiers[] {scheme, value, issuer, status, parts, sources} in canonical form
names legal, previous[], trading[], translations[] (each {name, lang, valid_from, valid_to}; translations also source), alternates[] (other sources' forms of the legal name: {name, source})
legal_form {local_code, local_name, elf_code, category}: ISO 20275 code and one of corporation, partnership, sole_trader, cooperative, foundation, association, public_body, branch, other
status {value, local_value, since, reason}: active, inactive, in_liquidation, dissolved, merged, struck_off, unknown
jurisdiction {country, subdivision, register: {authority, court, entity_id}}
addresses[] {type: registered/business/postal/branch, lines, street, house_number, postal_code, city, municipality_code, region, country, geo}
dates incorporated, registered, deregistered, fiscal_year_end
purpose Text per language
activities[] {scheme: nace/noga/wz/sic/naics/isic, code, label, primary, nace}
capital[] {type: nominal/paid_in/authorised, amount, currency, since}
size Employees and revenue, only from official or filing data
people[] Officers as the register publishes them: {name, role, local_role, function, signing_authority, since, until, residence_city, residence_country, nationality, origin, person_id} (include=people)
ownership[] {type: shareholder/direct_parent/ultimate_parent/beneficial_owner, holder, share_pct, since} (include=ownership)
relationships[] {type: subsidiary/branch_of/head_office/merged_into/predecessor/successor/auditor/…, company, since, until}
filings[], financials[] Filed documents and official figures (include=filings,financials)
events[] Timeline from gazettes and registers (include=events)
securities[], web Listings; website and domains
sources[] Raw documents (newest first) with licence and parser_version
freshness[] Per source and field group: last_checked, last_changed, next_refresh_due, error
quality completeness (share of core fields filled) and conflicts
provenance, claims See above

Companies referenced in ownership and relationships carry the identifiers the source gave; fetch them with GET /v1/companies/scheme:value.

Identifier schemes#

Write identifiers as scheme:value; spacing, dots and case do not matter, check digits are verified, and the record shows the canonical form.

Scheme Example Check
ch_uid CHE-101.329.561 eCH-0097 mod 11
lei BFM8T61CT2L1QCEMIK50 ISO 17442 (ISO 7064 mod 97-10)
us_cik 320193 leading zeros dropped
uk_crn 00445790, SC123456 format
de_register München:HRB:6684 (also Amtsgericht München HRB 6684) court, type (HRA, HRB, GnR, PR, VR, GsR), number
fr_siren, fr_siret 552100554, 55210055400013 Luhn
no_orgnr, dk_cvr, fi_ytunnus, ee_regcode, cz_ico 923609016, 24256790, 0112038-9, 10137319, 45274649 national check digits
pl_krs, be_kbo 0000028860, 0403.170.701 format, mod 97
au_abn, au_acn, nz_nzbn 51824753556, 004085616, 9429040402307 national check digits, GS1
jp_corporate_number, br_cnpj, sg_uen, ca_corp 7000012050002, 33000167000101 national check digits (CNPJ also alphanumeric)
vat DE129273398, CHE101329561 country format; Swiss VAT numbers are UIDs
isin CH0038863350 ISO 6166 (Luhn over the letters-as-numbers form); the issuer is found through GLEIF's ISIN-to-LEI mapping
ticker, wikidata, ch_chid, ch_ehraid XNAS:AAPL, Q312 format

Legal forms map to ISO 20275 Entity Legal Form codes (GLEIF's list, every jurisdiction) with a normalised category. Activity codes keep the scheme the source uses; NOGA 2008 (Switzerland) and WZ 2008 (Germany) codes also name their NACE Rev. 2 class (nace). Labels are in English.

View as Markdown