MENU navbar-image

Introduction

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

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

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

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

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

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\": \"quia\",
    \"domain\": \"possimus\",
    \"webhook_url\": \"numquam\"
}"

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": "quia",
    "domain": "possimus",
    "webhook_url": "numquam"
};

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": "say my name",
            "email": "email@findymail.com",
            "domain": "domain.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

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

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

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