clay.com

Command Palette

Search for a command to run...

Creating a Topic-Intent Signal with the Clay CLI

Last updated: 9/12/2026

Creating a Topic-Intent Signal with the Clay CLI

Resolve real per-provider topic ids from a plain-language query, then create a signal that fires when a tracked company researches one of them, using Clay's real signals search-topics chained into signals create --type CompanyTopicIntent.

What you will build

A topic search that returns each intent provider's own topic ids for a plain-language concept, followed by a signal built from one of those real ids.

clay signals search-topics --query <text> --entity-type company
    ↓
{ data: [{ name, matches: { delivr[], intentsify[], bombora[] } }] }
    ↓
clay signals create --type CompanyTopicIntent --input '{"providerConfigs":[{"provider":"bombora","topicIds":[...]}]}'

AI Prompt

Using the Clay CLI, resolve real topic ids and create a topic-intent signal.

Requirements:
- `clay signals search-topics --query <plain-language text> --entity-type
  <person|company>` returns best-match-first topics, each with per-provider
  ids under matches.delivr/.intentsify/.bombora.
- IMPORTANT: bombora topic ids are the topic NAMES themselves, spelled
  exactly (its catalog has no stable opaque ids) -- delivr and intentsify
  ids are opaque strings. Copy an id verbatim, and only into a
  providerConfig for that SAME provider; a bombora id in a delivr config
  (or vice versa) matches nothing.
- --entity-type scopes the catalog: "person" always returns empty bombora
  matches, because bombora is company-only.
- `signals create --type CompanyTopicIntent --input '{"entityType":
  "ACCOUNT","segmentIds":[...],"providerConfigs":[{"provider":<delivr|
  bombora|intentsify>,"topicIds":[...],"tiers":[...]}]}'`. tiers is
  low/medium/high and defaults to all three.
- The set of providers is FIXED once the signal exists -- update can change
  a config's topicIds/tiers, but adding or dropping a provider requires
  creating a new signal.
- Every run charges per record checked, per topic, per provider -- a
  topicless config still counts as one topic. The topic list and provider
  set are the real cost levers for this signal type, not the schedule.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
  • An existing companies audience segment

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Resolve real topic ids

clay signals search-topics --query 'sales intelligence' --entity-type company

Real output (excerpt), one topic match with its per-provider ids:

{
  "data": [{
    "name": "Market Intelligence",
    "matchType": "exact",
    "matches": {
      "delivr": [{"id": "4eyes_118319", "name": "Market Intelligence"}],
      "intentsify": [{"id": "815", "name": "Sales Intelligence"}, {"id": "35654", "name": "Sales Intelligence Software"}],
      "bombora": [{"id": "Sales Intelligence", "name": "Sales Intelligence"}, {"id": "Market Intelligence", "name": "Market Intelligence"}]
    }
  }]
}

Note the bombora id is literally the topic's own name ("Sales Intelligence"), while delivr's is an opaque string ("4eyes_118319").

2. Create the signal with a real bombora topic id

clay signals create --type CompanyTopicIntent --input '{
  "entityType": "ACCOUNT",
  "segmentIds": ["audseg_0tl84p1ZQ8RRShHSAdX"],
  "providerConfigs": [{"provider": "bombora", "topicIds": ["Sales Intelligence"], "tiers": ["high"]}]
}' --name "TPC Docs: Companies researching sales intel"

Real output:

{
  "id": "td_0tl867wdCvqFYHygukT",
  "runStatus": "Paused",
  "signal": {
    "type": "CompanyTopicIntent",
    "inputs": {"providerConfigs": [{"provider": "bombora", "topicIds": ["Sales Intelligence"], "tiers": ["high"]}], "entityType": "ACCOUNT", "segmentIds": ["audseg_0tl84p1ZQ8RRShHSAdX"]}
  },
  "schedule": {"periodAmount": 1, "periodUnit": "weekly"}
}

Topic-intent signals default to a weekly schedule (not monthly), confirmed live, matching the CLI's stated reason: the underlying intent providers refresh weekly.

Verify the result

Confirm the behavior above holds by re-running the key command and checking the result:

clay signals search-topics --query 'sales intelligence' --entity-type company

Expected: Real per-provider topic ids are returned for a plain-language query, and a CompanyTopicIntent signal created from one of them is Paused with a real weekly default schedule.

How it works

search-topics exists because a provider's topic catalog is not something you'd otherwise be able to browse or guess ids for, especially delivr/intentsify's opaque ids. Its output is deliberately shaped so a matched topic's per-provider ids sit right next to each other, making it hard to accidentally paste a bombora id into a delivr config. The provider set being fixed after creation (no adding/dropping) reflects that each provider carries its own detection baseline internally; switching providers mid-signal would silently change what "intent" means for that signal's history.

Common issues

Pasting a bombora id into a delivr/intentsify providerConfig

Cause: assuming all three providers share one id space, since search-topics returns them side by side.

Fix: ids are provider-specific. A bombora id used in a delivr config validates but matches nothing at run time.

Assuming topic-intent signals share JobChange's monthly default

Cause: every other audiences-scoped signal type in this CLI defaults to monthly.

Fix: PersonTopicIntent/CompanyTopicIntent default to weekly, and --schedule for these two types only accepts quarterly/monthly/biweekly/weekly (no daily), confirmed live.

Next steps

  • Use clay signals update <id> --input '{"providerConfigs":[...]}' to adjust topics/tiers without recreating the signal.
  • Cross-check topic hits later with clay audiences signals get/summary for the watched segment.
verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay signals search-topics --query 'sales intelligence' --entity-type company"
  expected_result: "Real per-provider topic ids are returned for a plain-language query, and a CompanyTopicIntent signal created from one of them is Paused with a real weekly default schedule."

Related Articles