# Data model > The entities behind your CRM and how they relate. ActuallyCare's data model follows the shape of a real estate business: people you know, deals in flight, properties you market, and the calendar that ties it together — plus newer verticals for vendor relationships and property management. This page is the conceptual map. For the exact fields and parameters of any operation, see the [tool reference](/tools) and the [endpoint reference](/api/reference). ## The core six The six entities you'll touch every day: | Entity | What it is | |---|---| | Contacts | Every person in your database | | Clients | People you represent | | Leads | Potential business in your pipeline | | Escrows | Active transactions, open to close | | Listings | Properties you're marketing | | Appointments | Your calendar | ### Contacts vs clients vs leads This distinction confuses almost everyone at first, so here it is plainly: - A **contact** is a *person*. Everyone in your database — past clients, leads, other agents, your lender, your mom — is a contact. It's the universal address book. - A **lead** is *potential business*. A lead represents someone moving through your pipeline who might transact with you. Leads get qualified, nurtured, and eventually [converted](/tools/leads/leads_convert) — or archived. - A **client** is an *active representation relationship*. When someone actually works with you — buying, selling, or both — they're a client. The key insight: lead and client aren't different people, they're different *relationships with the same person*. A typical journey is contact first, then lead, then client. The contact record is the person; the lead and client records describe what that person is to your business right now. ### Escrows, listings, and appointments - **Escrows** are transactions. An escrow opens when a deal goes under contract and tracks everything through closing. - **Listings** are inventory — properties you're marketing. A listing and an escrow often describe the same property at different stages: you list it, then it goes into escrow. - **Appointments** are calendar entries — showings you're driving to, listing presentations, closings, anything with a time attached. ## Around the transaction An escrow at the center of a deal accumulates satellite records: - **Documents** — files attached to the transaction. Documents can be run through AI risk analysis to surface red flags (see [`documents_get_risks`](/tools/documents/documents_get_risks)). - **Showings** — individual property showings, including buyer feedback. - **Open houses** — events with their own schedule and visitor logging. - **Deadlines and checklists** — contingency deadlines, the escrow checklist, and deadline alerts so nothing slips during the contract period. ## The vendor pipeline "Vendor" here means the service businesses around a transaction — lenders, escrow officers, inspectors, contractors, insurance agents, and other professionals you exchange business with. The vendor pipeline tracks those relationships the way the core pipeline tracks buyers and sellers: - **Prospects** — vendors you're evaluating but don't work with yet - **Partners** — vendors you actively work with - **Referrals** — business passed between you and a partner, in either direction - **Deals** — revenue opportunities that come out of those relationships - **Engagements** — logged interactions with partners, so the relationship history is on the record ## Property management For agents and brokerages doing property management, a dedicated set of entities covers the rental side: - **Rental applications** — applicants for a rental; an approved application can convert directly into a lease - **Leases** — the agreements themselves, with expiration tracking - **Tenancies** — the ongoing tenant relationship: rent collection, inspections, delinquency - **PM consultations** — intake conversations with property owners considering your management services; a consultation can convert into a tenancy ## Care status Care status is ActuallyCare's measure of follow-up health: is this relationship being actively cared for, or is it going cold? It changes as you log activity, and it gives "who needs attention?" a concrete answer instead of a gut feeling. Care status changes also fire `care_status.*` [webhook events](/concepts/webhooks), so you can build follow-up automation on top of it. ## Custom pipelines Beyond the built-in pipelines, ActuallyCare supports config-driven pipelines: pipeline types and stages are configuration, not code. Records move through stages, activity gets logged along the way, and you get pipeline-level reporting — which lets a team model a workflow the built-ins don't cover. See the [pipeline tools](/tools/pipelines). ## Entity links Sometimes two records are related in a way no built-in relationship captures — a partner who's the lender on a specific escrow, a document that matters to two different clients. **Entity links** are lightweight cross-references between any two records, in any combination. See the [entity link tools](/tools/entity-links). ## How your org shapes what you see Every user belongs to a team, and every team belongs to a brokerage: ```text Brokerage └─ Team └─ Agent (user) ├─ Contacts ── the person record │ ├─ as a Lead ──(convert)──► as a Client │ └─ Appointments ├─ Listings ◄─┐ ├─ Escrows ───┘ often the same property, two stages │ ├─ Documents (with AI risk analysis) │ ├─ Deadlines and checklists │ ├─ Showings │ └─ Open houses ├─ Vendor pipeline: Prospects ► Partners ► Referrals · Deals · Engagements └─ Property mgmt: Applications ► Leases ► Tenancies · PM consultations ``` Data visibility follows four **visibility scopes** that map onto the hierarchy: **standard** (your own records), **team** (across your team), **brokerage** (across the brokerage), and **admin** (platform administration). Roles are how users land in a scope — the classic real estate roles map directly (agent → standard, team_lead → team, broker → brokerage, system_admin → admin), and other verticals add their own roles (lender, property_manager, escrow_officer, and more) that slot into the same four scopes. Whatever credential you connect with (Claude, an API key, a JWT), you act as a specific user, so this hierarchy applies everywhere — see [the authentication model](/concepts/authentication). ## IDs and lifecycle Every record's primary key is a **UUID**. There are no special ID formats to parse — treat IDs as opaque strings. Core entities share a soft-delete lifecycle: 1. **Archive** — the record leaves normal lists but nothing is lost. Reversible. 2. **Restore** — bring an archived record back, exactly as it was. 3. **Delete** — destructive and permanent. Deletes are role-gated and require confirmation. Bulk versions of archive, restore, and delete exist for the core entities — see the [bulk operations tools](/tools/bulk-operations). When in doubt, archive: it's the safe default, and you can always restore.