Company, people, and relationship data model

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 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 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: 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.

{
  "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": "[email protected]",
    "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 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:

{
  "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.

{
  "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 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.

{
  "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 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 illustrates field review, and the agent workflow guide explains bounded research outputs. The website examples do not write to a CRM. Contact Vencavo to review production identifiers, field meanings, evidence, permissions, usage limits, and delivery terms for your integration.