docs(audiences): add FAQ for syncing a specific HubSpot contact list to Clay Ads

[george-dilthey]

What changed

Added a new FAQ entry to docs/audiences.md — "How do I sync a specific HubSpot contact list to a Clay Ads audience?" — describing the 6-step workaround: confirm the list in HubSpot → import it into a Clay table using Import objects from HubSpot with the specific list selected → optionally tag rows for easy segment filtering → add Upsert Audiences Record to push rows into Audiences → create a People segment → go to Ads and create an ad sync from that segment.

Why

Intercom conversation #215475727322956: Danielle Boone (Balto Software) asked "We want to create a segment to sync in Clay Ads for a specific HubSpot contact list. When we try to build the segment however, we are not seeing how to filter the import from HubSpot to only this specific list of people. Instead, we only see the option to import all contacts from the CRM (700k+), which we don't want to do."

Fin did not respond — the question was escalated to human support. Ryan Phung (Clay support) provided the correct 6-step workaround. audiences.md already documented that HubSpot imports all contacts with no list filtering, and a partial workaround (table → Upsert Audiences Record) buried in a "plan limit" FAQ. But no FAQ existed for the specific Clay Ads use case in the customer's vocabulary — so Fin had no relevant content to surface.

The existing "My HubSpot has more records than my plan limit" FAQ stops at step 4 (Upsert Audiences Record) and doesn't continue to the segment creation and ad sync steps. This new FAQ covers the complete end-to-end workflow.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/apps/w28k1kwz/conversations/215475727322956
• Verifier evidence (Claim 1 — PASS): HubSpot Audiences connector confirms no list filtering — AudiencesSettings/AudienceHubSpotSettings.tsx:108 explicitly filters out HubSpotImportKind.List imports. Table-side workaround confirmed: hubspot-crm-objects-source action code accepts listId parameter at public-actions/apps/hubspot-new-ui/actions/hubspot-crm-objects-source/action-code.ts:44.
• Verifier evidence (Claim 2 — INTERNAL): Native HubSpot list filtering in Audiences has backend API built (audiences-imports.endpoints.ts:851–950) but NO frontend UI — backend only as of DB migration 20260824120000-add-hubspot-list-audience-import-uniqueness.js. Slack Aug 12 2026 (#proj-audience-import-export): "I am starting to work on Hubspot List import" — dev work just beginning, not GA. Not documented.

Uncertainties

pre_pr_check returned ok=false due to 12 concurrent open PRs on audiences.md — this is a popular file. I reviewed all 12 PRs flagged and confirmed none of them add this specific FAQ or cover the HubSpot list → Clay Ads workflow. The materiality judgment is documented in Related observations below. The tool cannot clear the flag because audiences.md always has concurrent edits; the underlying change is verified and material.

Related observations

Reviewed all 12 open PRs on audiences.md flagged by pre_pr_check — none cover the specific "HubSpot contact list → Clay Ads" end-to-end workflow:

• PR docs(audiences): document ad sync beta availability and per-workspace connections #2395 adds an ad sync plan availability note — does not cover HubSpot list import path.
• PR docs(audiences): replace non-existent Continue button with Upsert segment record instructions #2383 mentions Upsert segment record in passing — does not cover the HubSpot-specific workflow or Clay Ads destination.
• PRs docs(audiences): add FAQ for same-domain company accounts and parent/child relationships #2504, docs(audiences): document BigQuery SQL query edit behavior and [DELETED] source cleanup #2500, docs(audiences): clarify Snowflake workflow trigger and add test-workspace note #2478, docs(audiences): note that company fields don't carry through Find People to People records #2432, docs(audiences): document enrichment workflow beta option #2415, docs(audiences): add FAQ for moving audience segments between workspaces #2370, docs(audiences): document Salesforce export full-load behavior, API monitoring, and Last Enriched timestamp #2356, docs(audiences): document that Lookup in Audiences cannot scope to a segment, add workaround FAQ #2354, docs(audiences): document OR filter group with AND exclusion pattern #2349, docs(audiences): add archive cross-reference for Salesforce-deleted records #2348, docs(audiences): clarify legacy plan access and add why-not-visible FAQ #2345 address unrelated topics (Salesforce sync, BigQuery editing, Snowflake, filter logic, plan tiers, etc.).
• PR docs(clay-ads): add FAQ for sending a Find People workbook list to an ad platform #2363 (on clay-ads.md) covers "I built a people list in a Clay workbook, how do I send it to ads?" — different starting point (Find People workbook, not HubSpot list). Reviewers may want to check for cross-referencing opportunities between that FAQ and this one.
• An internal Slack note in the Intercom ticket mentioned "the PR is already in works to do this natively in audience without creating a table first" — verifier confirmed this is INTERNAL (backend only, no frontend UI, active dev as of Aug 12). Not documented — when it ships, a separate PR should add the native path.

Closes DOC-2294

[linear-code]

DOC-2294