Skip to main content

​
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.
Do not generate a new external ID every time a failed request is retried. Reuse the identifier of the original event.

​
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

​
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.
Manually using a “duplicate record” action intentionally creates another record. It is different from ingest duplicate detection.
Next: Understand sources · Lead ingest for developers