> ## Documentation Index
> Fetch the complete documentation index at: https://octanist.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead updates

> Control how status and value updates from your CRM, integrations or the API are matched to Octanist leads, including auto-qualification, won value updates and same-company matching.

You can keep lead status and value in sync without qualifying leads by hand. Updates can come from:

* A CRM or recruitment integration, such as [Recruitee](https://octanist.com/docs/updating-integrations/recruitee.md), [Odoo](https://octanist.com/docs/updating-integrations/odoo.md) or [Zoho CRM](https://octanist.com/docs/updating-integrations/zoho-crm.md).
* [Zapier](https://octanist.com/docs/integrations/zapier.md).
* The [REST API](https://octanist.com/docs/api-reference/endpoint/update-lead.md) or [MCP server](https://octanist.com/docs/api-reference/mcp.md).
* A file upload under [Update Leads](https://octanist.com/docs/settings/update-and-export-leads.md).

Go to **Settings > Lead Updates** to choose how these updates are applied.

## How updates find the lead

An update is matched to a lead with these identifiers, in this order:

1. Octanist lead ID
2. External lead ID
3. Email
4. Phone

The first match is used. External lead IDs are exact and unique within your organization, so they are the most reliable way to match.

## Status flow

Status changes only move forward:

| From | Can become |
| - | - |
| Open | Qualified, Won or Lost |
| Qualified | Won or Lost |
| Won | Nothing. Won is final. |
| Lost | Nothing. Lost is final. |

Every external update is logged in the lead history with its source, such as Recruitee, ClickUp, Zoho or API. Failed updates are logged too.

## Settings

### Won Lead Auto-Qualification

When a lead is marked as won, also mark it as qualified if it wasn't already. The qualified conversion is then sent to your integrations before the won conversion. On by default.

Keep this on when your CRM jumps straight from a new lead to a won deal. Your ad platforms then still learn from the qualified step.

### Won Lead Value Updates

Allow integrations to change the value of leads that are already won. Off by default. When off, value updates on won leads are logged but not applied.

Turn this on when the final deal value is only known after the deal is won, for example after an invoice.

### Multiple Match Behavior

An email address or phone number can belong to several leads. Under **When multiple leads match**, choose what happens:

| Option | Effect |
| - | - |
| Return error | The update fails and needs manual resolution. |
| Update most recent | Updates the lead created most recently. This is the default. |
| Update first lead | Updates the lead created first. |
| Update all | Applies the update to all matching leads. |
| Split value across all | Splits the value evenly across all matching leads and updates them all. |

> [!NOTE]
>
> With **Update all**, each lead gets the full value and its own conversion.

### Same-Company Lead Matching

When an update finds no exact match, apply it to an open lead from the same company email domain. For example, a deal for `jan@company.com` can count toward a lead from `sanne@company.com`. Off by default.

* Exact matches always come first.
* Only open leads on exactly the same domain can match. Won and lost leads are never changed this way.
* Personal email providers, such as Gmail, Hotmail, Outlook, iCloud and Proton, internet providers such as Ziggo and KPN, and temporary email services are always excluded.
* When several open leads share the domain, **Multiple Match Behavior** decides what happens.

> [!WARNING]
>
> A deal can end up on the wrong lead, such as a colleague working on another deal. Attribution then follows the wrong lead, and the qualified and won conversions sent to your ad platforms can't be taken back. Large companies, agencies and resellers often use one domain for many unrelated people.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.