The Ultimate Clay API Guide for Cold Outreach Success [2026]

Clay has a real Public API now. That is the most important correction to older Clay API guides. Since July 2026, developers can search Clay’s GTM database, run reusable enrichment and scoring logic, read supported data surfaces, and connect Clay to backend services, internal tools, queues, and agents. Webhook-table workarounds still matter, but they are no longer the whole story.

Last updated: September 2026. This guide was checked against Clay’s current developer documentation and the leading search results for “Clay API.” It separates the new Public API from Clay’s outbound HTTP API action, documents the asynchronous run model, and removes endpoints and limits that Clay does not document.

Clay API in 60 seconds

• Use Searches when you need companies or people from Clay’s GTM database.
• Use Routines when you need enrichment, research, scoring, routing, cleanup or another repeatable GTM function.
• Use Tables when an Enterprise workspace needs to query known Clay tables programmatically.
• Use Audiences and Signals for records, saved segments, activities, and change-triggered workflows.
• Use a webhook to learn when an asynchronous routine finishes; verify its signature and keep polling as a fallback.
• Use Clay’s HTTP API action when Clay needs to call an external service. That is the opposite direction from your app calling Clay’s Public API.
• Keep API keys server-side. Every Public API request uses the clay-api-key header.

The practical 2026 pattern is: search or import a focused ICP list → run only the routines each record needs → verify completion → route qualified records to your CRM or sequencer.

What changed in Clay’s developer platform in 2026?

Older articles rank for “Clay API” because they explain webhooks, Zapier or Clay’s HTTP API column. Those methods are still useful, but the premise that Clay has no public developer API is obsolete. Clay now describes its platform as usable from agents, terminals, backend services, internal tools, and custom applications.

Clay also ships an agent plugin with skills and the clay CLI for shell-capable coding agents such as Claude Code, Codex, and Cursor. It is not intended for general chat apps that cannot run the CLI. Direct API calls remain the right choice for production backend jobs and custom applications.

Primary sources: Clay Developer Platform overview, Quickstart, and Routines overview.

Clay Public API vs. Clay HTTP API: what is the difference?

The names are easy to confuse, but the data direction is different. With the Public API, your application calls Clay. With an HTTP API action, a Clay table or workflow calls another application. A webhook can mean either an inbound table trigger in older table-based designs or a signed completion notification in the Public API run model, so describe the direction explicitly in technical documentation.

Choose the Public API when Clay is a capability inside your product or infrastructure. Choose an HTTP API action when the workflow already lives in Clay and needs one external step. Choose a table webhook when a form, CRM or automation tool simply needs to add rows to a Clay table.

How do you authenticate to the Clay Public API?

Create an API key under Settings → Account → API keys (beta). Keys are tied to a Clay user and that user’s workspace access. Send the key in the clay-api-key header on every request. Clay’s current public base path is https://api.clay.com/public/v0.

export CLAY_PUBLIC_API_KEY="***"

curl https://api.clay.com/public/v0/me 
  -H "clay-api-key: $CLAY_PUBLIC_API_KEY"

Store the key in a secrets manager or server-side environment variable. Do not put it in browser JavaScript, a mobile binary, a public repository, application logs, analytics events or screenshots. Use separate keys and least-privilege workspace access where your operating model allows it; rotate a key immediately if it is exposed.

Before building a large integration, call the authenticated-user endpoint and confirm that the returned user and workspace are the ones you expect. This avoids spending credits or writing data in the wrong workspace.

How do Clay Searches work?

Searches return structured company or people records from Clay’s proprietary GTM database. The current advanced-search flow is: fetch the query reference, author a Clay search query, create the search, and page through the iterator. Clay supports cross-entity filters (such as people whose companies match firmographic criteria) and nested Boolean logic.

Do not copy a guessed search endpoint or an old filters-mode example. Clay’s documentation marks filters-mode search creation as deprecated and directs developers to query-mode. Use the generated search query reference and create-search reference for the current request schema.

Current search result limits

Clay documents these as result limits, not generic request-rate limits. When a search-result limit is exceeded, the API returns HTTP 402 with the relevant limit and, for period limits, reset information. Invalid filters still return 400. The rolling window ages usage out daily at midnight UTC rather than resetting on a fixed billing date.

Design a search that protects downstream spend

1. Start with the smallest testable ICP. Combine role, location, company size, industry, and any required account criteria before you enrich.
2. Page deliberately. Store the search id and cursor state so a worker can resume without duplicating fetched records.
3. Deduplicate before expensive routines. Use a stable key such as normalized email, profile URL or domain plus role policy.
4. Separate fit from contactability. A company can match the ICP while a person record still lacks a verified business email.
5. Record source and retrieval time. Freshness and provenance matter when a contact later changes jobs.

Clay Public API vs. Generect Live API for search and email finding

People searching for “Clay API” often need a narrower answer than a platform overview: which API should originate people and companies, and which one should find a verified business email? Clay Public API and Generect Live API overlap at search, but they are strongest at different layers. Clay combines GTM search with reusable enrichment, research, scoring, and routing routines. Generect is a live contact source with dedicated company search, lead search, email finding, and email validation endpoints.

Sources: Clay Searches and plan limits, Clay rate-limit handling, Generect Live API documentation, and Generect pricing. A dash means the cited producer documentation does not publish a numeric value; it is not an estimate.

Decision rule: use Generect when the job starts with live company/contact discovery and verified-email status, then pass only qualified records to Clay for enrichment, research, scoring or routing. Use Clay Search when Clay’s own GTM database and query language are the intended source. In either design, keep source provenance so the CRM can distinguish Generect-sourced fields from Clay-generated outputs.

How do Clay Routines work?

Routines are Clay’s umbrella for repeatable programmable logic: enrichment, research, scoring, routing, cleanup, and similar GTM work. Clay-managed functions cover common jobs. Custom functions expose logic your team already built in Clay. Workflows overlap with functions but remain Alpha and are built and managed differently.

A direct function run is asynchronous. Start it with up to 100 items, keep each item’s caller-defined id, save the returned routine_run_id, then fetch results until the run is complete or handle a signed webhook notification.

ROUTINE_RUN_ID=$(curl --request POST 
  --url "https://api.clay.com/public/v0/routines/function:t_abc123/run" 
  --header "Content-Type: application/json" 
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY" 
  --data '{
    "items": [
      {"id": "lead-1042", "inputs": {"domain": "example.com"}}
    ]
  }' | jq -r '.routine_run_id')

The function:t_abc123 value is an example id format from Clay’s documentation; replace it with a routine id from your workspace and use the routine’s actual input names. Do not assume output keys. Custom-function results depend on the outputs you defined.

curl --request GET 
  --url "https://api.clay.com/public/v0/routines/run/$ROUTINE_RUN_ID/results" 
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY"

While work is running, Clay returns HTTP 202 with status and progress counters and no data array. A complete run returns HTTP 200 and a data array. Match each result to its input with your item id, not response order. A completed run can contain failed items, and the finished count includes both successful and failed items.

Retrieve all routine result pages

A complete run can be paginated. If the response includes a cursor, pass it back to the same results endpoint and continue until the cursor is omitted. Treat cursors as opaque strings. The run-level total and finished values describe the whole run, not only the current page.

curl --get 
  --url "https://api.clay.com/public/v0/routines/run/$ROUTINE_RUN_ID/results" 
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY" 
  --data-urlencode "cursor=$NEXT_CURSOR" 
  --data-urlencode "limit=20"

Use batch runs for large input sets

For inputs larger than the inline 1–100 item contract, use Clay’s batch flow: request a presigned upload URL, upload a JSONL input file, start the asynchronous batch run, and read results from the batch results endpoint. Prefer this over splitting a large dataset into a burst of concurrent inline calls. It reduces orchestration overhead and makes rate-limit handling more predictable.

How should you handle Clay routine webhooks?

A routine run can accept an optional webhook_id. When the run finishes, Clay sends a signed POST containing the routine_run_id. The notification tells you what result to fetch; it is not a substitute for reading and validating the run result.

1. Create the webhook with Clay’s CLI and store the returned signing secret immediately. Clay says the secret is shown once and cannot be retrieved later.
2. Pass the webhook id when starting an inline or batch routine run.
3. Read the raw request body before JSON parsing.
4. Compute an HMAC-SHA256 over that exact body with the signing secret.
5. Compare your value with the X-Clay-Signature header using a timing-safe comparison.
6. Reject invalid signatures, deduplicate repeated deliveries by run id, acknowledge valid deliveries quickly, then fetch results.
7. Keep a modest polling fallback because Clay explicitly states webhook delivery is not guaranteed.

The documented signature format is sha256=<hex digest>. A test event has an empty data object, so handlers should not assume every verified delivery contains a run id.

Operationally, write the run id and mode (inline or batch) to your job record when you start the run. The two modes use separate result paths. This prevents a shared webhook from fetching an inline run through the batch endpoint or vice versa.

How do rate limits and retries work?

Clay applies a per-workspace request rate limit. If you exceed it, the Public API returns HTTP 429 and a Retry-After header. When available, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset help you pace traffic before the ceiling.

• Treat 429 as retryable and wait at least the Retry-After interval.
• Use exponential backoff with jitter for concurrent workers.
• Cap attempts and move persistent failures to a dead-letter or manual-review queue.
• Poll asynchronous results at a modest interval instead of in a tight loop.
• Prefer batch endpoints for large workloads.
• Distinguish request throttling (429) from search-result allowance errors (402) and invalid input (400).

Clay does not publish one universal numeric request-per-second value in the rate-limit guide. Code against the response headers rather than hard-coding a number copied from a third-party blog.

Cold outreach workflow: Search → enrich → verify → route

A production outreach workflow should not enrich every record equally. The efficient design narrows the list in stages and makes each expensive action conditional on evidence from the previous stage.

Step 1: define the contract before collecting records

Write the ICP, required fields, exclusion rules, and destination schema first. For example: target accounts must match industry and employee-band rules; contacts must match an allowed seniority and function; the destination requires first name, last name, company domain, role, source, and a deliverability status. A record that cannot satisfy the minimum contract should not enter expensive research.

Step 2: search Clay or supply your own focused source list

Use Clay Searches when you want to originate companies or people from Clay’s GTM database. If you want a live upstream contact source, call Generect first: search accounts with POST /api/linkedin/companies/by_icp/, search people with POST /api/linkedin/leads/by_icp/, find a work email with POST /api/linkedin/email_finder/, and validate an existing address with POST /api/linkedin/email_validator/. Then send the qualified Generect records (not the whole raw population) to the minimum useful Clay routine.

GENERECT_BASE="https://api.generect.com"

# 1) Search a focused live lead set
curl -X POST "$GENERECT_BASE/api/linkedin/leads/by_icp/" 
  -H "Authorization: Token $GENERECT_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"without_company":true,"locations":["Germany"],"personas":[["Marketing leaders",["marketing"],["Director","VP","Head"],[]]],"limit_by":25}'

# 2) Find a work email for one qualified person
curl -X POST "$GENERECT_BASE/api/linkedin/email_finder/" 
  -H "Authorization: Token $GENERECT_API_KEY" 
  -H "Content-Type: application/json" 
  -d '[{"first_name":"Ada","last_name":"Lovelace","domain":"example.com"}]'

# 3) Re-check an address before routing it to Clay
curl -X POST "$GENERECT_BASE/api/linkedin/email_validator/" 
  -H "Authorization: Token $GENERECT_API_KEY" 
  -H "Content-Type: application/json" 
  -d '["[email protected]"]'

For Generect Email Finder and Generect Email Validator, treat exist=yes plus catch_all=false as the strongest deliverability state. Keep unknown and catch-all addresses in a separate review policy instead of calling them verified. Once a record passes, give it a stable caller-defined id before invoking Clay so its routine result can be joined back to the original Generect record safely.

This Generect → Clay pattern is deliberately asymmetric: Generect supplies fresh contact and email evidence upstream; Clay runs the enrichment and decision logic downstream. If Clay Search is already the source, do not call Generect merely to add a brand name. Call Generect only when live discovery, dedicated email finding or email validation changes the decision.

Related Generect guides: sales lead databases, automated lead generation, and sales process automation.

Step 3: normalize and deduplicate

Normalize domains, lowercase emails, standardize country and seniority values, and resolve duplicates before enrichment. Decide whether “one person per account,” “one persona per business unit” or “all qualified contacts” is the intended policy. Deduplicating only at the end wastes credits and can create conflicting CRM records.

Step 4: run cheap deterministic gates first

Check fields already present, basic ICP rules, suppression lists, and required consent or geographic policies before AI research. If the email is known, validate it before personalization. If a record is outside the ICP, stop. Conditional execution is the main control for both data-credit and action usage.

Step 5: run the minimum useful routine

Use a Clay-managed function for a common enrichment or research task or a custom function for team-specific logic. Keep inputs and outputs narrow. A scoring routine should return the score, reason codes, and version, not an unstructured essay. A research routine should return cited evidence or “not found,” not fabricate certainty.

Step 6: verify completion and item status

Use a signed webhook for fast reaction and polling as a reliability fallback. On completion, inspect every item status. Separate provider failures from “no match” outcomes and business-rule rejections. Retry only transient failures; sending a permanently invalid input through the same provider repeatedly wastes budget.

Step 7: route only qualified, contactable records

Send qualified records to the CRM or sequencer with a stable external id and a source timestamp. Keep “fit,” “contactability,” and “message readiness” as separate fields. A high-fit account with an unknown email is not ready for a cold-email sequence; it may be appropriate for research, ads or a manual account plan.

Step 8: close the loop

Write delivery, reply, meeting, opportunity, suppression, and bounce outcomes back to the system of record. Review performance by source, routine version, segment, and provider. The purpose of the API is not merely to move rows; it is to make the enrichment and routing policy measurable and improvable.

When should you still use Clay tables and inbound webhooks?

The table-first workflow remains useful for operations teams that want a visual workspace and do not need to embed Clay inside a product. An inbound webhook can add a row, table columns can enrich and classify it, and an HTTP API action or native integration can push the final record onward.

Do not build a fragile proxy that pretends a table webhook is synchronous. Enrichment can take time, providers can fail per item, and result ordering is not a reliable join key. If an external caller needs a synchronous-looking interface, accept the request, return a job id, process asynchronously, and expose job status from your own service.

How do Clay HTTP API actions work?

An HTTP API action lets a Clay workflow call an external API. Configure the HTTP method, URL, headers, query parameters, and JSON body, then map values from prior columns or workflow nodes. Use it for a service that Clay does not integrate with natively or when you need your own validation, scoring, warehouse or CRM endpoint.

1. Read the destination API contract. Confirm authentication, required fields, rate limits, idempotency, and error responses.
2. Keep secrets in Clay’s secure integration or secret mechanism. Do not paste keys into prompts or visible output fields.
3. Send only needed fields. Minimize personal data and avoid leaking whole rows to a service that needs one value.
4. Map success and error states. A 200 transport response does not always mean the business action succeeded.
5. Add idempotency. Use a stable lead or event id where the destination supports it.
6. Test a few rows. Inspect both Clay output and destination state before enabling automatic runs.

For email validation, for example, call a documented verifier endpoint with an email, store the provider’s status fields, and route only according to an explicit policy. Generect’s email-verification response distinguishes yes, no, and unknown outcomes and can include catch-all and MX context; an unknown result should not be silently treated as valid. See our email verification API comparison.

Where does Claygent fit?

Claygent is appropriate when the answer requires reading and interpreting the web rather than retrieving a known database field. Examples include classifying what a company sells, identifying a relevant pricing model, summarizing a public product launch or extracting a constrained fact from an approved URL.

Run deterministic and inexpensive checks first. Then use Claygent only for records that pass the ICP and contactability gates. Ask for a structured schema with an evidence URL, a short quotation or evidence note, and an explicit “not found” outcome. Human-review samples are essential before research output becomes outreach copy.

How do you connect Clay to cold email tools?

Use a native integration when it supports the fields, error visibility, and update behavior you need. Use an HTTP API action when the sending platform has a documented API but no suitable native connector. Use an automation platform such as Zapier or Make when speed and maintainability matter more than custom control.

Before sending, enforce suppression, legal basis and regional rules, company-level frequency caps, verified or explicitly accepted email status, and a stop rule for replies and bounces. Personalization does not compensate for weak targeting or poor list hygiene.

Data quality gates before outreach

A useful system treats data quality as a sequence of explicit decisions rather than a single “enriched” checkbox.

Generect’s July 2026 verification audit covered approximately 365,000 checks: 65.7% returned valid, 26.9% invalid, and 7.4% catch-all or unknown. That distribution is a reminder that “found” and “safe to send” are different claims. Your own mix will vary by source, geography, segment, and list age, so measure it rather than importing a universal benchmark.

Common Clay API mistakes and how to avoid them

Production checklist

• API key stored server-side and scoped through the correct user/workspace access.
• Official API reference linked in code review; no endpoint copied from network inspection or an old blog.
• Run ids, item ids, search ids, cursors, routine version, and source timestamps persisted.
• Queues have concurrency limits, retry caps, exponential backoff, jitter, and dead-letter handling.
• Webhook handler verifies the exact raw body and acknowledges quickly.
• Polling fallback reconciles jobs that did not receive a webhook.
• Every item status is inspected; partial failures are visible in monitoring.
• Search result allowances and HTTP request throttling are tracked separately.
• Deduplication and suppression happen before destination writes.
• PII retention, deletion, access, and vendor-sharing policies are documented.
• A small sample of AI research and personalization is reviewed on every material prompt or model change.
• Metrics connect source and routine versions to valid-contact rate, bounce rate, reply rate, meetings, and pipeline.

What leading Clay API guides miss

The strongest competing guides explain table webhooks, HTTP API columns, and practical integrations. Those remain valuable for no-code operators. The gap is freshness: many still frame the question around whether Clay has an API or describe narrow access patterns without the current Searches and Routines model.

This guide adds the missing 2026 developer contract: API-key authentication, plan-based search allowances, query-mode discovery, asynchronous routine execution, per-item failures, cursor pagination, signed completion webhooks, webhook delivery caveats, rate-limit headers, batch processing, and the Alpha status of Workflows. Those details matter when a workflow moves from a demo table into a production system.

Official Clay API resources

• Developer Platform overview
• Quickstart and API key setup
• Searches and current result limits
• Routines overview
• Routines API guide
• Authentication
• Webhook signatures and delivery
• Rate-limit handling
• Machine-readable documentation index

Clay’s generated reference is the authority for endpoint paths, request bodies, and response schemas. Recheck it before implementation because beta and Alpha surfaces can change. If a route is not in the official index or OpenAPI reference, do not present it as supported.

Frequently Asked Questions