Skip to content
DomainTools Technical Documentation

Integrate with Iris Investigate UI

The Iris Investigate Platform offers a rich UI to search and pivot through domain name data. Nearly all the data in the Iris Investigate “Pivot Engine” pane is accessible in the Iris Investigate API, and the most common research patterns can be easily accomplished with that API.

When to Use UI Integration

Section titled “When to Use UI Integration”

However, even with these capabilities in the API, there remains a number of scenarios where users can only meet their goals with the complete set of tools and resources offered in the Iris Investigate UI. These scenarios include:

  • “OR” searches, or nested “AND” and “OR” searches across multiple fields and values
  • Ad-hoc investigations into a single domain’s hosting, WHOIS, or screenshot history
  • Graph visualization and graph-initiated pivoting
  • Passive DNS queries on IPs and hostnames

That means users may start their investigation in the Iris Investigate UI, but then expect to bring the results of their investigation into a third-party product. The search_hash parameter in the API makes this possible.

How It Works

Section titled “How It Works”

First, a user conducts an investigation in the Iris Investigate UI, potentially building a complex query to find all the connected infrastructure for a given domain name or threat actor. They access the Advanced Search in Iris Investigate and export the encoded representation of their search.

Next, the user provides this encoded string to your solution, and you craft an Iris Investigate API search with that string in the search_hash parameter. No other search parameters are required or supported (except the essential authorization parameters that should always be present). The Iris API “unpacks” the encoded search, runs the same query again, and returns the most up-to-date complete result set.

Using the search_hash Parameter

Section titled “Using the search_hash Parameter”

Example Query

Section titled “Example Query”
https://api.domaintools.com/v1/iris-investigate/?search_hash=ENCODED_SEARCH_STRING

Example with cURL

Section titled “Example with cURL”
curl -X GET \
  'https://api.domaintools.com/v1/iris-investigate/?search_hash=ENCODED_SEARCH_STRING' \
  -H "X-Api-Key: $DOMAINTOOLS_API_KEY"

Workflow

Section titled “Workflow”

  1. User conducts investigation in Iris Investigate UI

    • Builds complex query with multiple pivots
    • Refines results using UI features

  2. User exports search hash

    • Accesses Advanced Search
    • Copies encoded search string

  3. Your application receives search hash

    • User provides encoded string to your integration
    • Your application stores or processes the hash

  4. Your application queries the API

    • Constructs API call with search_hash parameter
    • Receives up-to-date results matching the UI search

  5. Your application processes results

    • Displays, analyzes, or stores the domain data
    • Applies additional business logic as needed

Benefits

Section titled “Benefits”
  • Leverage UI capabilities: Users can use advanced UI features not available in the API
  • Seamless integration: Transfer complex searches from UI to API without reconstruction
  • Always current: API re-runs the query to provide the most up-to-date results
  • Simplified development: No need to replicate complex UI search logic in your integration

See Also

Section titled “See Also”