Skip to main content
The brand library holds what a domain scan compares look-alike domains against. A scan without it still finds look-alikes of acme.com. With it, the scan also flags websites that show your logo or brand names, tries word combinations such as acme-login.com, and leaves out domains you own. Domain monitoring appears as the SpoofGuard tag in the API reference. In the dashboard, the same library is Lookalike Domains → Brand library. Every item belongs to your organization. All API keys and dashboard users of the organization share one library, and the same item can be attached to many scans. Availability: Domain Monitoring, the plan feature that also opens domain scans. Cost: no metered allowance. Library items 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:
The library endpoints, analysis_update and analysis_rescan have no allowance or capacity of their own. They never return the allowance 429 or the capacity 409 described in Plans and quotas. start_domain_analysis is different. Each scanned domain holds one Monitored Assets slot, from the same pool as your monitors. When every slot is in use, the call returns 409 and nothing is created:
Monitored Assets slots explains how to free a slot. Two kinds of 429 can come back from any endpoint on this page:
  • "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: 10 scan starts an hour and 180 other 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.
spoofguard_logos_create takes multipart/form-data with two fields:
  • name: up to 100 characters, unique within your organization.
  • logo: a JPEG, PNG or GIF image of up to 20 MB.
The call returns 201 with the logo’s id, name, logo_link (the URL of the stored image) and timestamps. Keep the id: you attach the logo to a scan with it. A logo attached to a scan does two things. The scan compares look-alike websites with your logo, and the result counts them in total_logo_spoofing. The scan also runs a Google Lens reverse-image search for the logo. Without a logo, the scan’s module_statuses reports logo_spoofing with the reason logo_not_supplied. To rename a logo or replace its image, send spoofguard_logos_update as multipart/form-data with name, logo or both. Both upload calls accept only multipart/form-data. A JSON body returns 415.

​
Create a branding keyword set

spoofguard_branding_create takes a JSON body:
  • name: up to 100 characters, unique within your organization.
  • keywords: 1 to 3 keywords. A keyword can be a phrase.
A look-alike website counts as brand spoofing only when every keyword in the set appears in its page content. Matching ignores case and needs whole words: acme matches “Acme Login” but not “acmesoft”. Each keyword you add narrows the match, so a set with one strong keyword catches the most pages. Matches are counted in the scan’s total_brand_spoofing. Without a keyword set, module_statuses reports brand_spoofing with the reason branding_list_not_supplied. spoofguard_branding_update takes name, keywords or both. keywords replaces the whole set.

​
Create a word list

A word list feeds the word-combination check, which joins your domain with each word to build candidates such as acme-login.com. The check runs only on a scan that has a word list attached. spoofguard_wordlists_create takes three required fields:
  • name: up to 512 characters.
  • code: a slug of letters, digits, hyphens and underscores. You attach the list to a scan by its code, not its id.
  • words: a non-empty list. Each word may contain letters and digits only, with no spaces, hyphens or dots.
The call returns 201 in every successful case, but it does not always create a list:
  • Words are stored lowercase and sorted.
  • Only the first 10 words are kept. details names the words that were dropped.
  • A code you already use returns that list unchanged. existing_wordlist_code holds the code, and your new words are not saved.
  • The same set of words returns the existing list. No new list is created. details says so, and code and existing_wordlist_code hold the existing list’s code.
Read code from the response and use that value when you attach the list. spoofguard_wordlists_update is a PUT: send name, code and words every time. It returns the stored name, code and words. A code that another of your lists already uses returns 400.

​
Set the default word lists

The other checks in a scan, such as TLD swaps and common-word additions, use built-in word lists. Each check has a default list and a few alternatives. spoofguard_wordlists_defaults_list returns one entry per check: To change a default, send the check’s code as module_name and one of its wordlist_options as default_wordlist to spoofguard_wordlists_defaults_update:
The call returns the defaults of every check. A list outside the check’s wordlist_options returns 400, and the message names the allowed options. Your own word lists cannot be defaults: attach them to a scan instead. Defaults apply to every scan your organization starts or rescans after the change. Scans already finished keep their results.

​
Create a trusted-domain list

A trusted-domain list removes domains you own or trust from scan results, so they are not reported as look-alikes. The API calls it a whitelist. spoofguard_whitelists_create takes name (up to 512 characters, unique within your organization) and domains (1 to 1,000 entries):
The response carries the list’s id, which you attach to scans, plus a uid, name, domains and timestamps. Each entry matches in one of three ways: Write entries in lowercase. A matching domain is dropped from the scan’s results and counts and listed in the scan’s whitelisted_domains instead. Matching runs each time you read the scan, so an edit to the list changes every scan that uses it straight away. spoofguard_whitelists_update takes name, domains or both. domains replaces the whole list.

​
Attach items to a scan

Attach items when you start a scan. start_domain_analysis takes the IDs and the word-list code next to domain:
All four are optional. Scan an organization’s domain for look-alikes covers the rest of the call.
A domain with an existing scan ignores these fields. If acme.com already has a scan, start_domain_analysis returns that scan, or a 400 while it is still running, and attaches nothing. When every Monitored Assets slot is in use, it returns the capacity 409 instead, even for a domain you already scan. Attach items to the existing scan as shown below.
To change an existing scan:
1

Attach the logo, keywords and trusted domains

Send logo_id, branding_id, whitelist_id or any mix of them to analysis_update. Only the fields you send change.
A trusted-domain list applies straight away. The next read of the scan leaves out the domains it matches.
2

Rescan for the logo, keywords and word list

Call analysis_rescan. Pass wordlist_code in its body to add a word list. The rescan adds the Google Lens search when a logo is attached, and runs the logo and keyword checks over the regenerated candidates.
Rules for attaching:
  • You can swap an item, not detach it. Send another ID to replace an attached item. Leave a field out to keep the attached item. null or an empty value returns 400.
  • Deleting a logo, branding keyword set or trusted-domain list detaches it everywhere. Every scan that used it loses it.
  • Deleting a word list does not detach it. A scan that used it returns 400 on rescan until you pass another wordlist_code.
  • whitelist_domains adds single domains. Send a list of domains to analysis_update to add them to the scan’s trusted-domain list. If the scan has a list, the domains are added to it, which changes every scan that shares it. If not, the domains go to your list named after the domain’s name, acme for acme.com, which is created if needed and attached.
  • Unknown IDs are refused. An ID or code that is not in your library returns 400.
analysis_detail shows what a scan uses: logo, branding and whitelist hold the attached items, whitelisted_domains the domains they removed, and module_statuses the checks that did not run for lack of a logo or keywords.

​
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