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 /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 /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
​
companies
object[]

One to 20 companies, each with company_name, domain, linkedin_url, linkedin_numeric_id and linkedin_vanity_name as below. The response has one result per company, in order.

Required array length: 1 - 20 elements
​
company_name
string

Competitor company name. Required unless linkedin_url resolves to a company page.

Example:

"Globex Inc"

​
domain
string

Company domain. Recommended for accurate account matching.

Example:

"globex.com"

​
linkedin_url
string

LinkedIn company page URL.

Example:

"https://www.linkedin.com/company/globex"

​
linkedin_numeric_id
string

The company's LinkedIn numeric id: id from Search LinkedIn Companies, or numericId from Resolve LinkedIn Company. When set, Clustr takes this company page as resolved.

Example:

"1035"

​
linkedin_vanity_name
string

The company page's vanity name (linkedin.com/company/<vanity>): universalName from the same calls.

Example:

"globex"

​
website_url
string

The competitor's marketing website, e.g. https://www.globex.com. This is the site Clustr reads to find the competitor's customers (case studies, testimonials, logo walls). Defaults to https://<domain>.

Example:

"https://www.globex.com"

​
title_groups
enum<string>[]

The roles to follow at this competitor: sales, cs, exec (leadership), founder, customer_facing (solutions, partner, implementation) and custom. Used by the first search and every refresh. Leave it out to use your enabled job titles.

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

The people Preview Competitors listed, each with linkedin_id (the preview's public_identifier), name, title, function, photo_url and follow. Followed people are monitored up to your free slots, in this order, and the rest are Paused. Skipped people (follow: false) stay off the Team, even when a later search finds them. The first scan uses this list as the team; people missing from it arrive with the monthly refresh, for you to review. The list holds at most 500 people. Leave it out to follow everyone the first search finds, up to your free slots.

Maximum array length: 500

Response

Competitor registered

​
success
boolean
required
Example:

true

​
data
object
required