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.

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

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\": \"molestias\"
}"

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": "molestias"
};

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/1" \
    --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/1"
);

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/12" \
    --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/12"
);

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. Users 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\": \"nam\",
    \"domain\": \"ut\",
    \"webhook_url\": \"quos\"
}"

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": "nam",
    "domain": "ut",
    "webhook_url": "quos"
};

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\": \"deleniti\"
}"

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": "deleniti"
};

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

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\": \"rerum\"
}"

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": "rerum"
};

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