> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/clay.md).

# Clay

The Clay integration connects your Clay workspace to Harmony, giving your team visibility into who has access to Clay, what role each person holds, and how many credits each person uses. Clay appears as a managed application in Application Management.

#### What the Clay integration enables

| Capability              | Description                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| User Discovery          | Surface every member of your Clay workspace, including invitations that have not been accepted         |
| Role Visibility         | See each member's Clay role; workspace Admins are flagged as administrators in access reviews          |
| Seat Visibility         | See which members belong to a workspace on a paid Clay plan                                            |
| Credit Usage            | Track the data credits and actions Clay credits to each member per day, split by where they were spent |
| Multi-Workspace Support | Connect several Clay workspaces, each as its own instance                                              |

***

#### Prerequisites

1. **A Clay workspace Admin** - use the API key of a member with the **Admin** role in the workspace you want to connect
2. **The Admin's legacy API key** - Harmony uses the key under **Settings** > **Account** > **API key (legacy)**, not a Public API key
3. **Your Clay workspace ID** - the number in your Clay URL (see [Step 2](#step-2-find-your-clay-workspace-id))
4. **A Harmony account** with admin privileges

***

#### Connect Clay to Harmony

**Step 1: Copy your Clay legacy API key**

Sign in to Clay as the workspace Admin whose key Harmony should use, then:

1. Click your account name and open **Settings**
2. Under **Account settings**, click **Account**
3. Open the **API key (legacy)** tab
4. Click **Regenerate key** and **copy the key** from the window that opens. It starts with `clay_user_`. Clay shows the full key only once - after you close the window, only a redacted version is visible

{% hint style="warning" %}
**Use the legacy key, not a Public API key.** Keys created under **API and CLI** > **API keys** are for Clay's Public API, which does not expose workspace members or credit usage, and Harmony cannot connect with them.
{% endhint %}

{% hint style="info" %}
**Regenerate key** issues a new legacy key and immediately invalidates the previous one. Other tools that use the legacy key, such as Zapier, then need the new key too.
{% endhint %}

**Step 2: Find your Clay workspace ID**

Open the workspace in Clay and look at the address bar. The workspace ID is the number after `/workspaces/` - for example `1458070` in `app.clay.com/workspaces/1458070/home`.

{% hint style="info" %}
**Why Harmony asks for the workspace.** A Clay API key belongs to a person, not a workspace, and every Clay sign-up also gets a personal workspace of its own. The workspace ID tells Harmony which of the key owner's workspaces to read.
{% endhint %}

**Step 3: Navigate to Integrations**

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Clay** under **SaaS Applications**, or search for it by name
4. Click its card. If a Clay workspace is already connected, click **+ Create instance**

**Step 4: Enter Credentials**

1. **Instance name** (required) - for example the name of the Clay workspace
2. **API key (legacy)** - the key you copied in Step 1
3. **Workspace ID** - the number you found in Step 2
4. Click **Connect**

When you click **Connect**, Harmony checks the key and workspace with Clay before saving. If the key is not a legacy key, the key's user is not a member of that workspace (Harmony lists the workspaces the key can reach), or Clay refuses the key access to the workspace's member list, the connection is refused with the reason.

Once connected, Harmony begins syncing members and credit usage from your Clay workspace. To connect another workspace, open the Clay card again, click **+ Create instance**, and repeat Step 4 with that workspace's ID.

***

#### Disconnect Clay from Harmony

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Clay** under **SaaS Applications** and click its card
4. Click the delete (trash) icon next to the instance you want to remove
5. Confirm when prompted

Once disconnected, Harmony stops syncing data from Clay. Previously synced data remains available in Harmony.

***

#### What Harmony Syncs from Clay

| Data         | Description                                                                                                                                                                                                                 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Members      | Clay user ID, name, and email address of every workspace member                                                                                                                                                             |
| Invitations  | Pending invitations, recorded with status **Pending** until the person joins                                                                                                                                                |
| Role         | The member's Clay role (Admin, Editor, Viewer or Sales Rep); Admins are classified as administrators                                                                                                                        |
| SCIM flag    | Whether the member is managed through SCIM provisioning                                                                                                                                                                     |
| Seat usage   | Members of a workspace on a paid plan are recorded as holding a paid seat; trial and free plans as free. When Harmony cannot tell whether the plan is paid, the tier shows **Unknown**. Pending invitations are not counted |
| Plan         | The workspace's plan name. Harmony also stores the current billing period, data-credit allowance, action limit and remaining balances, but does not display them                                                            |
| Credit usage | Data credits and actions per member per day (see below for what is counted)                                                                                                                                                 |

{% hint style="info" %}
**How credit usage is attributed.** Clay credits table and workbook spend to the person who **owns** the table, not to whoever ran it, and scheduled, auto-run and webhook runs spend there with nobody acting. Harmony therefore records credit usage in two kinds:

* **Own use (sets Last Login):** credits a member spent calling Clay from an AI tool such as Claude or ChatGPT (MCP). Clay attributes these to the person who made the call, so they set the member's **Last Login** and count them as active.
* **Credited to a table's owner (Activity column only):** table and workbook credits, with the spend Clay flags as recurring kept separate. They appear in the member's **Activity** column but do not set **Last Login** or count the member as active.

Workflows, signals, Public API calls, and functions run outside an AI tool are not included, so per-member totals are lower than the workspace total on Clay's **Settings** > **Usage** page.
{% endhint %}

{% hint style="info" %}
**No login data.** Clay exposes no login or last-active information. The Clay integration sets **Last Login** only from a member's own MCP credit usage, so a member who works in Clay's web app without using it through an AI tool has no **Last Login** from Clay, even though their table usage appears in the **Activity** column.
{% endhint %}

{% hint style="info" %}
**No seat limit.** Clay plans are priced on credits and actions rather than seats, and Clay reports no seat limit. Harmony shows how many members are on a paid plan, not a purchased seat count.
{% endhint %}

{% hint style="info" %}
**Sync cadence:** members and plan details refresh every 6 hours. Credit usage is collected once a day for the day before yesterday (UTC), so Clay's usage reports have settled; the first sync backfills the last 90 days.
{% endhint %}

***

#### Viewing Clay Data in Harmony

* **Application Management** - Clay appears as a managed application, where you can review its member list, roles, seat counts and per-member usage
* **User profiles** - individual users show their Clay access alongside other application data
* **Multiple workspaces** - each connected workspace appears as its own Clay instance, named after the workspace

***

#### Permissions Explained

Clay's Public API does not expose workspace members, plans or credit usage, so Harmony reads them from the API the Clay web app itself uses, authenticated with the legacy API key you provide. All access is read-only, and reading does not consume Clay credits or actions.

| What Harmony calls                                      | Why                                                            |
| ------------------------------------------------------- | -------------------------------------------------------------- |
| `GET /v3/workspaces/{id}/permissions`                   | Workspace members, pending invitations, roles and SCIM flag    |
| `GET /v3/my-workspaces`                                 | Workspace name and remaining credit balances                   |
| `GET /v3/workspaces/{id}/subscriptions`                 | Current plan phase, billing period, allowance and action limit |
| `GET /v3/workspaces/{id}/billingplans`                  | Plan name                                                      |
| `GET /v3/credit-reporting/{id}/creditReportType/{type}` | Daily credit usage from Clay's usage reports                   |

Things to know about the key:

* **The legacy key carries no scopes.** It has the full permissions of the Clay user it belongs to, which is why Harmony asks for an Admin's key
* Harmony only reads. It does not invite or remove members, change roles, run tables or enrichments, or buy credits

***

#### Troubleshooting

<details>

<summary>The connection is rejected or syncs fail with an authentication error</summary>

**Possible causes:**

* A Public API key (from **API and CLI** > **API keys**) was entered instead of the legacy key. Harmony refuses it when you click **Connect**
* The legacy key was regenerated in Clay after it was connected. Regenerating immediately invalidates the previous key

**Solutions:**

1. Click **Regenerate key** under **Settings** > **Account** > **API key (legacy)** and copy the new key - Clay shows the full key only once
2. In Harmony, delete the Clay instance and connect it again with that key (the key cannot be edited on a connected instance). Syncing starts again with the new instance

</details>

<details>

<summary>Syncs fail with an access error for the workspace</summary>

**Possible causes:**

* The key's owner is no longer a member or an Admin of the workspace

**Solutions:**

1. Restore the key owner's Admin access in Clay, or delete the Clay instance in Harmony and connect it again with the legacy key of a current Admin of that workspace
2. Harmony retries a refused sync once a day for up to two weeks, so after restoring access syncing resumes by the next daily retry. If syncs have failed for longer than that, contact Harmony Support to restart them

</details>

<details>

<summary>Members are listed but their license tier shows Unknown</summary>

**Possible causes:**

* Clay refused the key access to the workspace's billing
* Clay reports no current subscription for the workspace
* The workspace is on a plan Harmony cannot classify as paid or free, such as an invoiced contract

**Solutions:**

1. Delete the Clay instance in Harmony and connect it again with a workspace Admin's legacy key
2. If an Admin's key is already in use, contact Harmony Support

</details>

<details>

<summary>Credit usage in Harmony is lower than on Clay's Usage page</summary>

**Possible causes:**

* This is expected. Harmony reads only table, workbook and MCP credits - see [What Harmony Syncs from Clay](#what-harmony-syncs-from-clay)

**Solutions:**

1. Use Clay's **Settings** > **Usage** page for the workspace's total spend

</details>

<details>

<summary>Rotating the API key</summary>

Click **Regenerate key** under **Settings** > **Account** > **API key (legacy)** in Clay, which immediately invalidates the old key, then straight away delete the Clay instance in Harmony and connect it again with the new key (the key cannot be edited on a connected instance). Syncs that run before then fail. Update any other tools that use the legacy key, such as Zapier.

</details>

***

#### Data & Privacy

<details>

<summary>Key privacy principles</summary>

For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).

* Harmony accesses Clay data in read-only mode and does not modify anything in your Clay workspace
* The integration can be revoked at any time by disconnecting it in Harmony or regenerating the legacy key in Clay

</details>

<details>

<summary>What Harmony does not collect</summary>

Harmony reads only workspace membership, plan details and credit usage totals. It does not collect:

* Table, workbook or audience records, or any enrichment results
* Table names, prompts, functions or workflow definitions
* Searches or the people and companies found through them
* IP addresses or login history - Clay exposes neither

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/saas-applications/clay.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
