Skip to main content
POST
Register one competitor, or several at once with companies. Requires the competitor-monitoring entitlement (403 when the feature is off). You can register any number of competitors. Slots count people: when a new competitor’s first team search runs, the Sales and CS people it finds are monitored up to your free slots, highest ranked first, and the rest are added Paused (no slot). Preview Competitors tells you beforehand how many people each company has and how many slots that takes. A company that is already one of your competitors is refused with 409 COMPETITOR_EXISTS, and the message ends with the existing competitor’s id. In the companies form its result has status: "exists" and existing_competitor_id. If the team search finds nobody, the competitor is still created with an empty team; add people by URL. Pick the company first with Search LinkedIn Companies and pass its linkedin_numeric_id and linkedin_vanity_name. A linkedin_url sent without them is looked up here, and one that names no LinkedIn company page is refused with 422 COMPANY_NOT_RESOLVED: monitoring a page that does not resolve finds nobody.
Registering starts the competitor’s first scan. After that, the schedule runs it every two weeks, and POST /v2/competitor_monitoring/run runs one now.The scan starts in the background, so the response comes back immediately with the created competitor. Watch it with GET /v2/competitor_runs. If the scan fails to start the competitor still exists and the scheduled run picks it up. With companies, every created competitor gets its own first scan.
Send one company with the fields below, or several with companies.

Authorizations

Authorization
string
header
required

The API key you created on the API settings page of the Clustr app.

Body

application/json

Either the single form (company_name and the fields beside it) or companies, a list of 1 to 20 companies in the same shape. company_name is required in the single form unless linkedin_url resolves to a company page.

companies
object[]

Several competitors at once. The answer lists one result per company.

Required array length: 1 - 20 elements
company_name
string
domain
string
linkedin_url
string

The competitor's LinkedIn company page. Without linkedin_numeric_id it is resolved on registration, and one that names no company page is refused with 422 COMPANY_NOT_RESOLVED.

linkedin_numeric_id
string

The company's LinkedIn numeric id, as GET .../linkedin/companies/resolve returns it. When set the page is trusted as already resolved.

linkedin_vanity_name
string

The company page's vanity name (linkedin.com/company/).

website_url
string

The competitor's marketing website, the site its customers are found on. https:// when omitted. A public http(s) URL, else 400 INVALID_WEBSITE_URL.

title_groups
enum<string>[]

The role groups to follow at this competitor, on the first search and each refresh. Omitted or empty: your enabled job titles.

Available options:
sales,
cs,
exec,
founder,
customer_facing,
custom
people
object[]

The people the preview listed, each followed or skipped. Followed people are monitored up to the free slots, in this order, the rest paused; skipped people are never added by a later search. Omitted: the first search follows everyone it finds up to the free slots.

Maximum array length: 500

Response

Competitors' answer, relayed; each new competitor's first scan then starts in the background. Single form: data.competitor and data.slot_usage. Bulk form: data.competitors (the ones created), data.results (one per company, in order) and data.slot_usage.

success
boolean
required
data
object
required