Read search results

Every search you run, single or bulk, produces a search item: the input, the status, and the emails found. This endpoint gives them back to you.

Good to know

Up to 100 results per call.
Limited to 30 calls per minute: wait at least 3 seconds between calls. Webhooks avoid this limit entirely.
Long lists are paginated. See Pagination.

Get one result

The most common use. Send the _id you received when you started the search:

{ "id": "kMnquYkBTs8kZM9ND26h" }

This also works for a single row of a bulk search.

List your single searches

{ "mode": "single" }

Filter by task with type (email-search, email-verification, domain-search):

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

Newest first.

List the rows of a bulk search

Send the file id you got from /bulk-search:

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

Rows come back in the same order as your data array.

List the rows of all your bulk searches

{ "mode": "bulk" }

Sorted by creation date then row order. Rows of bulk searches started at the same time can be mixed: use their file field to group them. type can't be used with mode: "bulk".

Where is the email?

items[0].status                       → is it finished? see /statuses
items[0].results.emails[0].email      → the email
items[0].results.emails[0].certainty  → how reliable it is, see /certainties
items[0].userData.externalId          → your own id, if you sent one

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

Get results from single or bulk searches

Headers

Authorizationstringrequired
Your API key, as is (no Bearer prefix).
Content-Typestringrequired
Always application/json.

Body parameters

modestringoptional
Type of searches ('bulk' for bulk searches, 'single' for single searches)
Rule: single or bulk
idstringoptional
The _id of the item you want to fetch
Rule: existing id
filestringoptional
The file id for your bulk. Useful when you want to retrieve only the searches for a given bulk
Rule: has to be a valid fileId
limitnumberoptional
Number of results to fetch
Rule: default value is 10, max value is 100
nextbooleanoptional
If you want to paginate, use this field. true = next page | false = previous page
sortsarray of objectsoptional
Array used to paginate your files, it is this item you need to pass to your requests to fetch the next page
Show item properties (1)
- sort itemnumberrequired
  Tuples of (number, string)

Request example

curl -X POST "https://app.icypeas.com/api/bulk-single-searchs/read" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
  "mode": "bulk",
  "limit": 50,
  "file": "#FILEID#"
}'

const response = await fetch("https://app.icypeas.com/api/bulk-single-searchs/read", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
  body: JSON.stringify({
    "mode": "bulk",
    "limit": 50,
    "file": "#FILEID#"
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://app.icypeas.com/api/bulk-single-searchs/read",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "mode": "bulk",
        "limit": 50,
        "file": "#FILEID#",
    },
)
print(response.json())

<?php
$body = <<<'JSON'
{
    "mode": "bulk",
    "limit": 50,
    "file": "#FILEID#"
}
JSON;

$ch = curl_init("https://app.icypeas.com/api/bulk-single-searchs/read");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$body = @'
{
  "mode": "bulk",
  "limit": 50,
  "file": "#FILEID#"
}
'@

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/bulk-single-searchs/read" -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 10

Paste this in the Body field of Make, Zapier, n8n or Postman.

{
  "mode": "bulk",
  "limit": 50,
  "file": "#FILEID#"
}

Responses

200SuccessResponse when your input is good.

Example response · 200
{
  "success": true,
  "items": [
    {
      "name": "My cool search",
      "user": "#USERID#",
      "file": "#FILEID#",
      "results": {
        "firstname": "Example",
        "lastname": "Email",
        "fullname": "Example Email",
        "gender": "UNKNOWN",
        "emails": [
          {
            "email": "example-email@icypeas.com",
            "certainty": "ultra_sure",
            "mxProvider": "google",
            "mxRecords": [
              "google.com"
            ]
          }
        ],
        "phones": []
      },
      "order": 0,
      "status": "FOUND",
      "system": {
        "createdAt": "2023-01-01T13:49:49.630Z",
        "modifiedAt": "2023-01-01T13:49:49.630Z"
      },
      "userData": {
        "externalId": "my-custom-id",
        "webhookUrl": "https://www.call-me-when-done.com/my-custom-id"
      },
      "_id": "oSmI5YYBMa6Snk9TvjDA"
    }
  ],
  "total": 2534,
  "sorts": [
    [
      1679388635082,
      "xxxx"
    ],
    [
      1679388543443,
      "yyyy"
    ]
  ]
}

Response fields

successboolean
This field lets you know if your request was successful
itemsarray of objects
Array of results
Show item properties (9)
- namestring
  Name of the search ('__icypeas__individual' if it is a single search).
- userstring
  User ID of the user linked to this search.
- filestring
  File id when it is a bulk search
- resultsobject
  Object containing the results of your search.
  Show properties (6)
  - firstnamestring
    First name found during the search, if any.
  - lastnamestring
    Last name found during the search, if any.
  - fullnamestring
    Concatenation of the user's first and last names, if any.
  - emailsarray of objects
    Array of the found email addresses.
    Show item properties (4)
    emailstring
    Email address found during the search.
    certaintyenum
    How sure Icypeas is that this address exists: ultra_sure, very_sure, probable, undeliverable or not_found. See the Email certainty page.
    mxProviderenum
    Who hosts the mailbox (google, microsoft, ovh…). See the MX providers page.
    mxRecordsarray
    Array of MX records. Those are strings
  - phonesarray
    Currently empty.
  - saasServicesarray
    Currently empty.
- ordernumber
  If in bulk search mode, it is the row of the file it was in.
- statusstring
  Status of this search.
- systemobject
  Information concerning the search.
  Show properties (2)
  - createdAtstring
    ISO String Date representing the creation date of the search.
  - modifiedAtstring
    ISO String Date representing the last modification date of the search.
- userDataobject
  Custom data that were passed when running either the bulk search or the single search
  Show properties (2)
  - webhookUrlstring
    Custom webhook URL that will be called for this search (the field is empty if no URL has been passed when running the single/bulk search)
  - externalIdstring
    Custom id provided by the user (the field is empty if not custom id was passed when running the single/bulk search)
- _idstring
  ID of the search.
totalnumber
Total number of results
sortsarray of objects
Array used to paginate your files, it is this item you need to pass to your requests to fetch the next page
Show item properties (1)
- sort itemnumber
  Tuples of (number, string)

200Validation errorResponse when there are validation errors.

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200
{
  "validationErrors": [
    {
      "expected": "string",
      "type": "required",
      "field": "user",
      "message": "validation_required"
    }
  ],
  "success": false
}

Type	Fields	When it happens
`string` validation_string	`modefile`	Error sent when the field is not a string
`stringEmpty` validation_string_empty	`mode`	Error sent when the field is an empty string
`stringEnum` validation_string_enum	`mode`	Error sent when the field is a string that is not in the enum
`number` validation_number	`limit`	Error sent when the field is not a number
`boolean` validation_boolean	`next`	Error sent when the field is not a boolean
`array` validation_array	`sorts`	Error sent when the field is not a array
`FilePropertyError` file_property_error	`file`	Error sent when the file property is absent in bulk mode
`InvalidFileError` invalid_file_error	`file`	Error sent when the file could not be fetch
`SearchNotFoundError` search_not_found_error	`id`	Error sent when the id does not correspond to a real search
`ModeOrIdShouldBeUsedError` mode_or_id_should_be_used_error	`idmode`	Error raised when neither mode nor id is used

401UnauthorizedResponse when we could not authenticate you.

Example response · 401
{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Response fields

messagestring
Human-readable message.
errorstring
Error name
statusnumber
HTTP error code
codestring
Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429
{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Response fields

messagestring
Human-readable message.
errorstring
Error name
statusnumber
HTTP error code
codestring
Error code

Get one result​

List your single searches​

List the rows of a bulk search​

List the rows of all your bulk searches​

Where is the email?​

Get one result

List your single searches

List the rows of a bulk search

List the rows of all your bulk searches

Where is the email?