How conversion happens
There is no dedicated “Convert lead” button. Conversion happens automatically when you publish a scheduled appointment (a lead activity) for that lead. Publishing the appointment is what creates the Client, the Property, and the Project, and changes the contact from a lead into a client. Saving the appointment as a draft does not convert anything. A draft only saves the appointment and the address you entered (and may send the client an appointment email). Conversion runs only the first time the appointment is moved to Published.Who can convert a lead
Because a first-time conversion creates a project, converting a lead requires a role that can create projects: Admin, Sales Admin, Sales Member, or Client Coordinator. Ops Manager can create and edit lead activities, but cannot create projects — so publishing an appointment for a not-yet-converted lead fails for that role. Ops Managers can still publish appointments for leads that are already converted. Crew Leader cannot work with lead activities at all. Access is also limited by organization and branch. Users who are not managers can only create or update appointments that are assigned to themselves.Rule 1 — Conversion is triggered by publishing an appointment, not a standalone action
A lead becomes a client only when an appointment for that lead is saved as Published for the first time. Saving the appointment as a draft does not convert the lead; it only saves the appointment and the address. After a successful publish, the schedule refreshes and publish notifications go out (to the assignee and, as an email, to the client).Rule 2 — The order of effects on publish is fixed
When the appointment is published, conversion performs its steps in this exact order:- Save the address onto the lead — the address, city, state, and postal code you entered are stored on the lead.
- Re-read the lead (with its primary contact loaded). If the lead can’t be found at this point, conversion stops.
- Find or create the Client (this also changes the contact’s type to “client” — see Rules 4 and 5).
- Find or create the Property under that client.
- Find or create the Project for that lead and client.
Rule 3 — The lead’s existing contact is reused, not duplicated
The lead’s primary contact (name, email, phone) is carried over to the new client. Conversion reuses that same contact rather than creating a second one, so the contact’s identity is preserved from lead to client. If the lead has no primary contact, conversion stops with an error (“Lead does not have a primary contact.”). The project’s primary contact is later set from the client’s primary contact (Rule 7). Worth knowing: First name is optional when you capture a lead, but conversion requires the primary contact to have a first name (and a last name). If the primary contact has no first name, conversion fails — fill it in on the lead before publishing the appointment.Rule 4 — Converting changes the contact’s type from lead to client
When the lead’s existing contact is carried over, that contact’s type is changed to client. This happens whether a matching client already existed or a brand-new client is created — in both cases the same contact is reused and re-typed as a client. If conversion ever creates a brand-new contact (no existing one to carry over), that contact is created as a client with no preferred contact method set. This type change is what makes the contact appear as a client, and it’s why the lead afterward shows the “converted into a client” banner (Rule 9).Rule 5 — Client matching: phone first, then email; otherwise create new
When finding an existing client, conversion looks for a client whose primary contact’s email or phone matches the lead’s contact. If there are matches, it prefers a phone match first (phone is treated as the stronger identifier), then an email match (case-insensitive). If no match is found, a new client is created. When an existing client is matched, that client is reused and its primary contact’s name, email, and phone are updated only where they differ from the new values. A newly created client records when it became a client and who published the conversion. Worth knowing: Client matching keys on the contact’s email or phone only. If no email and no phone are present, a new client is always created.Rule 6 — Property matching: same client + exact same address; otherwise create new
When finding an existing property, conversion looks for a property under the same client with the exact same address text. If found, that property’s address details (city, state, postal code, and any provided attributes) are updated. If not found, a new property is created under the client, filling in placeholder values for any missing address components. An empty address stops conversion with an error (“Address is required when creating a property.”). Worth knowing: Address matching is exact-text. An address that means the same thing but is typed differently will create a second property for the same client, so property matching is looser than client or project matching.Rule 7 — Project matching: one project per lead + client; otherwise create new, linked to the lead
Conversion first looks for an existing project tied to the same lead and same client. If one exists, it is reused and no new project is created — this is the core “no duplicate project” guard. Otherwise a new project is created and linked back to the lead. When a new project is created:- The client is re-checked (must still exist, be in the same organization, not be deleted, and have a primary contact).
- The project name is the name you provided, or a fallback of
{First Last} - {date}. - The project’s primary contact comes from the client’s primary contact, along with the organization, client, property, branch, and lead.