Leads
Overview
A lead is a not yet qualified opportunity — somebody has shown interest, but neither is it settled whether anything will come of it, nor whether a customer will emerge at all.
That is precisely why a lead is its own object and not already a customer: as long as it is unclear whether there is anything in it, these records do not belong in the customer base. Otherwise the customer base dilutes with names that never become customers — and every evaluation on it goes crooked.
Core tasks
Capture a lead. New lead requires a name; company, customer, contact, status, score, owner, source and notes are optional. Once a customer is chosen, a contact can be selected — not before, because the selection would otherwise have nothing to draw on.
Score and classify. The score is the numeric assessment, the source records where the lead came from — both feed into reporting later. Through lead pipeline and stage the lead moves along the process.
Track the state. Six statuses ship: New, Working, Qualified, Nurture, Archived and Converted.
Nurture is the most important of them and the most often overlooked: it is the honest answer to "interesting, but not now" — instead of leaving the lead open and clogging the list, or archiving it and forgetting it.
Qualify and convert. Qualify lifts the lead to the next state. Convert turns it into a customer, optionally a contact, and a deal in the chosen pipeline — in one step, without retyping. This works in the lead view and right in the list: if a lead is In progress or Qualified, its row (and its card on the board) offers the quick action Convert — the same dialog, the same effect. A lead that has already been converted no longer offers it.
New leads arrive. When a lead is created — by hand, through a form, the booking page, a WhatsApp or SMS message or the API —, its owner is notified; without an owner, everyone allowed to maintain leads in that brand (crm.lead.manage). Whoever creates the lead themselves gets nothing. Whether the notification also comes by email, push or Slack is set per person under notifications for the event New lead.
Let company data be added. Every new lead is enriched automatically: the company domain of its email address becomes the website, and if exactly one customer carries the same domain, the lead is linked to it (company and industry then come from that customer). With AI switched on, it also adds company, industry and website. Only empty fields are filled — what you maintained stays. The Company data card in the lead view shows when and how the lead was enriched, and Enrich now runs it again. Without AI (switched off or restricted) the rules run on their own.
Work on several at once. Leads can be selected and changed together. The feedback names partial successes too, rather than silently half-completing a bulk operation.
Fields in detail
The What it does column answers what changes in the system — not what the field is called. The grey name behind the label is the API field: the same thing runs under that name through automation, import and AI tools.
Creating and editing a lead
| Field | Required | Values / format | What it does |
|---|---|---|---|
Name name | yes | text, max. 255 characters | The only required entry. Appears in the list, in search and in the history, and is proposed as the deal title on conversion. Without a name nothing is saved. |
Company companyName | no | text, max. 255 characters | A plain note on the lead, independent of the customer base. Shown in the list as a second line below the name and tells people with the same name apart. |
Language locale | no | one of the configured languages | The language you address this lead in. Mails and text blocks for this lead are produced in it; empty means the system default. Only on the lead page, not in the create dialog. |
Customer customerId | no | an existing customer | Attaches the lead to an existing customer. Only then can a contact be picked — otherwise the selection would have nothing to reach into. Conversion does not create a second customer. |
Contact primaryContactId | no | a contact of the chosen customer | The person you talk to. The list only offers contacts of the customer chosen above; without a customer the field stays locked ("Pick a customer first"). |
Score score | no | whole number 0–100 | Your numeric assessment. It triggers nothing and moves nothing on its own — it can be sorted and filtered on and feeds the funnel and the forecast. |
Expected value valueAmount | no | amount, 0 or more | What the deal would be worth. The value adds up per lead stage and carries the funnel before there is a deal; conversion takes it over as the deal value. A negative amount is set to 0. Only on the lead page, not in the create dialog. |
Expected close expectedCloseDate | no | date | When you expect the decision — a plan, not a fact. Conversion passes the date on to the deal. Only on the lead page, not in the create dialog. |
Owner ownerId | no | an employee | Who works the lead. Governs who sees it with crm.lead.view (without view_all you only see your own) and is the proposal for the deal owner on conversion. Empty = "Without owner", a value of its own in filter and grouping. |
Source sourceId | no | master data "Sources" | Where the lead came from. The basis of the source report; passed on to the deal on conversion. Maintained under CRM settings. |
Lead pipeline leadPipelineId | no | a pipeline of type "lead" | The path this lead travels. Determines which lead stages are on offer at all. |
Lead stage leadStageId | no | a stage of the chosen pipeline | Where the lead stands. The stage carries the status: you change the status by changing the stage — from the list as well. If the pipeline has no stage for the wanted status, the system says "Not moved" instead of quietly doing nothing. Without a pipeline the field stays locked. |
Tags tags | no | several terms, max. 100 characters each | Free multi-way grouping across pipeline and source. Filterable and reportable. |
Website website | no | address, max. 255 characters | The company's website — by hand or from enrichment. On conversion it becomes the new customer's website. Lead view only. |
Industry industry | no | text, max. 120 characters | The company's industry — by hand or from enrichment. On conversion it becomes the new customer's industry. Lead view only. |
Notes notes | no | multi-line text | Free text on the lead. Shown on the page and searched; it does not replace the communication history. |
Watchers watcherIds | no | list of users | Who may read the lead without owning it. An additional read permission next to the owner, not a way around the rules: without crm.lead.view a watcher sees nothing either. Saving replaces the whole list. |
Brand brandId | no | one of your brands | Assigns the lead to a brand. Whoever cannot see the brand cannot see the lead — the list's brand filter reads the same field. Empty means: assigned to no brand. |
Converting
Convert creates customer, optionally contact, and deal in one step.
| Field | Required | Values / format | What it does |
|---|---|---|---|
Pipeline pipelineId | yes | a pipeline of type "deal" | Which sales pipeline the new deal is created in. Determines the selectable stages. |
Stage stageId | yes | a stage of the chosen pipeline | Where the deal starts. |
Deal title dealTitle | no | text, max. 500 characters | Title of the new deal. Left empty, the lead name is used. |
Create contact createContact | no | yes/no | Additionally creates a contact from the lead data. Off means: only customer and deal are created. |
Deal owner ownerId | no | an employee | Who owns the new deal. Pre-filled with the lead owner. |
After conversion the lead sits on Converted and leaves the default view. It is not deleted — the work continues on the deal.
List: columns and filters
| Column | From | What it shows |
|---|---|---|
| Name | name + companyName | Name, with the company underneath. |
| Status | leadStageStatusKey | The status carried by the current stage. Changeable in the row — which moves the stage. |
| Score | score | Sortable and editable straight in the row (with crm.lead.manage). |
| Owner | ownerId | Changeable in the row. |
| Lead pipeline | leadPipelineName | The path being travelled. |
| Source | sourceLabel | Where it came from. |
| Created | createdAt | When it was captured. |
Filtering is by status, owner, source, tag and brand; materialised formula fields from the CRM settings appear as further columns and filters. The row carries the quick action Convert on the right (only for In progress/*Qualified*). The source can also be chosen as a filter in funnel & analysis.
Interface and automation only
No mask carries these fields; they can be set through the interface, an import or an automation.
| Field | Values / format | What it does |
|---|---|---|
contactData | label-to-value mapping | Contact details on the lead while there is no contact record yet (mail, phone from a form). Conversion turns them into the contact. |
utmParams | label-to-value mapping | Campaign markers of the origin (utm_source, utm_medium, …) as a web form delivers them. Refines the source down to the individual ad. |
externalRefs | label-to-value mapping | Origin in a foreign system — the identifier under which the same record is kept there. A second import recognises the lead by it instead of creating it again. |
customerUlid | identifier of a customer | Forces exactly this existing customer on conversion. Left empty, Customer decides; otherwise a new one is created. |
newCustomerName | text, max. 255 characters | Name of the customer created on conversion. Left empty, company or lead name is used. |
newCustomerType | business or individual | Whether the new customer is created as a company or as a private person. |
enrichedAt / enrichmentSource | timestamp / rules or ai | Read-only: when the lead was enriched and whether AI contributed. Enrich on demand: POST /api/v1/crm/leads/{ulid}/enrich. |
Settings & permissions
- Module
module.crm. With it off, the page is gone — entirely, not merely hidden. - Two levels of visibility:
crm.lead.viewshows your own leads,crm.lead.view_all
additionally everyone else's. Salespeople who should see only their own get the first level. crm.lead.manage allows creating and changing.
- Statuses, sources and pipelines are master data and are maintained under
- Automatic assignment through pipeline routing — including
round-robin distribution of ownership.
- Intake in the CRM settings: Enrich new leads automatically on/off and,
per channel, whether a WhatsApp or SMS first contact from an unknown number creates a ticket (default), a lead instead of the ticket, or both. Further rules — owner, stage, task — are automations on Lead created.
- Visibility rule “own only”: what you may not see you cannot change, delete, convert or enrich
either.
FAQ & troubleshooting
I see fewer leads than a colleague. Then you hold crm.lead.view and they additionally hold crm.lead.view_all. That is not a fault but the intent of the two-level visibility.
The contact cannot be selected. Choose the customer first. Contacts hang off customers, see Contacts.
A converted lead has disappeared from the list. It is at Converted. The resulting deal and the customer carry the work forward.
A WhatsApp message became a ticket instead of a lead. The lead is only created on first contact: if the number already belongs to a contact or a ticket runs from it, it stays a ticket. Also check the setting under Intake.
Enrichment added nothing. An address at a public mailbox provider (such as gmail.com) reveals no company, and fields already maintained stay untouched. Without AI switched on, only the rules apply.
Two leads are obviously the same company. That is what Duplicates is for — they can be merged there rather than deleting one by hand.