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 (Enterprise plan only) */
  async enrichCompany(domain: string): Promise<CompanyEnrichment> {
    if (!this.config.enterpriseApiKey) {
      throw new Error('Enterprise API key required for company enrichment');
    }
    const res = await this.fetchWithRetry(`${this.config.baseUrl}/v1/companies/enrich`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.config.enterpriseApiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ domain }),
    });
    return res.json();
  }

  private async fetchWithRetry(url: string, init: RequestInit): Promise<Response> {
    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
      try {
        const controller = new AbortController();
        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
        const res = await fetch(url, { ...init, signal: controller.signal });
        clearTimeout(timeout);

        if (res.status === 429) {
          const retryAfter = parseInt(res.headers.get('Retry-After') || '5');
          await new Promise(r => setTimeout(r, retryAfter * 1000));
          continue;
        }
        return res;
      } catch (err) {
        if (attempt === this.config.maxRetries) throw err;
        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
      }
    }
    throw new Error('Max retries exceeded');
  }
}

Step 2: Type Definitions for Clay Data

// src/clay/types.ts
interface PersonEnrichment {
  name?: string;
  email?: string;
  title?: string;
  company?: string;
  linkedin_url?: string;
  location?: string;
}

interface CompanyEnrichment {
  name?: string;
  domain?: string;
  industry?: string;
  employee_count?: number;
  linkedin_url?: string;
  location?: string;
  description?: string;
}

interface BatchResult {
  sent: number;
  failed: number;
  errors: Array<{ row: Record<string, unknown>; error: string }>;
}

class ClayWebhookError extends Error {
  constructor(message: string, public statusCode: number) {
    super(message);
    this.name = 'ClayWebhookError';
  }
}

Step 3: Python Client

# clay_client.py — Python wrapper for Clay webhook and Enterprise API
import httpx
import asyncio
from dataclasses import dataclass, field
from typing import Any

@dataclass
class ClayClient:
    webhook_url: str
    enterprise_api_key: str = ""
    base_url: str = "https://api.clay.com"
    max_retries: int = 3
    timeout: float = 30.0

    async def send_to_table(self, data: dict[str, Any]) -> None:
        """Send a single record to a Clay table via webhook."""
        async with httpx.AsyncClient(timeout=self.timeout) as client:
            for attempt in range(self.max_retries + 1):
                response = await client.post(
                    self.webhook_url,
                    json=data,
                    headers={"Content-Type": "application/json"},
                )
                if response.status_code == 429:
                    retry_after = int(response.headers.get("Retry-After", "5"))
                    await asyncio.sleep(retry_after)
                    continue
                response.raise_for_status()
                return
        raise Exception("Max retries exceeded")

    async def send_batch(self, rows: list[dict], delay: float = 0.2) -> dict:
        """Send multiple records with rate limiting."""
        results = {"sent": 0, "failed": 0, "errors": []}
        for row in rows:
            try:
                await self.send_to_table(row)
                results["sent"] += 1
            except Exception as e:
                results["failed"] += 1
                results["errors"].append({"row": row, "error": str(e)})
            await asyncio.sleep(delay)
        return results

    async def enrich_person(self, email: str) -> dict:
        """Enterprise API: Look up person data by email."""
        async with httpx.AsyncClient(timeout=self.timeout) as client:
            response = await client.post(
                f"{self.base_url}/v1/people/enrich",
                json={"email": email},
                headers={"Authorization": f"Bearer {self.enterprise_api_key}"},
            )
            response.raise_for_status()
            return response.json()

Step 4: Singleton Pattern for Multi-Use

// src/clay/instance.ts — reuse a single client across your app
let instance: ClayClient | null = null;

export function getClayClient(): ClayClient {
  if (!instance) {
    instance = new ClayClient({
      webhookUrl: process.env.CLAY_WEBHOOK_URL!,
      enterpriseApiKey: process.env.CLAY_API_KEY,
    });
  }
  return instance;
}

Error Handling

Pattern	Use Case	Benefit
Retry with backoff	429 rate limits, network errors	Automatic recovery
Batch with delay	Sending many rows	Respects Clay rate limits
Enterprise API guard	Missing API key	Clear error before API call
Timeout control	Slow webhook delivery	Prevents hung connections

Examples

Webhook Handler for Clay Callbacks

// Express handler for Clay HTTP API column callbacks
app.post('/api/clay/callback', (req, res) => {
  // Respond 200 immediately (Clay expects fast response)
  res.json({ ok: true });

  // Process async
  processEnrichedData(req.body).catch(console.error);
});

Output

Return typed, validated enrichment results or a classified retryable/terminal failure with a correlation ID. The client and callback boundary must redact webhook URLs, credentials, and unneeded lead attributes in logs; callers must not treat an HTTP acknowledgement as proof that downstream enrichment was processed.

Resources

• Clay University -- HTTP API Integration
• Clay University -- Webhook Guide
• Clay University -- Using Clay as an API

Next Steps

Apply patterns in clay-core-workflow-a for real-world lead enrichment.