Clay Advanced Troubleshooting

Overview

Deep debugging techniques for complex Clay issues that resist standard troubleshooting. Covers provider-level isolation, waterfall diagnosis, HTTP API column debugging, Claygent failure analysis, and Clay support escalation with proper evidence.

Prerequisites

• Access to Clay table with the failing enrichments
• curl and jq for API testing
• Understanding of Clay's enrichment architecture (providers, waterfall, columns)
• Browser developer tools for network inspection

Instructions

Step 1: Isolate the Failure Layer

#!/bin/bash
# clay-layer-test.sh — test each integration layer independently
set -euo pipefail

echo "=== Layer Isolation Test ==="

# Layer 1: Webhook delivery
echo "Layer 1: Webhook"
WEBHOOK_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST "$CLAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"_debug": true, "domain": "google.com"}')
echo "  Webhook: $WEBHOOK_CODE"

# Layer 2: Enterprise API (if applicable)
if [ -n "${CLAY_API_KEY:-}" ]; then
  echo "Layer 2: Enterprise API"
  API_RESULT=$(curl -s -X POST "https://api.clay.com/v1/companies/enrich" \
    -H "Authorization: Bearer $CLAY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"domain": "google.com"}')
  echo "  API response keys: $(echo "$API_RESULT" | jq 'keys')"
fi

# Layer 3: HTTP API callback endpoint
echo "Layer 3: Callback endpoint"
CALLBACK_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST "${CLAY_CALLBACK_URL:-http://localhost:3000/api/clay/enriched}" \
  -H "Content-Type: application/json" \
  -d '{"_debug_test": true}')
echo "  Callback: $CALLBACK_CODE"

echo ""
echo "First failing layer = root cause location"

Step 2: Diagnose Enrichment Column Failures

In the Clay UI, click on red/error cells to see detailed error messages:

# Common enrichment column error patterns and root causes:
errors:
  "No data found":
    meaning: "Provider has no data for this input"
    check:
      - Is the input domain valid? (not personal email domain)
      - Is the input name spelled correctly?
      - Is the provider connected? (Settings > Connections)
    fix: "Add more waterfall providers for broader coverage"

  "Rate limit exceeded":
    meaning: "Provider API rate limit hit"
    check:
      - How many rows are processing simultaneously?
      - Is the provider's rate limit known? (see provider docs)
    fix: "Reduce table row count, add delay between batche…

Clay Architecture Variants

Overview

Three proven architecture patterns for Clay data enrichment at different scales. Clay is a hosted SaaS -- your architecture decisions focus on how you send data in (webhooks), how you get enriched data out (HTTP API columns, CRM sync, or CSV export), and how you orchestrate the flow.

Prerequisites

• Clay account with appropriate plan tier
• Clear understanding of data volume and latency requirements
• Infrastructure for chosen architecture tier (if queue-based or event-driven)

Instructions

Architecture 1: Direct Integration (Simple)

Best for: Small teams, < 1K enrichments/day, ad-hoc usage.

┌──────────────┐     webhook     ┌───────────┐
│ Your App     │───────POST─────>│ Clay Table │
│ (or CSV)     │                 │ (enriches) │
└──────────────┘                 └─────┬─────┘
                                       │
                                  CRM action
                                  or CSV export
                                       │
                                       v
                                 ┌───────────┐
                                 │ CRM / DB  │
                                 └───────────┘

// Direct: send leads synchronously, export results manually
async function directEnrich(leads: Lead[]): Promise<void> {
  for (const lead of leads) {
    await fetch(process.env.CLAY_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(lead),
    });
    await new Promise(r => setTimeout(r, 250)); // Rate limit
  }
  console.log(`Sent ${leads.length} leads. Check Clay table for enriched data.`);
  // Enriched data reaches CRM via Clay's native CRM action column
}

Pros: Zero infrastructure, 5-minute setup, works on all Clay plans. Cons: No retry logic, no programmatic access to enriched data, manual export only.

Architecture 2: Webhook-in, HTTP API-out (Standard)

Best for: Growing teams, 1K-10K enrichments/day, CRM integration.

┌──────────────┐     webhook     ┌───────────┐   HTTP API col   ┌──────────────┐
│ Your App     │───────POST─────>│ Clay Table │──────POST──────>│ Your Webhook │
│              │                 │ (enriches) │                 │ Handler      │
└──────────────┘                 └───────────┘                 └──────┬───────┘
                                                                      │
                                                                 Process +
                                                                 Route
                                                                      │
                                                          ┌─────…

Clay CI Integration

Overview

Set up CI/CD pipelines for Clay-powered applications. Since Clay is a web platform (not a local service), CI focuses on: (1) testing webhook handler code, (2) validating data transformation logic, (3) checking enrichment data schema compliance, and (4) optional live integration tests against Clay's API.

Prerequisites

• GitHub repository with Actions enabled
• Clay webhook URL stored as GitHub secret
• Node.js/Python project with test framework

Instructions

Step 1: Create GitHub Actions Workflow

# .github/workflows/clay-integration.yml
name: Clay Integration Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  CLAY_WEBHOOK_URL: ${{ secrets.CLAY_WEBHOOK_URL }}
  CLAY_API_KEY: ${{ secrets.CLAY_API_KEY }}

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
        env:
          # No Clay credentials needed for unit tests (use mocks)
          CLAY_WEBHOOK_URL: "https://mock.webhook.test"

  data-validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - name: Validate input data schemas
        run: npx tsx scripts/validate-clay-schemas.ts
      - name: Check for PII in test fixtures
        run: |
          if grep -rn '@gmail.com\|@yahoo.com\|@hotmail.com' test/fixtures/; then
            echo "ERROR: Real email addresses found in test fixtures"
            exit 1
          fi

  integration-tests:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: [unit-tests]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - name: Test webhook connectivity
        run: |
          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
            -X POST "$CLAY_WEBHOOK_URL" \
            -H "Content-Type: application/json" \
            -d '{"_ci_test": true, "_run_id": "${{ github.run_id }}"}')
          if [ "$HTTP_CODE" != "200" ]; then
            echo "Webhook connectivity check failed: HTTP $HTTP_CODE"
            exit 1
          fi

Step 2: Configure Secrets

# Store Clay credentials as GitHub secrets
gh secret set CLAY_WEBHOOK_URL --body "https://app.clay.com/api/v1/webhooks/your-id"
gh …

Clay Common Errors

Overview

Quick reference for the top 12 most common Clay errors across webhooks, enrichment columns, HTTP API columns, Claygent, and CRM integrations. Each error includes the exact symptom, root cause, and fix.

Prerequisites

• Clay account with an active table
• Access to Clay table error indicators (red cells, exclamation marks)
• Browser developer tools for webhook debugging

Instructions

Error 1: Webhook Returns 422 Unprocessable Entity

Symptom: Data sent to webhook URL but rows never appear in table.

Cause: Invalid JSON payload or missing Content-Type header.

Fix:

# Always include Content-Type header
curl -X POST "$CLAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "domain": "example.com"}'

# Validate JSON before sending
echo '{"email": "test@example.com"}' | jq . || echo "Invalid JSON!"

Error 2: Webhook URL Returns 404

Symptom: 404 Not Found when POSTing to webhook URL.

Cause: Table was deleted, webhook was replaced, or URL was copied incorrectly.

Fix: Open the Clay table, click + Add > Webhooks > Monitor webhook, and re-copy the URL. Each table has a unique webhook ID.

Error 3: Enrichment Column Shows "No Data Found"

Symptom: Enrichment column returns empty for most rows.

Cause: Input data quality is poor (personal email domains, invalid domains, missing fields).

Fix:

// Pre-validate before sending to Clay
const personalDomains = ['gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com'];

function isEnrichable(row: { domain?: string; email?: string }): boolean {
  if (!row.domain || !row.domain.includes('.')) return false;
  if (personalDomains.some(d => row.domain!.endsWith(d))) return false;
  if (row.email && personalDomains.some(d => row.email!.endsWith(d))) return false;
  return true;
}

Error 4: "Credit Balance Insufficient"

Symptom: Enrichment stops mid-table with credit error.

Cause: Monthly credit allowance exhausted.

Fix: Check credit balance in Settings > Plans & Billing. Options:

• Connect your own provider API keys (saves 70-80% credits)
• Reduce waterfall depth (fewer providers = fewer credits per row)
• Upgrade plan for more monthly credits

Error 5: Webhook Submiss…

Clay Core Workflow A: Lead Enrichment Pipeline

Overview

Primary workflow for Clay: take a list of companies or contacts, push them into a Clay table via webhook, let Clay's enrichment columns fill in missing data (emails, titles, company info, tech stack), and export the enriched results to your CRM or outreach tool. This is the core use case for 90%+ of Clay users.

Prerequisites

• Completed clay-install-auth setup
• Clay table with webhook source configured
• At least one enrichment provider connected (Apollo, Clearbit, Hunter, etc.)
• Destination CRM or outreach tool (HubSpot, Salesforce, Instantly, etc.)

Instructions

Step 1: Design Your Clay Table Schema

In the Clay web UI, create a table with these column types:

Step 2: Set Up Waterfall Email Enrichment

In Clay UI, add a waterfall enrichment column:

1. Click + Add Column > Find Work Email (Waterfall)
2. Configure provider order (cheapest first):

• Apollo (2 credits) -- highest coverage
• Hunter.io (2 credits) -- strong for smaller companies
• Prospeo (2 credits) -- European coverage

1. Map input: first_name, last_name, domain
2. Enable Stop on first result to save credits
3. Enable Auto-run on new rows

Step 3: Push Leads into Clay via Webhook

// src/workflows/enrich-leads.ts
import { getClayClient } from '../clay/instance';

interface LeadInput {
  domain: string;
  first_name: string;
  last_name: string;
  source?: string;
}

async function enrichLeadList(leads: LeadInput[]): Promis…

Clay Core Workflow B: Claygent AI Research & Personalization

Overview

Complements the enrichment pipeline (clay-core-workflow-a) with AI-powered research and personalization. Uses Claygent (Clay's built-in AI research agent powered by GPT-4) to scrape websites, extract insights, and generate personalized outreach copy for each prospect. 30% of Clay customers use Claygent daily, generating 500K+ research tasks per day.

Prerequisites

• Completed clay-core-workflow-a with enriched table
• Clay Pro plan or higher (Claygent requires Pro+)
• Understanding of prompt engineering basics

Instructions

Step 1: Add a Claygent Research Column

In your Clay table with enriched leads:

1. Click + Add Column > Use AI (Claygent)
2. Choose model: Claygent Neon (best for data extraction and formatting)
3. Write your research prompt referencing table columns:

Research {{Company Name}} ({{domain}}) and find:
1. Their most recent funding round (amount, date, investors)
2. Any recent product launches or major announcements from the last 6 months
3. Their primary competitors

Return results as structured data. If information is not found, return "Not found" for that field.

1. Enable Auto-run on new rows

Step 2: Configure Multi-Output Claygent (Neon Model)

Claygent Neon can extract multiple data points into separate columns from a single run:

Research the company at {{domain}} and extract:

Output 1 (Recent News): The most notable company news from the last 90 days. One sentence.
Output 2 (Tech Stack): List the main technologies they use (check job postings, BuiltWith, Wappalyzer data).
Output 3 (Pain Points): Based on their Glassdoor reviews and recent job postings, identify likely operational pain points.
Output 4 (Competitor): Name their primary competitor.

Map each output to a separate column for downstream use in personalization.

Step 3: Build a Personalized Email Opener Column

Add an AI column (not Claygent -- use the faster AI model for text generation):

You are a sales copywriter. Write a personalized 2-sentence email opener for {{first_name}} at {{Company Name}}.

Context about the prospect:
- Title: {{Job Title}}
- Company size: {{Employee Count}} employees
- Industry: {{Industry}}
- Recent news: {{Recent News}}
- Tech stack: {{Tech Stack}}

Rules:
- Reference one specific fact about their company (not generic)
- Do NOT use "I noticed" or "I came across" (overused)
- Keep it under 40 words
- Sound human, not AI-generated
- End with a natural transition to your value prop

Step 4: Quality-Check AI Output Before Campaign Launch

Before using AI-generate…

Clay Cost Tuning

Overview

Reduce Clay data enrichment spending by connecting your own API keys (70-80% savings), optimizing waterfall depth, improving input data quality, and implementing budget controls. Clay's March 2026 pricing split credits into Data Credits and Actions, changing the optimization calculus.

Prerequisites

• Clay account with visibility into credit consumption
• Understanding of which enrichment columns are in your tables
• Access to Clay Settings > Plans & Billing

Instructions

Step 1: Connect Your Own Provider API Keys (Biggest Savings)

This is the single most impactful cost reduction. Clay charges 0 Data Credits when you use your own API keys:

Setup: Go to Settings > Connections in Clay, click Add Connection, and paste your provider API key. All enrichments using that provider will consume 0 Clay credits (1 Action is still consumed per enrichment).

Step 2: Optimize Waterfall Enrichment Depth

Each waterfall step costs credits (if using Clay-managed keys) and time:

# Expensive waterfall (5 providers, 10-15 credits/row):
expensive:
  - apollo:      2 credits
  - hunter:      2 credits
  - prospeo:     2 credits
  - dropcontact: 3 credits
  - findymail:   3 credits
  total_max: 12 credits/row
  coverage: ~92%

# Optimized waterfall (2 providers, 4 credits/row):
optimized:
  - apollo:      2 credits  # Highest coverage provider first
  - hunter:      2 credits  # Strong backup
  total_max: 4 credits/row
  coverage: ~83%
  savings: "67% credit reduction, ~9% coverage loss"

March 2026 change: Failed lookups no longer cost Data Credits. This makes wider waterfalls less expensive than before, since you only pay when data is actually found.

Step 3: Pre-Filter Input Data

Credits wasted on unenrichable rows are the most common cost leak:

// src/clay/cost-filter.ts
function estimateCreditCost(rows: any[], creditsPerRow: number): {
  filteredRows: any[];
  estimatedCredits: number;
  savings…

Clay Data Handling

Overview

Manage lead data through Clay enrichment pipelines in compliance with GDPR, CCPA, and data privacy best practices. Clay enriches records with PII (emails, phone numbers, LinkedIn profiles, job titles), requiring careful handling of consent, retention, and export controls.

Prerequisites

• Clay account with enriched tables
• Understanding of GDPR/CCPA requirements for B2B data
• Data retention policy defined by your legal team
• CRM or database for enriched data storage

Instructions

Step 1: Classify Enriched Data by Sensitivity

// src/clay/data-classification.ts
enum DataSensitivity {
  PUBLIC = 'public',       // Company name, industry, employee count
  BUSINESS = 'business',   // Work email, job title, LinkedIn URL
  PERSONAL = 'personal',   // Phone number, personal email
  RESTRICTED = 'restricted' // Home address, personal phone
}

const FIELD_CLASSIFICATION: Record<string, DataSensitivity> = {
  company_name: DataSensitivity.PUBLIC,
  industry: DataSensitivity.PUBLIC,
  employee_count: DataSensitivity.PUBLIC,
  domain: DataSensitivity.PUBLIC,
  work_email: DataSensitivity.BUSINESS,
  job_title: DataSensitivity.BUSINESS,
  linkedin_url: DataSensitivity.BUSINESS,
  first_name: DataSensitivity.BUSINESS,
  last_name: DataSensitivity.BUSINESS,
  phone_number: DataSensitivity.PERSONAL,
  personal_email: DataSensitivity.RESTRICTED,
  home_address: DataSensitivity.RESTRICTED,
};

function classifyRow(row: Record<string, unknown>): Record<DataSensitivity, string[]> {
  const classified: Record<DataSensitivity, string[]> = {
    public: [], business: [], personal: [], restricted: [],
  };
  for (const [field, value] of Object.entries(row)) {
    if (value == null) continue;
    const sensitivity = FIELD_CLASSIFICATION[field] || DataSensitivity.BUSINESS;
    classified[sensitivity].push(field);
  }
  return classified;
}

Step 2: Validate Input Data Before Enrichment

// src/clay/data-validation.ts
import { z } from 'zod';

const ClayInputSchema = z.object({
  domain: z.string().min(3).refine(d => d.includes('.'), 'Invalid domain'),
  first_name: z.string().min(1).max(100),
  last_name: z.string().min(1).max(100),
  email: z.string().email().optional(),
  source: z.string().optional(),
  consent_basis: z.enum(['legitimate_interest', 'consent', 'contract']).optional(),
});

function validateForEnrichment(rows: unknown[]): {
  valid: z.infer<typeof ClayInputSchema>[];
  invalid: { row: unknown; errors: string[] }[];
} {
  const valid: z.infer<typeof ClayInputSchema>[] = [];
  const invalid: { row: unknown; errors: string[] }[] = [];

  for (const row of rows) {
    const result = ClayInputSchema.safeParse(row);
    if …

Clay Debug Bundle

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A'

Overview

Collect all diagnostic information needed for Clay support tickets. Clay is a web platform, so debugging focuses on webhook delivery, enrichment column errors, HTTP API responses, and credit consumption -- not pods or clusters.

Prerequisites

• Clay account with access to affected table
• curl for testing webhook/API connectivity
• Browser developer tools for capturing network requests

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# clay-debug-bundle.sh — collect Clay integration diagnostics
set -euo pipefail

BUNDLE_DIR="clay-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Clay Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 2: Test Webhook Connectivity

# Test webhook endpoint is reachable
echo "--- Webhook Test ---" >> "$BUNDLE_DIR/summary.txt"
WEBHOOK_URL="${CLAY_WEBHOOK_URL:-not_set}"
if [ "$WEBHOOK_URL" != "not_set" ]; then
  HTTP_CODE=$(curl -s -o "$BUNDLE_DIR/webhook-response.txt" -w "%{http_code}" \
    -X POST "$WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d '{"_debug": true, "_test": "debug-bundle"}')
  echo "Webhook HTTP Status: $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"
  echo "Webhook URL: ${WEBHOOK_URL:0:50}..." >> "$BUNDLE_DIR/summary.txt"
else
  echo "CLAY_WEBHOOK_URL: NOT SET" >> "$BUNDLE_DIR/summary.txt"
fi

Step 3: Capture Environment and Configuration

# Capture environment (redacted)
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "Python: $(python3 --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -s -r)" >> "$BUNDLE_DIR/summary.txt"
echo "CLAY_API_KEY: ${CLAY_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "CLAY_WEBHOOK_URL: ${CLAY_WEBHOOK_URL:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

# Capture .env (redacted)
if [ -f .env ]; then
  sed 's/=.*/=***REDACTED***/' .env > …

Clay Deploy Integration

Overview

Deploy applications that integrate with Clay (webhook receivers, enrichment processors, CRM sync services) to production platforms. Clay itself is a hosted SaaS -- you deploy the code that interacts with Clay, not Clay itself. The critical requirement is a publicly accessible HTTPS endpoint for Clay's HTTP API columns to call back to.

Prerequisites

• Application code that handles Clay webhooks or HTTP API callbacks
• Platform CLI installed (vercel, gcloud, or docker)
• Clay webhook URL and/or API key stored securely
• HTTPS endpoint accessible from the public internet

Instructions

Step 1: Vercel Deployment (Serverless)

Best for: Webhook receivers, small-scale enrichment handlers.

# Set Clay secrets in Vercel
vercel env add CLAY_WEBHOOK_URL production
vercel env add CLAY_API_KEY production
vercel env add CLAY_WEBHOOK_SECRET production

# Deploy
vercel --prod

// api/clay/callback.ts — Vercel serverless function
import type { VercelRequest, VercelResponse } from '@vercel/node';
import crypto from 'crypto';

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') return res.status(405).end();

  // Validate webhook signature
  const signature = req.headers['x-clay-signature'] as string;
  const secret = process.env.CLAY_WEBHOOK_SECRET!;
  const expected = crypto.createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature || ''), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process enriched data from Clay HTTP API column
  const enrichedLead = req.body;
  console.log('Received enriched lead:', {
    email: enrichedLead.email,
    company: enrichedLead.company_name,
    score: enrichedLead.icp_score,
  });

  // Push to CRM, database, or outreach tool
  await processLead(enrichedLead);

  return res.status(200).json({ status: 'processed' });
}

Step 2: Cloud Run Deployment (Container)

Best for: High-volume enrichment pipelines, CRM sync services.

# Dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 8080
ENV PORT=8080
CMD ["node", "dist/index.js"]

# Build and deploy to Cloud Run
gcloud builds submit --tag gcr.io/$PROJECT_ID/clay-handler

gcloud run deploy clay-handler \
  --image gcr.io/$PROJECT_ID/clay-handler \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-secrets "CLAY_API_KEY=clay-api-key:latest,CLAY_WEBHOOK_SECRET=clay…

Clay Enterprise RBAC

Overview

Control access to Clay tables, enrichment credits, and integrations at the team level. Clay uses a workspace model where team members are assigned Admin, Member, or Viewer roles. This skill covers role assignment, credit budget allocation, API key isolation, and audit procedures.

Prerequisites

• Clay Team or Enterprise plan
• Workspace admin privileges
• Understanding of team structure and data access needs

Instructions

Step 1: Define Role Matrix

Clay has three built-in roles with fixed permissions:

Recommended role assignments:

roles:
  admin:
    assign_to:
      - Revenue Operations Lead
      - GTM Engineering Lead
    why: "Controls billing, integrations, and team access"

  member:
    assign_to:
      - SDRs building prospect lists
      - Growth engineers building pipelines
      - Marketing ops running enrichment campaigns
    why: "Can create tables and run enrichments but can't change billing or integrations"

  viewer:
    assign_to:
      - Sales managers reviewing lead quality
      - Executives checking pipeline metrics
      - Finance reviewing credit usage
    why: "Read-only access to enriched data and exports"

Step 2: Invite and Manage Team Members

In Clay UI: Settings > Members > Invite

Best practices:

• Use company email addresses (not personal)
• Start new members as Viewers until they complete Clay training
• Audit member list quarterly -- remove departed employees immediately

Step 3: Isolate API Keys by Integration

Create separate API keys for each downstream system to enable independent revocation:

api_keys:
  crm-sync-prod:
    purpose: "HubSpot CRM sync from Clay"
    used_by: "HTTP API column in Outbound Leads table"
    rotation: quarterly

  outbound-instantly:
    purpose: "Push qualified leads to Instantly.ai"
    used_by: "HTTP API column for outreach"
    rotation: quarterly

  internal-dashboard:
    purpose: "Pull enrichment metrics for internal dashboard…

Clay Hello World

Overview

Minimal working example: send a company domain to a Clay table via webhook, let Clay's enrichment columns fill in company data, and retrieve the enriched result. Clay does not have a traditional SDK — you interact with it via webhooks (data in), HTTP API columns (data out), and the web UI.

Prerequisites

• Completed clay-install-auth setup
• Clay workbook with a webhook source configured
• At least one enrichment column added to the table

Instructions

Step 1: Create a Clay Table with Enrichment

In the Clay web UI:

1. Create a new workbook
2. Add columns: domain, company_name, employee_count, industry
3. Click + Add at bottom, select Webhooks > Monitor webhook
4. Copy the webhook URL
5. Add an enrichment column: + Add Column > Enrich Company (uses the domain column as input)

Step 2: Send Your First Record via Webhook

# Send a single company domain to your Clay table
curl -X POST "https://app.clay.com/api/v1/webhooks/YOUR_WEBHOOK_ID" \
  -H "Content-Type: application/json" \
  -d '{"domain": "openai.com"}'

Within seconds, Clay creates a new row and auto-runs the enrichment column. The company_name, employee_count, and industry columns fill in automatically.

Step 3: Send Multiple Records

# Batch send — each object becomes a row
for domain in stripe.com notion.so figma.com linear.app; do
  curl -s -X POST "https://app.clay.com/api/v1/webhooks/YOUR_WEBHOOK_ID" \
    -H "Content-Type: application/json" \
    -d "{\"domain\": \"$domain\"}"
  echo " -> Sent $domain"
done

Step 4: Send from Node.js

// hello-clay.ts — send records to Clay via webhook
const CLAY_WEBHOOK_URL = process.env.CLAY_WEBHOOK_URL!;

interface LeadInput {
  email?: string;
  domain?: string;
  first_name?: string;
  last_name?: string;
  linkedin_url?: string;
}

async function sendToClay(lead: LeadInput): Promise<Response> {
  const response = await fetch(CLAY_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(lead),
  });

  if (!response.ok) {
    throw new Error(`Clay webhook failed: ${response.status} ${response.statusText}`);
  }
  return response;
}

// Send a test lead
await sendToClay({
  email: 'jane@stripe.com',
  first_name: 'Jane',
  last_name: 'Doe',
  domain: 'stripe.com',
});
console.log('Record sent to Clay — check your table for enriched …

Clay Incident Runbook

Overview

Rapid response procedures for Clay-related production incidents. Clay is a hosted SaaS platform, so incidents fall into two categories: (1) Clay-side issues (platform outage, provider degradation) and (2) your-side issues (webhook misconfiguration, credit exhaustion, handler failures).

Prerequisites

• Named incident commander, service/data owners, and escalation contacts
• Access to redacted telemetry, queue state, table configuration, and runbooks
• A tested ability to pause enrichment, CRM sync, and webhook intake
• Approved communications and evidence-retention procedures

Severity Levels

Instructions

Step 1: Quick Triage (2 Minutes)

#!/bin/bash
# clay-triage.sh — rapid diagnostic for Clay incidents
set -euo pipefail

echo "=== Clay Incident Triage ==="
echo "Time: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo ""

# 1. Check Clay platform status
echo "--- Clay Platform Status ---"
curl -s -o /dev/null -w "clay.com: HTTP %{http_code}\n" https://www.clay.com
echo ""

# 2. Test webhook delivery
echo "--- Webhook Test ---"
if [ -n "${CLAY_WEBHOOK_URL:-}" ]; then
  WEBHOOK_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
    -X POST "$CLAY_WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d '{"_triage": true, "_ts": "'$(date -u +%s)'"}')
  echo "Webhook: HTTP $WEBHOOK_CODE"
  if [ "$WEBHOOK_CODE" = "200" ]; then echo "  -> Webhook OK"; fi
  if [ "$WEBHOOK_CODE" = "404" ]; then echo "  -> ISSUE: Webhook URL invalid/expired"; fi
  if [ "$WEBHOOK_CODE" = "429" ]; then echo "  -> ISSUE: Rate limited"; fi
else
  echo "CLAY_WEBHOOK_URL not set!"
fi
echo ""

# 3. Test Enterprise API (if applicable)
echo "--- Enterprise API Test ---"
if [ -n "${CLAY_API_KEY:-}" ]; then
  API_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
    -X POST "https://api.clay.com/v1/people/enrich" \
    -H "Authorization: Bearer $CLAY_API_KE…

Clay Install & Auth

Overview

Clay is a web-based data enrichment platform — there is no SDK to install. Integration happens through webhook URLs (inbound data), HTTP API enrichment columns (outbound calls from Clay), and the Enterprise API (programmatic people/company lookups). This skill covers account setup, API key management, provider connections, and webhook configuration.

Prerequisites

• Clay account at clay.com (free tier available)
• For Enterprise API: Enterprise plan subscription
• For webhook integration: HTTPS endpoint or tunneling tool (ngrok)

Instructions

Step 1: Get Your Clay API Key (Enterprise Only)

Navigate to Settings > API in your Clay workspace. Copy your API key. Clay's Enterprise API is limited to people and company data lookups — it is not a general-purpose table API.

# Store your Clay API key securely
export CLAY_API_KEY="clay_ent_your_api_key_here"

# Verify with a test lookup (Enterprise API)
curl -s -X POST "https://api.clay.com/v1/people/enrich" \
  -H "Authorization: Bearer $CLAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}' | jq .

Step 2: Configure Webhook Inbound Source

Every Clay table can receive data via a unique webhook URL. This is the primary way to send data into Clay programmatically.

1. Open a Clay workbook (or create one)
2. Click + Add at the bottom of the table
3. Search for Webhooks and click Monitor webhook
4. Copy the generated webhook URL

# Store your table's webhook URL
export CLAY_WEBHOOK_URL="https://app.clay.com/api/v1/webhooks/your-unique-id"

# Send a test record to your Clay table
curl -X POST "$CLAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "Acme Corp",
    "title": "VP of Sales"
  }'

The record appears as a new row in your Clay table within seconds.

Step 3: Connect Data Provider API Keys

Clay supports 150+ enrichment providers. Connecting your own API keys saves 70-80% on Clay credits.

1. Go to Settings > Connections in Clay
2. Click Add Connection for each provider
3. Paste your API key

Common providers to connect:

Clay Known Pitfalls

Overview

Real gotchas when using Clay's data enrichment platform. These are the mistakes that cost credits, waste time, or break integrations -- learned from production experience. Each pitfall includes the exact symptom, root cause, and fix.

Prerequisites

• Active Clay account with tables configured
• Understanding of Clay's credit and enrichment model
• Experience with at least one Clay enrichment workflow

Instructions

Pitfall 1: Webhook 50K Limit Surprise

Symptom: Webhook silently stops accepting new data. No error, no notification. New rows simply don't appear.

Root cause: Each Clay webhook has a hard 50,000 submission lifetime limit. This limit persists even after deleting rows from the table.

Fix:

• Monitor webhook submission count in your application
• Create a new webhook on the same table when approaching 45K
• Use the WebhookRotator pattern from clay-load-scale
• Set up an alert at 40K submissions

Pitfall 2: Waterfall Burns Credits Without "Stop on First Result"

Symptom: Credits consumed at 3-5x the expected rate on waterfall enrichment columns.

Root cause: By default, waterfall enrichment may query ALL providers even after the first one finds data. You must explicitly enable "stop on first result."

Fix: In each waterfall column's settings, ensure the stop condition is configured. Without it, a 5-provider email waterfall costs 10-15 credits per row instead of 2-3.

Pitfall 3: Personal Email Domains Waste Credits

Symptom: Company enrichment returns empty for 30-50% of rows.

Root cause: Rows contain gmail.com, yahoo.com, hotmail.com domains. Clay's company enrichment can't match personal email domains to companies.

Fix:

const PERSONAL_DOMAINS = new Set([
  'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com',
  'icloud.com', 'aol.com', 'protonmail.com', 'mail.com',
]);

function filterBeforeEnrichment(rows: any[]) {
  return rows.filter(r => {
    const domain = r.domain?.toLowerCase();
    if (PERSONAL_DOMAINS.has(domain)) {
      console.log(`Filtered: ${domain} (personal email domain)`);
      return false;
    }
    return true;
  });
}
// Apply BEFORE sending to Clay. Typical savings: 20-40% of credits.

Pitfall 4: Auto-Update Re-Enriches Entire Table

Symptom: Thousands of credits consumed overnight. Enrichment columns re-ran on rows that were already enriched.

Root cause: Table-level auto-update was ON, and a…

Clay Load & Scale

Overview

Strategies for processing 10K-100K+ leads through Clay monthly. Clay is a hosted platform -- you can't add servers. Scaling focuses on: table partitioning, webhook management, batch submission pacing, credit budgeting at scale, and multi-table architectures.

Prerequisites

• Clay Growth or Enterprise plan
• Understanding of Clay's credit model (Data Credits + Actions)
• Queue infrastructure for batch processing (Redis, SQS, or BullMQ)
• Monitoring for credit consumption

Instructions

Step 1: Capacity Planning

// src/clay/capacity-planner.ts
interface CapacityPlan {
  monthlyLeads: number;
  creditsPerLead: number;
  totalCreditsNeeded: number;
  planRequired: string;
  estimatedMonthlyCost: number;
  webhooksNeeded: number;        // Each webhook has 50K lifetime limit
  tablesRecommended: number;
}

function planCapacity(monthlyLeads: number, creditsPerLead = 6): CapacityPlan {
  const totalCredits = monthlyLeads * creditsPerLead;

  // Determine plan
  let plan: string, cost: number;
  if (totalCredits <= 2500) {
    plan = 'Launch ($185/mo)';
    cost = 185;
  } else if (totalCredits <= 6000) {
    plan = 'Growth ($495/mo)';
    cost = 495;
  } else {
    plan = `Enterprise (custom pricing for ${totalCredits} credits/mo)`;
    cost = 495 + Math.ceil((totalCredits - 6000) / 1000) * 50; // Rough estimate
  }

  // With own API keys: 0 data credits, only actions consumed
  console.log(`TIP: With own API keys, you need 0 Data Credits.`);
  console.log(`     Only ${monthlyLeads} Actions needed (Growth plan includes 40K).`);

  return {
    monthlyLeads,
    creditsPerLead,
    totalCreditsNeeded: totalCredits,
    planRequired: plan,
    estimatedMonthlyCost: cost,
    webhooksNeeded: Math.ceil(monthlyLeads / 50_000 * 12), // Annual webhooks needed
    tablesRecommended: Math.ceil(monthlyLeads / 10_000), // ~10K rows per table for manageability
  };
}

// Example
const plan = planCapacity(50_000);
console.log(plan);
// Monthly leads: 50,000
// Credits needed: 300,000 (or 0 with own API keys)
// Webhooks needed: 12/year
// Tables recommended: 5

Step 2: Implement Batch Queue Architecture

// src/clay/batch-processor.ts
import { Queue, Worker } from 'bullmq';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

// Create a queue for Clay webhook submissions
const clayQueue = new Queue('clay-enrichment', { connection: redis });

interface EnrichmentJob {
  leads: Record<string, unknown>[];
  webhookUrl: string;
  batchId: string;
  priority: 'high' | 'normal' | 'low';
}

// Submit a batch for processing
async function queueBatch(
  leads: Record<string, unknown>[],
  webhookUrl: string,
  priority: 'high' | …

Clay Local Dev Loop

Overview

Clay is a web-based platform with no local runtime. Your local dev loop consists of: (1) scripts that push data into Clay via webhooks, (2) Clay enrichment running in the cloud, and (3) HTTP API columns pushing enriched data back to your local endpoint via ngrok. This skill sets up that feedback loop.

Prerequisites

• Completed clay-install-auth setup
• Node.js 18+ or Python 3.10+
• ngrok installed (npm install -g ngrok or ngrok.com)
• Clay table with webhook source configured

Instructions

Step 1: Expose Your Local Server via ngrok

Clay's HTTP API enrichment columns need a public URL to call your local endpoints.

# Start ngrok tunnel to your local server
ngrok http 3000
# Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok-free.app)

Step 2: Create a Local Webhook Receiver

// src/clay-receiver.ts — receives enriched data from Clay HTTP API columns
import express from 'express';

const app = express();
app.use(express.json());

// Clay HTTP API column calls this endpoint
app.post('/api/clay/enriched', (req, res) => {
  const enrichedData = req.body;
  console.log('Enriched record received from Clay:', {
    email: enrichedData.email,
    company: enrichedData.company_name,
    title: enrichedData.job_title,
    enrichment_source: enrichedData._clay_source,
  });

  // Process the enriched data (save to DB, trigger outreach, etc.)
  res.json({ status: 'received', timestamp: new Date().toISOString() });
});

// Health check for Clay HTTP API column testing
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', service: 'clay-dev-receiver' });
});

app.listen(3000, () => {
  console.log('Clay dev receiver listening on http://localhost:3000');
  console.log('Configure Clay HTTP API column to POST to: <ngrok-url>/api/clay/enriched');
});

Step 3: Build a Test Data Sender

// src/send-test-leads.ts — push test data into Clay via webhook
const CLAY_WEBHOOK_URL = process.env.CLAY_WEBHOOK_URL!;

const testLeads = [
  { email: 'cto@stripe.com', domain: 'stripe.com', source: 'dev-test' },
  { email: 'vp@notion.so', domain: 'notion.so', source: 'dev-test' },
  { email: 'head@figma.com', domain: 'figma.com', source: 'dev-test' },
];

async function sendTestBatch() {
  for (const lead of testLeads) {
    const res = await fetch(CLAY_WEBHOOK_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(lead),
    });
    console.log(`Sent ${lead.email}: ${res.status}`);
    await …

Clay Migration Deep Dive

Overview

Comprehensive guide for migrating from standalone enrichment tools (ZoomInfo, Apollo, Clearbit, Lusha) to Clay, or consolidating multiple tools into a single Clay-based pipeline. Clay replaces the need for individual provider subscriptions by aggregating 150+ providers into waterfall enrichment workflows.

Prerequisites

• Current enrichment tool subscription(s) with data export capability
• Clay account on Growth or Enterprise plan
• Understanding of current enrichment volume and costs
• CRM with existing enriched data

Migration Types

Instructions

Step 1: Audit Current Enrichment Stack (Week 1)

// migration/audit.ts — document your current enrichment setup
interface EnrichmentAudit {
  provider: string;
  monthlyVolume: number;
  monthlyCoost: number;
  dataFields: string[];
  hitRate: number;           // % of lookups that return data
  integrationMethod: string; // API, CSV, Zapier, native CRM
  canExportHistory: boolean;
}

const currentStack: EnrichmentAudit[] = [
  {
    provider: 'ZoomInfo',
    monthlyVolume: 5000,
    monthlyCoost: 15000,  // ZoomInfo is expensive
    dataFields: ['email', 'phone', 'title', 'company', 'revenue'],
    hitRate: 75,
    integrationMethod: 'API + Salesforce native',
    canExportHistory: true,
  },
  {
    provider: 'Apollo.io',
    monthlyVolume: 3000,
    monthlyCoost: 400,
    dataFields: ['email', 'title', 'company', 'linkedin'],
    hitRate: 65,
    integrationMethod: 'API',
    canExportHistory: true,
  },
  {
    provider: 'Custom Python scripts',
    monthlyVolume: 1000,
    monthlyCoost: 0,  // Just developer time
    dataFields: ['email', 'company_data'],
    hitRate: 40,
    integrationMethod: 'Cron job + DB',
    canExportHistory: true,
  },
];

function generateMigrationReport(stack: EnrichmentAudit[]): void {
  const totalCost = stack.reduce((s, p) => s + p.monthlyCoost, 0);
  const totalVolume = stack.reduce((s, p) => s + p.monthlyVolume, 0);
  console.log(`Current stack: ${stack.length} providers`);
  console.log(`Total monthly cost: $${totalCost}`);
  console.log(`Total monthly volume: ${totalVolume} lookups`);
  console.log(`Average hit rate: ${(stack.reduce((s, p) => s…

Clay Multi-Environment Setup

Overview

Configure Clay integrations across dev/staging/prod with isolated tables, separate webhook URLs, and environment-specific enrichment settings. Clay is a single workspace per account, so multi-environment isolation requires separate tables, careful naming, and environment-aware application code.

Prerequisites

• Clay account (one workspace can hold multiple tables)
• Environment variable management per deployment target
• Understanding of Clay table and webhook concepts

Instructions

Step 1: Create Per-Environment Tables

In Clay, create separate tables for each environment:

Each table gets its own webhook URL. Copy each URL to the appropriate environment's secrets.

Step 2: Environment Configuration

// src/config/clay.ts — environment-aware Clay configuration
interface ClayEnvConfig {
  webhookUrl: string;
  apiKey?: string;                // Enterprise API (if applicable)
  maxRowsPerBatch: number;
  delayBetweenRowsMs: number;
  enableCRMSync: boolean;
  tablePrefix: string;
}

function getClayConfig(): ClayEnvConfig {
  const env = process.env.NODE_ENV || 'development';

  const configs: Record<string, ClayEnvConfig> = {
    development: {
      webhookUrl: process.env.CLAY_WEBHOOK_URL_DEV!,
      maxRowsPerBatch: 10,          // Small batches to conserve credits
      delayBetweenRowsMs: 500,      // Slow, safe
      enableCRMSync: false,         // Never push dev data to real CRM
      tablePrefix: '[DEV]',
    },
    staging: {
      webhookUrl: process.env.CLAY_WEBHOOK_URL_STG!,
      maxRowsPerBatch: 100,
      delayBetweenRowsMs: 250,
      enableCRMSync: false,         // Use sandbox CRM if needed
      tablePrefix: '[STG]',
    },
    production: {
      webhookUrl: process.env.CLAY_WEBHOOK_URL!,
      apiKey: process.env.CLAY_API_KEY,
      maxRowsPerBatch: 1000,
      delayBetweenRowsMs: 100,
      enableCRMSync: true,
      tablePrefix: '',
    },
  };

  const config = configs[env];
  if (!config) throw new Error(`Unknown environment: ${env}`);
  if (!config.webhookUrl) throw new Error(`CLAY_WEBHOOK_URL not set for ${env}`);

  return config;
}

Step 3: Environment Variable Management

# .env.development
CLAY_WEBHO…

Clay Observability

Overview

Monitor Clay data enrichment pipeline health across four dimensions: credit consumption velocity, enrichment success rates (hit rates), data quality scores, and CRM sync reliability. Clay's credit-based pricing model makes observability essential for cost control.

Prerequisites

• Clay account with table access
• Metrics infrastructure (Prometheus/Grafana, Datadog, or custom)
• Webhook receiver that logs enrichment results
• Understanding of your enrichment column configuration

Instructions

Step 1: Instrument Your Clay Webhook Handler

// src/clay/metrics.ts — collect metrics from enriched data flowing back from Clay
interface ClayMetrics {
  enrichmentsReceived: number;
  enrichmentsWithEmail: number;
  enrichmentsWithCompany: number;
  enrichmentsWithPhone: number;
  estimatedCreditsUsed: number;
  averageICPScore: number;
  leadsTier: { A: number; B: number; C: number; D: number };
}

class ClayMetricsCollector {
  private metrics: ClayMetrics = {
    enrichmentsReceived: 0,
    enrichmentsWithEmail: 0,
    enrichmentsWithCompany: 0,
    enrichmentsWithPhone: 0,
    estimatedCreditsUsed: 0,
    averageICPScore: 0,
    leadsTier: { A: 0, B: 0, C: 0, D: 0 },
  };
  private scoreSum = 0;

  record(lead: Record<string, any>, creditsPerRow: number = 6) {
    this.metrics.enrichmentsReceived++;
    if (lead.work_email) this.metrics.enrichmentsWithEmail++;
    if (lead.company_name) this.metrics.enrichmentsWithCompany++;
    if (lead.phone_number) this.metrics.enrichmentsWithPhone++;
    this.metrics.estimatedCreditsUsed += creditsPerRow;

    const score = lead.icp_score || 0;
    this.scoreSum += score;
    this.metrics.averageICPScore = this.scoreSum / this.metrics.enrichmentsReceived;

    if (score >= 80) this.metrics.leadsTier.A++;
    else if (score >= 60) this.metrics.leadsTier.B++;
    else if (score >= 40) this.metrics.leadsTier.C++;
    else this.metrics.leadsTier.D++;
  }

  getReport(): string {
    const m = this.metrics;
    const emailRate = m.enrichmentsReceived > 0
      ? ((m.enrichmentsWithEmail / m.enrichmentsReceived) * 100).toFixed(1)
      : '0';
    const companyRate = m.enrichmentsReceived > 0
      ? ((m.enrichmentsWithCompany / m.enrichmentsReceived) * 100).toFixed(1)
      : '0';

    return [
      `=== Clay Enrichment Report ===`,
      `Total processed: ${m.enrichmentsReceived}`,
      `Email find rate: ${emailRate}%`,
      `Company match rate: ${companyRate}%`,
      `Avg ICP score: ${m.averageICPScore.toFixed(1)}`,
      `Lead distribution: A=${m.leadsTier.A} B=${m.leadsTier.B} C=${m.leadsTier.C} D=${m.leadsTier.D}`,
      `Estimated credits used: ${m.estimatedCreditsUsed}`,
      `Cost per email found: ${(m.estimatedCreditsUsed / Math.max(m.enrichmentsWithEmail, 1)).toFixed(1)} credits`,
    ].join('\n')…

Clay Performance Tuning

Overview

Optimize Clay table processing speed, enrichment hit rates, and credit efficiency. Clay processes enrichment columns sequentially per row, and each enrichment column makes external API calls. Performance tuning focuses on reducing wasted enrichments, ordering columns optimally, and managing table auto-run behavior.

Prerequisites

• Clay table with enrichment columns configured
• Understanding of which providers are in your waterfall
• Access to Clay table settings and column configuration

Instructions

Step 1: Order Enrichment Columns by Speed

Clay runs enrichment columns left-to-right. Place fast columns first:

Why order matters: Fast columns populate data that slow columns may need as input (e.g., company name feeds into Claygent research prompt).

Step 2: Add Conditional Run Rules

Prevent enrichments from running on rows that won't yield results:

# In Clay column settings > "Only run if" condition:

# Email waterfall: only run if we have enough input data
ISNOTEMPTY(domain) AND ISNOTEMPTY(first_name) AND ISNOTEMPTY(last_name)

# Claygent: only run for high-value prospects
ICP Score >= 60 AND ISNOTEMPTY(Company Name)

# CRM push: only run for enriched, qualified leads
ICP Score >= 70 AND ISNOTEMPTY(Work Email)

This prevents:

• Waterfall enrichment on rows with missing domains (wasted credits)
• Claygent research on low-value prospects (expensive AI credits)
• CRM pushes for incomplete records

Step 3: Optimize Input Data Before Import

// src/clay/pre-process.ts — clean data before sending to Clay
interface RawLead {
  domain?: string;
  email?: string;
  first_name?: string;
  last_name?: string;
}

function preProcessForClay(rows: RawLead[]): {
  ready: RawLead[];
  filtered: { row: RawLead; reason: string }[];
  stats: { total: number; ready: number; filtered: number; deduped: number };
} {
  const personalDomains = new Set([
    'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com',
    'icloud.com', 'aol.com', 'protonmail.com', 'mail.com',
  ]);

  const seen = new Set<string>();
  co…

Clay Policy Guardrails

Overview

Policy enforcement and guardrails for Clay data enrichment pipelines. Clay processes personal and business data at scale, requiring strict controls around credit spending, data privacy compliance, input validation, and export restrictions.

Prerequisites

• Clay integration in production or pre-production
• Understanding of GDPR/CCPA requirements
• Credit budget defined by management
• Data classification policy for your organization

Instructions

Step 1: Credit Spending Guardrails

// src/clay/policies/credit-policy.ts
interface CreditPolicy {
  dailyLimit: number;
  perTableLimit: number;
  perBatchLimit: number;
  alertThresholdPct: number;
  hardStopEnabled: boolean;
}

const CREDIT_POLICIES: Record<string, CreditPolicy> = {
  conservative: {
    dailyLimit: 200,
    perTableLimit: 500,
    perBatchLimit: 100,
    alertThresholdPct: 70,
    hardStopEnabled: true,
  },
  standard: {
    dailyLimit: 500,
    perTableLimit: 2000,
    perBatchLimit: 500,
    alertThresholdPct: 80,
    hardStopEnabled: true,
  },
  aggressive: {
    dailyLimit: 2000,
    perTableLimit: 10000,
    perBatchLimit: 2000,
    alertThresholdPct: 90,
    hardStopEnabled: false, // Alert only, don't stop
  },
};

class CreditPolicyEnforcer {
  private dailyUsed = 0;
  private tableUsage = new Map<string, number>();

  constructor(private policy: CreditPolicy) {}

  checkBatch(tableId: string, rowCount: number, creditsPerRow: number): {
    allowed: boolean;
    reason?: string;
  } {
    const estimated = rowCount * creditsPerRow;

    // Batch limit
    if (estimated > this.policy.perBatchLimit) {
      return {
        allowed: false,
        reason: `Batch (${estimated} credits) exceeds per-batch limit (${this.policy.perBatchLimit}). Split into smaller batches.`,
      };
    }

    // Daily limit
    if (this.dailyUsed + estimated > this.policy.dailyLimit) {
      if (this.policy.hardStopEnabled) {
        return {
          allowed: false,
          reason: `Would exceed daily limit: ${this.dailyUsed} + ${estimated} > ${this.policy.dailyLimit}`,
        };
      }
      console.warn(`WARNING: Exceeding daily limit (${this.dailyUsed + estimated}/${this.policy.dailyLimit})`);
    }

    // Per-table limit
    const tableTotal = (this.tableUsage.get(tableId) || 0) + estimated;
    if (tableTotal > this.policy.perTableLimit) {
      return {
        allowed: false,
        reason: `Table ${tableId} would exceed limit: ${tableTotal} > ${this.policy.perTableLimit}`,
      };
    }

    // Alert threshold
    const dailyPct = ((this.dailyUsed + estimated) / this.policy.dailyLimit) * 100;
    if (dailyPct > this.policy.alertThresholdPct) {
      console.warn(`Credit alert: ${dailyPct.toFixed(0)}% of daily limit used`);
    }

    return { allowed: true };
  }

  recordUsage(ta…

Clay Production Checklist

Overview

Complete checklist for launching Clay enrichment pipelines in production. Covers table configuration, credit budgeting, webhook reliability, CRM sync validation, and monitoring setup.

Prerequisites

• Clay table tested with sample data (100+ rows enriched successfully)
• CRM integration tested in staging
• Credit budget approved for monthly volume
• Team trained on Clay table management

Instructions

Phase 1: Table Configuration

• [ ] Table schema finalized -- all columns named, typed, and ordered
• [ ] Enrichment columns configured -- each column has correct provider and input mapping
• [ ] Waterfall configured -- providers ordered cheapest-first with "stop on first result"
• [ ] Auto-run settings verified -- table-level auto-update ON, column-level auto-run ON for needed columns
• [ ] Conditional run rules set -- enrichments only trigger when input data exists
• [ ] Formula columns tested -- ICP scoring and lead grading formulas validated
• [ ] AI/Claygent columns reviewed -- prompts produce consistent, quality output

Phase 2: Data Quality Gates

• [ ] Input validation in place -- scripts validate data before webhook submission
• [ ] Personal email filter -- gmail.com, yahoo.com, etc. blocked from enrichment
• [ ] Deduplication active -- duplicate records detected before sending to Clay
• [ ] Sample enrichment run completed -- 500+ row test with >60% email find rate
• [ ] Credit cost per row calculated -- know your average credits per enriched lead

// Pre-submission validation (run before pushing to Clay)
function validateForProduction(rows: any[]): { valid: any[]; rejected: any[] } {
  const personalDomains = ['gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com'];
  const seen = new Set<string>();
  const valid: any[] = [];
  const rejected: any[] = [];

  for (const row of rows) {
    const key = `${row.domain}:${row.first_name}:${row.last_name}`.toLowerCase();

    if (!row.domain?.includes('.'))
      rejected.push({ row, reason: 'invalid domain' });
    else if (personalDomains.some(d => row.domain.endsWith(d)))
      rejected.push({ row, reason: 'personal email domain' });
    else if (seen.has(key))
      rejected.push({ row, reason: 'duplicate' });
    else {
      seen.add(key);
      valid.push(row);
    }
  }

  console.log(`Validation: ${valid.length} valid, ${rejected.length} rejected (${(rejected.length / rows.length * 100).toFixed(1)}% filt…

Clay Rate Limits

Overview

Clay enforces rate limits at the plan level, webhook level, and enrichment provider level. Understanding these limits prevents data loss, credit waste, and integration failures.

Prerequisites

• Clay account with known plan tier
• Webhook URL(s) for your tables
• Understanding of your data volume requirements

Instructions

Step 1: Understand Clay Rate Limit Tiers

Key insight: The 50K webhook submission limit is per-webhook, not per-table. Once exhausted, create a new webhook on the same table.

Step 2: Implement Webhook Rate Limiting

// src/clay/rate-limiter.ts — respect Clay's plan-level rate limits
import PQueue from 'p-queue';

interface RateLimiterConfig {
  maxPerHour: number;     // Plan limit (e.g., 400 for Explorer)
  maxPerSecond: number;   // Practical burst limit
  webhookLimit: number;   // 50K per webhook lifetime
}

const PLAN_LIMITS: Record<string, RateLimiterConfig> = {
  explorer: { maxPerHour: 400, maxPerSecond: 2, webhookLimit: 50_000 },
  pro:      { maxPerHour: Infinity, maxPerSecond: 10, webhookLimit: 50_000 },
  enterprise: { maxPerHour: Infinity, maxPerSecond: 20, webhookLimit: 50_000 },
};

class ClayRateLimiter {
  private queue: PQueue;
  private submissionCount = 0;
  private hourlyCount = 0;
  private hourlyResetAt: Date;
  private config: RateLimiterConfig;

  constructor(plan: keyof typeof PLAN_LIMITS) {
    this.config = PLAN_LIMITS[plan];
    this.queue = new PQueue({
      concurrency: 1,
      interval: 1000,
      intervalCap: this.config.maxPerSecond,
    });
    this.hourlyResetAt = new Date(Date.now() + 3600_000);
  }

  async submit(webhookUrl: string, data: Record<string, unknown>): Promise<Response> {
    // Check webhook lifetime limit
    if (this.submissionCount >= this.config.webhookLimit) {
      throw new Error(
        `Webhook submission limit (${this.config.webhookLimit}) reached. Create a new webhook.`
      );
    }

    // Check hourly limit
    if (Date.now() > this.hourlyResetAt.getTime()) {
      this.h…

Clay Reference Architecture

Overview

Production architecture for Clay-based lead enrichment and go-to-market data operations. Covers the three integration patterns (webhook-only, webhook + HTTP API, and full Enterprise API), table schema design, and CRM synchronization flows.

Prerequisites

• Clay account with appropriate plan tier
• Clear understanding of data volume and enrichment needs
• CRM integration target (HubSpot, Salesforce, etc.)
• Defined Ideal Customer Profile (ICP)

Instructions

Step 1: Choose Your Integration Pattern

Pattern A: Webhook-Only (All Plans)
──────────────────────────────────────
Your App ──POST──> Clay Webhook ──> Clay Table ──> Enrichment
                                                      │
                                         Manual export via CSV
                                         or native CRM action

Pattern B: Webhook + HTTP API Callback (Growth+ Plans)
──────────────────────────────────────────────────────
Your App ──POST──> Clay Webhook ──> Clay Table ──> Enrichment
                                                      │
                                                HTTP API Column
                                                      │
                                               POST to your app
                                                      │
                                                  CRM / DB

Pattern C: Full Automation with Enterprise API (Enterprise)
──────────────────────────────────────────────────────────
Your App ──POST──> Clay Webhook ──> Clay Table ──> Enrichment
    │                                                  │
    │                                           HTTP API Column
    │                                                  │
    └──Enterprise API──> Person/Company lookup    POST to your app
                         (lightweight, fast)           │
                                                   CRM / DB

Step 2: Design Table Schema

Standard Lead Enrichment Table:

┌─────────────────────────────────────────────────────────────┐
│ CLAY TABLE: Outbound Leads                                  │
├─────────────┬───────────────┬──────────────────────────────┤
│ Input Cols  │ Enrichment    │ AI + Formula + Output        │
├─────────────┼───────────────┼──────────────────────────────┤
│ domain      │ Company Name  │ ICP Score (formula)          │
│ first_name  │ Employee Count│ Lead Tier (formula: A/B/C)   │
│ last_name   │ Industry      │ Personalized Opener (AI)     │
│ source      │ Tech Stack    │ Recent News (Claygent)       │
│ linkedin_url│ Work Email    │ CRM Push (HTTP API)          │
│             │ Job Title     │ Outreach Push (HTTP API)     │
│             │ Phone Number  │                              │
│             │ LinkedIn URL  │                   …

Clay Reliability Patterns

Overview

Production reliability patterns for Clay data enrichment pipelines. Clay's async enrichment model, credit-based billing, and dependency on 150+ external data providers require specific resilience strategies: credit budget circuit breakers, webhook delivery tracking, dead letter queues for failed batches, and graceful degradation when Clay is unavailable.

Prerequisites

• Clay integration in production or pre-production
• Redis or similar for state tracking
• Understanding of Clay's async enrichment model
• Monitoring infrastructure (see clay-observability)

Instructions

Step 1: Credit Budget Circuit Breaker

Stop processing when credit burn exceeds budget to prevent runaway costs:

// src/clay/circuit-breaker.ts
class CreditCircuitBreaker {
  private state: 'closed' | 'open' | 'half-open' = 'closed';
  private dailyCreditsUsed = 0;
  private failureCount = 0;
  private lastFailureAt: Date | null = null;
  private readonly cooldownMs: number;

  constructor(
    private dailyLimit: number,
    private failureThreshold: number = 5,
    cooldownMinutes: number = 15,
  ) {
    this.cooldownMs = cooldownMinutes * 60 * 1000;
  }

  canProcess(estimatedCredits: number): { allowed: boolean; reason?: string } {
    // Check circuit state
    if (this.state === 'open') {
      // Check if cooldown has elapsed
      if (this.lastFailureAt && Date.now() - this.lastFailureAt.getTime() > this.cooldownMs) {
        this.state = 'half-open';
        console.log('Circuit breaker: half-open (testing)');
      } else {
        return { allowed: false, reason: `Circuit OPEN. Cooldown until ${new Date(this.lastFailureAt!.getTime() + this.cooldownMs).toISOString()}` };
      }
    }

    // Check budget
    if (this.dailyCreditsUsed + estimatedCredits > this.dailyLimit) {
      return { allowed: false, reason: `Daily credit limit reached: ${this.dailyCreditsUsed}/${this.dailyLimit}` };
    }

    return { allowed: true };
  }

  recordSuccess(creditsUsed: number) {
    this.dailyCreditsUsed += creditsUsed;
    if (this.state === 'half-open') {
      this.state = 'closed';
      this.failureCount = 0;
      console.log('Circuit breaker: closed (recovered)');
    }
  }

  recordFailure() {
    this.failureCount++;
    this.lastFailureAt = new Date();
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'open';
      console.error(`Circuit breaker: OPEN after ${this.failureCount} failures`);
    }
  }

  resetDaily() {
    this.dailyCreditsUsed = 0;
  }
}

Step 2: Dead Letter Queue for Failed Submissions

// src/clay/dead-letter-queue.ts
interface DLQEntry {
  row: Record<string, unknown>;
  …

Clay Integration Patterns

Overview

Production-ready patterns for Clay integrations. Clay does not have an official SDK -- you interact via webhooks (inbound), HTTP API enrichment columns (outbound from Clay), and the Enterprise API (programmatic lookups). These patterns wrap those interfaces into reliable, reusable code.

Prerequisites

• Completed clay-install-auth setup
• Familiarity with async/await patterns
• Understanding of Clay's webhook and HTTP API model

Instructions

Step 1: Create a Clay Webhook Client (TypeScript)

// src/clay/client.ts — typed wrapper for Clay webhook and Enterprise API
interface ClayConfig {
  webhookUrl: string;         // Table's webhook URL for inbound data
  enterpriseApiKey?: string;  // Enterprise API key (optional)
  baseUrl?: string;           // Default: https://api.clay.com
  maxRetries?: number;
  timeoutMs?: number;
}

class ClayClient {
  private config: Required<ClayConfig>;

  constructor(config: ClayConfig) {
    this.config = {
      baseUrl: 'https://api.clay.com',
      maxRetries: 3,
      timeoutMs: 30_000,
      enterpriseApiKey: '',
      ...config,
    };
  }

  /** Send a record to a Clay table via webhook */
  async sendToTable(data: Record<string, unknown>): Promise<void> {
    const res = await this.fetchWithRetry(this.config.webhookUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
    if (!res.ok) {
      throw new ClayWebhookError(`Webhook failed: ${res.status}`, res.status);
    }
  }

  /** Send multiple records in sequence with rate limiting */
  async sendBatch(rows: Record<string, unknown>[], delayMs = 200): Promise<BatchResult> {
    const results: BatchResult = { sent: 0, failed: 0, errors: [] };
    for (const row of rows) {
      try {
        await this.sendToTable(row);
        results.sent++;
      } catch (err) {
        results.failed++;
        results.errors.push({ row, error: (err as Error).message });
      }
      if (delayMs > 0) await new Promise(r => setTimeout(r, delayMs));
    }
    return results;
  }

  /** Enterprise API: Enrich a person by email (Enterprise plan only) */
  async enrichPerson(email: string): Promise<PersonEnrichment> {
    if (!this.config.enterpriseApiKey) {
      throw new Error('Enterprise API key required for person enrichment');
    }
    const res = await this.fetchWithRetry(`${this.config.baseUrl}/v1/people/enrich`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.config.enterpriseApiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email }),
    });
    return res.json();
  }

  /** Enterprise API: Enrich a company by domain…

Clay Security Basics

Overview

Security best practices for Clay integrations covering API key management, webhook endpoint security, provider credential isolation, and lead data protection. Clay handles sensitive PII (emails, phone numbers, LinkedIn profiles) at scale, making security critical.

Prerequisites

• Clay account with admin access
• Understanding of environment variables and secrets management
• Access to deployment platform's secrets manager

Instructions

Step 1: Secure API Key Storage

# .env (NEVER commit to git)
CLAY_API_KEY=clay_ent_your_api_key_here
CLAY_WEBHOOK_URL=https://app.clay.com/api/v1/webhooks/your-id

# .gitignore — add these patterns
.env
.env.local
.env.*.local
*.key

For production, use your platform's secrets manager:

# GitHub Actions
gh secret set CLAY_API_KEY --body "clay_ent_your_key"

# Google Cloud Secret Manager
echo -n "clay_ent_your_key" | gcloud secrets create clay-api-key --data-file=-

# AWS Secrets Manager
aws secretsmanager create-secret \
  --name clay/api-key \
  --secret-string "clay_ent_your_key"

Step 2: Authenticate Incoming Webhook Callbacks

When Clay's HTTP API columns call your endpoint, validate the request origin:

// src/middleware/clay-auth.ts
import crypto from 'crypto';

const CLAY_WEBHOOK_SECRET = process.env.CLAY_WEBHOOK_SECRET!;

function verifyClayCallback(
  payload: string,
  signature: string | undefined
): boolean {
  if (!signature || !CLAY_WEBHOOK_SECRET) return false;

  const expected = crypto
    .createHmac('sha256', CLAY_WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

// Express middleware
function clayAuthMiddleware(req: any, res: any, next: any) {
  const signature = req.headers['x-clay-signature'] as string;
  const rawBody = JSON.stringify(req.body);

  if (!verifyClayCallback(rawBody, signature)) {
    console.warn('Rejected unauthorized Clay callback from', req.ip);
    return res.status(401).json({ error: 'Invalid signature' });
  }
  next();
}

Step 3: Isolate Provider API Keys

Connect provider keys directly in Clay (Settings > Connections) rather than passing them through your application. This keeps provider credentials out of your codebase:

Clay Upgrade & Migration

Overview

Guide for navigating Clay plan upgrades and the March 2026 pricing overhaul. Clay restructured from Starter/Explorer/Pro to Launch/Growth tiers, split credits into Data Credits + Actions, and cut data costs 50-90%. This skill covers migration decisions, integration impact, and adaptation strategies.

Prerequisites

• Active Clay account
• Understanding of current credit consumption
• Access to Clay billing dashboard

Instructions

Step 1: Understand the 2026 Pricing Change

Old Plans (Legacy -- available until April 10, 2026):

New Plans (March 2026+):

Key changes:

• Credits split into Data Credits (buying enrichment data) and Actions (using the platform)
• Data costs cut 50-90% (each enrichment is cheaper)
• No enrichment charges on failed lookups (no data = no charge)
• Credit rollover capped at 2x monthly limit

Step 2: Audit Your Current Usage

# Check current plan and credit usage from Clay dashboard
# Navigate to Settings > Plans & Billing
# Record:
# - Current plan tier
# - Monthly credits used (average over 3 months)
# - Which enrichment providers consume most credits
# - Whether you use HTTP API columns
# - Whether you use webhook sources

Decision matrix for migration:

Step 3: Adapt Integration Code for New Credit Model

// src/clay…

Clay Webhooks & Events

Overview

Clay's event-driven architecture has two webhook patterns: (1) Inbound webhooks -- you POST data into Clay tables via unique webhook URLs, and (2) Outbound HTTP API columns -- Clay POSTs enriched data to your endpoint after enrichment completes. This skill covers both patterns with production-ready handlers.

Prerequisites

• Clay table with webhook source configured (for inbound)
• Clay table with HTTP API enrichment column (for outbound)
• HTTPS endpoint accessible from the internet
• Familiarity with Express.js or similar framework

Instructions

Step 1: Inbound Webhook -- Send Data into Clay

Every Clay table has a unique webhook URL. When you POST JSON to this URL, a new row appears in the table.

// src/clay/inbound.ts — send data into Clay tables
class ClayInboundWebhook {
  constructor(
    private webhookUrl: string,
    private submissionCount: number = 0,
    private readonly LIMIT: number = 50_000,
  ) {}

  async sendRow(data: Record<string, unknown>): Promise<void> {
    if (this.submissionCount >= this.LIMIT) {
      throw new Error(`Webhook exhausted (${this.LIMIT} submissions). Create a new webhook in Clay.`);
    }

    const res = await fetch(this.webhookUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });

    if (!res.ok) {
      throw new Error(`Clay webhook failed: ${res.status} ${res.statusText}`);
    }

    this.submissionCount++;
  }

  async sendBatch(rows: Record<string, unknown>[], delayMs = 200): Promise<{ sent: number; failed: number }> {
    let sent = 0, failed = 0;
    for (const row of rows) {
      try {
        await this.sendRow(row);
        sent++;
      } catch {
        failed++;
      }
      await new Promise(r => setTimeout(r, delayMs));
    }
    return { sent, failed };
  }
}

// Usage
const webhook = new ClayInboundWebhook(process.env.CLAY_WEBHOOK_URL!);
await webhook.sendRow({
  email: 'cto@acme.com',
  domain: 'acme.com',
  first_name: 'Jane',
  last_name: 'Doe',
  source: 'website-form',
});

Step 2: Outbound Callback -- Receive Enriched Data from Clay

Clay's HTTP API enrichment column POSTs data to your endpoint after enrichment runs. Set up a handler:

// src/clay/outbound-handler.ts — receive enriched data from Clay
import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json({ limit: '1mb' }));

// Signature verification middleware
function verifyClaySignature(req: any, res: any, next: any) {
  const signature = req.headers['x-clay-signature'];
  const secret = process.env.CLA…