# 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 and activity codes

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.