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.

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 parsedwhois=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.