Searching

The search API has been developed to provide as little friction as possible, in order to facilitate the extraction of data at scale for purposes such as automation or integrations with other apps. In this section you may learn how to correctly use and consume the various endpoints.

Using the Search API

Generally, you should start by obtaining the size and cost of the query and available search tokens at /v1/search/count. For that, you simply need to execute a POST request with the Authorization and Content-Type headers and JSON query parameter in the body.

POST https://api.intelsentry.io/v1/search/count
Authorization: Bearer <token>
Content-Type: application/json
 
{
    "query": "example.com"
}

HTTP/1.1 200
Content-Type: application/json
 
{
    "status": 200,
    "count": 30797,
    "cost": 16,
    "searches_left": 1500
}

After parsing the count, cost, and searches_left JSON keys, you should now know whether you can (and want) to execute the full query.

With this, you can now proceed with the actual query at /v1/search. There are three modes of operation, depending on your desired granularity.

POST https://api.intelsentry.io/v1/search
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "query": "example.com"
}

POST https://api.intelsentry.io/v1/search
Authorization: Bearer <token>
Content-Type: application/json
 
{
    "query": "example.com",
    "full_search": true
}

POST https://api.intelsentry.io/v1/search
Authorization: Bearer <token>
Content-Type: application/json
 
{
    "query": "example.com",
    "pages": 2
}

In these examples, Request 1 will always consume only 1 search token, and get the amount of results depending on your max results (e.g. 2000 for Researcher PRO).

On the other hand, Request 2 will consume as many tokens as needed to extract all results, indicated by the "full_search": true body parameter.

Finally, Request 3 tells the API the number of tokens you want to spend in the "pages": x body parameter, extracting x * max_results results, with x ∈ [1, ⌈results_size/results_per_token⌉]. Remember that you previously got the ⌈results_size/results_per_token⌉ value from the cost JSON key in /v1/search/count.

Note that you cannot provide both full_search and pages body parameters in the request. Similarly, providing "full_search": false or "pages": 1 is useless.

Consuming the Search API

No matter what type of request you choose, the response by the API will always contain the same format.

HTTP/1.1 200
Content-Type: application/json
 
{
    "results": [
    "https://account.example.com/ResetPassword.aspx:redacted:redacted",
    "https://login.example.com/:redacted@gmail.com:redacted",
    "https://login.example.com/Login.aspx:redacted@gmail.com:redacted"
    ],
    "status": 200,
    "results_count": 3,
    "max_results_count": 3,
    "cost": 1,
    "tokens_left": 1499
}

HTTP/1.1 200
Content-Type: application/json
 
{
    "status": 200,
    "results_count": 0,
    "max_results_count": 0,
    "cost": 0,
    "tokens_left": 1499,
    "results": null
}

Depending on whether there are search results or not, the results JSON key will contain an array of strings, which is the actual data, or be null.

On the other hand, the other JSON keys will help you understand the result of the operation.

• cost: The amount of search tokens that has been deducted from your account after the search.
• tokens_left: The amount of search tokens left after the deduction of the search cost.
• results_count: The number of results extracted from the search i.e. an array of 3 strings in the results key means a results_count of 3.
• max_results_count: The actual size of the query, would it be fully executed with all the needed search tokens.
• status: The status code of the response, replicated from the HTTP status code.

In any case, if there were no results from the search, your account will not be deducted any tokens.