Introduction

Base URL: https://app.findymail.com/

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.

Authenticating requests

To authenticate requests, include 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.

Email 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\": \"[email protected]\"
}"

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": "[email protected]"
};

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

Example response (200):


{
    "email": "[email protected]",
    "verified": true
}

Example response (200):


{
    "error": "Not enough credits"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/verify

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

email string

Email to verify Example: [email protected]

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
        }
    ]
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

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

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

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
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/lists

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

name string

Name of the list Example: quam

Update a contact list

requires authentication

Example request:

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

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

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

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

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

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
vary: Origin


{
    "message": "Unauthenticated."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

PUT api/lists/{id}

PATCH api/lists/{id}

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id integer

The ID of the list. Example: 131

Body Parameters

name string

New name of the list Example: enim

isShared boolean true false

Enable/disable list sharing with the team Example: true

Delete a given list

requires authentication

Example request:

curl --request DELETE \
    "https://app.findymail.com/api/lists/131" \
    --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/131"
);

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

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

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
vary: Origin


{
    "message": "Unauthenticated."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

DELETE api/lists/{id}

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id integer

The ID of the list. Example: 131

Get contacts saved

requires authentication

Example request:

curl --request GET \
    --get "https://app.findymail.com/api/contacts/get/10" \
    --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/10"
);

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": "[email protected]",
              "linkedin_url": "https://linkedin.com/in/linkedin",
              "company": "MyCompany",
              "job_title": "CEO"
          },
      ],
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/contacts/get/{id}

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id integer optional

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

Email 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\": \"aut\",
    \"domain\": \"voluptas\",
    \"webhook_url\": \"https:\\/\\/www.brekke.info\\/incidunt-nisi-sit-aspernatur-fugiat\"
}"

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": "aut",
    "domain": "voluptas",
    "webhook_url": "https:\/\/www.brekke.info\/incidunt-nisi-sit-aspernatur-fugiat"
};

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

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


{
    "payload": {
        "contact": {
            "name": "john doe",
            "email": "[email protected]",
            "domain": "website.com"
        }
    }
}

Example response (200):


{
    "contact": {
        "name": "John Doe",
        "domain": "website.com",
        "email": "[email protected]"
    }
}

Example response (200):


{
    "error": "Not enough credits"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/search/name

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

name string

Person's full name Example: aut

domain string

Email domain (best) or company name Example: voluptas

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. Example: https://www.brekke.info/incidunt-nisi-sit-aspernatur-fugiat

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\": \"http:\\/\\/streich.biz\\/nam-dolores-aspernatur-rerum-voluptatem-ullam.html\"
}"

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": "http:\/\/streich.biz\/nam-dolores-aspernatur-rerum-voluptatem-ullam.html"
};

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

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


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

Example response (200):


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

Example response (200):


{
    "error": "Not enough credits"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/search/domain

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

domain string

Email domain Example: domain.com

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. Example: http://streich.biz/nam-dolores-aspernatur-rerum-voluptatem-ullam.html

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 30 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\": \"https:\\/\\/www.brakus.org\\/aut-voluptas-ut-esse\",
    \"webhook_url\": \"http:\\/\\/sipes.com\\/quod-et-quis-voluptas-ut-saepe-facilis-voluptatem\"
}"

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": "https:\/\/www.brakus.org\/aut-voluptas-ut-esse",
    "webhook_url": "http:\/\/sipes.com\/quod-et-quis-voluptas-ut-saepe-facilis-voluptatem"
};

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

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


{
    "payload": {
        "contact": {
            "name": "john doe",
            "email": "[email protected]",
            "domain": "website.com"
        }
    }
}

Example response (200):


{
    "contact": {
        "name": "John Doe",
        "domain": "website.com",
        "email": "[email protected]"
    }
}

Example response (200):


{
    "error": "Not enough credits"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/search/linkedin

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

linkedin_url string

Person's Linkedin URL. (can be full URL "https://linkedin.com/in/johndoe" or username only "johndoe") Example: https://www.brakus.org/aut-voluptas-ut-esse

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. Example: http://sipes.com/quod-et-quis-voluptas-ut-saepe-facilis-voluptatem

Response

Response Fields

payload

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

Misc

Get Linkedin Profile

requires authentication

Get information from a Linkedin profile.

This endpoint uses 1 credit per request (warning: this uses a credit even if the profile does not exist. Please make sure the input is correct)

This endpoint does NOT return an email. To find email from a Linkedin profile, please use "Email Finder > Find from Linkedin" instead.

Example request:

curl --request POST \
    "https://app.findymail.com/api/linkedin/profile" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"linkedin_url\": \"https:\\/\\/linkedin.com\\/in\\/johndoe\"
}"

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

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

let body = {
    "linkedin_url": "https:\/\/linkedin.com\/in\/johndoe"
};

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

Example response (200):


{
    "linkedInId": "123",
    "fullName": "John Doe",
    "username": "johndoe",
    "headline": "CEO at Example",
    "jobTitle": "CEO",
    "summary": "Summary",
    "city": "City",
    "region": "Region",
    "country": "Country",
    "companyLinkedinUrl": "https://linkedin.com/company/example",
    "companyName": "Example",
    "companyWebsite": "example.com",
    "isPremium": true,
    "skills": [],
    "jobs": [
        {
            "jobTitle": "CEO",
            "companyName": "Example",
            "companyWebsite": "https://linkedin.com/company/example",
            "jobDescription": "Description",
            "startDate": "2020-01-01",
            "endDate": ""
        },
        {
            "jobTitle": "CTO",
            "companyName": "Example",
            "companyWebsite": "https://linkedin.com/company/example",
            "jobDescription": "Description",
            "startDate": "2020-01-01",
            "endDate": "2021-01-01"
        }
    ]
}

Example response (200):


{
    "error": "Not enough credits"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/linkedin/profile

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

linkedin_url string

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

Find Employees

requires authentication

Find one or more employees using the company website and job title.

This endpoint uses 1 credit per found contact.

This endpoint does NOT return an email.

Example request:

curl --request POST \
    "https://app.findymail.com/api/search/employees" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"website\": \"google.com\",
    \"job_titles\": [
        \"Software Engineer\",
        \"CEO\"
    ],
    \"count\": 1
}"

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

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

let body = {
    "website": "google.com",
    "job_titles": [
        "Software Engineer",
        "CEO"
    ],
    "count": 1
};

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

Example response (200):


[
    {
        "name": "John Done",
        "linkedinUrl": "https://www.linkedin.com/in/john-doe/",
        "companyWebsite": "https://www.findymail.com",
        "companyName": "Findymail",
        "jobTitle": "Software Engineer"
    }
]

Example response (200):


{
    "error": "Not enough credits"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/search/employees

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

website string

company website Example: google.com

job_titles string[]

target job titles

count integer optional

Number of contacts to return (max). Default 1. Example: 1

Phone Finder

Find phone

requires authentication

Find someone's phone number from a Linkedin URL. Uses 10 finder credits if a phone is found.

For legal reasons, requests for EU citizens will not return any result.

Example request:

curl --request POST \
    "https://app.findymail.com/api/search/phone" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"linkedin_url\": \"http:\\/\\/treutel.com\\/laboriosam-voluptatibus-et-sapiente-maxime-quia-molestiae.html\"
}"

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

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

let body = {
    "linkedin_url": "http:\/\/treutel.com\/laboriosam-voluptatibus-et-sapiente-maxime-quia-molestiae.html"
};

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

Example response (200):


{
    "phone": "+1234567890"
}

Example response (200):


{
    "error": "Not enough credits"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/search/phone

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

linkedin_url string

Person's Linkedin URL. (can be full URL "https://linkedin.com/in/johndoe" or username only "johndoe") Example: http://treutel.com/laboriosam-voluptatibus-et-sapiente-maxime-quia-molestiae.html

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
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Introduction

Authenticating requests

Email Verifier

Verify an email for potential bounce

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Contacts

Get the list of contact lists

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Create a new list

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Update a contact list

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Body Parameters

Delete a given list

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Get contacts saved

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Email Finder

Find from name

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Response

Response Fields

Find from domain

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Response

Response Fields

Find from Linkedin

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Response

Response Fields

Misc

Get Linkedin Profile

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Find Employees

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Phone Finder

Find phone

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

User

Get remaining credits

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request