docs(audiences): document Excluded people matching — LinkedIn URL or email only

[george-dilthey]

What changed

Added an "Excluding people (or companies) from your search" sub-section to docs/audiences.md (under "Importing from people and companies search") documenting that the Excluded people panel in Audiences searches matches on LinkedIn URL or email only — not on title or other fields — and that exclusions are Clay-internal and do not prevent CRM duplicates on write-back.

Also updated docs/find-people-overview.md and docs/lookup-rows.md to consistently reflect that the Exclude people filter matches by LinkedIn URL or email (the existing wording said only "professional profile URL," missing email as a valid matching key).

Why

An enterprise customer (Intercom conversation #215475618206882) ran a people search in Audiences, excluded an audience of "all Salesforce contacts with a title," and still got duplicate records in Salesforce. They asked: "what does this feature actually do?" The human admin (Peter Johnston) had to escalate and explain: (1) exclusions match on LinkedIn URL or email, not title, and (2) Clay deduplication is within Clay only — it doesn't prevent Salesforce from creating duplicates on write-back. Neither of these facts was documented anywhere in the Audiences docs. Fin couldn't answer the question, so it escalated.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475618206882
• Slack (Peter Johnston in #team-enterprise-product-support confirming the matching behavior): https://clay-hq.slack.com/archives/C09184YSQRM/p1787581805021129?thread_ts=1787580595.222429&cid=C09184YSQRM
• Verifier (Claim 1 — exclusions match LinkedIn URL or email): PASS — clay-base/apps/api/v3/search/services/search.service.ts:1353-1363 shows the switch statement that handles only SemanticType.PersonLinkedInUrl and SemanticType.Email, silently dropping all other fields (title, phone, etc.) via the default case. clay-base/apps/api/v3/search-dsl/services/search-dsl-resolvers.ts:334-399 confirms identifiers that don't resolve to a Clay profile ID are rejected.
• Verifier (Claim 2 — exclusions are Clay-internal): PASS — clay-base/apps/api/v3/search-dsl/services/search-dsl-bitmap.service.ts and clay-base/libs/search-dsl/src/planner/planner.ts:2745-2748 show the bitmap filter operates at ClickHouse query time as a search-result filter only, with no integration into any CRM writeback logic.

Uncertainties

None — both claims verified PASS against the code.

Related observations

• Multiple existing open PRs on docs/audiences.md cover unrelated topics (docs(audiences): expand field mapping intent best practice to cover SFDC import sync path #2323, docs(audiences): add common HubSpot contact and company field examples #2321, docs(audiences): add FAQ for Salesforce duplicate company records #2305, docs(audiences): add FAQ for time-gated audience segment membership #2303, docs(audiences): document Salesforce SOQL import for Enterprise customers #2295, docs(audiences): restructure Clay table section and rename Upsert/Update Audiences Record actions #2291, docs(audiences): rewrite Clay table import section and fix Upsert action name #2288, docs(audiences): add FAQ for fixing existing duplicates, fix Import Record Matching scope #2280, docs(audiences): add CRM and warehouse sync cadence anchor sections #2272, docs(audiences): note that HubSpot sync time of day is not shown in the UI #2261, docs(clay-ads): add EEA consent, platform fields, delete-recreate behavior, match rate clarification #2251, docs(audiences): document Update segment record as admin-only and clarify permission error #2245, docs(audiences): document Enhanced Matching skip logic and hashed email output fields #2232, docs(audiences): document Enhanced Matching skip logic and hashed email output fields #2231, docs(audiences): add concrete use-case guidance to Audiences vs. Tables FAQ #2225, docs(audiences): clarify Find People destination when using Audience as Target companies #2224, docs(audiences): explain Clay-prefixed auto-populated fields and fix export credits FAQ #2215, docs(audiences): explain why Audiences fields have values when CRM fields are blank #2210, docs(audiences): cover archived workbook behavior in Origin source filter FAQ #2204, docs(audiences): explain signal vs bulk-enrichment relationship and fix auto-enrich timing #2203, docs(audiences): explain that archived source tables remain in Origin source filter #2202, docs(audiences): document signal date limitation and add FAQ #2195, docs(audiences): add Clay table import via Add data sidebar wizard #2192, docs(audiences): correct filter operators — remove false "does not contain any of" claim, add workaround #2185, docs(audiences): document Salesforce one-connection limit and Incomplete status #2184, docs(audiences): document how to pause or stop a workflow #2179, docs(audiences): document Salesforce Leads as import-only, no export sync #2166). None of them document the Excluded people feature or its matching behavior.
• PR docs(audiences): clarify Find People destination when using Audience as Target companies #2224 also touches docs/find-people-overview.md but covers using a Companies Audience segment as target companies — not the exclusion matching mechanism. No conflict.
• PR docs(manage-cell-data): document Lookup Multiple Rows cell size limit and workaround #2239 also touches docs/lookup-rows.md but covers cell size limits for Lookup Multiple Rows — entirely different section. No conflict.

Closes DOC-2086

[linear-code]

DOC-2086