EmailFinder.io Bulk Email Finder API Documentation (V1)

The EmailFinder API enables you to find employee emails in batches of up to 1,000 employees. This API also supports single email finder calls as well as our realverify guaranteed send technology..

Calling the API

V1 of the API is hosted at https://www.emailfinder.io/api/v1. All calls use this URL as the base.

Authentication

The EmailFinder API uses token-based authentication. If you're logged into your EmailFinder account, you'll see your API key below.

Your API key is <<log in to see your key>>.

Simply include key as a query parameter or a header parameter in your queries, like this: https://www.emailfinder.io/api/v1/batches?key=<<log in to see your key>>.

If you don't include an API key or use the wrong one, EmailFinder will respond with a 401 authorization error.

Status and Error Codes

Here are the most common HTTP status codes you may receive from our API and what they mean.

  • 200: Request and response were successful.
  • 401: The API key you used was not found.
  • 404: The recipient you're looking for wasn't found or is not accessible from your account.
  • 405: The method you attempted was not allowed.
  • 500: There was a server error.

Batches

List batches

This is the index call for your batches. Batches store the bulk employee data you submit for processing. A status attibute on the batch will tell you whether the batch is still processing or finished.

Example

GET https://www.emailfinder.io/api/v1/batches?key=<<log in to see your key>>

Result

{
  "status": "SUCCESS",
  "message": "Loaded all batches.",
  "data": [
    {
      "id": 24,
      "user_id": 1,
      "name": "Marketing batch A",
      "created_at": "2020-02-04T23:38:06.876Z",
      "updated_at": "2020-02-04T23:38:06.955Z",
      "status": "ready"
    }
  ],
  "last_page": true,
  "total_count": 1
}

Create a batch

Add a batch of employees to process on your account.

Parameters
key (required)
Your API key
name (required)
A name to identify or describe your batch
data (required)
JSON formatted employee payload
webhook_url (optional)
Fully-formed URL to accept a POST request containing the batch attributes when the batch status changes to finished.
verified (optional)
Put 'true' or '1' if you want to test the best email by sending a real email. Omit this param if not desired.
The JSON payload should have these keys.
first_name (required)
First name of the employee
last_name (required)
Last name of the employee
company (required)
Name of company (can be string or website or domain)
meta (optional)
JSON formatted metadata, which could include an internal ID
Example

POST https://www.emailfinder.io/api/v1/batches

Result

{
  "status": "SUCCESS",
  "message": "Created batch.",
  "data": {
    "id": 24,
    "user_id": 1,
    "name": "Marketing batch A",
    "created_at": "2020-02-04T23:38:06.876Z",
    "updated_at": "2020-02-04T23:38:06.955Z",
    "status": "ready"
  }
}

List employees

This is the index call for the employees in a batch. It's the equivalent to exporting the data from EmailFinder and is done on a batch-by-batch basis.

Each employee has a confidence attribute with a number between 0 and 100 and an email_verified attribute with one of these values: unverified, verified_true or verified_false.

Example

GET https://www.emailfinder.io/api/v1/batch/<batch_id>/employees?key=<<log in to see your key>>

Result of unverified batch

{
  "status": "SUCCESS",
  "message": "Loaded employees.",
  "data": [
    {
      "id": 1,
      "website_id": 1,
      "first_name": "elon",
      "last_name": "musk",
      "email_address": "elon@tesla.com",
      "email_confidence": 97,
      "email_updated_at": "2020-02-07T06:53:51.186Z",
      "created_at": "2020-02-07T06:24:28.575Z",
      "updated_at": "2020-02-07T06:53:51.187Z",
      "email_verified": "unverified",
      "meta": {
        "other_key": "def456",
        "internal_id": "abc123"
      }
    }
  ]
}

Result of verified batch

{
  "status": "SUCCESS",
  "message": "Loaded employees.",
  "data": [
    {
      "id": 1,
      "website_id": 1,
      "first_name": "elon",
      "last_name": "musk",
      "email_address": "elon@tesla.com",
      "email_confidence": 97,
      "email_updated_at": "2020-02-07T06:53:51.186Z",
      "created_at": "2020-02-07T06:24:28.575Z",
      "updated_at": "2020-02-07T06:53:51.187Z",
      "email_verified": "verified_true",
      "meta": {
        "other_key": "def456",
        "internal_id": "abc123"
      }
    }
  ]
}