Resolving Topic-Intent Ids by Plain-Language Query with the Clay CLI

clay signals search-topics turns a plain-language description into the exact per-provider topic ids a PersonTopicIntent or CompanyTopicIntent signal's providerConfigs[].topicIds field takes. It is the only supported way to discover those ids from the CLI; there is no separate command that lists a provider's full topic catalog.

What you will build

A topic search scoped to companies, and the same search scoped to people, to show how --entity-type changes which providers can match at all.

clay signals search-topics --query "<text>" --entity-type company
clay signals search-topics --query "<text>" --entity-type person

AI Prompt

Using the Clay CLI, resolve topic ids for both a company-scoped and a person-scoped
topic-intent signal from the same plain-language query.

Requirements:
- `clay signals search-topics --query "<text>" --entity-type company|person`.
- Each result names one topic with its best match score, and a matches object holding
  that topic's id in each of delivr, intentsify, and bombora, where that provider has an
  equivalent. An empty array under a provider means it has no equivalent for that topic.
- --entity-type person always returns empty bombora matches, because bombora is
  company-only.
- bombora ids are the literal topic name; delivr and intentsify ids are opaque strings and
  must only be used in a providerConfig for that same provider.
- 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)

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. Search scoped to companies

clay signals search-topics --query "cloud migration" --entity-type company

Real output, trimmed to the top match:

{
  "data": [
    {
      "name": "Cloud Migration",
      "score": 0.668,
      "matchType": "exact",
      "matches": {
        "delivr": [
          { "id": "4eyes_119434", "name": "Cloud Migration" },
          { "id": "4eyes_121350", "name": "Software Migration" }
        ],
        "intentsify": [
          { "id": "18010", "name": "Cloud Migration Services Providers" },
          { "id": "6178", "name": "Cloud Migration" }
        ],
        "bombora": []
      }
    }
  ]
}

bombora is empty here even on a company-scoped query, because this particular topic simply has no Bombora equivalent, not because of the entity-type restriction.

2. Search the same query scoped to people

clay signals search-topics --query "cloud migration" --entity-type person

Real output, trimmed:

{
  "data": [
    {
      "name": "Server Migration",
      "score": 0.6763,
      "matchType": "semantic",
      "matches": {
        "delivr": [{ "id": "4eyes_121213", "name": "Server Migration" }],
        "intentsify": [{ "id": "8598", "name": "Server Migration" }],
        "bombora": []
      }
    }
  ]
}

Every result under --entity-type person reports an empty bombora array unconditionally, since Bombora only supports company-level intent regardless of the topic searched.

Verify the result

clay signals search-topics --query "<any text>" --entity-type person

Expected: every entry in data[].matches.bombora is an empty array.

How it works

The search ranks topics by relevance to the plain-language query (matchType is "exact" for a literal name match and "semantic" otherwise) and reports, per result, whichever id each of the three providers uses for that same concept. Because a signal's providerConfigs[].topicIds takes provider-specific ids, this command is the bridge between a human-readable topic and the exact value each provider config needs, without requiring a separate lookup per provider.

Common issues

Copying an id into the wrong provider's config

An id from matches.intentsify is meaningless inside a bombora providerConfig, and vice versa. bombora's own ids are literal topic names rather than opaque strings, which makes a mismatched copy easy to catch by inspection, but delivr and intentsify ids are both opaque and look interchangeable at a glance.

An empty matches array for one provider does not mean the query failed

It means that specific provider has no equivalent topic, which is common and expected. Check matchType and score on the result itself to judge whether the search found a good match at all before concluding a particular provider lacks coverage.

Next steps

• How Topic-Intent Signals Are Billed
• Provider Rules on Topic-Intent Signals

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay signals search-topics --query \"<text>\" --entity-type person"
  expected_result: "Every result's matches.bombora array is empty, regardless of the query."

Related Articles

• How Topic-Intent Signals Are Billed with the Clay CLI
• Creating a Topic-Intent Signal with the Clay CLI
• Watching People for Topic Intent with the Clay CLI