Person Entity Watcher - Crustdata Docs

A Person Entity Watcher monitors a list of people you supply (by profile URL) and notifies you when their profiles change. You describe what to watch for; each scheduled run compares every person against their last snapshot and delivers only what changed. The list is yours to edit any time — add or remove people without recreating the watch. Where Person Discovery Watchers find new people matching a filter, Entity Watchers track a known set — an ATS of candidates, key contacts, a target roster — and surface movement within it:

A tracked person starts a new job or changes their title or headline — a strong “in motion” signal.
A tracked person earns a certification or receives an award.
A tracked person relocates, adds a degree, or lists a new skill.

Create a person watch with:

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

Every request requires the x-api-version: 2025-11-01 header and a Bearer token. Replace YOUR_API_KEY in each example with your API key. This endpoint is open to all API customers — no per-endpoint grant is needed.

Pricing — you pay only for notifications. The first run of every watch is a free baseline that records each person’s starting values internally (for diffing only — it isn’t delivered) and never fires. After that you’re charged 5 credits per notification — 5 credits for each watched person that changed on a run. A run that surfaces nothing costs nothing, and the price is the same whether you check hourly or monthly. If your balance is too low, the run is suspended rather than partially delivered. See Pricing for the canonical rates.

How a person entity watcher runs

Create the watch

POST your entities (people to watch), a track (what to watch for), a config (schedule + caps), and one or more notifications channels. The response returns the full watch object, including its id.

Baseline run (free)

The first run records an internal snapshot of the fields you’re tracking for each person — just enough to diff against next time. With no prior snapshot to compare, the baseline never fires and is never charged, and isn’t itself delivered — it only establishes “before”. To read a person’s current profile on demand, use the Enrich APIs.

Recurring runs

On your schedule (every_hours), the watcher re-checks each person, diffs them against their last snapshot, and delivers a notification for every person whose track condition just became true. You’re charged 5 credits per notification.

An Entity Watcher only fires on a transition — the moment a value crosses from its previous state to a new one. It never fires on the baseline, and won’t re-notify about a change it already reported. To read a list’s current state on demand instead of watching for change, use the Person Enrich API.

What you can track

The track describes the change that triggers a notification — a tree of condition leaves, optionally combined with and / or groups. A leaf has the shape:

{ "field": "<dot-path into the profile>", "type": "<operator>", "value": "<optional>" }

Operator	Applies to	Fires when
`changed`	a scalar field (e.g. `basic_profile.current_title`)	the value becomes different from the last snapshot
`added`	an array field (e.g. `certifications`, `honors`)	a new element appears in the array
`>`, `<`, `=`, `!=`, `=>` (≥), `=<` (≤)	a scalar, or a predicate on an array element	the comparison flips from false to true (e.g. `professional_network.connections => 500`)

Crustdata writes “greater-than-or-equal” as => and “less-than-or-equal” as =< — not >= / <=. Those reversed forms return unknown operator.

value is required for the comparison operators and omitted for changed and added. Combine leaves with a group node — { "op": "and" | "or", "conditions": [ … ] } — to watch several signals at once. An or group fires if any child fires; an and group fires only when all conditions hold and at least one just became true.

Common person signals

Examples only — a person profile has 200+ addressable fields, and you can track any of them (any scalar with changed, any array with added).

Signal	`field`	`type`
Started a new job	`experience.employment_details.current`	`added`
Title changed	`basic_profile.current_title`	`changed`
Headline changed	`basic_profile.headline`	`changed`
Relocated	`basic_profile.location.raw`	`changed`
New certification	`certifications`	`added`
New award or honor	`honors`	`added`
New education / degree	`education.schools`	`added`
New skill listed	`skills.professional_network_skills`	`added`
Connection count changed	`professional_network.connections`	`changed`

field paths address the same profile structure the Enrich API returns, so browse the full set of trackable fields in the Person Enrich reference. changed requires a scalar path and added an array path — mixing them returns a 400 (for example, "changed" on the array experience.employment_details.current is rejected; watch basic_profile.current_title instead).

Recipes: combine signals

Group leaves with or to fire on any of several signals, or and to require them together. These track blocks are all live-verified.

{
  "op": "or",
  "conditions": [
    { "field": "experience.employment_details.current", "type": "added" },
    { "field": "basic_profile.current_title", "type": "changed" }
  ]
}

{
  "op": "or",
  "conditions": [
    { "field": "certifications", "type": "added" },
    { "field": "honors", "type": "added" },
    { "field": "education.schools", "type": "added" }
  ]
}

Drop either into the track field of a create request. Groups nest, so you can mix and/or — e.g. “a title change and a new certification.”

`track` and `fields` are different

Two independent knobs, and the distinction matters:

Key	Controls	Answers
`track`	When the watch fires	”What change do I want to be notified about?”
`fields`	What the notification delivers	”What data about the person do I want in the payload?”

Set them independently. Track one field but deliver many (watch for a title change, yet receive the full employment history and education), or track many and deliver few. track decides whether you get a notification; fields decides what’s inside it.

fields defaults to a minimal projection. If you omit fields, the delivered record contains only basic_profile and social_handles.The field you’re tracking is not automatically added to the payload — the fired changes array always tells you exactly what moved, but to get the surrounding profile data in record, request it in fields.

Requesting all fields

fields does not affect pricing — an entity watch is a flat 5 credits per notification regardless of how many field groups you deliver (see Pricing). There’s no cost reason to keep the payload thin; request whatever your workflow needs. There’s no wildcard — to receive the complete record, list every field group your API key is entitled to. fields is a top-level key (a sibling of track), fixed at create time.

Person — all fields

{
  "entities": { "professional_network_profile_urls": ["https://www.linkedin.com/in/sherryrobinson"] },
  "track": { "field": "experience.employment_details.current", "type": "added" },
  "fields": [
    "basic_profile",
    "professional_network",
    "social_handles",
    "experience",
    "education",
    "skills",
    "certifications",
    "honors",
    "contact",
    "dev_platform_profiles"
  ]
}

Some groups require a field-level entitlement on your key (e.g. certifications). Requesting a group you aren’t entitled to returns a field-permission error, so list only the groups your key can access. The group names match the Enrich API — see the Person Enrich fields reference.

Choosing the entities

entities maps an identifier type to a list of values. A single watch holds up to 10,000 people.

Accepted identifier keys
`professional_network_profile_urls`

{ "entities": { "professional_network_profile_urls": ["https://www.linkedin.com/in/sherryrobinson"] } }

Schedule and limits

The config block controls timing and result caps:

Field	Required	Meaning
`trigger.type`	yes	Must be `"interval"`.
`trigger.every_hours`	yes	How often the watch runs, in hours (integer ≥ 1). Because you pay per notification, a higher frequency only makes changes surface sooner — it doesn’t raise the price.
`max_results_per_run`	no	Cap on notifications per run (1–1000, default 25).
`preferred_hour`	no	Hour of day (0–23) to prefer for the run.
`expires_at`	no	Auto-expire date, `YYYY-MM-DD`.

Delivery channels

Add one or more channels to notifications and every change fans out to all of them.

Channel	Shape
Webhook	`{ "type": "webhook", "url": "https://…", "headers": { … } }`
Slack	`{ "type": "slack", "webhook_url": "https://hooks.slack.com/services/…" }`
Google Chat	`{ "type": "google_chat", "url": "https://chat.googleapis.com/…" }`

At least one notification channel is required today. Every delivery is also recorded, so beyond the live push you can re-read a watch’s past runs from the run-history endpoint.

Quick start

Watch one person and get a webhook whenever they start a new job. This request and response are real.

curl --request POST \
  --url https://api.crustdata.com/watch/person \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "entities": {
      "professional_network_profile_urls": ["https://www.linkedin.com/in/sherryrobinson"]
    },
    "track": { "field": "experience.employment_details.current", "type": "added" },
    "config": {
      "trigger": { "type": "interval", "every_hours": 24 },
      "max_results_per_run": 100
    },
    "notifications": [
      { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" }
    ]
  }'

{
  "id": 46936,
  "kind": "entity",
  "dataset": "person",
  "api_version": "2025-11-01",
  "config_version": "2025-11-01",
  "status": "active",
  "entities": {
    "professional_network_profile_urls": ["https://www.linkedin.com/in/sherryrobinson"]
  },
  "track": { "field": "experience.employment_details.current", "type": "added" },
  "fields": null,
  "config": {
    "trigger": { "type": "interval", "every_hours": 24 },
    "max_results_per_run": 100,
    "expires_at": null,
    "preferred_hour": null
  },
  "notifications": [
    { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" }
  ],
  "created_at": "2026-07-16T03:16:38.351849Z",
  "last_run_at": null
}

Edit the watched list any time

Unlike a saved search, an Entity Watcher’s list is mutable — add or remove people as your pipeline or contact list changes, without recreating the watch. PATCH the watch with a new entities object:

curl --request PATCH \
  --url https://api.crustdata.com/watch/person/46936 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "entities": {
      "professional_network_profile_urls": [
        "https://www.linkedin.com/in/sherryrobinson",
        "https://www.linkedin.com/in/williamhgates"
      ]
    }
  }'

{
  "id": 46936,
  "status": "active",
  "entities": {
    "professional_network_profile_urls": [
      "https://www.linkedin.com/in/sherryrobinson",
      "https://www.linkedin.com/in/williamhgates"
    ]
  }
}

Newly added people are baselined silently on the next run — they establish their “before” snapshot first, so adding someone never fires a spurious notification. You can also PATCH status (active / paused), config, and notifications. A watch’s track and fields are fixed once created; to change what you watch for, create a new watch.

Manage your watches

Action	Request
List your watches	`GET /watch/person?status=active&limit=50&offset=0`
Get one	`GET /watch/person/{id}`
Pause / resume	`PATCH /watch/person/{id}` with `{ "status": "paused" }`
Add/remove entities	`PATCH /watch/person/{id}` with a new `entities`
Delete	`DELETE /watch/person/{id}` → `204`

Full request/response for each, verified live.

List your watches — GET /watch/person

curl --request GET \
  --url 'https://api.crustdata.com/watch/person?status=active&limit=50&offset=0' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

[
  {
    "id": 46957,
    "kind": "entity",
    "dataset": "person",
    "status": "active",
    "entities": {
      "professional_network_profile_urls": ["https://www.linkedin.com/in/sherryrobinson"]
    },
    "track": { "type": "added", "field": "experience.employment_details.current" },
    "config": { "trigger": { "type": "interval", "every_hours": 24 }, "max_results_per_run": 25 },
    "notifications": [{ "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" }],
    "created_at": "2026-07-16T13:39:18.247195Z",
    "last_run_at": "2026-07-16T13:39:18.598964Z"
  }
]

Returns an array of your person watches. Filter with status, page with limit and offset.

Get one watch — GET /watch/person/{id}

curl --request GET \
  --url https://api.crustdata.com/watch/person/46957 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

{
  "id": 46957,
  "kind": "entity",
  "dataset": "person",
  "api_version": "2025-11-01",
  "config_version": "2025-11-01",
  "status": "active",
  "entities": {
    "professional_network_profile_urls": ["https://www.linkedin.com/in/sherryrobinson"]
  },
  "track": { "type": "added", "field": "experience.employment_details.current" },
  "fields": null,
  "config": {
    "trigger": { "type": "interval", "every_hours": 24 },
    "max_results_per_run": 25,
    "expires_at": null,
    "preferred_hour": null
  },
  "notifications": [{ "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" }],
  "created_at": "2026-07-16T13:39:18.247195Z",
  "last_run_at": "2026-07-16T13:39:18.598964Z"
}

last_run_at is null until the baseline run completes, then carries the most recent run’s timestamp.

Pause or resume — PATCH status

curl --request PATCH \
  --url https://api.crustdata.com/watch/person/46957 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{ "status": "paused" }'

{ "id": 46957, "status": "paused" }

A paused watch stops running until you resume it. Send { "status": "active" } to resume.

Delete a watch — DELETE /watch/person/{id}

Request

curl --request DELETE \
  --url https://api.crustdata.com/watch/person/46957 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

Returns 204 No Content. Deletion is terminal — the watch cannot be resumed.

What a notification looks like

Every fired person carries two things: the changes array (exactly what moved, independent of fields) and a record (the person’s current data projected to the fields you requested — the same shape the Enrich API returns, so with default fields it’s just basic_profile + social_handles). The person’s identity travels inside the record as crustdata_person_id. Two ways to receive these, each with a different envelope:

Pushed to your webhook

When a watch fires, we POST this body to each channel. The example below is from a watch created with fields: ["basic_profile", "experience"]:

Webhook POST body

{
  "metadata": {
    "watch_id": 46936,
    "kind": "entity",
    "dataset": "person",
    "api_version": "2025-11-01",
    "run_id": 64200,
    "notification_id": "ntf_64200",
    "delivered_at": "2026-07-16T03:20:00.000000Z",
    "summary": { "delivered": 1, "total_count": 1, "max_results_per_run": 100, "truncated": false }
  },
  "results": [
    {
      "changes": [
        {
          "field": "experience.employment_details.current",
          "type": "added",
          "new_elements": [ { "title": "…", "name": "…", "start_date": "…" } ]
        }
      ],
      "record": {
        "basic_profile": { "name": "…", "current_title": "…", "headline": "…" },
        "experience": { "employment_details": { "current": [ { "title": "…", "name": "…", "start_date": "…" } ] } },
        "crustdata_person_id": 6324687
      }
    }
  ]
}

For an entity watch, results is a flat list — one object per fired person, each with its own changes and record. A changed scalar reports as { "field": …, "type": "changed", "from": …, "to": … }; an added array as { "field": …, "type": "added", "new_elements": [ … ] }.

Pulled from run history

To re-read a past run — or audit exactly what was delivered — the run-history endpoint returns the same content under a different envelope.

GET /watcher/watches/{id}/runs/{run_id}/summary

{
  "id": 64200,
  "status": "SUCCESS",
  "new_records_count": 1,
  "notifications": [
    {
      "sent_at": "2026-07-16T03:20:00Z",
      "http_status": 200,
      "payload": {
        "subscription_id": 46936,
        "event_type": "indb:entity:person",
        "timestamp": "2026-07-16T03:20:00Z",
        "notifications": [
          {
            "uid": "person_6324687_64200",
            "changes": [ { "field": "experience.employment_details.current", "type": "added", "new_elements": [ { … } ] } ],
            "record": { "basic_profile": { … }, "experience": { … }, "crustdata_person_id": 6324687 }
          }
        ]
      }
    }
  ]
}

Rate limits

Watch-management requests are rate-limited to 10 requests per minute per API key. This bounds bursty create/update loops; steady use is unaffected.

Person Discovery Watcher

Need to find new matching people instead of watching a known list? Use the Person Discovery Watcher.

Person field reference

Browse the full set of trackable field paths for people.

​How a person entity watcher runs

​What you can track

​Common person signals

​Recipes: combine signals

​track and fields are different

​Requesting all fields

​Choosing the entities

​Schedule and limits

​Delivery channels

​Quick start

​Edit the watched list any time

​Manage your watches

​What a notification looks like

​Pushed to your webhook

​Pulled from run history

​Rate limits

Person Discovery Watcher

Person field reference

How a person entity watcher runs

What you can track

Common person signals

Recipes: combine signals

`track` and `fields` are different

Requesting all fields

Choosing the entities

Schedule and limits

Delivery channels

Quick start

Edit the watched list any time

Manage your watches

What a notification looks like

Pushed to your webhook

Pulled from run history

Rate limits