Person Discovery Watcher - Crustdata Docs

A Person Discovery Watcher turns a Person Search filter into a continuous feed. Each run re-evaluates your filters and delivers only the new matches to your channel — webhook or Slack. You get a deduplicated stream of people entering your criteria, without re-running searches yourself.

POST https://api.crustdata.com/watch/person/search

Pricing: the first run is a free baseline (up to 5 matches), then 0.5 credits per new person delivered.

Discovery vs. Entity watchers

A Discovery Watcher finds people you don’t know yet — it re-runs a filter and surfaces whoever newly matches. Use it to build a feed of candidates or decision-makers entering your ICP. An Entity Watcher tracks a known list of people and alerts you when their profiles change — a new job, a title bump, a location move. If you already hold the profile URLs, see Entity Watchers.

How it runs

Create the watch

POST your filters, a config (schedule + result cap), and one or more notifications channels. The response returns a watch id.

Baseline run (free)

Within seconds, the first run delivers a free baseline sample of up to 5 matches so you can confirm the setup and payload shape. No credits are charged.

Recurring runs

On your schedule (every_hours), the watcher re-runs your filters and delivers people new or refreshed since the previous run, up to max_results_per_run. You’re charged per delivered person.

Each run delivers matches whose profile was added or updated since the last run — a feed of movement within your filter set, not a one-time export. To pull the full current match set, use Person Search.

Request body

Field	Required	Description
`filters`	Yes	A filter tree, identical to Person Search. `{ "op": "and"\|"or", "conditions": [ { "field", "type", "value" } ] }`.
`config.trigger`	Yes	`{ "type": "interval", "every_hours": N }` — how often the watch runs (e.g. `1`, `6`, `24`, `168`).
`config.max_results_per_run`	No	Max records delivered per run. Default `25`. The first (baseline) run is always capped at 5.
`config.expires_at`	No	ISO date (`"2027-01-01"`). The watch auto-stops after this date.
`notifications`	Yes	One or more delivery channels (see below).

The response returns the watch id:

{ "id": 46849 }

All examples require the headers authorization: Bearer YOUR_API_KEY, content-type: application/json, and x-api-version: 2025-11-01. For the full list of field values and operators, see the Person Search reference.

Filter format

Watcher filters use the same syntax and fields as Person Search — no new filter language to learn. Every filter is a tree:

{
  "op": "and",
  "conditions": [
    { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Head of Data" },
    { "field": "professional_network.location.raw", "type": "(.)", "value": "United States" }
  ]
}

Each leaf is a { field, type, value } triple: field is the attribute, type is the operator ((.) for contains, =, in, not_in, => for ≥, =< for ≤, and so on), and value is what to match. Each op combines its conditions with and or or, and op-groups nest — put an and group inside an or group’s conditions for “A and B, or C”. See the Person Search reference for the full field and operator catalog.

Recipes

Persona: title + location

Alert daily when new ML engineers in Paris appear:

curl --request POST \
  --url https://api.crustdata.com/watch/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Machine Learning Engineer" },
        { "field": "professional_network.location.raw", "type": "(.)", "value": "Paris" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 }, "max_results_per_run": 25 },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Persona at a company-size band

New VPs of Finance at 51–500-employee companies:

curl --request POST \
  --url https://api.crustdata.com/watch/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "experience.employment_details.current.title", "type": "in", "value": ["Chief Financial Officer", "VP Finance", "Vice President Finance"] },
        { "field": "experience.employment_details.current.company_headcount_latest", "type": "=>", "value": 51 },
        { "field": "experience.employment_details.current.company_headcount_latest", "type": "=<", "value": 500 }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Seniority + skills

New CXO-level people with machine-learning skills:

curl --request POST \
  --url https://api.crustdata.com/watch/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "experience.employment_details.current.seniority_level", "type": "=", "value": "CXO" },
        { "field": "skills.professional_network_skills", "type": "(.)", "value": "machine learning" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" } ]
  }'

Movement signal: recently changed jobs

People who recently changed jobs (a new decision-maker signal — best for sales/GTM):

curl --request POST \
  --url https://api.crustdata.com/watch/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "experience.employment_details.current.title", "type": "(.)", "value": "VP of Sales" },
        { "field": "recently_changed_jobs", "type": "=", "value": true }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Education filter, excluding companies

Stanford alumni who are not currently at the big three:

curl --request POST \
  --url https://api.crustdata.com/watch/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "education.schools.school", "type": "(.)", "value": "Stanford" },
        { "field": "experience.employment_details.current.company_name", "type": "not_in", "value": ["Google", "Meta", "Amazon"] }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 168 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Delivery channels

Every watch needs at least one channel in notifications. Add one or more; matches fan out to all of them.

{ "type": "webhook", "url": "https://your-app.com/webhooks/crustdata", "headers": { "X-Watch-Name": "ml-engineers-paris" } }

{ "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" }

[
  { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" },
  { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" }
]

A Slack channel must be a genuine Slack incoming webhook (https://hooks.slack.com/services/…). Any other URL will fail delivery.

Manage a watch

curl --request GET \
  --url 'https://api.crustdata.com/watcher/watches/46849/runs?limit=20' \
  --header 'authorization: Bearer YOUR_API_KEY'

curl --request GET \
  --url https://api.crustdata.com/watcher/watches/46849/runs/54811/summary \
  --header 'authorization: Bearer YOUR_API_KEY'

curl --request DELETE \
  --url https://api.crustdata.com/watcher/watches/46849 \
  --header 'authorization: Bearer YOUR_API_KEY'

Pricing

	Credits
First run (baseline, up to 5 matches)	Free
Each new person delivered on later runs	0.5

You’re charged only for records actually delivered — never for a run that finds nothing new. For the full credit catalog, see Pricing.

Entity watchers

Watch a known list of people for profile changes.

Person Search

Run the underlying search on demand and pull the full current match set.

Person Search reference

The complete catalog of filter fields and operators.

Pricing

Credit costs across every Crustdata endpoint.

​Discovery vs. Entity watchers

​How it runs

​Request body

​Filter format

​Recipes

​Persona: title + location

​Persona at a company-size band

​Seniority + skills

​Movement signal: recently changed jobs

​Education filter, excluding companies

​Delivery channels

​Manage a watch

​Pricing

​Related

Entity watchers

Person Search

Person Search reference

Pricing

Discovery vs. Entity watchers

How it runs

Request body

Filter format

Recipes

Persona: title + location

Persona at a company-size band

Seniority + skills

Movement signal: recently changed jobs

Education filter, excluding companies

Delivery channels

Manage a watch

Pricing

Related