# 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 more recent
one. `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}`) |
| `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`, `ticker`, `wikidata`, `ch_chid`, `ch_ehraid` | `US0378331005`, `XNAS:AAPL`, `Q312` | Luhn (ISIN), 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.