3. Clay ↔ Salesforce Integration

Jira stories: KLN-5 KLN-35 KLN-32 KLN-3 KLN-4
The native Clay ↔ Salesforce connector replaces all manual CSV exports/imports. It ensures enrichment data and reply signals flow automatically between systems, keeping lead data consistent and auditable.

⚠️ Before this connector
Clay enrichment and reply outcomes were siloed — requiring manual uploads that caused data drift, increased errors, and reduced Sales trust in SFDC data. This integration removes that dependency entirely.

3.1 Integration User Setup

One dedicated integration user is required per CRM system (e.g. one for iCare). This user must never have broad admin permissions — least-privilege access only.

Configuration Item	Setting	Notes
Profile	API Only / No UI access	Replicates IBoost Integration user model
Permission Set	Read: Contacts · Write: Leads, Campaign Members	Create dedicated permission set, do not use existing sets
Role	SBS role assigned	Required for iCare access scope
Field-level access	Scoped to approved writeback fields only	See field allowlist in section 3.2
Validation bypass	Permission to bypass validation rules	Needed — enriched leads may lack required fields
GBU access	All GBUs must be accessible	Confirm at user setup — critical for multi-GBU campaigns

3.2 Field Allowlist (Clay → Salesforce Writeback)

Only approved fields may be written back by Clay. All other fields are read-only from Clay's perspective.

Field	Object	Direction	Status
Has_Replied__c	Campaign Member	Clay → SFDC	✅ Active
ReplyClassification__c	Campaign Member	Clay → SFDC	✅ Active
external_hard_bounced__c	Lead	Smartlead → Clay → SFDC	✅ Active
overall_hard_bounced__c	Lead	Formula: Pardot HB OR Clay HB	✅ Active
company_description__c	Lead	Clay → SFDC (enrichment)	⏳ Pending Legal
Industry	Lead	Clay → SFDC (enrichment)	⏳ Pending Legal
Cold_Lead_Eligible__c	Lead	SFDC formula (read-only)	✅ Active

3.3 Enrichment Precedence Rules

When conflicting signals exist across systems, these rules determine which source wins. (KLN-3)

Data Type	Precedence Rule
Hard bounce signals	Pardot hard bounce takes precedence over Clay. overall_hard_bounced__c = Pardot HB OR Clay HB (union — never overwrite Pardot's signal with Clay's).
Email validation	Clay enriches but does not overwrite Pardot bounce status. SFDC is the system of record for deliverability decisions.
Enrichment fields	Clay may update company_description__c and Industry only if the SFDC field is currently blank. No overwrite of existing values unless explicitly approved.
Reply classification	Has_Replied_c is set-once (first response only). ReplyClassification_c can be updated on reclassification but all changes must be auditable.

3.4 Sync Cadence

Data Type	Trigger	Frequency	Owner
Campaign Member export (SFDC → Clay)	Manual (pre-campaign)	Per campaign launch	MARCOM Ops
Enrichment writeback (Clay → SFDC)	Automated via connector	Near real-time	CRM Admin
Reply sync (Clay → SFDC)	Automated via connector	Near real-time	CRM Admin
Hard bounce sync (Smartlead → Clay → SFDC)	Automated	Daily batch	CRM Admin
Eligibility flag recalculation	SFDC formula (auto)	On save / batch	Salesforce (formula)

3.5 Error Handling & Runbook

Monitor sync errors — CRM Admin checks Clay connector logs weekly. Errors surfaced in Clay's native error dashboard.
Missing field exceptions — if Clay cannot write back due to missing required SFDC fields, the validation bypass permission handles graceful partial updates. Log exceptions in the sprint Jira ticket.
Hard bounce discrepancies — if overall_hard_bounced_c does not match expected value, check Pardot HB source first, then Clay's external_hard_bounced_c. Never manually override without audit trail. (KLN-4)
Escalation path — Integration issues → CRM Admin → IT Infra (if connector-level). Data quality issues → MARCOM Ops. Legal/compliance concerns → DPO directly.

Page tree