Keep CRM Data Clean with an AI Hygiene Agent

Part 1: Before you start

1. 1.Install the Clay CLI

   Use version 1.3.1 or later, installed from Clay's own instructions. This page does not include an install command because the CLI reference it was written from does not list one. You also need jq, which the script uses to read the JSON the CLI prints.

2. 2.Log in to your workspace

   Browser login is the default. Use the device flow on a headless machine. A static key in the CLAY_API_KEY environment variable also works. Workflow commands need the terracotta:cli scope, so an auth error that names it means your login cannot manage workflows.

   Log in with a browser

   $ clay loginCopy

   Log in on a headless machine

   $ clay login --deviceCopy

   Confirm who you are logged in as

   $ clay whoamiCopy

3. 3.Pick the workspace to build in

   The workflow is created in your active workspace. Switch first if you belong to more than one.

   List workspaces

   $ clay workspaces listCopy

   Show the active workspace

   $ clay workspaces currentCopy

   Switch workspace

   $ clay workspaces switch <workspaceId>Copy

4. 4.Find your action keys

   Action package ids and keys are specific to your workspace. Save the catalog, search it for an email verifier, a Claygent or Use AI action, and your CRM update action, then paste their ids into the top of the script. Skip "clay workflows actions test": it spends credits.

   Save the action catalog

   $ clay workflows actions list > catalog.jsonCopy

   Search the catalog

   $ grep -Eio '"[^"]*(zerobounce|neverbounce|claygent|use ai|hubspot|salesforce)[^"]*"' catalog.json | sort -uCopy

   See an action's inputs and outputs

   $ clay workflows actions schema <packageId> <actionKey>Copy

5. 5.Export the records to clean

   Export contacts not updated in 90 days from HubSpot or Salesforce with the columns in the sample CSV. Start with a small export that includes a test record.

Part 2: Workflow spec

What the script builds: CRM hygiene agent.

1. 1

   Verify the email

   action

   Flags hard bounces, which often mean the person left the company.

   Reads

   email

   Writes

   email_status
2. 2

   Standardize title and fill firmographics

   action

   A Claygent or Use AI step maps free-text titles to fixed lists and fills a missing industry, with a confidence value.

   Reads

   titlecompanycompany_domainindustry

   Writes

   senioritydepartmentindustryconfidence

   Prompt

   Copy

   You clean CRM records. Given this contact and company: title: {{title}} company: {{company}} ({{company_domain}}) current industry: {{industry}} Return JSON with: - seniority: one of C-level, VP, Director, Manager, Individual contributor - department: one of Sales, Marketing, RevOps, Finance, Customer Success, Product, Engineering, Other - industry: the company's industry if current industry is empty, otherwise the current value - confidence: high, medium, or low for the whole record Use the company website for industry. If you are unsure, return low confidence and leave fields empty.
3. 3

   Update the CRM record

   action

   Writes high-confidence fixes and an "AI hygiene reviewed on" date back to the record.

   Reads

   crm_idsenioritydepartmentindustryemail_status

   Writes

   CRM response

   Verify in your workspace: Writing only high-confidence fields needs a run condition or field-level logic, which the CLI help does not document. Set it in the Clay UI, and do not map fields that would overwrite rep-entered data.

Part 3: Build script

Creates the workflow, trigger, and three steps, then pauses so you can map step inputs and the confidence rule. It validates the graph, offers one test run, and asks before publishing.

Save it as build-crm-hygiene.sh, fill in the 6 action ids at the top, then run bash build-crm-hygiene.sh.

1#!/usr/bin/env bash2# Builds the "CRM hygiene agent" Clay workflow3# in YOUR Clay workspace, using YOUR Clay CLI login.4# Written against Clay CLI v1.3.1. Not run or tested by GTM Playbooks.5# Lines tagged VERIFY use a shape the CLI help does not document.6set -euo pipefail7 8# Copy these from catalog.json (see "Find your action keys").9VERIFIER_PACKAGE_ID="" # Email verification (for example ZeroBounce)10VERIFIER_ACTION_KEY=""11AGENT_PACKAGE_ID=""    # Claygent or Use AI12AGENT_ACTION_KEY=""13CRM_PACKAGE_ID=""      # HubSpot or Salesforce: update record14CRM_ACTION_KEY=""15 16# One input to test before real traffic. Use yourself or a teammate.17TEST_ROW='{"crm_id":"","email":"","first_name":"","last_name":"","title":"","company":"","company_domain":""}'18 19for v in VERIFIER_PACKAGE_ID VERIFIER_ACTION_KEY AGENT_PACKAGE_ID AGENT_ACTION_KEY CRM_PACKAGE_ID CRM_ACTION_KEY; do20  [[ -n "${!v}" ]] || { echo "Set $v at the top of this script." >&2; exit 1; }21done22command -v clay > /dev/null || { echo "Clay CLI not found on PATH." >&2; exit 1; }23command -v jq > /dev/null || { echo "jq is required to read CLI output." >&2; exit 1; }24clay whoami > /dev/null || { echo "Not logged in. Run: clay login" >&2; exit 1; }25 26# VERIFY: only "workflows create" documents an "id" field in its output.27read_id() {28  local id29  id=$(jq -r '.id // empty' "$1")30  [[ -n "$id" ]] || { echo "No id found in $1. Open it and adjust read_id." >&2; exit 1; }31  echo "$id"32}33 34mkdir -p clay-crm-hygiene35cd clay-crm-hygiene36 37echo "1/7 Create the workflow"38clay workflows create --name "CRM hygiene agent" > workflow.json39WF_ID=$(read_id workflow.json)40WF_URL=$(jq -r '.url // empty' workflow.json)41 42echo "2/7 Add the CSV upload trigger"43# VERIFY: triggerType "csv_upload" is inferred; the help does not show it.44clay workflows triggers create "$WF_ID" --input '{"triggerType":"csv_upload"}' > trigger.json45TRG_ID=$(read_id trigger.json)46 47echo "3/7 Step 1: verify the email"48# VERIFY: help shows nodeType and name only; actionPackageId and actionKey are a guess.49STEP1=$(jq -nc --arg p "$VERIFIER_PACKAGE_ID" --arg k "$VERIFIER_ACTION_KEY" '{nodeType: "tool", name: "Verify the email", actionPackageId: $p, actionKey: $k}')50clay workflows nodes create "$WF_ID" --input "$STEP1" > step1.json51STEP1_ID=$(read_id step1.json)52 53echo "4/7 Step 2: standardize title and fill firmographics"54# VERIFY: action fields inside "step" are inferred from the documented utility example.55STEP2=$(jq -nc --arg n "$STEP1_ID" --arg p "$AGENT_PACKAGE_ID" --arg k "$AGENT_ACTION_KEY" '{target: {type: "after-node", nodeId: $n}, step: {kind: "action", actionPackageId: $p, actionKey: $k}}')56clay workflows nodes insert "$WF_ID" --input "$STEP2" > step2.json57STEP2_ID=$(read_id step2.json)58 59echo "5/7 Step 3: update the crm record"60# VERIFY: same inferred insert shape as step 2.61STEP3=$(jq -nc --arg n "$STEP2_ID" --arg p "$CRM_PACKAGE_ID" --arg k "$CRM_ACTION_KEY" '{target: {type: "after-node", nodeId: $n}, step: {kind: "action", actionPackageId: $p, actionKey: $k}}')62clay workflows nodes insert "$WF_ID" --input "$STEP3" > step3.json63clay workflows graph get "$WF_ID" --mode full > graph.json64 65echo "6/7 Map step inputs"66cat <<EOF67 68Step inputs are specific to your workspace. Map them before validating:69  Step 1 verify:  email70  Step 2 agent:   title, company, company_domain, industry, and the agent prompt71  Step 3 CRM:     crm_id plus only the fields step 2 returned with high confidence;72                  send low-confidence rows to a review list instead73Map them in the Clay UI${WF_URL:+ at $WF_URL}, or per node with:74  clay workflows nodes get $WF_ID <nodeId>75  clay workflows nodes update $WF_ID <nodeId> --input node.json76graph.json in this folder shows the current nodes and edges.77 78EOF79read -r -p "Press Enter when inputs are mapped. "80 81echo "7/7 Validate, test once, publish"82clay workflows graph validate "$WF_ID"83clay workflows diagram "$WF_ID"84 85if jq -e 'all(.[]; . != "")' <<< "$TEST_ROW" > /dev/null; then86  read -r -p "Run TEST_ROW once? It can spend Clay credits and update a CRM record. [y/N] " answer87  if [[ "$answer" == [yY] ]]; then88    clay workflows runs test "$WF_ID" --inputs "$TEST_ROW" > test-run.json89    echo "Saved test-run.json. Check each step with: clay workflows runs steps $WF_ID <runId>"90  fi91else92  echo "TEST_ROW is empty, skipping the test run."93fi94 95read -r -p "Publish the workflow now? [y/N] " answer96if [[ "$answer" == [yY] ]]; then97  clay workflows publish "$WF_ID" --name v198fi99 100echo "Workflow $WF_ID, CSV upload trigger $TRG_ID. All responses are saved in $(pwd)."

Part 4: CRM export CSV

Save this as clay-crm-hygiene/crm-export.csv and replace the sample row with your export. Keep the headers exactly as shown, because they become the trigger inputs.

1crm_id,email,first_name,last_name,title,company,company_domain,industry2your-test-record-id,jane@example.com,Jane,Doe,vp sales & ops,Example Co,example.com,

Part 5: Run it on your export

After publishing, upload the export to the trigger and start with a few rows. Each row is one run.

Verify in your workspace

The Clay CLI help does not document these details. Check each one before you rely on the build.

• The CSV trigger type "csv_upload" is inferred. If "triggers create" exits with code 2 (validation), check which trigger types your workspace accepts.
• The help documents "nodes create" with nodeType and name only. If it rejects actionPackageId and actionKey, create the node with a name only and pick the action in the Clay UI.
• The reference says action steps take actionPackageId and actionKey but shows only a utility example for "nodes insert", so the placement of those fields inside "step" is inferred.
• Only "workflows create" documents an id field in its response. The script reads .id from trigger and node responses too and stops if it is missing.
• Package ids and action keys differ by workspace and depend on which integrations you have connected. Copy them from your catalog; this page does not guess them.
• Step input mapping is dynamic per workspace. The CLI path is "nodes get" then "nodes update", where incomingEdges is a full replacement. The argument order for "nodes get" is inferred from "nodes update".
• The help does not say whether step 1 connects to the trigger automatically. "clay workflows graph validate" reports a disconnected graph.
• This build does not merge duplicates. Handle those separately before or after the hygiene run.
• "runs test" without --live is assumed to run the draft. The reference lists --live without describing it.
• Workflow runs can spend Clay credits and write to connected tools. Exit code 3 means re-run clay login, and exit code 4 means you are rate limited (wait for details.retryAfter).