How to Connect Clay to Salesforce for CRM Enrichment and Upserts

According to Salesforce's State of Sales report, sales representatives spend only 28% of their week actually selling, with the remaining 72% consumed by administrative tasks, manual data entry, and CRM tool management. This capacity crisis directly impacts outbound sales performance. Sales teams spend hours clean-up records, validating lead information, and manually copy-pasting details across tools. Because database records degrade quickly as contacts change roles or transition to new companies, manual data enrichment is insufficient to keep pipelines clean.

Connecting a Clay table directly to your Salesforce instance automates this data hygiene loop. A clay salesforce integration lets GTM teams build data waterfalls, pulling records from the CRM, enriching them using dozens of data providers, and pushing the clean details back to Salesforce. Instead of running one-off CSV exports, you establish an automated pipeline. This integration ensures that your sales outreach is guided by accurate, updated account profiles, maximizing connect rates and reducing team administrative overhead.

Establishing a connection between Clay and Salesforce requires configuring the appropriate authentication flow. For standard developer environments or basic company settings, user-level OAuth is the simplest approach. When you initiate this connection, Clay prompts you to log in with your Salesforce credentials to authorize access. However, for organizations with strict security rules, standard user login is often blocked by IP restrictions or organization policies.

Enterprise Salesforce setups often require external client app OAuth credentials. As of the Spring 2026 release, Salesforce has disabled the creation of new legacy Connected Apps by default, making External Client Apps the standard for server-to-server integrations. To connect Clay using an External Client App, you must configure a secure authentication flow.

First, log into your Salesforce instance as an administrator and navigate to the Setup menu. Search for and open the External Client App Manager, then click to register a new app. Provide a descriptive name, enable OAuth settings, and select the Client Credentials Flow check box. After saving the configuration, open the Policies tab of the External Client App. This is a critical step that administrators frequently miss. Under the policies settings, you must authorize the Client Credentials Flow and assign a Run As user. The Run As user acts as your integration user, meaning all data written by Clay will carry this user's audit context.

Once the app is saved and configured, navigate to the Connected Apps OAuth Usage page in Setup. Find your newly created app and click Install to activate it. You can now view and copy the consumer details. Copy the client ID, client secret, and token endpoint URL. In your Clay workspace, navigate to Settings and open the Connections menu. Click Add connection, search for Salesforce, select the client credentials option, and input the credentials to complete the secure OAuth handshake. (Learn more about secure developer connections on the storage for agents page).

Standard lookup actions in Clay allow you to find records using basic fields like email address or lead name. However, when working with complex CRM databases, simple lookups are insufficient. For example, you may need to search for contacts who belong to accounts in a specific region or find records updated within the last week. To execute these searches, you must write custom query filters.

SOQL lookups in Clay execute database-level queries in real time. This capability allows you to retrieve records by joining tables and applying precise query filters. To implement this, add a new enrichment column to your Clay table and select the Lookup records via SOQL action. You can write your select statement in the query editor, matching database attributes against variables in your Clay table.

SELECT Id, Name, Email, Title, AccountId FROM Contact WHERE Email = '{{Company Domain}}'

When designing your queries, you must account for Salesforce API limits. Running unoptimized queries across millions of records will deplete your API budget and throttle performance. To maintain query speed, always filter your SOQL requests using indexed fields. Fields such as Record Id, Email, Name, and custom fields configured as External IDs are indexed by default. Avoid filtering by unindexed text area fields, which force full table scans. If your query fails or returns unexpected results, validate the SOQL syntax using the Query Editor inside the Salesforce Developer Console before running the enrichment in Clay. (For details on pricing and API limits, see the pricing page).

Importing data is only half the battle. Once you enrich your lead profiles in Clay, you must write those updates back to your CRM. Running simple insert operations will create duplicate records, cluttering your database and confusing your sales reps. To solve this, you must run upsert operations, which check for existing records before making changes.

A salesforce clay upsert operation checks your CRM for a matching record using a unique identifier. If a matching record is found, Clay updates the existing record with the new enriched details. If no match is found, Clay inserts a new lead or contact. To set this up, add a Salesforce action column to your Clay table and choose the Upsert Record action. Select the target object, such as Lead or Contact, and specify the key field. You can use the standard Salesforce Record ID or a custom External ID field to map the records.

After defining the key, map your enriched Clay columns to the target Salesforce fields. Ensure that your field types match, mapping text columns to text fields and date columns to date fields. To prevent API limit exhaustion during large-scale runs, Clay does not execute updates row-by-row. Instead, Clay automatically bundles the updates and processes them in batches using Salesforce's Composite API. This batch processing reduces API request usage, allowing you to update thousands of records without depleting your organization's daily limits.

Prepare lead files before your Clay Salesforce integration

Clean and structure prospect files in Fastio before running your clay salesforce integration. Extract tables with Metadata Views and automate CRM updates. Starts with a 14-day free trial.

Start 14-Day Trial

Before your lead lists and data extracts reach Clay for enrichment, they must be gathered, reviewed, and organized. Sales teams often receive prospect data in unstructured formats, including PDF invoices, scanned trade show documents, contract documents, or Excel files.

To manage these incoming files, teams often rely on generic object storage solutions like Amazon S3 or default folders in Google Drive. However, these tools are designed for static file storage. They do not index contents for AI queries, support collaborative co-editing, or extract structured data automatically. For teams running modern GTM operations, a shared cloud workspace like Fastio provides a collaborative environment designed for human and agent workflows. Fastio is an intelligent workspace platform where humans and AI agents share the same file context, which you can manage inside dedicated Fastio workspaces with all file interactions logged in an append-only audit log.

Using Fastio's Metadata Views, you can turn any folder of incoming documents into a live, queryable database. Rather than building manual scripts or complex OCR rules, you describe the columns you want extracted in natural language. The AI designs a typed schema (supporting Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time), scans the documents in the workspace, and populates a spreadsheet grid. This structured extraction layer works across PDFs, images, Word docs, scanned pages, and handwritten notes.

Once Fastio extracts the data, you can add new columns without reprocessing the files. Because Fastio is built for agentic workflows, AI agents can use the Fastio MCP server to programmatically create schemas, match files, trigger data extraction, and query results. This structured extraction layer prepares your lead data, providing clean tables that you can import into Clay for enrichment and upsert into Salesforce. Fastio offers usage-based pricing starting with a 14-day free trial (credit card required). Plans include the Starter plan at $29/month, the Business plan at $99/month, and the Growth plan at $299/month.

When running automated data enrichment loops, you will occasionally encounter integration errors. Understanding these failures and how to troubleshoot them keeps your outbound sales pipeline running without interruption.

One common error is the OAUTH_EC_APP_NOT_FOUND failure. This error indicates that Salesforce cannot locate your External Client App or that the app's OAuth policies are blocking the connection. To resolve this, open Salesforce Setup and verify the app's configuration. Ensure that your Run As integration user has the appropriate Permission Sets to run the app and access the target objects. Additionally, check that the app is installed under the Connected Apps OAuth Usage page.

Another common failure is the invalid field name error during SOQL query execution or upserts. This occurs when you try to reference custom fields without using their API names. Salesforce custom fields always end with double underscores and the letter c (field_name__c). If a query fails, verify the field API names under the Object Manager in Setup. If you hit API limits during high-volume updates, configure your Clay table to process records in smaller batches, or set your Fastio workflows to trigger enrichments on a schedule to distribute the API load over time.