# Company, people, and relationship data model

> Inspect actual company export fields and proposed person, role, membership, reporting, event, and technology models with explicit unknowns.

This reference explains company fields, people, roles, memberships, and relationship evidence for integration design. The website examples use fictional companies with reserved `.example` domains. Their people and events are also fictional; they do not expose records from Vencavo's data foundation. [Talk to us about integration requirements](/contact/) to assess the fields, delivery, and identifiers your application needs.

This document separates the **website company sample export** from a **proposed connected-record model**. The JSON below explains that design; it is not a versioned API contract, an endpoint response, or an extra export format.

## What the company sample actually exports

The [database explorer](/database/#database) filters four fictional companies and exports the currently selected rows as CSV. Its five columns map to the local company fields below. Display-only initials and colors are not exported.

| Local field | CSV column | Meaning                                              | Forma Labs example |
| ----------- | ---------- | ---------------------------------------------------- | ------------------ |
| `name`      | Company    | Fictional company display name                       | Forma Labs         |
| `domain`    | Domain     | Reserved sample domain                               | forma.example      |
| `industry`  | Industry   | Demonstration industry category                      | SaaS               |
| `location`  | Location   | Supplied display location; not verified headquarters | San Francisco, US  |
| `size`      | Employees  | Employee band; not an exact headcount                | 51–200             |

CSV quoting keeps a value such as `London, UK` in one column. The existing company JSON preview calls `size` **`employees`**, keeps its band as a string, and adds `source: "fictional-preview"` and `production_verified_at: null`. Neither that JSON nor the CSV contains a verified production record. The CSV does not export people, reporting lines, signals, sources, or verification dates.

## Connect a person, a role, and a company membership

Maya Chen is the same fictional professional shown on the [people page](/data/people/): VP Sales at Forma Labs, in Sales, with VP seniority. Separating these concepts avoids treating a job title as a permanent property of a person or as proof of a manager.

- **Person** identifies the professional in this illustration. Contact values belong to the sample and are not verified.
- **Role** describes the supplied title, function, and seniority.
- **Company membership** joins that person and role to a company. Membership alone does not establish an employment start date, a complete department roster, or a reporting relationship.

In this proposed shape, a `.example` domain is a fixture company key. Keys beginning `local:` are **illustrative local IDs introduced only to explain the joins**; they are not IDs supplied by the current sample, stable production identifiers, or resolvable URLs. Confirm production identifiers and entity-resolution rules during the integration assessment. A name match alone would be insufficient to merge two people or companies.

```json
{
  "model_status": "proposed-fictional-example",
  "company": {
    "key": "forma.example",
    "name": "Forma Labs",
    "domain": "forma.example",
    "industry": "SaaS",
    "location": "San Francisco, US",
    "employee_band": "51–200"
  },
  "person": {
    "key": "local:maya-chen",
    "name": "Maya Chen",
    "country": "United States",
    "work_email": "maya@forma.example",
    "phone_number": null
  },
  "role": {
    "key": "local:forma-sales-vp",
    "title": "VP Sales",
    "department": "Sales",
    "seniority": "VP"
  },
  "membership": {
    "key": "local:maya-at-forma",
    "person_key": "local:maya-chen",
    "company_key": "forma.example",
    "role_key": "local:forma-sales-vp",
    "source_kind": "fictional-preview",
    "source_reference": null,
    "observed_at": null,
    "verified_at": null
  }
}
```

The current fixture includes an illustrative phone-availability flag, not a telephone number; `phone_number` therefore stays null here. The sample email uses a reserved domain and does not prove deliverability or permission to contact someone. The proposed `employee_band` name above makes the value's meaning clear; it does not rename the working CSV or company JSON fields.

## A missing reporting line is not an edge

The [org-chart page](/data/org-charts/) supplies company, department, role, and seniority context. It does not supply Maya's manager. A title, two people in the same department, or their placement in a diagram cannot establish who reports to whom.

This proposed lookup result represents the gap without creating a manager:

```json
{
  "model_status": "proposed-fictional-example",
  "subject_membership_key": "local:maya-at-forma",
  "reporting_edge": null,
  "reporting_status": "unknown",
  "source_reference": null,
  "observed_at": null,
  "verified_at": null
}
```

A supported reporting edge would need a report membership key, a manager membership key, a defined relationship type, and evidence attributable to that relationship. Both memberships would need to resolve to the intended people, roles, and company context. None is asserted here. A role change also does not, by itself, establish that a reporting line changed.

For these proposed examples, **`null` means the value is not supplied**. It does not mean false, zero, an empty string, "no manager exists," or "no event happened." A missing property has no defined meaning in this proposed example; it must not silently be interpreted as a verified negative. Agree how your integration distinguishes unknown, not collected, not applicable, and access-restricted values before clients depend on that distinction. Likewise, the absence of other memberships does not mean a company has no other employees.

## Describe a change without inventing its dates

Maya's fictional fixture carries the signal title **"A new sales leader"** and describes a move from Sales Director to VP Sales in the fictional scenario. The proposed event below uses that same change. Its keys are illustrative local IDs, and no source has been observed or verified.

```json
{
  "model_status": "proposed-fictional-example",
  "key": "local:maya-role-change",
  "event_type": "role_change",
  "title": "A new sales leader",
  "detail": "Maya moved from Sales Director to VP Sales in this fictional scenario.",
  "person_key": "local:maya-chen",
  "company_key": "forma.example",
  "membership_key": "local:maya-at-forma",
  "field": "role.title",
  "previous_value": "Sales Director",
  "next_value": "VP Sales",
  "event_at": null,
  "observed_at": null,
  "verified_at": null,
  "source_reference": null,
  "review_status": "unverified"
}
```

Three dates answer different questions:

| Proposed field | Question answered                                                      | Why it remains null here                |
| -------------- | ---------------------------------------------------------------------- | --------------------------------------- |
| `event_at`     | When did the underlying role change happen?                            | The fixture supplies no effective date. |
| `observed_at`  | When did a system observe the supporting evidence?                     | No external source was observed.        |
| `verified_at`  | When was that event or relationship last checked against its evidence? | No production verification occurred.    |

A recent observation would not make an older event recent. A verification date would describe a review, not replace the event date or guarantee the claim remains current. The company preview's `production_verified_at` is also null; it is not a substitute for field-level or relationship-level evidence. Confirm timestamp format, timezone, precision, and update policy for the selected delivery. The example supplies no dates.

The [signals example](/data/signals/) separately illustrates a hiring event. A job listing is not proof of a hire, and a role change is not proof of buying intent. Discuss event coverage and delivery requirements with us; the illustration does not run a monitoring job or publish an event endpoint.

## Technology context needs installation evidence

Maya's fixture has the technology category **CRM**. This is demonstration context, not a detected vendor, a product installation, a customer relationship, or an install-base assertion. It cannot establish that Forma Labs uses any particular CRM.

```json
{
  "model_status": "proposed-fictional-example",
  "company_key": "forma.example",
  "category": "CRM",
  "product": null,
  "installation_status": "unknown",
  "source_reference": null,
  "observed_at": null,
  "verified_at": null
}
```

To evaluate a technology assertion, require the specific product, correct company identity, a defined meaning of "uses," attributable evidence, observation and verification context, and a way to represent uncertainty or removal. A vendor mention on a webpage would not automatically prove an active installation. Confirm the available technology fields and their evidence during the access assessment. The fictional category does not establish detection coverage.

## Use supplied values without overwriting unknowns

Suppose an account starts with `domain: forma.example` and an industry entered by your team. The [enrichment example](/platform/company-enrichment/) supplies the fictional company fields above. Apply them deliberately:

| Situation                                | Review action                                                         |
| ---------------------------------------- | --------------------------------------------------------------------- |
| Account name is absent                   | Propose Forma Labs after confirming the domain match.                 |
| Existing industry differs                | Preserve both values for review; the preview has no recency evidence. |
| Target system expects an exact headcount | Keep the employee band separately; do not substitute its midpoint.    |
| Source revenue is absent                 | Leave the existing revenue unchanged.                                 |
| Manager or event date is unknown         | Keep it unknown; do not infer it from seniority or observation time.  |
| No company matches the domain            | Keep the account unresolved; do not create an inferred profile.       |

The [RevOps workflow](/use-cases/revops/) illustrates field review, and the [agent workflow guide](/developers/agent-workflows/) explains bounded research outputs. The website examples do not write to a CRM. [Contact Vencavo](/contact/) to review production identifiers, field meanings, evidence, permissions, usage limits, and delivery terms for your integration.