Bulk search

Process a whole list in one call: up to 5,000 rows per request. Icypeas runs them in parallel and you get the results when they're ready.

You send three things:

• a name, to find your bulk search later (it also appears in the app, under Bulks);
• a task: email-search, email-verification or domain-search;
• the data: one list per row.

You get back a file id. Follow the progress with /search-files/read, then fetch the rows with /bulk-single-searchs/read. Or skip the waiting with webhooks.

Limits

• 5,000 rows maximum per call. Split bigger lists.
• 1 call per second. See rate limits.

How to fill data

Find emails

Each row has 3 items: first name, last name, company name or domain. First name or last name can be empty, not both.

{
  "task": "email-search",
  "name": "Prospects March",
  "data": [
    ["John", "Doe", "icypeas.com"],
    ["Charline", "Lestelle", "Google"],
    ["", "Avocado", "yelp.fr"],
    ["Jeanine", "", "Comodoro LLC"]
  ]
}

Verify emails

Each row has 1 item: the email address.

{
  "task": "email-verification",
  "name": "Newsletter clean-up",
  "data": [
    ["john.doe@icypeas.com"],
    ["charline.lestelle@google.com"],
    ["jeanine@comodoro.com"]
  ]
}

Scan domains

Each row has 1 item: the domain or company name.

{
  "task": "domain-search",
  "name": "Partner domains",
  "data": [
    ["icypeas.com"],
    ["google.com"],
    ["yelp.fr"],
    ["Comodoro LLC"]
  ]
}

Match results with your own ids

Give each row your own id (a CRM id, a row number…) with custom.externalIds. It has to be as long as data: one id per row, in the same order. Ids come back in each result as userData.externalId. Icypeas doesn't check that they're unique.

{
  "task": "email-search",
  "name": "CRM sync",
  "data": [
    ["John", "Doe", "icypeas.com"],
    ["Charline", "Lestelle", "google.com"]
  ],
  "custom": {
    "externalIds": ["crm-1042", "crm-1043"],
    "webhookUrlItem": "https://example.com/icypeas/row-done",
    "webhookUrlBulkDone": "https://example.com/icypeas/bulk-done"
  }
}

• webhookUrlItem is called for each row as soon as it's processed (payload).
• webhookUrlBulkDone is called once when the whole list is done (payload). Add "includeResultsInWebhook": true to receive every result in that single call.

POSThttps://app.icypeas.com/api/bulk-search

Start a new bulk search from the API.

Headers

• Authorizationstringrequired

  Your API key, as is (no Bearer prefix).

• Content-Typestringrequired

  Always application/json.

Body parameters

• namestringrequired

  Name of the bulk search you are creating.

• taskstringrequired

  The type of bulk search you want to do.

  Rule: has to be either 'domain-search', 'email-search' or 'email-verification'

• dataarray of arraysrequired

  Emails, prospects or domains you want to analyze.

  Show item properties (1)

  • rowarrayrequired

    Each row you want to be analyzed. If you are doing an 'email-search' you should have 3 items in each row.In other modes it's only 1 item.

• customobjectoptional

  Custom object for passing custom webhooks and/or custom ids that will be added to each row

  Show properties (4)

  • webhookUrlItemurloptional

    Custom webhook to be called each time a row is processed. It receives the result of that row. See the 'Search item processed' webhook.

  • webhookUrlBulkDoneurloptional

    Custom webhook to be called when the whole bulk search is processed. It receives the statistics of the bulk search (and the results if includeResultsInWebhook is true). See the 'Bulk search done' webhook.

  • externalIdsarrayoptional

    Array of strings. Each id should correspond to each row in your data array. So, if provided, the length of externalIds should match the length of your data array. We do not check for the uniqueness of your IDs, you are responsible of that.

  • includeResultsInWebhookbooleanoptional

    If provided, we add the results of your search directly in the webhook called at the end of the bulk. Please if your bulk search has more than 1000 items, make sure you have properly configured your webhook and server to accept large POST requests. If not, do not use this option.

Request example

cURL

curl -X POST "https://app.icypeas.com/api/bulk-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
  "name": "Icypeas Prospects to analyze",
  "task": "email-search",
  "data": [
    [
      "John",
      "Doe",
      "icypeas.com"
    ],
    [
      "John",
      "Doe",
      "Icypeas"
    ]
  ]
}'

JavaScript

const response = await fetch("https://app.icypeas.com/api/bulk-search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
  body: JSON.stringify({
    "name": "Icypeas Prospects to analyze",
    "task": "email-search",
    "data": [
      [
        "John",
        "Doe",
        "icypeas.com"
      ],
      [
        "John",
        "Doe",
        "Icypeas"
      ]
    ]
  }),
});

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

Python

import requests

response = requests.post(
    "https://app.icypeas.com/api/bulk-search",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "name": "Icypeas Prospects to analyze",
        "task": "email-search",
        "data": [
            ["John", "Doe", "icypeas.com"],
            ["John", "Doe", "Icypeas"],
        ],
    },
)
print(response.json())

PHP

<?php
$body = <<<'JSON'
{
    "name": "Icypeas Prospects to analyze",
    "task": "email-search",
    "data": [
        [
            "John",
            "Doe",
            "icypeas.com"
        ],
        [
            "John",
            "Doe",
            "Icypeas"
        ]
    ]
}
JSON;

$ch = curl_init("https://app.icypeas.com/api/bulk-search");
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);

PowerShell

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

$body = @'
{
  "name": "Icypeas Prospects to analyze",
  "task": "email-search",
  "data": [
    [
      "John",
      "Doe",
      "icypeas.com"
    ],
    [
      "John",
      "Doe",
      "Icypeas"
    ]
  ]
}
'@

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

JSON body

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

{
  "name": "Icypeas Prospects to analyze",
  "task": "email-search",
  "data": [
    [
      "John",
      "Doe",
      "icypeas.com"
    ],
    [
      "John",
      "Doe",
      "Icypeas"
    ]
  ]
}

Responses

200SuccessResponse when your input is good.

Example response · 200

{
  "success": true,
  "status": "in_progress",
  "file": "#FILEID#"
}

Response fields

• successboolean

  This field lets you know if your request was successful

• statusstring

  The status of the bulk search.

• filestring

  The new file's id.

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
required validation_required	usernametaskdata	Error sent when the field is missing
string validation_string	usernametask	Error sent when the field is not a string
stringEmpty validation_string_empty	usernametask	Error sent when the field is an empty string
array validation_array	data	Error sent when the field is not a array
arrayEmpty validation_array_empty	data	Error sent when the field is an empty array
arrayLength validation_array_length	data	Error sent when the field has more elements than possible.
InsufficientCredits insufficient_credits	user	Error sent when you have less credits than the number of items in your data. We take into account ALL the searches currently queued or in progress in your account. If you have many paralel single or bulk searches, it will be taken into account
UnpaidSubscriptionError unpaid_subscription_error	user	Error sent when you have a pending payment and your subscription is therefore not paid
ExternalIdsArrayShouldMatchDataArrayError external_ids_array_should_match_data_array_error	externalIds	Error sent when you have specified an externalIds array but it does not match the size of your data array

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