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.

info

Want to know more about single search for email discovery? See here.

Want to know more about bulk search? See here.

Want to know more about statuses? See here.