API Documentation

Iris Detect

Overview

Introduction
- About Iris Detect APIs
Getting Started
API Limits
- Bypassing Rate Limits During Integration Work
Authentication
Authorization
List of API Endpoints
Appendix 1: Examples of API Responses

Introduction

Iris Detect protects against malicious domains impersonating your brands and domains so you can safeguard your organization, your customers, and your trademarks. You can also defend against supply chain attacks where malicious domains impersonate either well-known technology vendors or even partners you work with on a regular basis. Iris Detect does this by discovering new domains appearing globally that mimic your brands. You can quickly see key information from DNS, Whois and the DomainTools Risk Score to easily access the level of threat. Iris Detect also monitors domains over time so you can see how they evolve, and then lets you take action as needed.

About Iris Detect APIs

A number of the actions performed via the Detect UI can be programmatically scheduled for convenience. The Detect APIs enable automating your workflow further and feeding data from Iris Detect into your existing applications.

Functionality Supported via APIs:

Read: Retrieve data
Write: Make changes such as adding a domain to the watchlist or escalating a domain for further action.

Not supported by API in Version 1.0

Monitor Creation: All monitors need to be created via the Iris Detect UI. Due to the nature of this task and how iterative it can become, it will not be supported via programmatic access at this time.
Screenshots: Screenshot retrieval is not supported via API at this time.
Event-Based Updates: There is no way to “subscribe” to changes, all updates need to be retrieved by “pull” action.

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 escalated domains. By default, users have read-only access to the application. For using the Detect APIs you will also need your username as well as an API Key.

API 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 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 the preview parameter in requests will limit the responses to just 10 domains but allows for up to 30 requests per minute. This enables rapid iterative during development and testing.

Authentication

We recommend the following practices for authentication:

Authentication with HTTPS (HTTP over SSL) instead of HTTP.
Using HMAC signed queries instead of Open Key Authentication.
Using SHA-256 HMAC for the signed queries instead of MD5 or SHA-1.
Ensuring a safe process to protect your API credentials.

Authorization

Depending on your account type, you may have the ability to only retrieve the latest discovered domains and or add said domains to the watchlist for ongoing monitoring and analysis.

Read-Only Permissions: The account will not have permissions to the add/remove to watchlist endpoint.
Read + Write Permissions: The account will have all existing permissions.

Finding and Resetting the API Key

To find or reset the DomainTools API key via https://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.

Select the Reset button to confirm.

Protecting API Credentials

Your account will be charged for all queries authenticated with your username and key, even if you later determine the requests were fraudulent or its use unauthorized. We recommend the following steps to protect your API credentials:

For support requests, do not send the full API key to DomainTools support.
Use a HMAC-signed approach to requests. This ensures that the user and token are not sent as part of the URL.
When required, reset the API key.
Do not place them into a public repository, such as a git repository.

HMAC-Signed Authentication URI/Parameters

Parameter/URI	Value
URI	The URI for the API endpoint. It sits after api.domaintools.com e.g. /v1/yourdomain.com/whois.Check the User Guide for each DomainTools API product for the correct URI formation.
api_username	Your API username.
timestamp	Current timestamp, in ISO 8601 format. Timestamps should contain the timezone offset, like below: 2020-02-01T14:37:59-0800 2020-02-01T22:37:59Z 2020-02-02T10:37:59+1200
signature	HMAC signature of your request. SHA-256 HMAC is recommended. MD5 HMAC and SHA-1 HMAC are supported. Only sign the URL path.

Building a HMAC-Signed Authentication Request

About HMAC

HMAC, or hashed message authentication code, is the recommended authentication scheme. It follows the principles outlined in RFC2104 and provides a straightforward but secure method of protecting your API key.

About the HMAC Algorithms

MD5, SHA-1, and SHA-256 are supported HMAC hashing algorithms. We recommend SHA256 HMAC, as a successor of SHA1. Although NIST policy on hash functions still allows HMAC SHA-1, see Hash Functions in the NIST CSRC page. Overall, SHA-256 HMAC is also a more secure (ex, against brute force attacks) alternative to MD5 HMAC.

Please check your own compliance obligations, or guidance, as to what cryptographic functions should be used. For example, see the NIST FIPS 140-2 Guidance for more information for organizations that must use FIPS 140-2 compliant algorithms.

Creating a HMAC-signed authentication request

To create the signature, build a string with your API username, the timestamp in ISO 8601 format, and the URI you are requesting. That string is then signed with your API key using an HMAC function to generate the signature. The steps are below.

Add your api_username.

The API username is the account that has been provisioned access to the relevant DomainTools API product (aka API endpoint). If this username does not have access rights, an error message will be returned.

Associate a timestamp.

The timestamp value for the hash and timestamp parameter need to be identical. Make sure your server time is accurate and always use a fresh timestamp.

Add the request URI.

Please see the individual API product User Guides for the endpoint’s URI format.

Add the host.

The host is the API endpoint server. In this case, it is api.domaintools.com.

Use the appropriate HMAC algorithm.

MD5, SHA-1, or SHA-256 for the hashing algorithm are supported. See the HMAC Algorithms section for more information.

Below is an example used to return a SHA-256 HMAC signed hashed request with your api_username, timestamp, URI, api_key. You will likely find built-in support for HMAC authentication in your preferred programming language.

return hash_hmac('sha256', $this->api_username . $timestamp . $uri, $this->api_key);

The result is a request that expires after a brief period of time and, most importantly, does not contain your authentication key in the clear.

The resulting URLs will generally be similar, regardless of whichever programming language is used.

Security Note

Ensure that your current language version supports the required HMAC (and other relevant) extensions and libraries. For example, a failure in HMAC-signed URL will result in a URL with no signature value, such as below:

http://api.domaintools.com/v1/yourdomain.com/whois

List of API Endpoints

Monitor List

As the name specifies, this endpoints allows users to retrieve the monitors and 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. On the other hand, you can also request new or changed domains across all monitors in a single request by not specifying the monitor_id variable. Since the domains endpoint is limited to 1 query request per hour, doing requests for all monitors allows retrieving 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 will show the number of New, Changed, etc. for each monitor.

It’s possible to sort and order the results with options such as term, creation date, created by, and others. The required and optional parameters are outlined below.

The /ignored endpoint allows you to view domains you have ignored.

Endpoint URL

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

Method

GET

Parameters

Conditionally Required

Name	Type	Valid values	Default values	Notes
datetime_counts_since	datetime			Conditionally required if the include_counts parameter is includedISO-8601 date/time format

Optional

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 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 Phishing Protection 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 will provide 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

Parameters

Required

None

Optional

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[]=<TLD> 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	ISO-8601 date/time format		Can be used with `discovered_since` to define a complete date/time window. Exclusive.
discovered_since	datetime	ISO-8601 date/time format		Can be used with `discovered_before`. Relevant for the `/new` endpoint to control the timeframe for when a new domain was discovered. Inclusive.
changed_since	datetime	ISO-8601 date/time format		Most relevant for the `/watched` endpoint to control the timeframe for changes to DNS or Whois fields for watched domains.
escalated_since	datetime	ISO-8601 date/time format		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 Whois details.
offset	int	0-100000	0	For paginating requests beyond the limit.
limit	int	100 50 if include-domain-data=true	100 50 if include-domain-data=true	Limits result size.
preview	boolean			Use during API implementation and testing.Including with value = 1 will limit results to 10 but not be limited by hourly restrictions.

Example Usage

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

Examples of the response data can be found in the appendixes of this document.

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

Add & 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. 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

Parameters

Required

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

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’s Phishing Protection team. 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 Phishing Protection: 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

Parameters

Required

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

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"
}

Appendix 1: Examples of API Responses

Monitors List Response 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 Response 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.

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 data. Note the “risk_score_status": "provisional" field used to indicate a partially example of the response, including details for DNS and Whois data. The risk score status indicates whether the scoring is provisional or full. Newly discovered domains will have only initial proximity or phishing scores and the score is designated as provisional. After 24-36 hours, a full risk score is calculated and adds malware and spam scoring values.

{
    "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

{
    "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": "<username>"
        }
    ]
}