Email search

Find the professional email of one person from their name and their company. Costs 1 credit only if an email is found.

How to use it:

1. Send the person's firstname, lastname and domainOrCompany. You get back a search _id.
2. A few seconds later, read the result with /bulk-single-searchs/read, or receive it on a webhook.

Tips for better results

• Use the company website (icypeas.com) rather than its name (Icypeas) when you have it.
• You can leave firstname or lastname empty, but not both.
• For more than a few people, use the bulk search: it handles thousands of rows in parallel.

POSThttps://app.icypeas.com/api/email-search

Headers

• Authorizationstringrequired

  Your API key, as is (no Bearer prefix).

• Content-Typestringrequired

  Always application/json.

Body parameters

• firstnamestringrequired

  The firstname of the person you want to find.

  Rule: can be empty if a lastname is set

• lastnamestringrequired

  The lastname of the person you want to find.

  Rule: can be empty if a firstname is set

• domainOrCompanystringrequired

  The domain or the company name of the person you want to find.

• customobjectoptional

  Optional settings for this search: a webhook URL and/or your own id.

  Show properties (2)

  • webhookUrlurloptional

    A URL Icypeas calls with the result as soon as this search is done. See the 'Search item processed' webhook.

  • externalIdstringoptional

    Your own id for this search (for example a CRM id). It comes back with the result and in webhooks. Icypeas doesn't check that it's unique.

Request example

cURL

curl -X POST "https://app.icypeas.com/api/email-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
  "firstname": "John",
  "lastname": "Doe",
  "domainOrCompany": "icypeas.com"
}'

JavaScript

const response = await fetch("https://app.icypeas.com/api/email-search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
  body: JSON.stringify({
    "firstname": "John",
    "lastname": "Doe",
    "domainOrCompany": "icypeas.com"
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://app.icypeas.com/api/email-search",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "firstname": "John",
        "lastname": "Doe",
        "domainOrCompany": "icypeas.com",
    },
)
print(response.json())

PHP

<?php
$body = <<<'JSON'
{
    "firstname": "John",
    "lastname": "Doe",
    "domainOrCompany": "icypeas.com"
}
JSON;

$ch = curl_init("https://app.icypeas.com/api/email-search");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

PowerShell

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$body = @'
{
  "firstname": "John",
  "lastname": "Doe",
  "domainOrCompany": "icypeas.com"
}
'@

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/email-search" -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 10

JSON body

Paste this in the Body field of Make, Zapier, n8n or Postman.

{
  "firstname": "John",
  "lastname": "Doe",
  "domainOrCompany": "icypeas.com"
}

Responses

200SuccessResponse when your input is good.

Example response · 200

{
  "success": true,
  "item": {
    "_id": "#YOUR_SEARCH_ID#",
    "status": "NONE"
  }
}

Response fields

• successboolean

  true means that your search has been taken into account

• itemobject

  Information about your search

  Show properties (2)

  • _idstring

    Search id to follow its progression

  • statusstring

    Status of this search (NONE right after creation). See the Result statuses page.

200Validation errorResponse when there are validation errors.

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200

{
  "validationErrors": [
    {
      "expected": "string",
      "type": "required",
      "field": "firstname",
      "message": "validation_required"
    },
    {
      "expected": "string",
      "type": "required",
      "field": "lastname",
      "message": "validation_required"
    },
    {
      "expected": "string",
      "type": "required",
      "field": "domainOrCompany",
      "message": "validation_required"
    }
  ],
  "success": false
}

Type	Fields	When it happens
required validation_required	firstnamelastnamedomainOrCompany	Error sent when the field is missing
string validation_string	firstnamelastnamedomainOrCompanycustom.externalId	Error sent when the field is not a string
url validation_url	custom.webhookUrl	Error sent when the field is not a valid URL
stringEmpty validation_string_empty	firstnamelastnamedomainOrCompany	Error sent when the field is empty
FirstLastMandatoryDiscoveryError first_last_mandatory_discovery_error	firstnamelastname	Error sent when you need to at least specify a firstname or a lastname and you left both empty
UnpaidSubscriptionError unpaid_subscription_error	user	Error sent when you have a pending payment and your subscription is therefore not paid

401UnauthorizedResponse when we could not authenticate you.

Example response · 401

{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429

{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

Then: read the result

curl -X POST "https://app.icypeas.com/api/bulk-single-searchs/read" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{ "id": "THE_ID_YOU_RECEIVED" }'

The email is in items[0].results.emails[0].email, its reliability in certainty. See Read results and the step-by-step quickstart.