How it works

Finding or verifying an email takes a few seconds, because Icypeas really talks to the company's mail server. So the API works like a ticket counter: you drop off a request, you get a ticket number, you come back for the result.

1. 1. Send the searchPOST /email-search answers instantly with a search _id.
2. 2. Wait a few secondsIcypeas looks for the email and checks it with the mail server.
3. 3. Read the resultPOST /bulk-single-searchs/read with the _id, or get it pushed to a webhook.

The two ways to get your result

Option A: ask again until it's ready (polling)

The simplest. After starting a search, call /bulk-single-searchs/read with the search _id every few seconds, until status is no longer NONE, SCHEDULED or IN_PROGRESS.

• ✅ Easy: two requests and a pause.
• ⚠️ Limited to 30 reads per minute (see rate limits). Wait at least 3 seconds between two reads.

For a bulk search, check its progress with /search-files/read until the file is finished, then fetch the results page by page.

Option B: let Icypeas call you (webhooks) recommended

Give Icypeas the URL of your server, Zap or scenario, and it sends you the result as soon as it's ready. No waiting loop, no rate limit to worry about.

• Set one URL for all your searches on the API page of the app, or
• pass a custom.webhookUrl with a single search, or custom.webhookUrlItem / custom.webhookUrlBulkDone with a bulk search.

Read Webhooks to set them up.

Single or bulk?

	Single search	Bulk search
Use it for	One person at a time, in real time (a form, a CRM button, a Zap).	Lists: a CSV, a CRM export, a database.
Items per call	1	Up to 5,000
Speed limit	10 calls per second	1 call per second
Endpoints	/email-search, /email-verification, /domain-search	/bulk-search

Don't loop over single searches for big lists

Bulk searches are designed to process thousands of rows in parallel. They're faster for you and kinder to the rate limits.

Tasks

A task is the kind of work you ask Icypeas to do. Bulk searches and result filters refer to them by name.

Task	What it does	Input
email-search	Finds a person's professional email.	First name and/or last name, plus a company name or domain.
email-verification	Checks that an email address exists.	An email address.
domain-search	Finds the role-based emails of a domain (contact@, sales@…).	A domain or company name.
scrape/profile	Gets the data of a person from their profile URL.	A profile URL.
scrape/company	Gets the data of a company from its company page URL.	A company page URL.
url-search/profile	Finds the profile URL of a person.	Name, company, job title…
url-search/company	Finds the company page URL of a company.	Company name or website.

Good to know

• Every request is a POST with a JSON body, except the two single scraping endpoints which are GET.
• Input mistakes come back with HTTP 200 and "success": false. Always check success. See Errors.
• You're only charged for results. See Credit costs.