Create an entity watch
Creates an entity watch: a fixed list of people or companies you supply, plus a track tree
describing the change that should notify you.
track and fields are two independent knobs. track decides when the watch fires;
fields decides what the delivered record contains. If you omit fields, the record is
a minimal projection, and the tracked field is not added to it automatically. The changes
array always reports exactly what moved, whatever fields says.
The first run is a free baseline: it snapshots each subject’s starting values, never fires, and is never charged. Later runs diff against that snapshot and fire only on a transition, so a change is reported once and never repeated.
A single watch holds up to 10,000 subjects. fields and track field paths address the same
structure the dataset’s enrich endpoint returns, and both are checked against your key’s field
entitlements at creation.
Authorizations
API key passed as a Bearer token in the Authorization header.
Headers
API version to use. 2025-11-01 is the only accepted value. Send it on every call: it is
enforced today on POST /watch/{dataset}/search, where a missing or unrecognized value returns
400, and the other watch routes accept a request without it rather than relying on that.
2025-11-01 "2025-11-01"
Path Parameters
The dataset the watch is built on. Entity watches support person and company; there is no
job entity watch, and job returns 404 here. Use /watch/job/search for jobs.
person, company "person"
Body
Body for creating an entity watch. The dataset comes from the path.
The records to watch, as a map of identifier type to values. The accepted keys are exactly the ones the dataset's enrich endpoint accepts, and they are resolved to canonical ids when the watch runs. One watch holds up to 10,000 subjects across all keys.
People accept professional_network_profile_urls and business_emails. Companies accept
domains, names, professional_network_profile_urls, and crustdata_company_ids. Company
ids must be positive integers; every other identifier is a non-empty string.
The change that fires a notification. A single leaf or a nested AND/OR group.
- Option 1
- Option 2
Schedule, per-run caps, and data freshness for an entity watch.
Delivery channels. The key is required on an entity create, but the list may be empty for a pull-only watch, which pushes nothing and whose results you read from the run-history endpoints instead.
One delivery channel. Every channel on a watch receives every notification.
- Option 1
- Option 2
- Option 3
- Option 4
Ask what this watch would do instead of creating it. The request is validated exactly as a create is, nothing is persisted, and no credits are charged or reserved — so a preview works even on an account with no credits left, which is the balance a preview is usually being run to inform.
Answers 200 with the preview rather than 201 with a watch. Everything else in the body
means the same thing it means on a create, so preview and create differ by this flag alone.
true
Field groups to include in each delivered record, using the same names and nesting as
the dataset's enrich endpoint. There is no wildcard: list every group you want. Omit it
and the record falls back to a minimal projection, which for a person is
basic_profile plus social_handles.
The tracked field is not added to the payload automatically. fields does not affect
the price, so request whatever your workflow needs, and note that some groups need a
field-level entitlement on your key.
Response
The preview, when the body carried preview: true. Nothing was created and nothing was
charged.
What an entity watch would track, and which of the identifiers you supplied could not be read. Resolution covers every identifier because it is an id lookup; the sample covers three, because reading their stored records is the part that costs something.
true
How many of your identifiers matched a record we hold.
47
The identifiers that matched nothing. Worth reading before arming: an identifier that matches nothing is invisible afterwards — the watch simply never reports on it.
Up to three of the resolved subjects, cut to identity — a name and a link. This answers "did you find the people I pasted", not "what do those people look like right now".
The tracked paths your key is entitled to. A path you sent that is missing here has no grant behind it and will never fire.
What this watch will be charged, at the settings it was asked about.