Workflows Audience Enrichment

Build an audience enrichment workflow

Use this skill for an existing audience_enrichment workflow or an explicitly requested Audience-backed bulk enrichment migration. It owns the workflow-specific sequence: build enrichment steps, ensure the shared final Audiences writeback, and map enrichment results onto audience fields.

Read the complete workflows and audiences skills first. Read /workflows-discover-actions when choosing provider actions, and read the workflows skill's audiences.md before mapping the writeback.

Verify the workflow type

Start every task with:

bashCopy code
clay workflows get <workflowId>

Continue when .type is exactly audience_enrichment. For a regular workflow (null or absent type), convert only as part of an authorized Audience bulk enrichment migration, using the procedure below. For other tasks or workflow types, return to /workflows. Never convert or reclassify a workflow implicitly.

Plan the enrichment

Read the full graph and identify the audience trigger, existing enrichment steps, and current writeback node. Resolve the following from the workflow and user instructions, asking only where a choice remains:

• which audience fields should be populated
• whether the workflow should enrich people or companies
• whether the requested fields are actually missing or sparse
• the action or function to use when the workspace catalog offers consequential alternatives
• the audience size before testing or publishing

Use the audiences skill to inspect field fill rates and count matching records. Prefer direct enrichment actions for provider data, Clay functions for reusable workspace logic, agents for unstructured research or classification, conditionals for eligibility and fallbacks, and code for deterministic transformations.

Map unambiguous existing fields without asking whether to use them or create new ones. A request to update a field does not need another confirmation because it may already have values; do not add a fill-blanks-only restriction unless requested. For ambiguous mappings, offer plausible fields and a new-field option. Create needed fields without asking permission, following the workflows skill's audiences.md. Reuse field choices already made.

Present a short plan and get approval before editing the graph unless the user already authorized the edits. Get separate approval before publishing. Testing must be within the authorized scope; follow the shared policy in workflows-discover-actions/cost-and-budget.md for cost disclosure and significant-spend confirmation.

Build the enrichment path

Migrating an Audience bulk enrichment table

If the destination is a regular workflow, convert it with clay workflows update <workflowId> --type audience_enrichment once the user has authorized the migration. Then create draft Audience triggers matching the table's source segments and entity type. Conversion alone does not create triggers or run enrichment.

Read the table's full column settings and the destination trigger's output schema before creating nodes. Preserve the table's enrichment behavior while using the existing audience trigger as the source of the original record ID and fields:

• Replace a lookup that only reloads the triggering Audience record, and columns that only extract its fields, with direct trigger bindings. Keep formulas that transform those fields.
• Only carry over a related-company lookup when a downstream enrichment or writeback uses its output and that value is not already available from the trigger. Preserve user lookups that retrieve different records or implement additional filtering.
• Pin each required value on the consuming code or tool node using an inputSchema property with the trigger's sourceNodeId and the exact sourcePath from its output schema. For example, a trigger exposing fields.Name supplies sourcePath: "$.fields.Name"; this may differ from the Audience field ID name. A nested expression like {{fields.id}} does not replace an explicit upstream binding. Read /workflows's data-passing.md for the writable shape.
• In code, read the pinned input by its property name with context.get_input. On the final writeback, pin the original record ID from the trigger and the transformed value from the enrichment node, then reference those input names in inputMappingConfig. Read each node back and confirm its source bindings survived before running.

Use the shared writeback procedure below for the table's final Audience update. Do not copy the table's source-record lookup or legacy writeback action into a separate update path.

Build from the existing audience trigger. Preserve the trigger and any existing upsert-audiences-record node.

Use clay workflows actions list and clay workflows actions schema to choose and configure each enrichment. Never guess action input names, output paths, credentials, or provider availability. Put cheap eligibility checks before paid actions. When an enrichment can miss, use the user's chosen fallback or conditional path rather than silently writing a blank value.

Use the general workflows skill for node creation, insertion, data passing, and branch wiring. Do not manually create or reconnect the final audience writeback while building intermediate steps.

Ensure and configure the final writeback

After the enrichment graph is structurally complete, run:

bashCopy code
clay workflows ensure-audience-writeback <workflowId>

This command calls the same server-side helper as the audience enrichment editor. It creates or reuses exactly one upsert-audiences-record node, validates its entity type, and reconnects every eligible terminal route. Do not reproduce that topology change with manual node or edge edits.

Read the returned node before updating it. Preserve its tool identity and static entityType, then configure its inputMappingConfig with clay workflows nodes update using the writable shape from clay workflows nodes get.

Discover destination fields with:

bashCopy code
clay audiences fields list --entity-type people
clay audiences fields list --entity-type companies

Follow the workflows skill's audiences.md for the complete mapping shape. In particular:

• set lookupFields|selectedLookupFields to the static array ["id"]
• bind lookupFields|id to the audience trigger record id: use $.fields.id when the trigger output schema contains a fields object, otherwise use $.id; inspect the trigger output schema and never guess the path
• do not replace the record-id lookup with email, LinkedIn URL, phone, or domain; those aliases are for generic or net-new audience upserts where an existing audience record id is unavailable
• include every destination id in recordFields|selectedRecordFields and provide its matching recordFields|<id> binding
• set recordFields|removeNullValues to true unless the user explicitly wants blanks to clear existing values
• bind enrichment outputs from their declared $.result.<outputPath> paths; never invent paths

Read the writeback node again after updating it and confirm the mappings persisted.

Validate, test, and publish

Finish an audience enrichment workflow in this order:

1. Run clay workflows ensure-audience-writeback <workflowId>, read the returned node, and confirm its mappings persisted.

2. Validate the graph with the available workflow tools and show the resulting diagram.

3. Resolve the segment id from the workflow's existing audience_segment trigger. Do not search for audience entities or records to decide what to publish or run. If the workflow has no audience_segment trigger, stop this completion sequence and use the general workflows testing guidance; do not alter its triggers.

4. Explain the likely credit exposure and get approval for a credit-consuming test.

5. Test 10 segment records from the current draft by default:

   bashCopy code
   clay workflows runs test <workflowId> --audience-segment <segmentId> --limit 10
   

   Use a different limit only when the user requests or approves it.

6. Wait for the run to finish. Inspect both the enrichment output and the final Audiences update. If mappings need correction, correct and validate them, then return to step 4 and get renewed approval before another credit-consuming test.

7. Get separate approval, then publish the tested draft with clay workflows publish <workflowId>.

When the user asks to publish and run an audience_segment workflow, publish first, then test 10 records from the version just published with --audience-segment <segmentId> --limit 10 --live. Do not substitute an entity lookup, a record search, or a plain manual run for the requested segment run. Later edits remain draft-only until the workflow is published again.