Skip to main content
Version: Next

Retrieve your results

POSThttps://app.icypeas.com/api/bulk-single-searchs/read

We store each of your results into what we call a search item. When you do a single search, there is one search item linked to your single search. When you do a bulk search, you have as many search items as the number of rows in your data.

Search items are precise description of a result. It contains:

  • The found email(s).
  • The status of the search.
  • The firstname / lastname of the person (if found).
  • The level of verification.
  • ...
tip
  • You cannot retrieve more than 100 results per request.
  • The route is paginated, if you don't know how to handle pagination, please read here.
  • We apply a rate limits on all routes, please see here.

Fetch a single result using id:​

Everytime you do a single search, a _id is returned:

{
    "success": true,
    "item": {
        "_id": "kMnquYkBTs8kZM9ND26h",
        "status": "NONE",
    }
}

Then, to retrieve the whole result, call this route with that _id:

{
    "id": "kMnquYkBTs8kZM9ND26h"
}

You'll get the result you're looking for.

This also works with bulk search' results, if you want to fetch a single search item within your bulk.

Fetch single searches:​

To get all your single searches, call the route with:

{
    "mode": "single"
}

You can also filter the single searches by task (email-search, domain-scan, email-verification, ...):

{
    "mode": "single",
    "type": "email-search"
}
tip

Returned data are sorted by date of creation, so the latest searches are at the top of list.

Everytime you do a bulk search, a file id is returned:

{
    "success": true,
    "file": "kMnquYkBTs8kZM9ND26h",
    "status": "in_progress",
}

Then, to retrieve the searches in your bulk, call this route with that file:

{
    "mode": "bulk",
    "file": "kMnquYkBTs8kZM9ND26h"
}

You'll get the results you're looking for.

tip

Returned data are sorted by insertion order, it corresponds to your data array.

Extract results from all bulk searches:​

To get all your bulk searches, call the route with:

{
    "mode": "bulk"
}
caution

You cannot use the type parameter when using mode bulk.

tip

Returned data are sorted by creation date and then order. If you've enqueued many bulk searches (almost) concurrently, the results will be not be grouped together. Use the file field to know to which bulk the result is linked.

Body parameters and possible responses​

If you need all the specifications for this route, see below.

POSThttps://app.icypeas.com/api/bulk-single-searchs/read
Get results from single or bulk searches
BODY PARAMS
modestring(single or bulk)

Type of searches ('bulk' for bulk searches, 'single' for single searches)

idstring(existing id)

The _id of the item you want to fetch

filestring(has to be a valid fileId)

The file id for your bulk. Useful when you want to retrieve only the searches for a given bulk

limitnumber(default value is 10, max value is 100)

Number of results to fetch

nextboolean

If you want to paginate, use this field. true = next page | false = previous page

sortsarray

Array used to paginate your files, it is this item you need to pass to your requests to fetch the next page

sort item*number

Tuples of (number, string)

/api/bulk-single-searchs/read
{
    "mode": "bulk",
    "limit": 50,
    "file": "#FILEID#"
}
RESPONSES