> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Clay

> Send records to a Clay table to enrich them, and have Clay write the results back.

## What it does

[Clay](https://www.clay.com) enriches rows in a table: it looks up emails,
phones, job titles, company data and more across many data providers. With
Custral you can:

* **Send records to Clay** from a workflow. Each record becomes a row in a Clay
  table, and the table's enrichment columns run on it.
* **Write the results back** from Clay. An HTTP API column in the table updates
  the Custral record with what Clay found.
* **Create records from Clay.** Rows that start in Clay can create or update
  Custral records the same way.

Every lookup runs on **your own Clay account** and spends your Clay credits.
Custral holds no Clay credentials.

> [!NOTE]
>
> Clay's webhook sources and HTTP API columns are part of Clay's **Growth** and
> **Enterprise** plans. On a plan without them, export a CSV from Clay and
> [import it](https://docs.custral.com/data/records/import.md) instead.

## Send records to Clay

**1. Add a webhook source to your Clay table**

In the Clay table, choose **Add source → Webhook**. Copy the webhook URL.
If you set an auth token on the source, copy that too.

**2. Install the Clay module**

In Custral, install **Clay** from **Settings → Integrations → Modules**.

**3. Add the step to a workflow**

Add **Send to Clay Table** to a workflow, for example one that starts when
a person is created. Paste the webhook URL, pick the record, and paste the
auth token if the source has one.

### What Clay receives

One JSON object per record:

```json theme={null}
{
  "recordId": "rec_...",
  "object": "people",
  "name": "Jane Doe",
  "email": "jane@acme.com",
  "job_title": "Head of Sales",
  "stage": "Lead"
}
```

* Each property is sent under its **key**, the same key the API uses, so the
  write-back can name the same columns.
* Select, person and relation values arrive as their **names**, not as ids.
* **Extra fields** adds any JSON you like to the body, such as
  `{"source": "custral"}`.

"Try it" on the step shows what would be sent. It doesn't send anything to Clay.

## Write the results back

**1. Create a Custral API key**

In **Settings → Applications**, create a key with the **records:write**
scope. See [API keys](https://docs.custral.com/dev/auth/overview.md).

**2. Add an HTTP API column in Clay**

After your enrichment columns, add an **HTTP API** column. Set the method
to `POST`, the URL to
`https://api.custral.com/v1/records/people/upsert`, and a header
`Authorization: Bearer <your key>`.

**3. Map the enriched columns**

Set the body to match on email and send the columns you want written:

```json theme={null}
{
  "matchOn": "email",
  "fields": {
    "email": "/Email",
    "job_title": "/Title",
    "phone": "/Mobile Phone"
  }
}
```

Replace `/Email`, `/Title` and `/Mobile Phone` with your Clay columns.

The record with that email is updated. When no record has it, one is created.
See [writing the same record twice](https://docs.custral.com/dev/api-reference/records.md) for
`createFields` and the full rules.

Changes written this way are ordinary record edits, so they start your
**field updated** workflows.

## Limitations

* **Clay's limits apply.** A Clay webhook accepts 50,000 rows over its
  lifetime. When it fills up, add a new webhook source to the table and paste
  the new URL into the step.
* **The webhook URL and auth token are stored on the step.** Anyone who can
  edit the workflow can see them.
* **There is no Clay trigger.** Clay doesn't send events Custral can listen
  to. Use the write-back above, then start workflows from record changes.
* Custral doesn't read your Clay tables, and Clay doesn't see your Custral
  records other than the ones a workflow sends.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| "That isn't a Clay webhook URL." | The URL isn't on clay.com. | Copy the URL from the table's webhook source. Use **Send Webhook** for other services. |
| "Clay refused the auth token." | The token doesn't match the source. | Copy the token again from the webhook source, or clear it on both sides. |
| "Clay answered 4xx" | The webhook is full or was deleted. | Add a new webhook source and paste its URL. |
| Nothing is written back | The HTTP API column failed. | Check the column's output in Clay. A `match_ambiguous` error means two records share that email. |

## Send Webhook

**Send Webhook** is the same step for any HTTPS URL, such as a Zapier, Make or
n8n webhook. It sends the same JSON, and takes an optional header name and
value for auth.

## Related

* [Workflows](https://docs.custral.com/automation/workflows/overview.md): where the Clay step runs.
* [Apollo](https://docs.custral.com/integrations/apollo.md): another enrichment source.
* [Integrations overview](https://docs.custral.com/integrations/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.