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

# Enrich contacts with Clay

> Send contacts from a Conversion workflow to Clay, enrich them, and write the results back to Conversion.

Use Clay to enrich contacts as they move through a Conversion workflow. Conversion sends each contact to a Clay webhook, and Clay writes the enrichment results back through the Conversion API.

## Before you begin

Make sure you have:

* Permission to edit and activate workflows in Conversion
* A Conversion Administrator account to create an API key
* Permission to create webhook sources and enrichments in Clay
* Writable contact or company fields for the data you want to save

<Warning>
  This setup sends contact data to Clay. Only send the fields Clay needs, and make sure your use of Clay follows your organization's privacy and data-handling policies.
</Warning>

## Create a webhook in Clay

<Steps>
  <Step title="Create the webhook source">
    In a Clay workbook, click **+ Add**, search for **Webhooks**, and select **Monitor webhook**.
  </Step>

  <Step title="Copy the webhook URL">
    Copy the URL that Clay generates. You will add it to your Conversion workflow.

    Clay webhook sources accept JSON sent with a `POST` request. See [Webhooks in Clay](https://university.clay.com/docs/webhook-integration-guide) for current setup instructions and submission limits.
  </Step>
</Steps>

## Send contacts to Clay

<Steps>
  <Step title="Add an HTTP request node">
    Open the Conversion workflow that contains the contacts you want to enrich. Add an **HTTP request** node from **Integrations**.
  </Step>

  <Step title="Configure the request">
    Set **Method** to **Post** and paste the Clay webhook URL into **URL**.

    Add the contact data Clay needs to **Body**:

    ```json theme={null}
    {
      "email": "{{ contact.email }}",
      "first_name": "{{ contact.first_name }}",
      "last_name": "{{ contact.last_name }}"
    }
    ```

    The values inside double curly braces use [Liquid](/product-docs/liquid/overview) to insert data from each contact. You can type `/` in the Body editor to insert fields without writing the Liquid expressions yourself.
  </Step>

  <Step title="Test the webhook">
    Save and activate the workflow with one test contact. Confirm that Clay creates a row containing the values you sent.
  </Step>
</Steps>

The HTTP request node finishes after Clay accepts the webhook. Clay performs the enrichment and writes the result back to Conversion separately.

## Enrich the contact in Clay

In the Clay table, add the enrichments you need and map the webhook columns as inputs. For example, you can use an email address to enrich a contact's job title, company name, or company website.

Test each enrichment on one row and confirm that the result has the format expected by its destination field in Conversion.

## Create a Conversion API key

<Steps>
  <Step title="Open your integration settings">
    In Conversion, go to **Settings → Integrations**. Only workspace Administrators can manage API keys.
  </Step>

  <Step title="Add the key">
    In the **API** section, click **Add API key**. Name the key, such as `Clay enrichment`, and create it.
  </Step>

  <Step title="Copy the key">
    Copy the key when it appears. Conversion does not show the full key again.
  </Step>
</Steps>

<Warning>
  Treat the API key like a password. Store it in a reusable Clay HTTP header account instead of entering it directly in a table column.
</Warning>

## Write the enrichment results to Conversion

<Steps>
  <Step title="Create a header account in Clay">
    In your Clay table, click **Add enrichment** and select **HTTP API**. Open the **Select header account** menu, click **+ Add account**, and add:

    | Key         | Value                   |
    | ----------- | ----------------------- |
    | `X-API-Key` | Your Conversion API key |

    Name and save the account, then select it for the enrichment. Clay automatically sends `Content-Type: application/json` for the JSON request.
  </Step>

  <Step title="Configure the Conversion request">
    Open the **Configure** tab and enter:

    | Setting      | Value                                           |
    | ------------ | ----------------------------------------------- |
    | **Method**   | `POST`                                          |
    | **Endpoint** | `https://pub-api.conversion.ai/api/v2/contacts` |

    Add a JSON body that maps your Clay columns to Conversion field keys:

    ```json theme={null}
    {
      "email": "/email",
      "preserveExistingFields": true,
      "fields": {
        "job_title": "/job_title"
      },
      "companyFields": {
        "company_name": "/company_name",
        "website": "/website"
      }
    }
    ```

    For each value beginning with `/`, type `/` in Clay and select the corresponding column. The values must be dynamic column references, not the literal example text.
  </Step>

  <Step title="Check your field keys">
    Keys inside `fields` must match writable contact field keys in Conversion. Keys inside `companyFields` must match writable company field keys.

    To find or create fields, go to **Settings → Objects**, open **Contact** or **Company**, and select **Fields**.
  </Step>

  <Step title="Choose how to handle existing values">
    Keep `preserveExistingFields` set to `true` to fill empty fields without replacing existing values. Set it to `false`, or remove it, only when Clay should overwrite existing values.

    <Warning>
      Do not include `subscriptionStatus` unless you intend to change the contact's email consent status. Enrichment does not require subscribing the contact.
    </Warning>
  </Step>

  <Step title="Test the write-back">
    Add a conditional run so the request only runs after its required enrichment columns contain values. Test the HTTP API enrichment on one row.

    A successful request returns a `200` status and includes the Conversion contact ID in `data.cnvContactId`. See [Upsert Contact](/api-reference/upsert-contact) for all request fields and response details.
  </Step>
</Steps>

## Test the complete workflow

1. Enroll one test contact in the Conversion workflow.
2. Confirm that Clay receives a new webhook row.
3. Confirm that the Clay enrichments finish successfully.
4. Confirm that the HTTP API enrichment returns a `200` status.
5. Open the contact in Conversion and verify that the expected fields were populated.

After the test succeeds, update the workflow trigger to include the contacts you want to enrich.