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:

When you use your own API keys, 0 Clay credits are consumed — credits only apply when using Clay's managed provider accounts.

Step 4: Create .env for Local Integration Code

# .env — for local scripts that interact with Clay
CLAY_API_KEY=clay_ent_your_key          # Enterprise API (if applicable)
CLAY_WEBHOOK_URL=https://app.clay.com/api/v1/webhooks/abc123  # Table webhook
CLAY_WORKSPACE_ID=ws_your_workspace     # Found in Settings > Workspace

# Provider keys (optional — for direct provider calls outside Clay)
APOLLO_API_KEY=your_apollo_key
CLEARBIT_API_KEY=your_clearbit_key
HUNTER_API_KEY=your_hunter_key

Step 5: Verify Webhook Authentication

Secure your webhook endpoint with a shared secret in the header:

# Send authenticated webhook data
curl -X POST "$CLAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-shared-secret" \
  -d '{"email": "test@acme.com", "source": "auth-verification"}'

Error Handling

Output

• Clay workspace configured with API access
• Webhook URL ready to receive programmatic data
• Provider API keys connected for credit savings
• .env file with all required credentials

Resources

• Clay University — HTTP API Overview
• Clay University — Webhook Integration Guide
• Clay Plans & Billing

Next Steps

After auth setup, proceed to clay-hello-world to send your first enrichment through Clay.