# Connecting Clay

> Source: https://docs.trailspark.ai/docs/connecting-clay

## Overview

Clay connects as a **two-sided round trip**: TrailSpark pushes each account's `correlation_id` and website `domain` into a webhook source in your own Clay table, you design the enrichment inside Clay, and an HTTP API column in your Clay table sends the results back to TrailSpark through a callback URL you set up there. Because both sides have to be wired up, connecting Clay is a two-step handshake rather than a single paste-and-go.

This also means Clay credits are spent by the columns **you** run in your Clay table — not by TrailSpark. TrailSpark's own caps (see [Enrichment Rules & Budget Caps](/docs/enrichment-rules-and-budget-caps)) control how many accounts get sent to Clay; what each one costs in Clay credits depends on the columns you've built.

## Before you start (in Clay)

In Clay, create a webhook source in the table you want TrailSpark to push accounts into, and copy that webhook's URL. You'll paste it in the next step.

## Step 1: Paste your Clay webhook URL

Go to **Settings** > **Integrations**, find **Clay** in the **Data enrichment** section, and click **Configure**.

- **Connection name** — a label for this connection (e.g., "Clay production")
- **Clay webhook URL** — paste the URL you copied from the webhook source you created in Clay. It's stored securely and never shown again.
- **Auth header (optional)** — only fill this in if your Clay webhook requires a header to accept requests. Leave both **Auth header name** and **Auth header value** blank otherwise.

Click **Connect**.

## Step 2: Copy your one-time setup values

Right after you connect, TrailSpark shows a one-time screen: **"Copy these now — they're shown only once."** It has two values:

- **Callback URL** — where Clay sends company details back to TrailSpark
- **Ingest token** — proves the callback request really came from your Clay table

Copy both immediately. For your security, TrailSpark can't show the ingest token again — if you lose it, disconnect Clay and reconnect to get a new one and a new callback URL.

## Step 3: Finish setup in Clay

The same screen walks through a **"Finish setup in Clay"** checklist:

1. **Webhook source added.** Done automatically — you already pasted its URL in Step 1.
2. **Map the incoming `correlation_id` field** to a column in your Clay table. TrailSpark uses it to match Clay's answer back to the right account.
3. **Send a sample row so Clay knows your columns.** Clay only shows the `correlation_id` and `domain` columns after your table receives its first row — click **Send sample row**, then refresh the Clay table to see them. TrailSpark uses one of your real account domains for the sample when it can, so the preview looks like a real row; the row itself is throwaway (its `correlation_id` is `setup-sample`) and safe to delete once you're done.
4. **Add an "HTTP API" enrichment column** in Clay that sends a POST request to your **Callback URL**, with the header `x-trailspark-ingest-token` set to your **Ingest token**. In the request body, include `correlation_id` plus the company details you want to return: `industry`, `employee_count`, `region`, and `market_segment`.
5. **Turn on auto-run** for the table so new accounts are enriched automatically as they arrive.

When you're done, click **"I've saved these — finish setup."**

### Two kinds of columns, two jobs

A working Clay table for TrailSpark typically has two kinds of enrichment columns, and it's worth keeping their jobs separate:

- **A data column, like Clay's Enrich Company** — this is Clay's own waterfall: it looks up industry, employee count, location, funding, and more from the `domain` column. This is the column that spends your Clay credits, per row per column.
- **An HTTP API column** — this doesn't look anything up. It just delivers the values you choose (from your data column, or typed directly) back to TrailSpark. Pick the **"HTTP API (headers)"** integration when you add it.

A minimal working table has one waterfall column feeding one HTTP API column.

### Setting up the HTTP API column

A few specifics that are easy to miss:

- Set the method to **POST** first — the body editor only appears once the method is set to POST.
- The endpoint is your **Callback URL**, and the header value comes from your **Ingest token** — both from the one-time setup screen in Step 2. The token is shown once; if you lose it, disconnect and reconnect to get a new one.
- **Add the header on the column configuration itself.** If your Clay workspace has a saved "header account" at the connection level, don't rely on it here — headers saved that way may not be applied to the request, which shows up as a 401 from TrailSpark even though the token is correct. Set `x-trailspark-ingest-token` directly on the column.

### The request body: keys are typed, values are picked

The JSON keys in the body — `correlation_id`, `domain`, `industry`, `employee_count`, `region`, `market_segment` — are typed in literally. These are the names TrailSpark recognizes; don't rename them. The values next to each key are `/` references you pick from your table's columns: the webhook columns for `correlation_id` and `domain`, and your waterfall column's outputs for the rest.

If your waterfall doesn't have an exact `region` or `market_segment` output, map the closest one it does have (HQ country for `region`, for example), or add a small formula column in Clay that derives it. You can also just leave a key out entirely — TrailSpark never writes an empty value, and an empty value never overwrites a field you already have filled in.

Clay's HTTP API column should POST a JSON body shaped like this:

```json
{
  "correlation_id": "abc123",
  "domain": "acme.com",
  "industry": "Software",
  "employee_count": 120,
  "region": "North America",
  "market_segment": "Mid-Market"
}
```

A few things to know about the contract:

- `correlation_id` (or `correlationId`) is required — it's how TrailSpark matches the answer back to the right account.
- Field names can be either style — `employee_count` or `employeeCount`, `market_segment` or `marketSegment` — TrailSpark reads both.
- **Extra fields are welcome.** Anything else your waterfall returns — funding stage, tech stack, whatever you find useful — can be added as its own key. After your first results come back, each one appears as a custom field under **Enriched fields** on the **Enrichment rules** tab, where you turn on the ones you want to use in ICP rules, scoring context, and destinations. See [Enrichment Rules & Budget Caps](/docs/enrichment-rules-and-budget-caps#enriched-fields).
- If Clay couldn't find a match for an account, send `"matched": false` (or `"status": "no_match"`) instead of the company-detail fields, so TrailSpark records it as no match rather than guessing.

## After you're connected

Once connected, the page shows **"Clay is connected."** Your webhook URL is saved securely and never shown again — to replace it, disconnect and reconnect.

- **Test connection** checks that your setup is complete (a valid webhook URL and an issued ingest token). It never sends a real row to Clay, so it never uses up your webhook's lifetime submissions.
- **Disconnect** stops TrailSpark from pushing any more accounts to this webhook. To swap in a different webhook URL or auth header, disconnect and reconnect.

### Nearing your webhook's lifetime limit

Clay webhook sources accept only a fixed number of submissions over their lifetime. As you approach that limit, TrailSpark shows a warning: **"This Clay webhook is nearing its lifetime limit."** When you see it, create a new webhook source in Clay, then disconnect and reconnect here with the new URL — that resets the limit and keeps company details flowing without interruption.

## Next Steps

- [Enrichment Rules & Budget Caps](/docs/enrichment-rules-and-budget-caps) — choose which accounts Clay enriches and set optional caps
- [Third-Party Intent & Field Provenance](/docs/how-enriched-data-shows-up) — how Clay's company details combine with your CRM
- [Connecting Reo.dev](/docs/connecting-reo-dev) — add a second enrichment source