Company Entity Watcher - Crustdata Docs

A Company Entity Watcher monitors a list of companies you supply and notifies you when their profiles change. Provide the companies (by domain, name, profile URL, or Crustdata company ID) and describe what to watch for. On each scheduled run, the watcher diffs every company against its last snapshot and delivers only what changed. The list is yours to edit any time — add or remove companies without recreating the watch. Where a Company Discovery Watcher finds new companies that match a filter, an Entity Watcher tracks a known set — a book of accounts, a competitor list, a portfolio — and surfaces movement within it:

A tracked company changes headcount or crosses a headcount threshold.
A tracked company appears in the news, raises funding, or adds an investor.
A tracked company rebrands, relocates its HQ, or shifts industry.

Companies have their own create endpoint:

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

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

Pricing — you pay only for notifications. Every watch’s first run is a free baseline: it records each company’s starting values internally for diffing (never delivered) and never fires. After that you pay 5 credits per notification — 5 credits for each watched company 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 full breakdown.

How a company entity watcher runs

Create the watch

POST your entities (companies 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)

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

Recurring runs

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

An Entity Watcher fires only 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 you about a change it already reported. To read a list’s current state on demand instead of watching for change, use the Company Enrich API.

What you can track

The track describes the change that triggers a notification. It’s 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. `headcount.total`)	the value becomes different from the last snapshot
`added`	an array field (e.g. `news`, `funding.investors`)	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. `headcount.total => 1000`)

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 for several signals at once. An or group fires if any child fires; an and group fires only when all its conditions hold and at least one just became true.

Common company signals

These are examples — a company profile has 500+ addressable fields, and you can track any of them (any scalar with changed, any array with added).

Signal	`field`	`type`
Headcount changed	`headcount.total`	`changed`
Crossed a headcount threshold	`headcount.total`	`=>` (with `value`)
In the news	`news`	`added`
Raised funding	`funding.total_investment_usd`	`changed`
New funding round	`funding.last_round_type`	`changed`
New investor	`funding.investors`	`added`
Made an acquisition	`funding.acquisitions`	`added`
Funding milestone	`funding.milestones`	`added`
Follower count changed	`followers.count`	`changed`
Hiring activity	`hiring.openings_count`	`changed`
Industry changed	`taxonomy.professional_network_industry`	`changed`
HQ relocated	`locations.country`	`changed`
Name change / rebrand	`basic_info.name`	`changed`

field paths address the same profile structure the Enrich API returns, so you can browse every trackable field in the Company Enrich reference. changed requires a scalar path, added requires an array path — mixing them returns a 400 (e.g. "changed" on the array news is rejected; use "added").

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": "headcount.total", "type": "changed" },
    { "field": "funding.total_investment_usd", "type": "changed" },
    { "field": "news", "type": "added" }
  ]
}

{
  "op": "or",
  "conditions": [
    { "field": "funding.last_round_type", "type": "changed" },
    { "field": "funding.investors", "type": "added" },
    { "field": "funding.acquisitions", "type": "added" }
  ]
}

{
  "op": "and",
  "conditions": [
    { "field": "headcount.total", "type": "=>", "value": 1000 },
    { "field": "hiring.openings_count", "type": "changed" }
  ]
}

Drop any of these into the track field of a create request. Groups can nest, so you can mix and/or — e.g. “a headcount change and the company crossed 1,000 employees.”

`track` and `fields` are different

These are 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 company do I want in the payload?”

Set them independently. You can track one field but deliver many (watch for a headcount change, yet receive full funding history and news in the payload), 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. Omit fields and the delivered record contains only basic_info.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 no matter 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 (sibling of track), fixed at create time.

Company — all fields

{
  "entities": { "domains": ["stripe.com"] },
  "track": { "field": "headcount.total", "type": "changed" },
  "fields": [
    "basic_info",
    "headcount",
    "funding",
    "locations",
    "taxonomy",
    "revenue",
    "hiring",
    "followers",
    "seo",
    "competitors",
    "social_profiles",
    "web_traffic",
    "employee_reviews",
    "people",
    "news"
  ]
}

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

Choosing the companies

entities is an object mapping an identifier type to a list of values. You can mix identifier types in one watch. A single watch holds up to 10,000 companies.

Accepted identifier keys
`domains`
`names`
`professional_network_profile_urls`
`crustdata_company_ids`

{ "entities": { "domains": ["netflix.com", "stripe.com"] } }

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. 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 two companies and get a Slack message whenever either changes headcount or appears in the news. This request and response are real:

curl --request POST \
  --url https://api.crustdata.com/watch/company \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "entities": { "domains": ["netflix.com", "stripe.com"] },
    "track": {
      "op": "or",
      "conditions": [
        { "field": "headcount.total", "type": "changed" },
        { "field": "news", "type": "added" }
      ]
    },
    "config": {
      "trigger": { "type": "interval", "every_hours": 168 },
      "max_results_per_run": 100
    },
    "notifications": [
      { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T00/B00/xxxxxxxx" }
    ]
  }'

{
  "id": 46941,
  "kind": "entity",
  "dataset": "company",
  "api_version": "2025-11-01",
  "config_version": "2025-11-01",
  "status": "active",
  "entities": { "domains": ["netflix.com", "stripe.com"] },
  "track": {
    "op": "or",
    "conditions": [
      { "field": "headcount.total", "type": "changed" },
      { "field": "news", "type": "added" }
    ]
  },
  "fields": null,
  "config": {
    "trigger": { "type": "interval", "every_hours": 168 },
    "max_results_per_run": 100,
    "expires_at": null,
    "preferred_hour": null
  },
  "notifications": [
    { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T00/B00/xxxxxxxx" }
  ],
  "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 companies as your account book or portfolio changes, without recreating the watch. PATCH the watch with a new entities object:

curl --request PATCH \
  --url https://api.crustdata.com/watch/company/46941 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "entities": {
      "domains": ["netflix.com", "stripe.com", "airbnb.com"]
    }
  }'

{
  "id": 46941,
  "status": "active",
  "entities": {
    "domains": ["netflix.com", "stripe.com", "airbnb.com"]
  }
}

Newly added companies are baselined silently on the next run — they establish their “before” snapshot first, so adding one 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/company?status=active&limit=50&offset=0`
Get one	`GET /watch/company/{id}`
Pause / resume	`PATCH /watch/company/{id}` with `{ "status": "paused" }`
Add/remove companies	`PATCH /watch/company/{id}` with a new `entities`
Delete	`DELETE /watch/company/{id}` → `204`

Full request/response for each, verified live:

List your watches — GET /watch/company

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

[
  {
    "id": 46941,
    "kind": "entity",
    "dataset": "company",
    "status": "active",
    "entities": { "domains": ["netflix.com", "stripe.com"] },
    "track": { "type": "changed", "field": "headcount.total" },
    "config": { "trigger": { "type": "interval", "every_hours": 168 }, "max_results_per_run": 25 },
    "notifications": [{ "type": "slack", "webhook_url": "https://hooks.slack.com/services/T00/B00/xxxxxxxx" }],
    "created_at": "2026-07-16T13:39:18.247195Z",
    "last_run_at": "2026-07-16T13:39:18.598964Z"
  }
]

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

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

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

{
  "id": 46941,
  "kind": "entity",
  "dataset": "company",
  "api_version": "2025-11-01",
  "config_version": "2025-11-01",
  "status": "active",
  "entities": { "domains": ["netflix.com", "stripe.com"] },
  "track": { "type": "changed", "field": "headcount.total" },
  "fields": null,
  "config": {
    "trigger": { "type": "interval", "every_hours": 168 },
    "max_results_per_run": 25,
    "expires_at": null,
    "preferred_hour": null
  },
  "notifications": [{ "type": "slack", "webhook_url": "https://hooks.slack.com/services/T00/B00/xxxxxxxx" }],
  "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 timestamp of the most recent run.

Pause or resume — PATCH status

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

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

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

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

Request

curl --request DELETE \
  --url https://api.crustdata.com/watch/company/46941 \
  --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 company carries two things: the changes array (exactly what moved, independent of fields) and a record (the company’s current data projected to the fields you requested — the same shape the Enrich API returns, so with the default fields it’s just basic_info). The company’s identity travels inside the record as crustdata_company_id. There are two ways to receive these, and they use different envelopes:

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_info", "headcount", "news"]:

Webhook POST body

{
  "metadata": {
    "watch_id": 46941,
    "kind": "entity",
    "dataset": "company",
    "api_version": "2025-11-01",
    "run_id": 64210,
    "notification_id": "ntf_64210",
    "delivered_at": "2026-07-16T03:20:00.000000Z",
    "summary": { "delivered": 1, "total_count": 1, "max_results_per_run": 100, "truncated": false }
  },
  "results": [
    {
      "changes": [
        {
          "field": "headcount.total",
          "type": "changed",
          "from": 8200,
          "to": 8460
        }
      ],
      "record": {
        "basic_info": { "name": "…", "domain": "…" },
        "headcount": { "total": 8460 },
        "news": [ { "title": "…", "url": "…", "published_at": "…" } ],
        "crustdata_company_id": 631480
      }
    }
  ]
}

For an entity watch, results is a flat list — one object per fired company, each with its own changes and record. A changed scalar reports as { "field": …, "type": "changed", "from": …, "to": … }; an added array reports 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": 64210,
  "status": "SUCCESS",
  "new_records_count": 1,
  "notifications": [
    {
      "sent_at": "2026-07-16T03:20:00Z",
      "http_status": 200,
      "payload": {
        "subscription_id": 46941,
        "event_type": "indb:entity:company",
        "timestamp": "2026-07-16T03:20:00Z",
        "notifications": [
          {
            "uid": "company_631480_64210",
            "changes": [ { "field": "headcount.total", "type": "changed", "from": 8200, "to": 8460 } ],
            "record": { "basic_info": { … }, "headcount": { … }, "news": [ … ], "crustdata_company_id": 631480 }
          }
        ]
      }
    }
  ]
}

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.

Company Discovery Watcher

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

Company field reference

Browse the full set of trackable field paths for companies.

​How a company entity watcher runs

​What you can track

​Common company signals

​Recipes: combine signals

​track and fields are different

​Requesting all fields

​Choosing the companies

​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

Company Discovery Watcher

Company field reference

How a company entity watcher runs

What you can track

Common company signals

Recipes: combine signals

`track` and `fields` are different

Requesting all fields

Choosing the companies

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