CRM
TL;DR
- Contacts, leads and a timeline, built in. Each person you record (from a WhatsApp message, a web form, an import or a manual entry) becomes a contact. Each contact can have an open lead that moves through your stages. Everything that happens is one entry on the contact's timeline.
- Twelve workflows, callable directly. Eight
crm.*workflows write and fourdata.crm.*workflows read. Start them from the API, an SDK, an AI assistant, or as steps of a composition. - One CRM per app. Every call names an Identity app. Contacts of one app are never visible from another, and everything is scoped to your organization.
- For your team, never for your app's users. Members of your organization use the CRM. Your app's end users cannot read or write it.
- Privacy built in. Record an opt-out, and erase a person's data on request while keeping your counts and funnel history.
How it fits together
| Piece | What it is | Main workflows |
|---|---|---|
| Contact | A person, deduplicated by phone, then by email. Name, WhatsApp id, owner, tags, free attributes, where they came from | crm.contact.upsert, crm.contact.update, data.crm.contact.list, data.crm.contact.get |
| Lead | One open opportunity per contact per pipeline, with a stage and an owner | crm.lead.capture, crm.lead.update-stage, crm.lead.assign, crm.lead.convert, data.crm.lead.list |
| Timeline | Notes, messages in and out, stage changes, assignments, conversions, newest first | crm.activity.add, data.crm.activity.list |
The most common call is crm.lead.capture: someone reached you, so find or create the contact, open a lead if none is open, and log what they said. It is safe to send twice. See Contacts and leads.
Where the data lives
Orkestia stores CRM data for you, keyed to your organization and one Identity app. You do not declare tables for it, and it is separate from App Data.
The CRM is deliberately small: contacts, leads, stages and a timeline. When your process needs more, keep the extra records in App Data and link them to the CRM by contact_uuid (and lead_uuid when it applies). Typical examples:
| Keep in the CRM | Keep in App Data |
|---|---|
| The person, their phone and email, tags, owner | Companies and accounts |
| One lead per contact and pipeline, its stage and owner | Several opportunities for the same person or company |
| Notes, messages and every stage change | Tasks, reminders and their outcomes |
Contact-level details in attributes (merged, so you can update one key) | Scores and fields you need to filter or sort on |
Lead lists filter by stage, open or closed, owner, pipeline and contact. Contact lists filter by owner, tag, source and a text search. Neither filters on attributes, so put a value you need to filter by in a tag (for example priority:high) or in App Data.
Guides
Ask your AI assistant
Add Ana Souza, +55 11 99999-8888, as a lead in the CRM of my app "Store", source web_form.
Show me the open leads in my app "Store" that nobody owns yet.
Move Ana's lead to qualified and add a note: asked for a quote for 20 seats.
Show me the full timeline of the contact ana@example.com.
For AI agents
| Do this | With |
|---|---|
| Find the app | identity.app.query. Never ask the user for an organization_uuid: it comes from the token |
| Find people and leads | data.crm.contact.list (search, tag, owner_user_uuid), data.crm.lead.list (stage, open_only, unassigned) |
| Read one person in full | data.crm.contact.get, then data.crm.activity.list for the timeline |
| Log an inbound person | crm.lead.capture with a ref when there is an external id, so a retry does not duplicate it |
| Add a note | crm.activity.add (kind: note, body required) |
| Change stage or owner | crm.lead.update-stage, crm.lead.assign |
| Convert or erase | crm.lead.convert, crm.contact.erase: owner or admin only, confirm with the user first. Erasure cannot be undone |
Contacts carry personal data. Show only what the user asked for, and do not copy phone numbers or emails into other systems unless asked.
Troubleshooting
Sign-in loops and state mismatches, expired sessions, notifications that do not show, updater errors, the organization mismatch warning, billing outages and where the app keeps its data on your computer
Contacts and leads
Capture people safely, deduplicate them by phone and email, move leads through your stages, assign owners, keep the timeline, and convert a lead into a user of your app