Signals

Create Job Offers Watchlist signal

Watch a fixed list of companies and get their new job postings as leads - reach the hiring decision-maker the day a role opens at an account you already care about.

Where the Job Offers signal DISCOVERS companies from filters, this one starts from your list: your target accounts, your customers, or your competitors.

Input: companies (names, domains or LinkedIn company URLs, or objects {name, domain, linkedinUrl} carrying all three - send the LinkedIn URL whenever you have it, it identifies the company exactly where a name cannot separate two companies sharing one; failing that a name matches more reliably than a domain), maxJobsPerCompanyPerDay (default 3; total daily volume is roughly this x the number of companies watched), cadenceHours (default 24), jobTitleInclude / jobTitleExclude, firstRunLookbackDays (default 30 - how far back the first check of a company looks, for the initial list and, by default, for every company added later, so a company does not deliver its whole posting history at once), addedCompaniesLookback (first_run by default; recent_only limits the first check of a company added later to the postings of the last cadenceHours), and optional persona targeting (enablePersonaTargeting, targetPersonas, maxLeadsPerCompany, companyOnlyWhenContactsRefused - default false, deliver the company alone, no contact, when people were found there but every one was filtered out by your persona/location/size settings, instead of nothing, requireContact - default false; true = only leads with a contact are delivered: a company where nobody matching your personas is found is neither delivered nor charged, whatever companyOnlyWhenContactsRefused says), plus enrichment flags (getEmails, getPhones).

Output: each new posting at a watched company is pushed to your webhookUrl. With persona targeting off you receive one company-level lead per posting (contact empty); with it on you receive the hiring decision-makers as person-leads. A posting is delivered ONCE - later checks only surface roles newer than what you have already received.

companies is consumed into the watchlist, so it is NOT echoed back in the config of this or any later response - the watched list has exactly one home. Read it with GET /api/v1/watchlists/{signalId}/companies, which is also the only place that tells you which companies were actually matched to an employer, and add or remove companies with POST / DELETE on the same path.

Use cases:

  • Account-based hiring alerts - the day a target account opens a role, reach the hiring manager while the need is fresh and no vendor has been chosen.
  • Expansion triggers in your customer base - watch existing customers and treat a new role on a team you sell to as a signal that budget and headcount just moved.
  • Competitor headcount watch - track competitors' postings to see which teams they are building, and time your differentiation play accordingly.
post/api/v1/signals/job-offers-watchlist

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/signals/job-offers-watchlist
  • Auth: HTTP bearer

Request body

namestring required

Name for this signal

webhookUrlstring nullable

Where each lead is POSTed as it is produced. Optional (since 2026-09-23): omit it when you read leads with GET /api/v1/signals/{signalId}/leads or route them to a connected CRM or sequencer with destinations on PATCH /api/v1/signals/{signalId}.

dailyLeadLimitinteger

Max leads per day

statusstring nullable

Initial status (default: draft).

Example request

{
  "config": {
    "cadenceHours": 24,
    "companies": [
      "Doctolib",
      {
        "domain": "payfit.com",
        "linkedinUrl": "https://www.linkedin.com/company/payfit",
        "name": "PayFit"
      },
      "lemlist"
    ],
    "enablePersonaTargeting": true,
    "getEmails": true,
    "jobTitleInclude": [
      "Account Executive",
      "Sales"
    ],
    "maxJobsPerCompanyPerDay": 3,
    "targetPersonas": [
      "Head of Sales"
    ]
  },
  "dailyLeadLimit": 30,
  "name": "Hiring at my target accounts",
  "status": "active",
  "webhookUrl": "https://example.com/webhooks/rodz"
}

Response

Signal created

idstring required
namestring required
statusstring required
signalTypeIdstring required
webhookUrlstring nullable
configobject nullable

Signal-specific configuration

dailyLeadLimitinteger required
leadsTodayinteger required
leadsTotalinteger required
duplicateHandlingstring required

Duplicate lead handling: 'refuse' (never accept), 'allow' (always accept), or 'Xd' (accept after X days)

createdAtstring required
updatedAtstring required
lastLeadAtstring nullable
appliedobject

Settings this signal runs with where they differ from config, keyed like config. {} when every stored setting is applied as stored. A null value means the stored field is not used by this signal. Every entry is explained by a warning naming the same field.

Example response

{
  "applied": {
    "allowUnknownCompanySize": false,
    "maxJobAgeDays": 180
  },
  "config": {
    "companySizeFilters": [
      "201-500",
      "501-1000"
    ],
    "getEmails": true,
    "jobTitles": [
      "CTO"
    ],
    "locations": [
      "France"
    ],
    "maxJobAgeDays": 90
  },
  "createdAt": "2026-01-15T10:30:00Z",
  "dailyLeadLimit": 50,
  "duplicateHandling": "refuse",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "lastLeadAt": "2026-03-15T14:22:00Z",
  "leadsToday": 3,
  "leadsTotal": 127,
  "name": "CTOs changing jobs in France",
  "signalTypeId": "job_changes",
  "status": "active",
  "updatedAt": "2026-03-16T08:00:00Z",
  "warnings": [
    {
      "code": "VALUE_BELOW_MINIMUM",
      "field": "maxJobAgeDays",
      "message": "`maxJobAgeDays` is 90; this signal applies 180. Job changes are delivered up to 180 days after the start date, and a shorter window is raised to that minimum.",
      "severity": "info",
      "values": [
        "90"
      ]
    }
  ],
  "webhookUrl": "https://your-server.com/webhooks/rodz"
}

Changes

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