Iris Enrich API Reference¶

Overview¶

The vast amount of data available in the Iris dataset for domain names makes it ideally suited to enrich proxy and DNS logs at scale across an organization. Typically this would be implemented in a SIEM solution, such as Splunk or QRadar, or a custom-built data analytics platform using open-source solutions like the ELK stack.

Key characteristics of the Iris Enrich API include:

Enrich at least 6,000 domains per minute with multiple attributes, including:
Domain risk scores from proximity and threat profile algorithms
RDAP, Whois, IP, active DNS, website & SSL data
Dedicated service levels for customized rate limiting
Optimized for domain name enrichment – pivot parameters not available

API Endpoint¶

The API returns JSON results and supports both POST and GET requests at this endpoint:

https://api.domaintools.com/v1/iris-enrich/

Authentication¶

The Iris Enrich API uses the same authentication mechanisms as the Iris Investigate API (open-key or signed). However, unlike the Investigate API, the Iris Enrich API uses an independent service level to define access levels, query caps and rate limits. It does not pull from the same queries as the Iris Investigate UI and can therefore be used at much greater scale and throughput. That means the API endpoint must be explicitly configured on an enterprise account.

Parameters¶

Because the Iris Enrich API is optimized for fast responses and high volume lookups, it does not offer most of the search parameters available in the Iris Investigate API. Instead, simply provide a list of up to 100 domains in the domain parameter (comma separated). For example:

https://api.domaintools.com/v1/iris-enrich/?domain=domaintools.com,domaintools.net

Response Format¶

The Iris Enrich API response format differs from the Investigate API in several key ways, including:

Counts of connected domains are not included
Most domain attribute values still appear under the “value” subkey for consistency with the Investigate API.
An additional “missing_domains” key is included which lists any domains submitted in the domains parameter that were not found in the Iris dataset. This makes it easier to know if no data was available for one or more of the domains you requested in a batch query.

Retrieve Screenshots in Iris APIs¶

Retrieve the most recent screenshot for a given domain with Iris APIs in a two-step process:

Retrieve the screenshot image URL
Retrieve and optionally resize the image file

Also consult the section on interpreting screenshot metadata, below.

1. Retrieve the Screenshot URL¶

Append queries with screenshots=1 to receive a screenshot JSON object in the response.

For example, the following Iris API queries (with header authentication) include screenshot requests.

Example Queries for Screenshot URL Retrieval¶

Iris Detect: https://api.domaintools.com/v1/iris-detect/domains/watched/?screenshots=1
Iris Enrich: https://api.domaintools.com/v1/iris-enrich/?domain=example.com&screenshots=1
Iris Investigate: https://api.domaintools.com/v1/iris-investigate/?domain=example.com&screenshots=1

Query Parameters for Screenshot URL Retrieval¶

Query Parameter	Required	Type	Valid Values	Description	Example
`screenshots`	yes	flag (1)	`1`	Triggers screenshot object in response.	`screenshots=1`

Response Fields for Screenshot URL Retrieval¶

Output field	Type	Valid Values	Description	Example
`ip_address`	string \| null	IP address	The IP address from which the screenshot was taken.	`212.129.31.169`
`last_attempt`	string	ISO 8601 date-time format	The date and time the screenshot was last attempted.	`2025-02-17T15:34:55Z`
`last_seen`	string	ISO 8601 date-time format	The date and time the screenshot was last observed	`2025-02-17T15:34:55Z`
`screenshot`	object	JSON object	Details about the screenshot.
`src`	str	URL	Link to the screenshot.	`https://screenshots.ne.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fespn.com&ts=2024-03-28T21%3A48%3A37Z&token=dec12499e06b61d17175c683387307c9b751c71fbbbd797b8e094c2c288f2b31`
`timestamp`	string	ISO 8601 date-time format	The date and time the provided screenshot (in `fullsize` field) was obtained.	`2024-08-05T16:17:45Z`

Response Example for Screenshot URL Retrieval¶

"screenshot": {
          "timestamp": "2025-03-07T19:53:44Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fdomaintools.com&ts=2025-03-07T19%3A53%3A44Z&token=2d6269e40f4bc48908b17d218e5647fc90c0034618e39ec20806910d3909785c",
          "ip_address": "141.193.213.21",
          "last_attempt": "2025-04-07T18:00:01Z",
          "last_seen": "2025-04-07T18:00:01Z"
        }

2. Retrieve and Optionally Resize the Screenshot Image via its URL¶

Use the src URL in the returned screenshot object to download the screenshot image. The URL already contains the required parameters domain, ts, rurl, and token. Optionally add resize_width and crop_height to resize the image.

Query Parameters for Screenshot Image File¶

Query Parameter	Required	Type	Valid Values	Description	Example
`resize_width`	no	integer	Width in pixels	If the value is less than the width of the image, the image will be shrunk horizontally to the given resize_width, preserving the aspect ratio.	`resize_width=500`
`crop_height`	no	integer	Height in pixels	If the value is less than the height of the image, the image will be cropped vertically to the given crop_height, removing pixels from the bottom of the image.	`crop_height=500`

Example Query for Screenshot Image File¶

api.domaintools.com/screenshot_image?domain=domaintools.com&ts=2025-04-30T14:32:10Z&resize_width=500&crop_height=500&rurl=https://www.domaintools.com/

Interpreting Screenshot Metadata¶

Use the last_attempt, last_seen, and timestamp to interpret the screenshot.

To confirm that the most recent screenshot was gathered during the current domain lifecycle—and isn't from an older, historic screenshot—compare the screenshot's timestamp with the domain's first_seen value in the API response. If the timestamp is later than first_seen, the screenshot was taken during the current domain lifecycle.

Initial capture¶

The screenshot was successfully captured during the first and only attempt. Since there have been no subsequent checks, all timestamp fields are identical.

Relationships: timestamp = last_seen = last_attempt

Response example:

        "screenshot": {
          "timestamp": "2025-05-12T14:38:19Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fxumi.fr&ts=2025-05-12T14%3A38%3A19Z&token=5fbd3aa604682d26d9f1f69810a87bfd75ea25e56eadb3553cefcff2ba804f28",
          "ip_address": "76.76.21.21",
          "last_attempt": "2025-05-12T14:38:19Z",
          "last_seen": "2025-05-12T14:38:19Z"
        }

Gather attempt was duplicate of initial screenshot¶

DomainTools re-checked a domain after previously taking an initial screenshot. The result was identical to the existing image and no new screenshot was generated.

Relationships: timestamp < last_seen = last_attempt

timestamp remains unchanged, preserving the original capture time.
last_attempt is updated to reflect the most recent screenshot check.
last_seen is updated to indicate the most recent time the image was confirmed valid.
Because no new image was needed, last_seen and last_attempt are equal.

Response example:

        "screenshot": {
          "timestamp": "2025-05-12T10:10:49Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fdomaintools.co.in&ts=2025-05-12T10%3A10%3A49Z&token=28d255010a09d1cc8a3326e1c1406971910293f09ddac0159eb35391f705be57",
          "ip_address": "104.219.250.192",
          "last_attempt": "2025-05-13T17:16:34Z",
          "last_seen": "2025-05-13T17:16:34Z"
        }

Recapture failed after previous successful capture¶

DomainTools successfully captured a screenshot on a previous attempt. The next attempt to capture the screenshot failed — the system was unable to retrieve a new image and could not confirm whether the content had changed.

Relationships: timestamp = last_seen, and last_seen < last_attempt

timestamp reflects the time the screenshot was originally captured.
last_seen is equal to timestamp, because that was the last time a screenshot was successfully observed
last_attempt is more recent than last_seen, but the attempt failed

Response example:

        "screenshot": {
          "timestamp": "2023-12-19T22:17:10Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Ffixhelpdesk.com&ts=2023-12-19T22%3A17%3A10Z&token=8cd6edb822594a0aa485e72f5cbb5414a73b657f7438b770844f46fe886c4ea9",
          "ip_address": "91.195.240.19",
          "last_attempt": "2025-05-13T10:25:04Z",
          "last_seen": "2023-12-19T22:17:10Z"
        }

Duplicate capture followed by failed attempt¶

A screenshot was captured, and subsequently re-captured as a duplicate. A subsequent attempt to refresh the (duplicate) screenshot failed.

Relationships: timestamp < last_seen, and last_seen < last_attempt

timestamp reflects the original screenshot date
last_seen is later than timestamp, indicating the image was revalidated as a duplicate on a later date
last_attempt reflects a more recent failed attempt to recapture the screenshot

Example response:

        "screenshot": {
          "timestamp": "2022-07-02T10:03:43Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fdomaintools.ca&ts=2022-07-02T10%3A03%3A43Z&token=6fa06c07ff1b7206ae8f38aadaf4e11b8cf538b7625944e2813a72ebec2c6648",
          "ip_address": "158.85.87.76",
          "last_attempt": "2025-05-13T10:12:04Z",
          "last_seen": "2024-05-22T10:11:09Z"
        }

Working with RDAP and WHOIS Registration Data¶

Domain registries and registrars are transitioning from WHOIS to the Registration Data Access Protocol (RDAP) as a method to communicate domain registration data.

In response, DomainTools is updating the Iris suite to support both WHOIS and RDAP registration data. These updates will be available in January 2025, prior to the date at which ICANN will permit gTLD registries and registrars to sunset WHOIS in their Registration Data Directory Services (RDDS).

Note that these changes apply to the subset of registration data and not other domain records provided in the responses.

New, Backward-Compatible Response Structure¶

Set parameters for parsed_whois=true and/or parsed_domain_rdap=true to return the parsed WHOIS and/or parsed RDAP record along with the default response. For example, a default query:

https://api.domaintools.com/v1/iris-enrich/?domain=github.com&api_username=USERNAME&api_key=KEY

This query returns standard registration data as part of the response root fields. Registration data is from either RDAP or WHOIS, depending on which record is more complete. Registration data is included at the same level as other domain data. For example:

response:
  limit_exceeded
  has_more_results
  message
  result_count
  total_count
  results
    domain
    whois_url
    adsense
    alexa
    popularity_rank
    ...

Include RDAP-specific and/or Whois-specific fields as their own objects, in addition to the regular response. For example, the same query but with both the full WHOIS and RDAP records specified:

https://api.domaintools.com/v1/iris-enrich/?domain=github.com&parsed_whois=true&parsed_domain_rdap=true&api_username=USERNAME&api_key=KEY

Registration data is included as before, but with additional root-level fields for parsed_whois and parsed_domain_rdap:

response:
  limit_exceeded
  has_more_results
  message
  result_count
  total_count
  results
    domain
    whois_url
    adsense
    alexa
    popularity_rank
    ...
    parsed_whois  # PARSED WHOIS FIELD
      registrant contact
      ...
    parsed_domain_rdap  # PARSED RDAP FIELD
      admin_contact
      ...

New, Backward-Compatible Response Field: Registrar IANA ID¶

The domain registrar's IANA ID is included in the RDAP object when the parsed_domain_rdap=true parameter is used in an API request.