Skip to main content
A domain scan finds look-alikes of acme.com at one point in time. Monitors keep watching after the scan and raise a look-alike alert when something changes. There are two kinds:
  • Scan-wide monitors cover a whole scan. They alert when new look-alikes appear, or when a variation of your domain gets name servers.
  • Per-domain monitors cover one discovered look-alike, such as acme-login.com. They alert on DNS records, open web ports, phishing databases, risk score, page content and spoofing of your brand.
Every alert lands in one inbox for your organization. You read it, filter it and mark alerts seen through the API. Domain monitoring appears as the SpoofGuard tag in the API reference. In the dashboard, the inbox is Lookalike Domains → Alerts.
These are not the monitors of the Alert System, whose results are matches. Look-alike monitors do not use your Monitored Assets capacity, and look-alike alerts do not go through your delivery settings.
Availability: Domain Monitoring, the plan feature that also opens domain scans. Cost: no metered allowance. Look-alike monitors use no Monitored Assets slots. Each call counts toward the per-second rate limit and, when it succeeds, uses one unit of your monthly API Calls allowance. Without Domain Monitoring, or when your license is not active, every endpoint on this page returns 403:
These endpoints have no allowance or capacity of their own, so they never return the allowance 429 or the capacity 409 described in Plans and quotas. Two other kinds of 429 can come back:
  • "message": "Rate limit exceeded" is the per-second rate limit or your API Calls allowance. See Rate limits.
  • "detail": "Request was throttled. Expected available in 12 seconds." is the domain monitoring service’s own limit of 180 requests a minute. Every API key and dashboard user of your organization shares it. Wait the seconds the message gives. The response has no Retry-After header.

​
How alerts reach you

Look-alike alerts are not sent by email or webhook. You read them from the alerts inbox, and the polling recipe below keeps an integration up to date. Monitors accept a recipients list, but no email is sent to those addresses.

​
Watch the whole scan

Two monitors belong to the scan itself. Both are off until you turn them on. Switch them with analysis_update:
Send false to turn one off. analysis_detail returns both fields with their current state. Scan-wide monitors do not appear in the monitor list. One alert from them can cover several domains, listed in its result_domains.

​
Monitor a discovered domain

Pick look-alikes from the scan’s results and send them with the conditions to watch to create_analysis_monitor:
The call returns 201 with a list of the monitors on those domains. Each one carries its uid, domain, analysis_id, conditions, enabled, recipients and timestamps. The list can also hold monitors you paused or deleted on those domains before, so pick the new one by created_at. Keep its uid to change or delete the monitor. Three rules decide which conditions make sense for a domain:
  • A, MX and port conditions alert only when something first appears. On a domain that already has an A record, an MX record, or both web ports open, that condition never fires. Read a_record, mx_record, http_open and https_open on the scan result first.
  • Spoofing conditions need a logo or brand keywords on the scan. Without one, create_analysis_monitor refuses is_spoofing and content_change_and_spoof with 400. monitor_update does not check, so attach a logo or keywords before you add a spoofing condition to an existing monitor. Set up a brand library shows how to attach them.
  • One active monitor per domain. A domain that already has an enabled monitor returns 400 and lists the domain in domains. A monitor you deleted while it was enabled still counts. To resume a paused monitor, send "enabled": true to monitor_update instead of creating a new one.

​
Change, pause or delete a monitor

monitor_update takes three fields:
  • enabled: required. It is applied on every update, so send true to keep the monitor running while you change something else.
  • conditions: replaces the list of conditions.
  • recipients: replaces the list of addresses.
The call returns a one-item list with the updated monitor. Send {"enabled": false} to pause a monitor. A paused monitor keeps its alerts. monitor_delete returns 204. It removes the monitor and its alerts from the inbox. Deleting a scan does the same for all of its monitors. A monitor deleted while enabled keeps blocking its domain: create_analysis_monitor refuses that domain with 400 afterwards. To stop alerts for a while, pause the monitor instead. If you may want to watch the domain again, pause the monitor before you delete it. Monitors also set the triage status of the domain in the scan’s results. Creating or enabling a monitor sets it to monitoring. Pausing or deleting the monitor sets it to reviewed.

​
List monitors

analysis_monitors lists the per-domain monitors of one scan, newest first: The response has count, next, previous and results. Raise page until next is null. monitor_detail returns one monitor.

​
Read the alerts inbox

alerts_list returns every look-alike alert of your organization, across all scans and monitors, newest first:
Leave out date_sort: the default order is newest first.
The example above is shortened. Each alert carries these fields: alert_type_counts counts the alerts per condition across every page of the filtered set. full_message is kept for older integrations: read change_detail instead. Raise page until next is null. monitor_alerts returns the 10 newest alerts of one monitor, with the total in count. To page through all of them, call the inbox with monitor_id.

​
Mark alerts seen

Send the alert uid values and seen to alerts_update_seen:
seen is required: send true to mark alerts seen, false to mark them unseen. The call returns the updated alerts as a list. IDs that are valid UUIDs but do not exist are skipped. Send only alert uid values: an ID that is not a UUID returns 502. The seen state belongs to your organization, so the dashboard’s Alerts tab shows the same state. To process new alerts on a schedule:
1

Fetch unread alerts

Call the inbox with seen=false and page_size=100.
2

Process them

Handle each alert in your own system, using condition, severity and result_domains.
3

Mark them seen

Send their uid values with "seen": true.
4

Repeat until the inbox is empty

Fetch page 1 again until count is 0. Alerts you mark seen leave the seen=false set, so the next unread alerts are always on page 1.
Each round uses two requests per 100 alerts. Keep the loop under the domain monitoring service’s limit of 180 requests a minute, which your whole organization shares with the dashboard.

​
Read one alert

alert_detail returns one alert by its uid, as a one-item list. Read the alert from index 0.

​
Errors

Errors from the API itself carry detail. Errors from the domain monitoring service carry details, except its own 429, which carries detail. The per-second rate limit and the API Calls allowance carry message. Read the first of detail, details and message that the body contains. Every status is explained once in Handle API errors.

​
Endpoints