Getting started
Welcome to Icypeas' API documentation. You'll find everything you need to get started and use our API.
The API allows you to make single and bulk searches as well as being notified during a search. You can also retrieve your remaining credits and your current subscription. To access the API, you need to have an account, so please if you do not, create one here.
Once you have an account, follow these few steps to access your API key.
Your first request
Let's start by finding a single email:
curl -H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
https://app.icypeas.com/api/email-search \
-d '{ "firstname": "Pierre", "lastname": "Landoin", "domainOrCompany": "icypeas.com" }'
Once you have replaced YOUR_API_KEY
by your actual API key, you can run this request. The response should look like this:
{
"success": true,
"item": {
"status": "NONE",
"_id": "p_gfS5EB4liCGm90KDFC"
}
}
Wait a few seconds and then check the result using the returned _id
from the previous step:
curl -H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
https://app.icypeas.com/api/bulk-single-searchs/read \
-d '{ "id": "p_gfS5EB4liCGm90KDFC" }'
You should get something like this:
{
"success": true,
"items": [
{
"name": "__icypeas__individual",
"user": "USER_ID",
"results": {
"firstname": "Pierre",
"lastname": "Landoin",
"gender": "UNKNOWN",
"fullname": "Pierre Landoin",
"emails": [
{
"email": "pierre.landoin@icypeas.com",
"certainty": "ultra_sure",
"mxRecords": ["google.com"],
"mxProvider": "google"
}
],
"phones": [],
"saasServices": []
},
"order": 0,
"status": "DEBITED",
"userData": {
"webhookUrl": "",
"externalId": ""
},
"system": {
"createdAt": "2024-08-13T09:43:38.815Z",
"modifiedAt": "2024-08-13T09:43:39.289Z"
},
"_id": ""
}
],
"sorts": [[], []],
"total": 1
}
Look at the status
field here. If it is:
NONE
SCHEDULED
IN_PROGRESS
Then the search is not processed yet and you need to wait a few seconds more and fetch this route again.
Here, the status is DEBITED
meaning the search is done, an email address has been found and the credit has been debited.