Skip to main content
POST
Derive a listener plan from a website

Authorizations

Authorization
string
header
required

A workspace API key, created in workspace settings and sent as Authorization: Bearer op_live_…. Session cookies are not accepted. Scopes: signals:read, accounts:read, listeners:read, listeners:analyse, pipeline:read, pipeline:write, collections:write, export:read.

Body

application/json

The wizard's step-1 answers. sources and objective decide the mode: find_local_prospects plans a places listener, find_dissatisfaction plans a rivals listener, and every other objective plans market.

companyName
string
required

The company's name.

Required string length: 2 - 120
website
string<uri>
required

The company's homepage. This is what gets crawled.

objective
enum<string>
required

What the listener is for. find_dissatisfaction returns a rival profile (competitor names, pain vocabulary); find_local_prospects returns a places profile (categories, locations); every other value, including custom, returns a market keyword plan.

Available options:
find_customers,
find_competitors,
find_partnerships,
find_dissatisfaction,
find_local_prospects,
custom
sources
enum<string>[]
required

Which platforms the resulting plan should carry queries for.

Minimum array length: 1

A platform.

Available options:
x,
linkedin,
facebook,
reddit,
hackernews,
linkedin_jobs,
indeed,
ashby,
greenhouse,
lever,
google_reviews,
g2,
trustpilot,
youtube,
vendor_community
customObjective
string

Free text describing the objective when objective is custom.

Maximum string length: 500
description
string

A short description of the business, used to plan when the site cannot be crawled. Required on the retry that follows a website_unreadable 422.

Maximum string length: 2000
acceptLimited
boolean
default:false

Set on a retry to proceed without a successful crawl, planning from description instead. Sending it true on the first call skips the crawl for no reason, since there is no description yet to plan from.

rivals
string[]

Competitors you already know about, read only when objective is find_dissatisfaction. The planner treats these as authoritative and fills in the ones it finds that you missed, which is the difference between a rival list you trust and one you have to check.

A competitor's name.

Maximum string length: 120

Response

A complete listener plan, generated and not applied — nothing is created here. crawlSource says whether this came from the site or from your description, which is worth recording: it later tells "this listener underperforms" apart from "this listener was built blind".

A complete listener plan derived from a website: everything the create call needs, with nothing applied yet. Edit it and pass the parts you want.

crawledUrl
string<uri>
required

The URL that was actually read, after redirects.

crawlSource
enum<string>
required

Which crawler produced the text. none is not a crawler — it records that no crawler could read the site and the plan came from description instead, which is what later tells "this listener underperforms" apart from "this listener was built blind".

Available options:
context,
firecrawl,
fallback,
none
pagesRead
string<uri>[]
required

Which pages the plan was generated from.

A URL.

plan
object
required

The search plan, plus what the crawl learned about the seller. The two halves answer the same question from opposite ends: the plan is what a buyer would say, the offering is what you would reply.

siteTitle
string

The site's own title, when it had one.

rivalProfile
object

Who else the market is paying, and what they say when it disappoints them. painVocabulary is separate from the plan's includeKeywords on purpose: a review reading "rude staff, an hour on hold" shares no keyword with "scheduling software", so the on-topic words for this mode have to be the words of the complaint rather than of the product.

placesProfile
object

Local prospecting: the businesses whose own reviews are read for evidence of the problem this product solves.