MENU navbar-image

Introduction

This documentation aims to provide all the information you need to work with our API.

Rate limit: all endpoints have a concurrent rate limit of 300 simultaneous requests, unless stated otherwise.

Base URL

https://app.findymail.com/

Authenticating requests

Authenticate requests to this API's endpoints by sending an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting API page.

Contacts

Get the list of contact lists

requires authentication

Example request:
curl --request GET \
    --get "https://app.findymail.com/api/lists" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.findymail.com/api/lists"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "lists": [
        {
            "id": 1,
            "name": "my list",
            "created_at": "2022-08-23T16:46:43.000000Z",
            "updated_at": "2022-08-23T16:46:43.000000Z",
            "shared_with_team": false,
            "is_owner": true
        }
    ]
}

Request      

GET api/lists

Update a contact list

requires authentication

Example request:
curl --request PUT \
    "https://app.findymail.com/api/lists/5" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"animi\",
    \"isShared\": true
}"

const url = new URL(
    "https://app.findymail.com/api/lists/5"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "animi",
    "isShared": true
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Request      

PUT api/lists/{id}

PATCH api/lists/{id}

URL Parameters

id  integer  

The ID of the list.

Body Parameters

name  string  

New name of the list

isShared  boolean  

Enable/disable list sharing with the team

Create a new list

requires authentication

Example request:
curl --request POST \
    "https://app.findymail.com/api/lists" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"consequatur\"
}"

const url = new URL(
    "https://app.findymail.com/api/lists"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "consequatur"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "list": {
        "id": 1,
        "name": "new list",
        "created_at": "2022-08-23T16:46:43.000000Z",
        "updated_at": "2022-08-23T16:46:43.000000Z",
        "shared_with_team": false,
        "is_owner": true
    }
}

Request      

POST api/lists

Body Parameters

name  string  

Name of the list

Delete a given list

requires authentication

Example request:
curl --request DELETE \
    "https://app.findymail.com/api/lists/7" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.findymail.com/api/lists/7"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Request      

DELETE api/lists/{id}

URL Parameters

id  integer  

The ID of the list.

Get contacts saved

requires authentication

Example request:
curl --request GET \
    --get "https://app.findymail.com/api/contacts/get/20" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.findymail.com/api/contacts/get/20"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
      "draw": 0,
      "recordsTotal": 1,
      "recordsFiltered": 1,
      "data": [
          {
              "id": 1,
              "name": "John Doe",
              "email": "john@company.com",
              "linkedin_url": "https://linkedin.com/in/linkedin",
              "company": "MyCompany",
              "job_title": "CEO"
          },
      ],
}

Request      

GET api/contacts/get/{id}

URL Parameters

id  integer optional  

Get contacts from a specified list. If 0, no list used ("All contacts").

Finder

Find from name

requires authentication

Find someone's email from name and website. Uses one finder credit if a verified email is found.

Example request:
curl --request POST \
    "https://app.findymail.com/api/search/name" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"numquam\",
    \"domain\": \"nostrum\",
    \"webhook_url\": \"sint\"
}"

const url = new URL(
    "https://app.findymail.com/api/search/name"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "numquam",
    "domain": "nostrum",
    "webhook_url": "sint"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "contact": {
        "name": "John Doe",
        "domain": "website.com",
        "email": "john@website.com"
    }
}

Example response (200):


{
    "error": "Not enough credits"
}

Example response (Callback, Webhook URL provided process asynchronous):


{
    "payload": {
        "contact": {
            "name": "john doe",
            "email": "email@website.com",
            "domain": "website.com"
        }
    }
}

Request      

POST api/search/name

Body Parameters

name  string  

Person's full name

domain  string  

Email domain (best) or company name

webhook_url  string optional  

Webhook URL that will receive the result as callback. If submitted, email search will happen in the background and notify this URL upon completion.

Response

Response Fields

payload    

(when using webhook_url) object POST method callback request triggered when webhook_url provided. See example response

Find from domain

requires authentication

Try finding a contact with a valid email at a given domain with a given role. A contact is only returned if we found a valid email.

Due to the heavy processing involved (real-time search), this endpoint is limited to 5 concurrent requests (when used synchronously) and async jobs can take up to 24 hours to be processed depending on our workload (usually sooner).

Example request:
curl --request POST \
    "https://app.findymail.com/api/search/domain" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"domain\": \"domain.com\",
    \"roles\": [
        \"CEO\",
        \"Founder\"
    ],
    \"webhook_url\": \"veniam\"
}"

const url = new URL(
    "https://app.findymail.com/api/search/domain"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "domain": "domain.com",
    "roles": [
        "CEO",
        "Founder"
    ],
    "webhook_url": "veniam"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "contacts": [
        {
            "domain": "website.com",
            "email": "john@website.com",
            "name": "john doe"
        }
    ]
}

Example response (200):


{
    "error": "Not enough credits"
}

Example response (Callback, Webhook URL provided process asynchronous):


{
    "payload": {
        "contacts": [
            {
                "name": "say my name",
                "email": "email@findymail.com",
                "domain": "domain.com"
            }
        ]
    }
}

Request      

POST api/search/domain

Body Parameters

domain  string  

Email domain

roles  string[]  

Target roles related to the given domain (max 3 roles)

webhook_url  string optional  

Webhook URL that will receive the result as callback. If submitted, search will happen in the background and notify this URL upon completion.

Response

Response Fields

payload    

(when using webhook_url) object POST method callback request triggered when webhook_url provided. See example response

Find from Linkedin

requires authentication

Find someone's email from a Linkedin URL. Uses one finder credit if a verified email is found.

This endpoint is limited to 10 concurrent requests (when used synchronously)

Example request:
curl --request POST \
    "https://app.findymail.com/api/search/linkedin" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"linkedin_url\": \"quis\",
    \"webhook_url\": \"itaque\"
}"

const url = new URL(
    "https://app.findymail.com/api/search/linkedin"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "linkedin_url": "quis",
    "webhook_url": "itaque"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "contact": {
        "name": "John Doe",
        "domain": "website.com",
        "email": "john@website.com"
    }
}

Example response (200):


{
    "error": "Not enough credits"
}

Example response (Callback, Webhook URL provided process asynchronous):


{
    "payload": {
        "contact": {
            "name": "john doe",
            "email": "email@website.com",
            "domain": "website.com"
        }
    }
}

Request      

POST api/search/linkedin

Body Parameters

linkedin_url  string  

Person's Linkedin URL. (can be full URL "https://linkedin.com/in/johndoe" or username only "johndoe")

webhook_url  string optional  

Webhook URL that will receive the result as callback. If submitted, email search will happen in the background and notify this URL upon completion.

Response

Response Fields

payload    

(when using webhook_url) object POST method callback request triggered when webhook_url provided. See example response

User

Get remaining credits

requires authentication

Example request:
curl --request GET \
    --get "https://app.findymail.com/api/credits" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.findymail.com/api/credits"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "credits": 150,
    "verifier_credits": 100
}

Request      

GET api/credits

Verifier

Verify an email for potential bounce

requires authentication

Uses one verifier credit on all attempted verification

Example request:
curl --request POST \
    "https://app.findymail.com/api/verify" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"ut\"
}"

const url = new URL(
    "https://app.findymail.com/api/verify"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "ut"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "email": "john@example.com",
    "verified": true
}

Example response (200):


{
    "error": "Not enough credits"
}

Request      

POST api/verify

Body Parameters

email  string  

Email to verify