Iris Detect API guide¶

Overview¶

The Iris Detect API enables automated workflows for discovering and triaging lookalike domains that impersonate your brands, partners, or infrastructure. Retrieve newly discovered domains, query watched domains, and programmatically escalate threats for blocking or submission to Google Web Risk. For a complete overview of Iris Detect capabilities and use cases, see the Iris Detect overview.

Iris Detect protects against malicious domains impersonating your brands and domains, safeguarding your organization, customers, and trademarks. You can also defend against supply chain attacks where malicious domains impersonate well-known technology vendors or partners you work with regularly.

Iris Detect discovers new domains appearing globally that mimic your brands. You can quickly see key information from DNS, WHOIS/RDAP, and the DomainTools Risk Score to assess the level of threat. Iris Detect also monitors domains over time so you can see how they evolve and take action as needed.

About Iris Detect APIs¶

The Detect API endpoints automate workflows and feed data from Iris Detect into other applications. Many actions performed via the Detect UI can be programmatically scheduled for convenience.

Functionality supported via APIs¶

Read: Retrieve data about discovered domains, monitors, and escalations
Write: Make changes such as adding a domain to the watchlist or escalating a domain for further action

Not supported by API¶

Monitor creation: All monitors must be created via the Iris Detect UI. Due to the iterative nature of this task, it's not supported via programmatic access at this time.
Event-based updates: There is no way to "subscribe" to changes. All updates must be retrieved by "pull" action. However, you can schedule email alerts for regular updates within the UI.

Getting started¶

Iris Detect requires an Enterprise account login on DomainTools, and your account must include Iris Detect access. Additionally, user permissions control whether users can manage monitors, triage domains, or escalate domains. By default, users have read-only access to the application.

To use the Detect APIs, you need your username and an API key.

Authentication¶

Consult the Iris API authentication options for details on the available authentication methods.

Authorization and permissions¶

API accounts require specific permissions to perform domain triage actions. These permissions must be configured by your account administrator.

Permission types¶

Depending on your account configuration, you may have different levels of access:

Read-only permissions: The account can only retrieve discovered domains but cannot perform triage actions. Accounts with read-only permissions don't have access to the add/remove to watchlist endpoint or escalation endpoints.
Read + write permissions: The account has full access to perform domain triage actions including:
Adding domains to the watchlist
Ignoring domains
Escalating domains (for internal blocking or to Google Safe Browsing)

Required permissions for API actions¶

To perform domain triage actions via the API, your API account must have the following permissions configured:

Add to watchlist: Required to add domains to your watchlist for ongoing monitoring
Ignore: Required to mark domains as false positives and remove them from active monitoring
Escalate: Required to escalate domains for internal blocking or to Google Safe Browsing

Note: The "manage monitors" permission is not relevant for API users, as monitor creation, editing, and deletion are only available through the Iris Detect user interface and cannot be performed via API.

If you need these permissions enabled for your API account, contact your account administrator.

API rate limits¶

Endpoints with special rate limits¶

Domains: The Domains endpoints can be queried with a frequency of up to once per hour for each the domains/new and domains/watched calls.
Pagination requests: Requests to get full domain lists are not restricted. For example, if the hourly call for new domains returns more than the limit of domains returned in a single response, the additional domains can be queried using the offset variable to complete the results without being impacted by the hourly restriction.

Bypassing rate limits during integration work¶

During integration of the domain API endpoints, including the preview parameter in requests limits the responses to just 2 domains but allows for up to 30 requests per minute. This enables rapid iteration during development and testing. (Use the preview parameter for development and testing only. Don't use it for sustained production queries. Sustained usage violates our Terms of Service and can result in service suspension.)

For complete information about Iris API rate limits across all products, consult the Iris API rate limits documentation.

Finding and resetting the API key¶

To find or reset the DomainTools API key via https://research.domaintools.com/:

Login to the DomainTools API Dashboard. Only the API owner account can reset the API key. There are two places to access this:

Select the Account menu and select the API Admin menu item to access the API Dashboard.
In the My Account section, select the View API Dashboard link that is located in the Account Summary tab.

DomainTools My Account Image

In the API Product Information tab, go to the section called API Username to obtain your username.
In the same tab, you can find your API Key.
To reset your API key:
Select the Reset API Key.
Creating a new key will cause the existing key to be discarded immediately. This action cannot be undone.
Any requests that are made with the old key will no longer validate for this user.

API endpoints¶

Monitor list¶

This endpoint allows users to retrieve the monitors and their respective IDs for your account. The monitor IDs can then be used to retrieve newly discovered or recently changed domains for individual monitors using the monitor_id variable.

You can also request new or changed domains across all monitors in a single request by not specifying the monitor_id variable. Since the endpoint is limited to 1 query request per hour, making a request for all monitors retrieves results for all monitors every hour. The monitor endpoint can still be used to help map domains to their monitor if that is important for the integration.

The include_counts variable shows the number of domains associated with the various categories such as New, Changed, etc. for each monitor.

You can sort and order the results with options such as term, creation date, created by, and others.

Endpoint URL¶

https://api.domaintools.com/v1/iris-detect/monitors

Method¶

GET

Conditionally required parameters¶

Name	Type	Valid values	Default values	Notes
`datetime_counts_since`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Conditionally required if the include_counts parameter is included.

Optional parameters¶

Name	Type	Valid values	Default values	Notes
`include_counts`	bool		false	Includes counts for each monitor for new, watched, changed and escalated domains
`sort`	string[]	term, created_date, domain_counts_changed, domain_counts_discovered	term	Provides options for sorting the monitor list.
`order`	string	asc, desc	desc	Toggles ordering for selected sort option.
`offset`	int	0-100000	0	For paginating requests beyond the limit.
`limit`	int	500		Restricted to maximum 100 if include_counts=true

Example usage¶

Retrieve all monitors with counts¶

GET https://api.domaintools.com/v1/iris-detect/monitors/?datetime_counts_since=2022-01-14%2016:27:31&include_counts=true &api_username=<username>&api_key=<API key>

Domains¶

The Domains endpoint enables users to retrieve details associated with domains for a specific monitor or all monitors. The endpoint can be used to view:

Newly discovered domains
Recently changed domains (with changes to key DNS and RDAP/WHOIS data tracked by the application)
Domains that have been recently escalated in the application, with the escalations being for internal blocking or for sending the domains to Google's Web Risk service.
Escalations can be triggered either directly in the application UX or via API (covered in the Escalation section below).

A number of optional parameters are made available to filter the results as needed.

The /new endpoint can provide newly discovered domains for monitors created in Iris Detect.

The /watched endpoint provides recently changed domains for the domains from a monitor's list of watched domains. (Domains can be selected for watching from either the Iris Detect UX or via API, discussed below.)

The /watched endpoint can also be used to query for domains that have been escalated for blocking or to Google Safe browsing. (Domains can be escalated either from the Iris Detect UX or via API, discussed below).

Endpoint URL¶

https://api.domaintools.com/v1/iris-detect/domains/new/
https://api.domaintools.com/v1/iris-detect/domains/watched/

Method¶

GET

Required parameters¶

None

Optional parameters¶

Name	Type	Valid values	Default values	Notes
`monitor_id`	string			Monitor ID from the monitors response – only used when requesting domains for specific monitors.
`escalation_types`	string[]	blocked, google_safe		Filters on specific escalation types
`tlds`	string[]	Use tlds[]= for each TLD. Do not combine TLDs in a single tlds[] parameter.		Filters on one or multiple TLDs
`risk_score_ranges`	string[]	0-0, 1-39, 40-69, 70-99, 100-100		Filters on domains with a risk score in different ranges.
`mx_exists`	boolean			Whether domain currently has an MX record in DNS.
`domain_state`	string	active, inactive
`discovered_before`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Can be used with `discovered_since` to define a complete date/time window. Exclusive.
`discovered_since`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Can be used with `discovered_before`. Relevant for the `/new` endpoint to control the timeframe for when a new domain was discovered. Inclusive.
`changed_before`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Most relevant for the `/watched` endpoint to control the timeframe for changes to DNS or WHOIS/RDAP fields for watched domains.
`changed_since`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Most relevant for the `/watched` endpoint to control the timeframe for changes to DNS or WHOIS/RDAP fields for watched domains.
`escalated_since`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Most relevant for the `/watched` endpoint to control the timeframe for when a domain was most recently escalated.
`search`	string			A "contains" search for domain name.
`sort`	string[]	discovered_date, changed_date, risk_score		Sort order of domain list response.
`order`	string	asc, desc		Ordering options for sorting
`include_domain_data`	boolean			Includes DNS and RDAP/WHOIS details.
`screenshots`	flag	1		Set to `1` to include screenshot data in the response. See working with screenshots for details.
`offset`	int	0-100000	0	For paginating requests beyond the response limit. No other parameter values can change when paginating.
`limit`	int	0-100 or 0-50 if include-domain-data=true	0	Limits result size.
`preview`	boolean			Use during API implementation and testing. Including with value = 1 will limit results to 2 but not be limited by hourly restrictions. For development and testing only; sustained usage violates Terms of Service.

Example usage¶

Note that date/time format follows ISO-8601. Not including a timezone indicator will be assumed to be in Pacific Time Zone.

Retrieve newly discovered domains since a specific date/time for Pacific Standard Time with millisecond precision¶

GET https://api.domaintools.com/v1/iris-detect/domains/new/?discovered_since=2022-01-12%2000:00.000000%20-08:00&api_username=<username>&api_key=<API key>

Retrieve all watched domains that changed within a given set of dates¶

GET https://api.domaintools.com/v1/iris-detect/domains/watched/?api_key=<api_key>&api_username=<username>&discovered_since=2023-01-01&discovered_before=2024-01-01

Retrieve domain that have been escalated for internal blocking since a specific date/time for Pacific Standard Time¶

GET https://api.domaintools.com/v1/iris-detect/domains/watched/?escalated_since=2022-01-11%2016:00:00%20-08:00&api_username=<username>&api_key=<API key>&escalation_types[]=blocked

Retrieve domains when results exceed response limit of 100 results using offset parameter¶

Example shows subsequent call for second group of 100 domains

GET https://api.domaintools.com/v1/iris-detect/domains/new/?offset=100&api_username=<username>&api_key=<API key>

Ignored domains¶

The Ignored Domains endpoint enables users to retrieve details about domains that have been marked as ignored (false positives) across their monitors. When a domain is marked as ignored, it's removed from active monitoring and no longer generates alerts. This endpoint allows you to review ignored domains and, if needed, move them back to your watchlist.

Like the other domain endpoints, you can retrieve ignored domains for a specific monitor or across all monitors. Various optional parameters are available to filter and search the results.

Endpoint URL¶

https://api.domaintools.com/v1/iris-detect/domains/ignored/

Method¶

GET

Required parameters¶

None

Optional parameters¶

Name	Type	Valid values	Default values	Notes
`monitor_id`	string			Monitor ID from the monitors response – only used when requesting domains for specific monitors.
`tlds`	string[]	Use tlds[]= for each TLD. Do not combine TLDs in a single tlds[] parameter.		Filters on one or multiple TLDs
`risk_score_ranges`	string[]	0-0, 1-39, 40-69, 70-99, 100-100		Filters on domains with a risk score in different ranges.
`mx_exists`	boolean			Whether domain currently has an MX record in DNS.
`domain_state`	string	active, inactive
`discovered_before`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Can be used with `discovered_since` to define a complete date/time window. Exclusive.
`discovered_since`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Can be used with `discovered_before` to control the timeframe for when a domain was discovered. Inclusive.
`changed_since`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Filters domains based on when they were last changed.
`escalated_since`	datetime OR integer	ISO-8601 date/time format for absolute time OR a negative integer for the (relative) number of seconds ago.		Filters domains based on when they were most recently escalated.
`search`	string			A "contains" search for domain name.
`sort`	string[]	discovered_date, changed_date, risk_score		Sort order of domain list response.
`order`	string	asc, desc		Ordering options for sorting
`include_domain_data`	boolean			Includes DNS and RDAP/WHOIS details.
`offset`	int	0-100000	0	For paginating requests beyond the response limit. No other parameter values can change when paginating.
`limit`	int	0-100 or 0-50 if include-domain-data=true	0	Limits result size.
`preview`	boolean			Use during API implementation and testing. Including with value = 1 will limit results to 2 but not be limited by hourly restrictions. For development and testing only; sustained usage violates Terms of Service.

Example usage¶

Retrieve all ignored domains¶

GET https://api.domaintools.com/v1/iris-detect/domains/ignored/?api_username=<username>&api_key=<API key>

Retrieve ignored domains for a specific monitor¶

GET https://api.domaintools.com/v1/iris-detect/domains/ignored/?monitor_id=JKwjv5Xp8x&api_username=<username>&api_key=<API key>

Retrieve ignored domains discovered within a specific timeframe¶

GET https://api.domaintools.com/v1/iris-detect/domains/ignored/?discovered_since=2023-01-01&discovered_before=2024-01-01&api_username=<username>&api_key=<API key>

Search for specific ignored domains¶

GET https://api.domaintools.com/v1/iris-detect/domains/ignored/?search=example&api_username=<username>&api_key=<API key>

Add and remove from watchlist¶

Analyzing and triaging newly discovered domains is an activity that should be done regularly, so New domains only show recently discovered domains. Triage options include:

Add to watchlist: Adding a domain to the Watchlist removes it from New and allows tracking of when domains most recently changed in DNS or WHOIS/RDAP. Watched domains will have screenshots captured daily so you see how the webpage evolves over time.
Ignore: If a domain is obviously a false positive, Ignoring the domain removes it from New and places it under Ignored. The decision can always be reversed and the domain can be moved from Ignored to Watched instead.

Endpoint URL¶

https://api.domaintools.com/v1/iris-detect/domains/

Method¶

PATCH

Required parameters¶

Name	Type	Valid values	Default value	Notes
watchlist_domain_ids	string[]			ID(s) of domains being triaged.
state	string	watched, ignored		Add domains to Watchlist or ignore and mute alerts for those domains.

Optional parameters¶

None

Example usage¶

Add domain to watchlist¶

URL:

https://api.domaintools.com/v1/iris-detect/domains/?api_username=<username>&api_key=<API key>

Body:

{
  "watchlist_domain_ids": ["<domain ID>"],
  "state": "watched"
}

Remove domain from watchlist¶

URL

https://api.domaintools.com/v1/iris-detect/domains/?api_username=<username>&api_key=<API key>

Body:

{
  "watchlist_domain_ids": ["<domain ID>"],
  "state": "ignored"
}

Escalate¶

Two escalation activities are supported for the API as shown below.

Escalating a New domain will also add it to be Watched for changes.

Domains can be sent to Google Web Risk. If Google agrees the domain is malicious, it will be blocked in Chrome browsers globally. This list is also picked up by Apple for their Safari browser and Firefox.
Domains can be marked for Blocking if they are to be blocked in internal network defense infrastructure. Loading a domain into a company's firewalls and other systems needs to take place via API query combined with a system action on the customer end.
Limits for escalation request API calls
- Blocked domains: A maximum of 100 domains per request.
- Google Web Risk: A maximum of 10 domains per request.
- There is a limit of 30 requests per minute (each request can include multiple domains per above).

Endpoint URL¶

https://api.domaintools.com/v1/iris-detect/escalations/

Method¶

POST

Required parameters¶

Name	Type	Valid values	Default value	Notes
watchlist_domain_ids	string[]			ID(s) of domains to be escalated
escalation_type	string	blocked, google_safe

Optional parameters¶

None

Example usage¶

Escalate to Google Safe Browsing¶

URL:

https://api.domaintools.com/v1/iris-detect/escalations/?api_username=<username>&api_key=<API key>

Body:

{
  "watchlist_domain_ids": ["<domain ID>"],
  "escalation_type": "google_safe"
}

Escalate for internal blocking¶

URL:

https://api.domaintools.com/v1/iris-detect/escalations/?api_username=<username>&api_key=<API key>

Body:

{
  "watchlist_domain_ids": ["<domain ID>"],
  "escalation_type": "blocked"
}

Working with screenshots¶

You can retrieve domain screenshots through the Iris Detect API by adding the screenshots=1 parameter to your domain requests. For detailed information about retrieving, resizing, and interpreting screenshot data, see working with screenshots in Iris APIs.

Appendix: API response examples¶

Monitor list example¶

This is a sample of the response from a query to the Monitor List endpoint, preceded by the request:

Request example¶

GET https://api.domaintools.com/v1/iris-detect/monitors/?datetime_counts_since=2022-01-20%2011:03:21&include_counts=true&api_username=<username>&api_key=<API key>

Response example¶

This is a sample of the response, including counts for each monitor:

{
    "total_count": 16,
    "offset": 0,
    "limit": 500,
    "monitors": [
      {
            "term": "domaintools",
            "match_substring_variations": true,
            "nameserver_exclusions": [],
            "text_exclusions": [],
            "id": "JKwjv5Xp8x",
            "created_date": "2022-01-15T00:32:04.418134+00:00",
            "updated_date": "2022-01-15T00:32:04.418134+00:00",
            "state": "active",
            "status": "completed",
            "domain_counts": {
                "new": 2,
                "watched": 5,
                "escalated": 1,
                "changed": 2
            },
            "created_by": "<username>"
        }
  ]
}

Domain list example¶

The following example is for querying domains/new endpoint, the results would be the same for the domains/changed endpoint for querying either changed domains or domains that have been escalated since a given date/time.

Request example¶

The request includes the boolean variable to include domain data for key fields for DNS and WHOIS/RDAP.

GET https://api.domaintools.com/v1/iris-detect/domains/new/?discovered_since=2022-01-20%20%2009:40:12.000000%20-08:00&api_username=<username>&api_key=<API key>&include_domain_data=1

Response example¶

This is an example of the response, including details for DNS and WHOIS/RDAP data. Note the "risk_score_status": "provisional" field used to indicate a partially example of the response, including details for DNS and WHOIS/RDAP data. The risk score status indicates whether the scoring is provisional or full. Newly discovered domains will have initial proximity or phishing scores within a few minutes and the score is designated as provisional. Full risk scoring (across all 4 algorithms including malware and spam) is typically available within 15-20 minutes of discovery. Risk scores are also updated when significant changes are detected to a domain's DNS records or other attributes. All active domains continue to be scored daily.

{
    "watchlist_domains": [
     {
            "state": "new",
            "domain": "bestanbanks.in",
            "status": "active",
            "discovered_date": "2022-01-20T20:26:14.378000+00:00",
            "changed_date": "2022-01-20T20:27:58.000000+00:00",
            "risk_score": 67,
            "risk_score_status": "provisional",
            "risk_score_components": {
                "proximity": 21,
                "threat_profile": {
                    "phishing": 67
              }
            },
            "mx_exists": true,
            "tld": "in",
            "id": "8avjyB1Xaj",
            "escalations": [
                {
                    "escalation_type": "blocked",
                    "id": "p6db6jQbVJ",
                    "created": "2022-01-07T16:44:40.491903+00:00",
                    "created_by": "<username>"
                }
            ],
            "monitor_ids": [
                "Y41pGXBjEq"
            ],
            "name_server": [
                {
                    "host": "dimitris.ns.cloudflare.com"
                },
                {
                    "host": "zainab.ns.cloudflare.com"
                }
            ],
            "registrant_contact_email": [
                "please contact the registrar listed above"
            ],
            "registrar": "GoDaddy.com, LLC",
            "create_date": 20220120,
            "ip": [
                {
                    "country_code": "US",
                    "ip": "172.67.192.30",
                    "isp": "CloudFlare Inc."
                },
                {
                    "country_code": "US",
                    "ip": "104.21.81.241",
                    "isp": "CloudFlare Inc."
                }
            ],
            "mx": [
                {
                    "host": "mx1.hostinger.in"
                },
                {
                    "host": "mx2.hostinger.in"
                }
            ]
        }
      ],
    "total_count": 1,
    "count": 1,
    "offset": 0,
    "limit": 100
}

Add domain to be watched example¶

This request is for adding a domain to the account's Watchlist. A similar request is used to ignore domains, using the "state" : "ignored" instead of "state" : "watched".

Request example¶

Request URL:

PATCH https://api.domaintools.com/v1/iris-detect/domains/?api_username=<username>&api_key=<API key>

Request Body:

 {
  "watchlist_domain_ids": ["AaLMA1oOE0"],
  "state": "watched"
}

Response example¶

{
    "watchlist_domains": [
        {
            "state": "watched",
            "domain": "facebook-09835.pl",
            "discovered_date": "2022-01-20T18:35:29.801000+00:00",
            "changed_date": "2022-01-20T18:57:34.000000+00:00",
            "id": "AaLMA1oOE0",
            "assigned_by": "<username>",
            "assigned_date": "2022-01-20T22:27:39.000000+00:00"
        }
    ]
}

Escalate a domain for blocking example¶

This request is for escalate a domain for internal blocking. A similar request is used to escalate domains to Google Safe Browsing using the "escalation_type" : "google_safe" instead of "escalation_type" : "blocked".

Request example¶

URL requested:

POST https://api.domaintools.com/v1/iris-detect/escalations/?api_username=<username>&api_key=<API key>

Request body:

{
  "watchlist_domain_ids": ["AaLMA1gOE0"],
  "escalation_type": "blocked"
}

Response example¶

```json { "escalations": [ { "watchlist_domain_id": "AaLMA1gOE0", "escalation_type": "blocked", "id": "BWdgkK8g6p", "created_date": "2022-01-20T23:25:48.990908+00:00", "updated_date": "2022-01-20T23:25:48.990908+00:00", "created_by": "" } ] }