Watchlists

Add companies to a watchlist

Add companies to a Job Offers Watchlist without recreating the signal — extend the list as your target-account list grows, or replace it when the quarter's territory changes.

Input: signalId (path), companies (array of 1 to 10,000 names, domains or LinkedIn company URLs), and mode: append (default) or replace (companies not in the list stop being checked).

Each entry is either a plain string or an object {name, domain, linkedinUrl} (all optional, at least one required) carrying everything you know about the company, e.g. {"name": "PayFit", "domain": "payfit.com", "linkedinUrl": "https://www.linkedin.com/company/payfit"}. Strings and objects can be mixed in one call, and entries naming the same company are merged into one watched company carrying all their identifiers.

Send the LinkedIn company URL whenever you have it. It identifies the company exactly; a name does not, and two companies sharing a name cannot be told apart from the name alone — the list will look fully matched while watching the wrong one. A name still matches more reliably than a domain, so send the name when the URL is not available. Re-sending a company with its URL added corrects a match made earlier from its name.

Output: added, alreadyWatched (already on the list, details refreshed), rejected (neither a usable name nor a domain), stoppedWatching (dropped by a replace), and totalWatched.

A company added here is matched to a real employer on its first check, not immediately — call GET /companies afterwards and read unmatched to confirm the list is fully covered. Its first check only looks back over the signal's firstRunLookbackDays, so adding a company does not dump its whole posting history on you.

post/api/v1/watchlists/{signalId}/companies

Request

  • Base URL: https://api.rodz.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.rodz.io/api/v1/watchlists/{signalId}/companies
  • Auth: HTTP bearer

Path parameters

signalIdstring required

Id of the watchlist signal, as returned by the create endpoint.

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Request body

mode'append' | 'replace'

append (default) adds these to the list. replace makes this the whole list: companies not in it stop being checked.

Example request

{
  "companies": [
    "Doctolib",
    "payfit.com",
    {
      "domain": "alan.com",
      "linkedinUrl": "https://www.linkedin.com/company/alan-eu",
      "name": "Alan"
    }
  ],
  "mode": "append"
}

Response

Successful Response

addedinteger required

Entries now being watched that were not before.

alreadyWatchedinteger

Entries already on the list, left unchanged.

rejectedinteger

Entries that could not be used — not a valid identifier for this list.

stoppedWatchinginteger

Entries dropped because mode was replace. Always 0 on append.

totalWatchedinteger required

Entries being watched after this call.

Example response

{
  "added": 2,
  "alreadyWatched": 1,
  "rejected": 0,
  "stoppedWatching": 0,
  "totalWatched": 43
}

Changes

No recorded changes to this operation across all 1 revision of this API.