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

# Prevent duplicate leads

> Use external IDs and duplicate rules to keep repeated submissions from creating unintended records.

# Prevent duplicate leads

Airlead provides two separate protections because a repeated request and a similar person are not always the same problem:

1. **Idempotency** recognizes the same upstream event.
2. **Duplicate detection** finds an existing person with the same email address or phone number.

## Use an external ID for every integrated lead

Send a stable `externalId` from the source system with every webhook request.

For the same source, sending the same external ID again returns the existing lead as an **idempotent replay** instead of creating another person and interest.

```json theme={null}
{
  "externalId": "crm-lead-1001",
  "firstName": "Maria",
  "lastName": "Example",
  "email": "maria@example.com"
}
```

<Warning>
  Do not generate a new external ID every time a failed request is retried. Reuse the identifier of the original event.
</Warning>

## Configure duplicate detection

Duplicate detection can compare new data by:

* email address
* phone number

It can search within:

* the current channel
* the entire workspace

The source can then:

* **Reject** the new lead, or
* **Warn** and keep it marked as a duplicate for review.

Both workspace-level duplicate detection and the source's duplicate rule must be enabled for this check to run.

## Idempotent replay vs. duplicate

| Result                           | Meaning                                                             | Recommended action                                       |
| -------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------- |
| `idempotent_replay`              | The same source already processed this external ID                  | Treat as success; do not resend with a new ID            |
| `duplicate`                      | Email or phone matches an existing person under the configured rule | Review according to your business policy                 |
| `rejected` with `duplicate_lead` | A duplicate matched and the source uses reject mode                 | Do not create another record; inspect the reported match |
| `accepted`                       | No configured protection blocked the submission                     | Continue with qualification and delivery                 |

## Choose the right scope

Use **channel scope** when the same contact may legitimately enter different lead programs.

Use **workspace scope** when your organization must review any repeated person before accepting another request.

Remember that one person can legitimately have several interests. A previous solar request should not automatically make a later heat-pump request invalid.

## Before importing or going live

1. Decide which upstream field becomes `externalId`.
2. Confirm that it remains stable across retries.
3. Enable duplicate detection at workspace level if required.
4. Configure email, phone, scope, and warn/reject behavior on the source.
5. Submit one synthetic lead.
6. Replay the same external ID and expect `idempotent_replay`.
7. Submit a new external ID with the same email or phone and verify the configured duplicate result.

## If duplicates already exist

1. Open **Records → Persons**.
2. Search by email address and phone number.
3. Compare interests, source, external ID, and creation time.
4. Preserve valid separate interests.
5. Correct or remove only records your process identifies as unintended duplicates.
6. Fix the source configuration before importing again.

<Note>
  Manually using a “duplicate record” action intentionally creates another record. It is different from ingest duplicate detection.
</Note>

Next: [Understand sources](/guides/channels-delivery/sources) · [Lead ingest for developers](/developers/lead-ingest)