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
}
]
}
Received response:
Request failed with error:
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
}
}
Received response:
Request failed with error:
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());
Received response:
Request failed with error:
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"
},
],
}
Received response:
Request failed with error:
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"
}
}
}
Received response:
Request failed with error:
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"
}
]
}
}
Received response:
Request failed with error:
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
}
Received response:
Request failed with error:
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"
}
Received response:
Request failed with error: