docs(audiences): add FAQ for finding Clay Company ID; fix broken Account IDs path

[george-dilthey]

What changed

Added a new FAQ section to docs/audiences.md — "How do I find the Clay Company ID for a company in Audiences?" — documenting two methods: (1) clicking a linked company chip on a person record and reading the numeric ID from the browser URL, and (2) using Lookup in Audiences on a Companies audience filtered by domain to retrieve the Company ID for use in Upsert Audiences Record's optional Associate company ID field.

Also corrected the existing "How do I access Account-level fields from a People audience?" FAQ, which previously described a non-existent UI navigation path ("Records → Related IDs → Account IDs" in the person record panel). Verification confirmed that path does not exist in the product. Replaced step 1 with the correct approach: a People Lookup in Audiences filtered by Email, whose result includes the Account IDs field (the Clay Company ID). Also updated the Salesforce Leads note to remove the reference to the same non-existent path.

Why

Intercom conversation #215475741728136: customer Akash Radadiya asked "how do i find the audiences company id?" Fin gave the customer instructions to navigate to "Records → Related IDs → Account IDs" — a path that does not exist in the product UI. The customer confirmed repeatedly that the section was not visible. A human support agent (Andrés Franco) escalated and gave the correct answer: click the company chip on a person record to open the company record, and read the Company ID from the URL. He also explained how to use "Lookup in Audiences" on a Companies audience to retrieve the Company ID for use in "Create or Update Audiences Record."

The verifier sub-agent confirmed:

• Company chip → URL method: PASS — code in PeopleRecordDetailView.tsx navigates to /workspaces/{id}/companies/{companyId} when a company chip is clicked; the integer is the Audiences internal Company ID.
• Lookup in Audiences by domain returns Company ID: PASS — lookupInAudiences action returns fields.id (the Company ID) in results (audience-record-source.ts:345).
• "Records → Related IDs → Account IDs" UI path: FAIL — thoroughly reviewed all Audiences entity detail components; this UI section does not exist in the person record panel. The related_ids.account_ids data is available in Lookup in Audiences action results but is not surfaced as a navigable UI path in the record panel.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475741728136
• Verifier: PASS on company chip URL method (PeopleRecordDetailView.tsx navigation logic); PASS on Lookup in Audiences domain filter returning Company ID (lookupInAudiences/index.ts, audience-record-source.ts:345); FAIL on "Records → Related IDs → Account IDs" UI path (not found in any Audiences entity detail component).

Uncertainties

None. The new FAQ content is verified PASS. The existing FAQ correction is based on a verifier FAIL finding confirmed by code review of all Audiences entity detail components.

Related observations

• The verifier noted a Slack report from #team-workflows (2026-07-20) stating "Lookup in Audiences simply does not run in workflows (Terracotta context)." The new FAQ refers to "in your table" which is accurate for table action cells. A separate doc update for this limitation in the Workflows context would be warranted if/when that bug is resolved.
• Several other open PRs touch docs/audiences.md — PRs docs(audiences): document Salesforce export full-load behavior, API monitoring, and Last Enriched timestamp #2356, docs(audiences): add FAQ for moving audience segments between workspaces #2370, docs(audiences): replace non-existent Continue button with Upsert segment record instructions #2383, docs(audiences): document ad sync beta availability and per-workspace connections #2395, docs(audiences): document enrichment workflow beta option #2415, docs(audiences): note that company fields don't carry through Find People to People records #2432, docs(audiences): clarify Snowflake workflow trigger and add test-workspace note #2478, docs(audiences): document BigQuery SQL query edit behavior and [DELETED] source cleanup #2500, docs(audiences): add FAQ for same-domain company accounts and parent/child relationships #2504, docs(audiences): add FAQ for syncing a specific HubSpot contact list to Clay Ads #2511, docs(audiences): note Add to workbook option requires support enablement #2513 — none address the Company ID topic or the broken Related IDs path. A reviewer should reconcile these at merge time.

Closes DOC-2313

[linear-code]

DOC-2313