crm-integration-stinger

# crm-integration-stinger CRM connectivity playbook for `crm-integration-wasp-drone`. Synthesized from 10 source notes covering Merge.dev pricing analysis, HubSpot/Salesforce/Attio official API docs, bi-directional sync architecture patterns, deduplication strategy, and lead enrichment tool comparisons. Research window: November 2025 -- May 2026. See `research/research-summary.md` for key findings and open questions. The six-guide structure maps directly to the six major decision surfaces the wasp-drone faces. --- ## When this stinger applies Load when any of the following are true: - The user needs to connect their product to HubSpot, Salesforce, Pipedrive, Attio, Folk, Close, or Copper. - The user is deciding between native API integration, Merge.dev/Unified.to, or no-code automation (Zapier, Make). - The user is designing a bi-directional sync and has not yet defined a conflict resolution policy. - The user is asking about the difference between Salesforce Leads vs Contacts, HubSpot's lack of a Lead object, or Attio's dynamic attributes. - The user has duplicate contacts/accounts in their CRM and needs a dedup strategy. - The user is adding lead enrichment (Clearbit/Breeze, Apollo, Clay) to their CRM write flow. - The user wants a code audit of existing CRM sync code. Do NOT load for: - Cold email sequencing or deliverability (route to `cold-outreach-wasp-drone`). - Researching who a company's ideal customers are from public evidence (route to `icp-research-wasp-drone`). - The product's own internal Person/Account schema (route to `db-wasp-drone`). - Implementation of the sync backend in Django or Node.js (route to `python-wasp-drone`). - Frontend CRM sync widget or CRM data display UI (route to `react-wasp-drone`). - GDPR data residency for CRM data (flag and route to `security-wasp-drone`). --- ## Critical directives These non-negotiables govern every engagement. Full justification in `guides/00-principles.md`. - **Map the CRM's data model before writing any spec or code.** The taxonomy varies radically by platform; a field mapping decision made against the wrong mental model requires weeks of retroactive cleanup. - **Define conflict resolution policy before declaring bi-directional sync designed.** The most common integration failure is two sources of truth diverging silently. A conflict resolution policy is not optional. - **State the Merge.dev trade-off explicitly.** At 500 customers on Launch plan: $1.17M/year. At the 3-CRM inflection point, re-run the native SDK math every time. - **Deduplication is first-class, not a follow-up task.** Design dedup into the sync from day one. Retrofitting is 10x more expensive. - **Run the rate limit math before committing to polling.** HubSpot Free/Starter: 100 requests/10 seconds. Salesforce CDC: 72-hour retention on replay. Naive polling architectures break at scale. - **Never overwrite consent or Do Not Contact flags during dedup merges.** Propagate opt-outs to all integrated systems immediately. GDPR/CCPA non-negotiable. - **Clearbit is Breeze Intelligence (HubSpot-acquired).** Do not recommend the standalone Clearbit API for non-HubSpot stacks; it is deprecated for external callers as of 2025-2026. See `guides/06-lead-enrichment.md`. --- ## Routing table | Request type | First guide | Key template | |---|---|---| | "Which integration approach should we use?" | `guides/01-integration-architecture.md` | `templates/integration-spec.md` | | "What's HubSpot/Salesforce/Attio's data model?" | `guides/02-crm-data-models.md` | `templates/field-mapping-table.md` | | "How do we map our schema to the CRM?" | `guides/03-field-mapping.md` | `templates/field-mapping-table.md` | | "Design our bi-directional sync" | `guides/04-sync-and-conflicts.md` | `templates/sync-design-spec.md` | | "We have duplicate contacts/accounts" | `guides/05-deduplication.md` | `templates/dedup-strategy-worksheet.md` | | "Add lead enrichment to our CRM writes" | `guides/06-lead-enrichment.md` | `templates/integration-spec.md` | | "Audit our sync code" | `guides/07-implementation-review.md` | `templates/code-audit-checklist.md` | --- ## Folder layout ``` crm-integration-stinger/ +- SKILL.md (this file) +- README.md (one-page overview) +- guides/ | +- 00-principles.md (the six non-negotiables) | +- 01-integration-architecture.md (native SDK vs Merge.dev vs Unified.to vs no-code) | +- 02-crm-data-models.md (object models for all 7 CRMs in scope) | +- 03-field-mapping.md (field mapping patterns and data-type traps) | +- 04-sync-and-conflicts.md (bi-directional sync + conflict resolution) | +- 05-deduplication.md (dedup hierarchy, survivorship, external ID alias) | +- 06-lead-enrichment.md (Apollo, Clay, Breeze Intelligence comparison) | +- 07-implementation-review.md (code audit checklist + common failure patterns) +- examples/ | +- hubspot-bidirectional-sync.md (happy-path HubSpot ↔ product bi-directional sync) | +- salesforce-lead-contact-migration.md (Lead-to-Contact lifecycle migration pattern) +- templates/ | +- integration-spec.md (full integration specification scaffold) | +- field-mapping-table.md (field mapping table template) | +- sync-design-spec.md (bi-directional sync design spec) | +- dedup-strategy-worksheet.md (dedup strategy decision worksheet) | +- code-audit-checklist.md (CRM sync code audit checklist) +- reports/ | +- README.md (how audit reports accumulate) +- research/ (owned by scripture-historian -- do NOT modify) +- research-plan.md +- research-summary.md +- index.md +- internal/ +- external/ (10 source notes, 2025-11 to 2026-05) ``` --- ## Open questions from research (surface to user before finalizing guides) 1. **Is Clearbit's original API deprecated for non-HubSpot customers?** Treat as deprecated until confirmed otherwise. Do not recommend standalone Clearbit API. See `guides/06-lead-enrichment.md`. 2. **Is Vessel.dev still production-active in 2026?** Omit from primary recommendations until confirmed. Use Merge.dev and Unified.to as the two unified API options. 3. **Which Merge.dev CRM integrations are production vs beta?** Folk, Close, and Copper may be beta. Flag to user when recommending Merge.dev for these platforms. 4. **Pipedrive rate limits not confirmed in research.** Treat as documented (API v1 docs exist) but advise user to verify before deploying. 5. **Attio bulk write status unknown as of 2026-05.** Do not assume bulk endpoint exists. Design Attio initial loads with single-record rate-limit math. --- *Forged by `stinger-forge` from `crm-integration-wasp-drone-command-brief.md` and `research/`. Part of the Legion AI Tools Factory by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*