Skip to content

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

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

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

Example Query

https://api.domaintools.com/v1/iris-investigate/?search_hash=ENCODED_SEARCH_STRING

Example with cURL

curl -X GET \
  'https://api.domaintools.com/v1/iris-investigate/?search_hash=ENCODED_SEARCH_STRING' \
  -H 'X-Api-Key: YOUR_API_KEY'

Workflow

  1. User conducts investigation in Iris Investigate UI
  2. Builds complex query with multiple pivots

  3. Refines results using UI features

  4. User exports search hash

  5. Accesses Advanced Search

  6. Copies encoded search string

  7. Your application receives search hash

  8. User provides encoded string to your integration

  9. Your application stores or processes the hash

  10. Your application queries the API

  11. Constructs API call with search_hash parameter

  12. Receives up-to-date results matching the UI search

  13. Your application processes results

  14. Displays, analyzes, or stores the domain data
  15. Applies additional business logic as needed

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