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. Cost for each feature is available here.

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

info

Two headers are needed to run a query against the API:

1. Authorization header containing your API key (and ONLY your API key)
2. Content-Type header with value application/json

See below for an example using Curl

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.