CRM records

Start with the record model

Use crm.record_objects.list to read object definitions the caller may see. It lists types rather than records, including built-in person, company, deal, and post types plus custom types. It is a free, read-only capability. Read the types first so a new fact belongs to the correct relationship object instead of becoming an unstructured duplicate.

Use crm.records.list to page through records the caller may read. You can narrow the result to one object type or a text query, and every response states its own ordering. It is also free and read-only. Search existing records before creating or changing one because an existing match can carry the identity, owner, timeline, and open work that a new record would miss.

Use crm.records.get for one CRM record or outreach contact id. It returns current values, revision history, associations, timeline, files, and the actions that the caller is allowed to take. Read this full context immediately before any mutation, since another teammate can have changed the record after an earlier list read.

A record is not a Row source and it is not a Worksheet. A worksheet supports a bounded data job. A record represents a durable relationship entity. In the app, check object type, associations, owner, recent activity, fields, and open work before you decide that a workbook result is new CRM information.

Put information in the right place

The place where information lives changes how the team can reuse and interpret it. Put a stable, reusable, queryable fact in a field. Put reasoning, uncertainty, meeting detail, and information not trusted enough for a field in a note. Put an occurrence that happened at a specific time on the timeline. Do not put narrative in a field merely because it may be useful once.

Examples of stable facts include a verified title, lifecycle stage, owner, company domain, explicit qualification, or consent state. A call, email, meeting, reply, stage change, or task completion is a dated activity. A note can record the source, date, uncertainty, and conflicting claims when the available evidence does not support changing a stable field.

Do not turn an enrichment guess into a field. First compare it with the record’s existing evidence and the result in the originating workbook. Keep a conflict visible when it is material. Human-entered values are owned judgment, so an enrichment guess does not overwrite them. A verified fact can be added when evidence supports it.

Review the relationship before change

Read before every CRM change. Start with the record, related company and people, activity timeline, open deals, tasks, source evidence, and likely duplicates. Check identity through full name, employer, title, verified work email or profile URL, and relationship to the relevant company. Existing matches can share an email, profile URL, company, name variant, or recent activity, so inspect those signals as a group rather than relying on one search result.

Check pipeline context where it applies: owner, stage, amount or expected value, next step, and timeline activity. A pipeline record is useful when it represents active, evidenced customer work with the right person and company, a credible stage, a clear owner, recent activity, and a concrete next step. A stronger enrichment result or the passage of time alone does not establish a stage change.

Do not create speculative records to make a list look complete. Create one record per real relationship entity when identity evidence and purpose are present. Link a person to a company when the evidence supports the link. Include source, owner, and next action when they are known, so the record adds operating memory rather than a lead-shaped duplicate.

Treat identity as evidence

Merge only when at least two independent identity signals show the same entity. Strong combinations include a verified work email plus the same profile, a profile URL plus matching employment, or a confirmed user correction. Before merging, compare field provenance, associations, timeline, ownership, open work, and deal state. This preserves relationship context that can be lost when two superficially similar records are treated as one.

Name similarity, company similarity, a shared public email domain, a first name, or an enrichment guess alone is insufficient. If signals are weak or conflict, leave the records separate and surface the pair for review. Do not delete evidence to remove ambiguity. Preserve sources, dates, and conflicting claims so a later operator can resolve the identity with additional information.

crm.records.merge is a free destructive write. It folds the loser record into the winner: values, activity links, relationships, files, and worksheet rows move to the winner, and the loser stops existing separately. Live vault links at the loser are marked with resolution_status stale so backlinks visibly re-resolve. The result includes a snapshot_id; retain it with the merge evidence.

Keep pipeline memory true

Pipeline is true when every open deal represents active, evidenced customer work. Review newly created records, suspected duplicate pairs, fields with conflicting or stale evidence, deals without a next step or owner, recently changed stages, and open deals with no activity in 21 or more days. A deal with a high value or late-stage label is not healthy merely because those fields exist.

Track duplicate-pair count and the count of deals with no activity in 21 or more days in each hygiene review. Report zero as a result, not as an assumption. Read representative records after low-risk, evidence-backed field corrections. This readback confirms that the new value appears on the right relationship and that notes, timeline, ownership, and open work still tell the same story.

Advance a stage only when a customer action or documented qualification meets the stage definition. Record the evidence and next step with the change. If the criteria are unclear, preserve the stage and state the decision needed. A CRM record should describe current relationship reality, not improve a forecast by hiding missing evidence.

When CRM evidence conflicts

When enrichment conflicts with a human-entered value, preserve the human-entered value. Read the source evidence, retain the conflicting claim with source and date in context, and return to the originating workbook if the underlying row needs more qualification. Do not create a fresh record or overwrite a field merely because the enrichment looks more complete.

When identity is unclear, report the independent signals that exist and the signal that is missing. Do not merge on a public email domain, a name, a company match, or a guessed enrichment. When a stage lacks customer evidence, keep it where it is and identify the documented qualification or customer action needed to support a later change.

When a record change creates an unexpected result, read it back with crm.records.get. Check current values, revision history, associations, timeline, files, and allowed actions. Preserve the object and merge snapshot identifiers when relevant. This gives the team a factual path to investigate instead of masking a relationship conflict with another write.