Company

Company is the central legal-entity relation in the Well financial graph. It represents any organization or counterparty a workspace interacts with — customers, vendors, banks, or the workspace's own operating company — and is the anchor for invoices, transactions, contacts, and connector-sourced enrichment. Every Company belongs to exactly one Workspace (workspace-scoped) and carries both human-readable profile fields and machine-normalized canonical identity fields (S0 tier) used by the invoice-payment scorer and deduplication pipeline. Companies are created by connector sync, invoice extraction, or manual entry, and enriched asynchronously via the @Enrichable decorator pipeline.

API operations

Data model

Attributes

Relationships

System-computed

• company_id is generated by PostgreSQL gen_random_uuid() at INSERT via defaultRaw. It is immutable after creation and used as the public JSON:API id.
• created_at is set by an onCreate MikroORM lifecycle hook to new Date() at INSERT time. Never updated thereafter.
• updated_at is set by both onCreate and onUpdate lifecycle hooks to new Date(). Reflects the most recent flush of any column on the entity.
• deleted_at is NULL on active records. Set to a non-null timestamp to soft-delete. All active queries filter WHERE deleted_at IS NULL. Hard deletes are not used for this entity.
• canonical_tax_id is computed by the S1 normalisation module from tax_id_value and registry_country. Format: <ISO2><stripped_digits>. Written only by the normalizer — never by connector sync or user PATCH. NULL until the S2 backfill runs.
• canonical_registry is computed by S1 from registry_country + registry_name + registered_value. Format: <ISO2>-<REGISTRY>-<VALUE>. NULL until S2 backfill runs.
• domain_normalized is derived from company.domain or the first email domain: root domain, lowercase, no www, no trailing path. NULL until S2 backfill runs.
• email_domains is a text[] array populated by the S1 normalizer by aggregating all CompanyEmail rows for this company and extracting their domain parts. GIN-indexed. Kept in sync on CompanyEmail writes.
• canonical_legal_name is produced by stripping punctuation, case-folding, and dropping common legal suffixes from registered_name or trade_name. E.g. 'Anthropic PBC' → 'anthropic'. NULL until S2 backfill runs.
• identity_completeness is a numeric(4,3) score in [0.000, 1.000] computed by S1 as the fraction of {canonical_tax_id, canonical_registry, domain_normalized, email_domains, canonical_legal_name} that are non-NULL. Recomputed on every S1 write and by S2 backfill. NULL until first computation.
• source_workspace_connector (FK workspace_connector_pk) records which connector sync originally created this company row. NULL means the row was created by invoice extraction, manual entry, or enrichment fallback — not by a connector. Presence in company_workspace_connectors.direction='input' is the 'connector-confirmed' signal used by the counterparty-bank discovery scorer.
• Fields decorated with @Enrichable (description, tax_id_value, tax_id_type, trade_name, registered_name, business_type, registered_value, registry_name, registry_country, social_links, locations, emails, phones, media) are eligible for population by the asynchronous enrichment pipeline (Cloud Tasks). The decorator marks the field for inclusion in the enrichment delta computation.
• locale defaults to LocalEnum.EN ('en') via the ORM default. Represents ISO 639-1 locale for the company's communications context.

Example

{
  "data": {
    "type": "company",
    "id": "3fa1c2d4-87ae-4b10-a9f3-ec5d1234abcd",
    "attributes": {
      "company_id": "3fa1c2d4-87ae-4b10-a9f3-ec5d1234abcd",
      "name": "Anthropic PBC",
      "description": "AI safety company building reliable, interpretable AI systems.",
      "domain": "anthropic.com",
      "locale": "en",
      "tax_id_value": "88-1234567",
      "tax_id_type": "EIN",
      "trade_name": "Anthropic",
      "registered_name": "Anthropic PBC",
      "business_type": "PBC",
      "registered_value": "7543821",
      "registry_name": "Delaware Division of Corporations",
      "registry_country": "US",
      "canonical_tax_id": "US881234567",
      "canonical_registry": "US-DELAWARE-7543821",
      "domain_normalized": "anthropic.com",
      "email_domains": ["anthropic.com"],
      "canonical_legal_name": "anthropic",
      "identity_completeness": 1.000,
      "created_at": "2025-03-15T10:22:00.000Z",
      "updated_at": "2026-01-04T08:11:45.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "a1b2c3d4-0000-4000-8000-000000000001" }
      },
      "source_workspace_connector": {
        "data": { "type": "workspace_connector", "id": "c9d8e7f6-1111-4111-8111-000000000002" }
      },
      "emails": {
        "data": [{ "type": "company_email", "id": "e1f2a3b4-2222-4222-8222-000000000003" }]
      },
      "phones": { "data": [] },
      "locations": {
        "data": [{ "type": "company_location", "id": "d5e6f7a8-3333-4333-8333-000000000004" }]
      },
      "social_links": {
        "data": [{ "type": "company_web_link", "id": "b9c0d1e2-4444-4444-8444-000000000005" }]
      },
      "people": {
        "data": [{ "type": "company_person", "id": "f3a4b5c6-5555-4555-8555-000000000006" }]
      },
      "categories": { "data": [] },
      "media": {
        "data": [{ "type": "company_media", "id": "a7b8c9d0-6666-4666-8666-000000000007" }]
      },
      "company_financial": {
        "data": { "type": "company_financial", "id": "e1e2e3e4-7777-4777-8777-000000000008" }
      },
      "relations": { "data": [] }
    }
  }
}