Integration and API Spec

Integration and API Spec

CRM Data Hygiene Automation

HubSpot is the primary CRM source and write-back target. The automation reads contact and deal records, performs merge operations on high-confidence duplicate pairs, writes enriched field values, and sets suppression properties. All access is via HubSpot's Private App API using a long-lived access token scoped to the minimum required permissions.

// Primary endpoints used
GET  /crm/v3/objects/contacts?limit=100&after={paginationToken}
GET  /crm/v3/objects/deals?limit=100&after={paginationToken}
POST /crm/v3/objects/contacts/merge
PATCH /crm/v3/objects/contacts/{contactId}
PATCH /crm/v3/objects/deals/{dealId}
// Pagination: use 'paging.next.after' cursor; loop until no next cursor returned

Clearbit Enrichment is called by the Enrichment Agent for every contact record that has one or more empty priority fields (job title, company size, or industry). The API returns a structured JSON person and company object. Only confirmed, non-null values returned by Clearbit are written back to HubSpot; existing field values are never overwritten.

// Enrichment endpoint
GET https://person.clearbit.com/v2/combined/find?email={contact_email}
// Response fields mapped to HubSpot
response.person.title       -> jobtitle
response.company.metrics.employees -> numberofemployees
response.company.category.industry -> industry
// Write only if HubSpot field is null AND field not in ENRICHMENT_PROTECTED_FIELDS

Slack is used exclusively as an output channel. The Deal Hygiene Agent composes a structured digest message and posts it to the designated #sales-ops channel once per weekly run. The message lists borderline duplicate pairs, stale deals awaiting rep confirmation, enrichment failures, and a run summary. No Slack data is read back into the automation.

// Post message endpoint
POST https://slack.com/api/chat.postMessage
// Required payload fields
{
  "channel": "{SLACK_SALES_OPS_CHANNEL_ID}",
  "blocks": [ ...BlockKit JSON... ],
  "text": "CRM Hygiene Run Complete - {run_date}"
}
// Authorization header
Authorization: Bearer {SLACK_BOT_TOKEN}

Google Sheets serves as the persistent hygiene audit log. After each weekly run, the Deal Hygiene Agent appends a single row to a designated audit sheet recording run metadata and counts. This log is read by the sales manager and ops lead but is never read back by the automation.

// Append row endpoint
POST https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_AUDIT_LOG_SPREADSHEET_ID}/values/{SHEETS_AUDIT_LOG_TAB_NAME}!A1:K1:append?valueInputOption=USER_ENTERED
// Row payload (array order must match header)
[run_id, run_date, trigger_type, contacts_scanned, duplicates_merged,
 duplicates_flagged, records_enriched, enrichment_failures,
 deals_flagged, deals_suppressed, run_duration_seconds]

// ── HubSpot ──────────────────────────────────────────────────────────
HUBSPOT_API_TOKEN              = "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
HUBSPOT_PORTAL_ID              = "12345678"
HUBSPOT_WEBHOOK_SECRET         = "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

// ── Clearbit ─────────────────────────────────────────────────────────
CLEARBIT_API_KEY               = "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
CLEARBIT_MONTHLY_LOOKUP_CAP    = 2000
ENRICHMENT_PROTECTED_FIELDS    = "jobtitle,hs_lead_status"   // comma-separated HubSpot internal names

// ── Slack ─────────────────────────────────────────────────────────────
SLACK_BOT_TOKEN                = "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx"
SLACK_SALES_OPS_CHANNEL_ID     = "C0XXXXXXXXX"

// ── Google Sheets ─────────────────────────────────────────────────────
GOOGLE_SERVICE_ACCOUNT_JSON    = "{...full service account key JSON...}"
SHEETS_AUDIT_LOG_SPREADSHEET_ID = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
SHEETS_AUDIT_LOG_TAB_NAME      = "Hygiene Log"

// ── Orchestration parameters ──────────────────────────────────────────
SCHEDULE_TIMEZONE              = "America/New_York"
STALE_DEAL_DAYS                = 30
DEDUP_CONFIDENCE_THRESHOLD     = 0.85
DEDUP_REVIEW_THRESHOLD_LOW     = 0.60