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.
`config.payload_delivery_type`	No	`"inline"` (default) or `"link"`. Where the records travel: inside the notification, or in one file the notification links to. See Payload delivery.
`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.

Baseline limit: 500,000 people. The baseline run only delivers 5, but it reads your entire match set to record what already exists. That read is capped at 500,000, and we check it when you create the watch, so a broader filter comes back 400 and you narrow it before anything runs. The cap applies to the baseline alone. Later runs deliver whatever newly matches, bounded by config.max_results_per_run.

Filters from other datasets

A person watch is not limited to person fields. Drop a company field or a job field into the same flat conditions list and the watch filters on where those people work, or on what their employer is hiring for:

{
  "op": "and",
  "conditions": [
    { "field": "experience.employment_details.current.title", "type": "(.)", "value": "platform engineer" },
    { "field": "technographics.technologies.name",            "type": "=",   "value": "Kubernetes" }
  ]
}

Platform engineers at companies running Kubernetes. Technology stack lives only on company records, so it was previously out of reach from a person watch. The join runs through each person’s current employer. You still receive people, and you’re still charged 0.5 credits per person. Reading the other dataset is free, and nothing from it appears in your payload: to pull the employer’s own record, call POST /company/search or POST /company/enrich yourself with the crustdata_company_id on the delivered person’s current employer. See Cross-dataset filters for the join rules, the lookup fields for that follow-up call, the limits, and why negation (!=, not_in, (!)) is rejected on a filter from another dataset.

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.

Where the records travel

By default a run’s people arrive inside the notification, under results. Set config.payload_delivery_type to "link" and the body carries no records at all. It carries metadata.payload_delivery.url instead, a pre-signed S3 URL for one NDJSON file holding every record of that run. Switch when a run can outgrow what your receiver accepts. An AWS Lambda proxy integration caps a request at 6 MB and an ALB target at 1 MB, and an oversize body is refused whole.

curl --request PATCH \
  --url https://api.crustdata.com/watch/person/search/46849 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "config": {
      "trigger": { "type": "interval", "every_hours": 24 },
      "payload_delivery_type": "link"
    }
  }'

Every channel on the watch gets the same link, and the run-summary endpoint serves the same file. Read metadata.payload_delivery.type rather than testing for results: a link watch falls back to an inline body if the file cannot be written. See Payload delivery for the file format, the link lifetime, the run-summary shape, and the errors.

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

​Filters from other datasets

​Recipes

​Persona: title + location

​Persona at a company-size band

​Seniority + skills

​Movement signal: recently changed jobs

​Education filter, excluding companies

​Delivery channels

​Where the records travel

​Manage a watch

​Pricing

​Related

Entity watchers

Person Search

Person Search reference

Pricing

Discovery vs. Entity watchers

How it runs

Request body

Filter format

Filters from other datasets

Recipes

Persona: title + location

Persona at a company-size band

Seniority + skills

Movement signal: recently changed jobs

Education filter, excluding companies

Delivery channels

Where the records travel

Manage a watch

Pricing

Related