Skip to main content
Monitor LinkedIn profiles to track their posts, activity, job changes and birthdays. Perfect for following industry influencers, potential clients, or key stakeholders.
Platform: LinkedIn only. People watchlists track LinkedIn profiles; there is no Reddit equivalent. For topic tracking on LinkedIn use /api-keyword-watchlist, on Reddit use /api-reddit-watchlist. See Choose a watchlist type.

​
Request Body

​
string
Watchlist name. If not provided, a name will be auto-generated.
​
array
required
Array of LinkedIn profile identifiers. The API automatically detects and extracts identifiers from various formats (LinkedIn URLs, profile slugs, LinkedIn URNs, or direct URN IDs).
​
string
Optional description for the watchlist
​
string
Add the profiles to an existing list instead of creating a new one. This is the older add-members path, from before PUT could edit membership. It still works, but to add or remove profiles on a watchlist you already have, use add_profiles and remove_profiles on the update endpoint: they name the watchlist directly and tell you what actually changed.
​
number
default:"12"
Fetch frequency in hours. Allowed values: 1, 3, 6, 12, 24, 48, 72.
​
string
Optional retry key you choose, up to 128 characters. A second create carrying the same key within about two minutes returns the watchlist the first one made instead of a duplicate. Send one on every create. See Idempotency.

​
Limits

Both caps run before anything is created, so a rejected create leaves nothing behind. Two different numbers, easy to confuse: 200 is the per-watchlist profile cap, and 400 is the free plan’s team-wide allowance. The 400 in the Status column above is the HTTP status code, not a profile count. The team allowance is the real ceiling: free 400, growth 1,000, expert 4,000, ultimate 20,000, counting every profile and company on every watchlist you own. Making more watchlists does not raise it, so a set of people larger than your plan allows needs an upgrade, not more lists. Check it before you create: GET /api-team reports it as limits.tracked_profiles_and_companies, with max and the team’s current used, alongside limits.profiles_per_watchlist for the 200 cap and limits.watchlists for the separate watchlist allowance.

​
Supported Profile Formats

Full URN format (automatically extracts the unique ID):

​
Idempotency

Two guards stop a retry from creating a second watchlist. Both run before the plan-watchlist check, so a retry that matches gets the existing watchlist back rather than a 402. A retry that does not match falls through to a normal create, plan check included, so 402 is still possible: most often when the matched watchlist turned out to be incomplete (see the warning below) and a fresh one has to be built.
  • Your own key (recommended). Send idempotency_key: any string up to 128 characters, unique per logical create. A UUID per create is the simplest choice. A second request with the same key, from the same team, within about two minutes is answered with the watchlist the first one made, whatever else the body says.
  • Without a key, a create is matched against watchlists your team made in the last couple of minutes that agree on the name you chose, the description, the Slack webhook, and the profiles themselves. A create that named a list_id matches when that list already holds every profile you asked for; a create that did not matches when the list holds exactly those profiles and no others.
Either way the answer is 201 with created: false and deduplicated: true. Treat it as success.
Best effort, not atomic. The duplicate lookup and the insert are separate steps, so two genuinely simultaneous identical creates can both go through. Retry one at a time rather than in parallel, and read created on the response instead of assuming. A matched watchlist whose collection tasks never got written is not handed back; a fresh one is built instead.
A key that is not a string, or is longer than 128 characters, is rejected with 400 before anything is created.

​
Response Fields

​
string
Unique identifier for the watchlist
​
string
Watchlist name
​
string
URL-friendly slug for the watchlist
​
string
Always “people” for people watchlists
​
number
What this counts depends on which response you got:
  • On a fresh create (created: true): the profile rows this call actually inserted. When you passed a list_id, that is the profiles this call added, not the list total.
  • On a deduplicated response (created: false): the number of identifiers you sent in the request, echoed back. It is not the existing watchlist’s profile total.
For the real total on an existing watchlist, call GET /api-people-watchlist?id=... and read profiles_count there.
​
number
Fetch frequency in hours
​
boolean
true when a new watchlist was created, false when an existing watchlist was returned instead. See Idempotency.
​
boolean
Present and true only when a duplicate guard returned an existing watchlist. Absent on a normal create.

​
Use Cases

Monitor thought leaders in your industry:
Keep tabs on decision-makers at target companies:
Watch what competitor executives are posting:

​
Frequently Asked Questions

200, on every plan. See Limits above, and note the separate team-wide allowance that caps the total across all your watchlists.
No. The team allowance counts every tracked profile and company on every watchlist you own, so extra watchlists do not raise your total. Upgrade the plan, or drop the profiles you are no longer working.
Tracking tasks are created immediately. People watchlists do not backfill, so the feed fills from the first fetch cycle onward rather than showing history right away. How fast that first cycle runs depends on Chrome extension activity.
Send add_profiles to PUT /api-people-watchlist. Do not call create again with the same name. Without an idempotency_key, a create is deduped only when the name, description, webhook and the exact profile set all match a create from about the last two minutes. A same-name create with a different profile set makes a second watchlist.
In this watchlist’s own feed, as posts with post_type set to job_update. Filter with GET /api-posts?watchlist_id=...&post_type=job_update. Those rows carry no intent label. See Design your watchlists.