# Records and data model

## Companies

A company has a name, a **domain** (the dedupe key, normalized: `https://www.Acme.com/about` becomes `acme.com`), a description, a logo, social links and custom fields. `upsert_company` creates one or updates the existing company with the same domain.

## People

A person has a name, an **email** (the dedupe key, lowercased), a title, a company and custom fields. `upsert_person` creates one or updates the existing person with the same email. Pass `id` to update someone who has no email yet.

## Deals

A deal has a name, a stage, an amount and currency, a company and custom fields. The stages are, in order: `lead`, `qualified`, `proposal`, `negotiation`, `won`, `lost`. `get_pipeline` returns every deal grouped by stage with counts and totals.

## Deal contacts

People involved in a deal, each with a role: `champion`, `decision_maker`, `economic_buyer`, `technical_evaluator`, `influencer`, `user` or `blocker`. A deal can have many people and a person can be on many deals (`set_deal_contact`, `remove_deal_contact`).

## Activities

A note, email, call or meeting logged against a company, person or deal with `log_activity`. `get_record` returns the ten most recent with each record.

## Tasks

A next step with a title, optional due date or date-time, assignee, reason, and an optional link to a record and a signal. Identical open tasks aren't created twice. `list_tasks` returns overdue first and undated last; pass an IANA timezone for local day boundaries.

## Buying signals

Evidence that an account may buy now: a type, a one-line why-now (up to 280 characters), the source URL and when it was observed. Types: `complaint`, `post_engagement`, `hiring`, `job_change`, `funding`, `tech_adoption`, `headcount`, `news`, `ad`, `review`, `website_change`, `other`. `list_signals` ranks accounts by timing × the number of distinct signal types; a person's signals count toward their company. The same entity, type and URL is never recorded twice.

## Suggestions

A proposed change: the operation an agent would have called, its exact input, the reason and evidence. A person approves it (the operation then runs, signed by both the agent and the approver) or rejects it.

## Custom fields

Typed fields of your own on companies, people or deals. Types: `text`, `number`, `date`, `boolean`, `select`, `multi_select`, `url`, `email`. Values are checked against the type for everyone, agents included. `describe_schema` lists them with their keys.

## Do-not-contact list

Emails and domains nobody should enrich or contact. Agents check it before enrichment and outreach, add to it when someone asks not to be contacted, and can't remove entries; only an admin can.

## Sources and history

Every value written by an agent can carry a `source` (`{ name, url }`): where the fact came from. Every write is in the change history with who made it, on whose behalf, and which fields changed. `list_changes` pages through it so an agent can catch up on what changed since it last looked.