Clay icon

Clay

Interact with Clay data enrichment platform
Join our community

Actions5

Overview

The "Update Record (Upsert)" operation in the Clay node allows you to create or update a record in a specified Clay table using Clay's auto-deduplication feature. This means if a record with the unique identifier already exists, it will be updated; otherwise, a new record will be created. This operation is particularly useful for maintaining clean and up-to-date datasets without duplicates.

Common scenarios include:

  • Synchronizing contact or company data from external sources into Clay tables.
  • Automatically updating records when new information arrives while preventing duplicate entries.
  • Integrating CRM or marketing automation tools with Clay to keep enriched data current.

For example, you might use this operation to upsert a contact by their email address, ensuring that if the contact exists, their details are updated, or else a new contact is added.

Properties

Name Meaning
Workspace Select your Clay workspace or enter its ID manually. The workspace contains the target table.
Workspace ID (manual) Manually enter the Clay workspace ID if not selecting from the list.
Table Select your Clay table within the workspace or enter its ID manually. This is where the record will be upserted.
Table ID (manual) Manually enter the Clay table ID if not selecting from the list.
Webhook URL The Clay webhook URL for the target table, obtained from the Clay table settings. This URL is used to send record data for creation or update.
Unique Identifier Field The field name used as the unique identifier for deduplication (e.g., Email, LinkedIn URL, Company Domain). This field must be included in the record data to enable auto-deduplication during update operations.
Important Note A warning notice that Clay's auto-dedupe feature must be enabled on the table with the specified unique identifier field.
Field Mapping Mode How to specify the fields for the record: either manual mapping of individual fields or providing all fields as a JSON object.
Fields When using manual mapping mode, specify one or more fields with exact Clay table column names and their corresponding values to set in the record.
Fields (JSON) When using JSON mode, provide all fields as a JSON object with keys matching Clay table column names exactly.

Output

The output JSON contains the result of the upsert operation:

  • success: Boolean indicating if the operation was successful.
  • message: A descriptive message about the operation outcome.
  • operation: The performed operation name (updateRecord).
  • data: The record data sent to Clay.
  • timestamp: ISO timestamp of when the operation occurred.
  • note (only for updateRecord): Indicates that the record was sent with auto-dedupe and may have been deduplicated rather than updated.

Example output JSON snippet:

{
  "success": true,
  "message": "Record updated/created successfully in Clay table",
  "operation": "updateRecord",
  "data": {
    "Email": "john.doe@example.com",
    "First Name": "John",
    "Last Name": "Doe"
  },
  "timestamp": "2024-06-01T12:00:00.000Z",
  "note": "Record was sent to Clay with auto-dedupe. If a matching record exists, it may have been deduplicated rather than updated."
}

No binary data output is involved in this operation.

Dependencies

  • Requires a valid Clay webhook URL configured for the target table.
  • Requires an API authentication token credential configured in n8n to authorize requests to Clay.
  • The Clay table must have the auto-dedupe feature enabled with the specified unique identifier field.
  • Proper workspace and table IDs must be provided or selected.

Troubleshooting

  • Invalid Clay webhook URL format: The webhook URL must match the expected pattern starting with https://api.clay.com/v3/sources/webhook/pull-in-data-from-a-webhook-. Verify the URL copied from Clay table settings.
  • Missing unique identifier field in record data: For update operations, the unique identifier field must be present in the fields sent. Ensure the field name matches exactly and is included.
  • No fields specified error: At least one field must be provided for the record creation or update. Check that fields are correctly mapped or JSON is valid.
  • Invalid JSON in Fields (JSON): If using JSON mode, ensure the JSON syntax is correct and keys match Clay table columns exactly.
  • Failed to update/create record: Could indicate network issues, invalid webhook URL, or insufficient permissions. Verify connectivity and credentials.
  • Auto-dedupe not working as expected: Confirm that the Clay table has auto-dedupe enabled and the unique identifier field is properly configured in Clay.

Links and References

Discussion