Data model

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 and the endpoint reference.

The core six#

The six entities you'll touch every day:

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 — 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).
• 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, 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.

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.

How your org shapes what you see#

Every user belongs to a team, and every team belongs to a brokerage:

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.

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. When in doubt, archive: it's the safe default, and you can always restore.