Questions? Feedback?

The LeadFinch API

There are three API endpoints, and all requests should be sent over POST with your api_key (which can be found in your My Account section).

All API endpoints return a JSON response, and either a 200 (success), 500 (failure - with error message) or 403 (forbidden).

Rate Limit: 6 calls per minute. Do not go over this limit or your API access may be blocked. If you require higher limits, please do get in touch.


Get Batches (https://emails.leadfinch.com/app/api/get_batches/)

This allows you to get a list of the batches for your account.

Required Parameters:

  • api_key

Sample Request (cURL):

$ curl https://emails.leadfinch.com/app/api/get_batches/ \
    -d api_key="abcdefghijklmnopqrstuvwxyz"

Sample Response:

[
    {
        "name": "My Favourite New Batch",
        "id": 1
    },
    {
        "name": "My Less Favourite Batch",
        "id": 2
    }
]

Create New Person (https://emails.leadfinch.com/app/api/create_new_person/)

This creates a new person and instantly triggers the LeadFinch engine to begin the process of finding the email address.

This endpoint will return the id of the person, which can be used to poll the /get_email_address/ endpoint.

Note that finding an email address is not an instantaneous process and that is why the /get_email_address/ endpoint exists.

Required Parameters:

  • first_name
  • last_name
  • domain

Optional Parameters:

  • new_batch_name (if passed will create new batch)
  • batch_id (if passed will add person to existing batch. Can be derived from above API endpoint.)

Sample Request (cURL):

$ curl https://emails.leadfinch.com/app/api/create_new_person/ \
    -d api_key="abcdefghijklmnopqrstuvwxyz" \
    -d first_name="James" \
    -d last_name="Bond" \
    -d domain="mi6.com" \
    -d batch_id="1"

Sample Response:

{
    "person_id": 4,
    "message": "Successfully created person. You may now poll the get email endpoint for the email address."
}

Get Email Address (https://emails.leadfinch.com/app/api/get_email_address/)

Once a person has been created, using /create_person/, this should be polled approximately every 15 seconds to test if an email match has been found.

Do not poll more frequently than 6 times per minute, or your API access may be blocked.

Both the status of this person and the email address (if any) will be displayed. Status can be any of: "queued", "running", "over_limit", or "complete".

The LeadFinch process is finished when this shows "complete". At this point in time an email address will be shown if a match was found.

Required Parameters:

  • api_key
  • person_id

Sample Request (cURL):

$ curl https://emails.leadfinch.com/app/api/get_email_address/ \
    -d api_key="abcdefghijklmnopqrstuvwxyz" \
    -d person_id="4"

Sample Response:

{
    "status": "complete",
    "email": "james.bond@mi6.com"
}