Contacts & Companies
Contact
A Contact (also called "Customer" in some UI areas) is a person your organization interacts with. Contacts are the central CRM object — orders, conversations, calls, and touchpoints all link back to a contact.
Key fields
| Field | Type | Description |
|---|---|---|
id | UUID | Primary key |
organization_id | UUID | Owning tenant |
first_name | text | Given name |
last_name | text | Family name |
phone_number | text | Primary phone (often WhatsApp number) |
email | text | Email address |
company | text | Company name (free text) |
city | text | City |
country | text | Country |
source | text | How the contact was acquired (e.g., shopify, whatsapp, manual) |
journey_stage | text | Current lifecycle stage (e.g., lead, prospect, customer) |
assigned_to | UUID | Team member responsible for this contact |
tags | text[] | Freeform labels |
metadata | jsonb | Arbitrary key-value data |
created_at | timestamptz | Record creation timestamp |
Relationships
- A Contact belongs to one Organization.
- A Contact can have many Orders.
- A Contact can have many Conversations (across channels).
- A Contact can have many Call Logs.
- A Contact can have many Labels (via
customer_labelsjoin table). - A Contact has a Journey Stage tracking their lifecycle.
Synonyms
The codebase uses both customer and contact to refer to this object. In the database, the table is named customers. In the CRM UI, the term "Contact" is preferred. Treat them as identical.
Company
A Company is an organization your business interacts with (B2B context). In the current schema, company information is stored as a text field on the Contact record rather than as a separate entity. Future versions may promote Company to a first-class object.
Label
A Label is a categorical tag applied to contacts for segmentation and filtering. Labels are organization-scoped and can be assigned to multiple contacts via the customer_labels join table.
Journey Stage
A Journey Stage represents a contact's position in the sales/support lifecycle. Stages are configurable per organization. Common stages: lead → prospect → customer → churned.
Related tables
| Table | Purpose |
|---|---|
customers | Contact records |
labels | Label definitions |
customer_labels | Contact ↔ Label associations |
customer_journey_stages | Stage definitions and transitions |
lead_sources | Acquisition source definitions |