curl --request POST \
  --url https://api.crustdata.com/watch/{dataset} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --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"
    ],
    "business_emails": [
      "jane@example.com"
    ],
    "domains": [
      "netflix.com",
      "stripe.com"
    ],
    "names": [
      "Netflix"
    ],
    "crustdata_company_ids": [
      631394
    ]
  },
  "track": {
    "field": "experience.employment_details.current",
    "type": "added",
    "value": 500
  },
  "fields": [
    "<string>"
  ],
  "config": {
    "trigger": {
      "type": "interval",
      "every_hours": 24
    },
    "max_results_per_run": 100,
    "refresh_frequency_days": 7,
    "preferred_hour": 9,
    "expires_at": "2027-01-01"
  },
  "notifications": [
    {
      "type": "webhook",
      "url": "https://your-app.com/webhooks/crustdata",
      "headers": {
        "X-Watch-Name": "ml-engineers-paris"
      }
    }
  ],
  "created_at": "2026-07-16T03:16:38.351849Z",
  "last_run_at": "2026-07-16T13:39:18.598964Z",
  "notifications_count": 12,
  "credits_consumed": 60,
  "last_notified_at": "2026-07-16T13:39:18.598964Z"
}

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 50,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.

POST

https://api.crustdata.com

watch

{dataset}

curl --request POST \
  --url https://api.crustdata.com/watch/{dataset} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --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"
    ],
    "business_emails": [
      "jane@example.com"
    ],
    "domains": [
      "netflix.com",
      "stripe.com"
    ],
    "names": [
      "Netflix"
    ],
    "crustdata_company_ids": [
      631394
    ]
  },
  "track": {
    "field": "experience.employment_details.current",
    "type": "added",
    "value": 500
  },
  "fields": [
    "<string>"
  ],
  "config": {
    "trigger": {
      "type": "interval",
      "every_hours": 24
    },
    "max_results_per_run": 100,
    "refresh_frequency_days": 7,
    "preferred_hour": 9,
    "expires_at": "2027-01-01"
  },
  "notifications": [
    {
      "type": "webhook",
      "url": "https://your-app.com/webhooks/crustdata",
      "headers": {
        "X-Watch-Name": "ml-engineers-paris"
      }
    }
  ],
  "created_at": "2026-07-16T03:16:38.351849Z",
  "last_run_at": "2026-07-16T13:39:18.598964Z",
  "notifications_count": 12,
  "credits_consumed": 60,
  "last_notified_at": "2026-07-16T13:39:18.598964Z"
}

Authorizations

Authorization

string

header

required

API key passed as a Bearer token in the Authorization header.

Headers

x-api-version

enum<string>

default:2025-11-01

required

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.

Available options:

2025-11-01

Example:

"2025-11-01"

Path Parameters

dataset

enum<string>

required

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.

Available options:

person,

company

Example:

"person"

Body

application/json

Body for creating an entity watch. The dataset comes from the path.

entities

object

required

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 50,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.

Show child attributes

track

object

required

The change that fires a notification. A single leaf or a nested AND/OR group.

Option 1
Option 2

Show child attributes

config

object

required

Schedule, per-run caps, and data freshness for an entity watch.

Show child attributes

notifications

object[]

required

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

Show child attributes

fields

string[]

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.

Example:

["basic_profile", "experience"]

Response

The watch was created and its baseline run was scheduled.

An entity watch, as returned by create, get, list, and update.

integer

Example:

46936

kind

enum<string>

Available options:

entity

Example:

"entity"

dataset

enum<string>

Available options:

person,

company

Example:

"person"

api_version

string

Example:

"2025-11-01"

config_version

string

Example:

"2025-11-01"

status

enum<string>

Available options:

active,

paused,

suspended,

expired,

cancelled

Example:

"active"

entities

object

Show child attributes

track

object

The saved track tree.

Option 1
Option 2

Show child attributes

fields

string[] | null

config

object

Schedule, per-run caps, and data freshness for an entity watch.

Show child attributes

notifications

object[]

One delivery channel. Every channel on a watch receives every notification.

Option 1
Option 2
Option 3
Option 4

Show child attributes

created_at

string<date-time>

Example:

"2026-07-16T03:16:38.351849Z"

last_run_at

string<date-time> | null

Example:

"2026-07-16T13:39:18.598964Z"

notifications_count

integer

Example:

12

credits_consumed

number

Example:

60

last_notified_at

string<date-time> | null

Example:

"2026-07-16T13:39:18.598964Z"