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 and secret.

Api authentication

When using our API, you have two mode of authentication:

• Using your API key only. We recommend this usage if you need to integrate the API with existing tools such as low-code or no-code platform.
• Using your API key & your API secret. The key is used to identify your request, while the secret is used to sign your request. This is better in term of security. To understand how to compute a signature, see here.

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.

Low code platforms

We have modules for the following platforms:

• N8N (https://www.n8n.io) here. Currently, the node is only usable when you are using an on-premise installation of N8N. If you need the node to be accessible directly in N8N, you need to share your interest with the community so that the people behind N8N accept to integrate Icypeas directly in their cloud solution.