docs(audiences): add FAQ for HubSpot deal stage filter requiring internal ID

[george-dilthey]

What changed

Added a new FAQ to docs/audiences.md: "Why does my HubSpot deal Stage filter return no results in a Companies audience?" — explaining that the Stage filter requires HubSpot's internal stage ID value (not the human-readable display name), with step-by-step instructions for finding the internal ID in HubSpot.

Why

A customer (Patrick Trost, Juicebox) could not filter their Companies audience by "Closed Won" HubSpot deal stage. They noticed "Closed Lost" worked when entering closedlost, but "Closed Won" — which in their custom pipeline uses a numeric internal ID — did not respond to "closed", "won", or "closedwon". The support agent (Bo) identified the root cause: Clay stores the raw HubSpot dealstage internal ID, not the display label. The workaround (look up the internal ID in HubSpot Settings → Objects → Deals → Pipelines) was confirmed working by the customer.

The docs had no mention of this behavior. The existing hubspot-integration-overview.md documents lifecycle stage internal codes in Clay tables, but nothing covers the deal Stage filter in Audiences.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475621643351
• Slack trigger thread: https://clay-hq.slack.com/archives/C0BP6KUTYSH/p1787358696204259?thread_ts=1787358696.204259&cid=C0BP6KUTYSH
• Support agent workaround (Bo's reply): https://clay-hq.slack.com/archives/C0BP6KUTYSH/p1787598363509389?thread_ts=1787358696.204259&cid=C0BP6KUTYSH
• Docsbot Verifier sub-agent verdict: PASS — the verifier sub-agent confirmed the claim against real code in both repos. File:line citations from the verifier:
  • clay-base/apps/frontend/src/components/Sources/types/action/registry/HubspotSources.ts:118 — 'Deal Stage': { path: ['properties.dealstage'], type: DataType.TEXT, filter: dealFilter } — the Audiences filter maps directly to HubSpot's raw dealstage property (the internal ID string), with no label resolution.
  • clay-base/services/big-source-sync/src/services/domain/hubspot/hubspot-crm-export-utils.ts:189–228 — buildHubspotCsvRowTransform casts booleans and numbers but does not transform dealstage — it is stored verbatim as-is from HubSpot.
  • clay-base/services/audiences/src/utils/field-mapping-helpers.ts:120–121 — For HubSpot imports, fieldId = mapping.hubspotFieldId reads the raw source field directly, confirming no label translation on the Audiences import path.
  • public-actions/apps/hubspot-new-ui/actions/utils.ts:379–384 — The regular Clay table enrichment path DOES add dealstageLabel by resolving the pipeline stage display name. The Audiences big-source-sync path has no equivalent — confirming the gap is real.
• Verifier Slack context: No discrepancy. The Jan 2025 Slack announcement (Eric Engoron, #all-product-progress) confirmed readable labels were added to HubSpot deal enrichment action results in Clay tables (dealstageLabel) — but the verifier confirmed this does not apply to the Audiences filter path.

Uncertainties

None — the Docsbot Verifier sub-agent returned PASS. The customer confirmed the workaround worked. The HubSpot Deals in Audiences feature is gated (early access), consistent with the existing note in the doc.

Related observations

• hubspot-integration-overview.md already has a FAQ about lifecycle stage internal codes (general case for Clay tables). No change needed there — this is an Audiences-specific issue.
• Screenshots from the customer confirm the filter accepts free-text input (not a dropdown), consistent with the internal ID requirement.

Closes DOC-2042

[linear-code]

DOC-2042