> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Person Discovery Watcher

> Create a watcher that alerts you when new people match your filters. Copy-paste curl recipes for personas, seniority, company size, tenure, and movement signals.

A Person Discovery Watcher re-runs a [Person Search](/person-docs/search/introduction) on a schedule and delivers new matches to your channel.

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

<Callout icon="coins" color="#5345e4">
  <strong>Pricing:</strong> first run is a free baseline (up to 5 matches), then
  <code>0.5 credits per new person</code> delivered.
</Callout>

## Request body

| Field                        | Required | Description                                                                                                                                          |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters`                    | Yes      | A filter tree, identical to [Person Search](/person-docs/search/reference). `{ "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](#delivery-channels)).                                                                                     |

The response returns the watch `id`:

```json theme={"theme":"vitesse-black"}
{ "id": 46849 }
```

<Note>
  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](/person-docs/search/reference).
</Note>

## Recipes

### Persona: title + location

Alert daily when new **ML engineers in Paris** appear:

```bash theme={"theme":"vitesse-black"}
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**:

```bash theme={"theme":"vitesse-black"}
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**:

```bash theme={"theme":"vitesse-black"}
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):

```bash theme={"theme":"vitesse-black"}
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:

```bash theme={"theme":"vitesse-black"}
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": "email", "to": ["sourcing@yourcompany.com"] } ]
  }'
```

## Delivery channels

Add one or more channels; matches fan out to all of them.

<CodeGroup>
  ```json Webhook theme={"theme":"vitesse-black"}
  { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata", "headers": { "X-Watch-Name": "ml-engineers-paris" } }
  ```

  ```json Slack theme={"theme":"vitesse-black"}
  { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" }
  ```

  ```json Email theme={"theme":"vitesse-black"}
  { "type": "email", "to": ["sourcing@yourcompany.com", "recruiter@yourcompany.com"] }
  ```

  ```json Multiple theme={"theme":"vitesse-black"}
  [
    { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" },
    { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" }
  ]
  ```
</CodeGroup>

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

## Manage a watch

<CodeGroup>
  ```bash List runs theme={"theme":"vitesse-black"}
  curl --request GET \
    --url 'https://api.crustdata.com/watcher/watches/46849/runs?limit=20' \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```

  ```bash Run detail (delivered records) theme={"theme":"vitesse-black"}
  curl --request GET \
    --url https://api.crustdata.com/watcher/watches/46849/runs/54811/summary \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```

  ```bash Cancel a watch theme={"theme":"vitesse-black"}
  curl --request DELETE \
    --url https://api.crustdata.com/watcher/watches/46849 \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```
</CodeGroup>

## 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.