Find emails
curl --request POST \
--url https://api.leadsforge.ai/public/v1/enrichment/emails \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"clientRequestID": "my-request-123",
"people": [
{
"company": "Salesforge",
"companyDomain": "salesforge.ai",
"externalID": "crm-contact-42",
"firstName": "John",
"lastName": "Doe",
"linkedinURL": "https://www.linkedin.com/in/example-profile"
}
],
"personIDs": [
"<string>"
],
"saveToList": false,
"webhookURL": "https://example.com/webhook"
}
'const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientRequestID: 'my-request-123',
people: [
{
company: 'Salesforge',
companyDomain: 'salesforge.ai',
externalID: 'crm-contact-42',
firstName: 'John',
lastName: 'Doe',
linkedinURL: 'https://www.linkedin.com/in/example-profile'
}
],
personIDs: ['<string>'],
saveToList: false,
webhookURL: 'https://example.com/webhook'
})
};
fetch('https://api.leadsforge.ai/public/v1/enrichment/emails', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientRequestID: 'my-request-123',
people: [
{
company: 'Salesforge',
companyDomain: 'salesforge.ai',
externalID: 'crm-contact-42',
firstName: 'John',
lastName: 'Doe',
linkedinURL: 'https://www.linkedin.com/in/example-profile'
}
],
personIDs: ['<string>'],
saveToList: false,
webhookURL: 'https://example.com/webhook'
})
};
fetch('https://api.leadsforge.ai/public/v1/enrichment/emails', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.leadsforge.ai/public/v1/enrichment/emails';
const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientRequestID: 'my-request-123',
people: [
{
company: 'Salesforge',
companyDomain: 'salesforge.ai',
externalID: 'crm-contact-42',
firstName: 'John',
lastName: 'Doe',
linkedinURL: 'https://www.linkedin.com/in/example-profile'
}
],
personIDs: ['<string>'],
saveToList: false,
webhookURL: 'https://example.com/webhook'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));import requests
url = "https://api.leadsforge.ai/public/v1/enrichment/emails"
payload = {
"clientRequestID": "my-request-123",
"people": [
{
"company": "Salesforge",
"companyDomain": "salesforge.ai",
"externalID": "crm-contact-42",
"firstName": "John",
"lastName": "Doe",
"linkedinURL": "https://www.linkedin.com/in/example-profile"
}
],
"personIDs": ["<string>"],
"saveToList": False,
"webhookURL": "https://example.com/webhook"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.leadsforge.ai/public/v1/enrichment/emails"
payload := strings.NewReader("{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.leadsforge.ai/public/v1/enrichment/emails")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.leadsforge.ai/public/v1/enrichment/emails");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<api-key>");
request.AddJsonBody("{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.leadsforge.ai/public/v1/enrichment/emails",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'clientRequestID' => 'my-request-123',
'people' => [
[
'company' => 'Salesforge',
'companyDomain' => 'salesforge.ai',
'externalID' => 'crm-contact-42',
'firstName' => 'John',
'lastName' => 'Doe',
'linkedinURL' => 'https://www.linkedin.com/in/example-profile'
]
],
'personIDs' => [
'<string>'
],
'saveToList' => false,
'webhookURL' => 'https://example.com/webhook'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api.leadsforge.ai/public/v1/enrichment/emails")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}"
response = http.request(request)
puts response.read_body{
"channel": "email",
"clientRequestID": "<string>",
"completedAt": "<string>",
"consumedCredits": 123,
"createdAt": "<string>",
"failed": 123,
"jobID": "<string>",
"processed": 123,
"reservedCredits": 123,
"resultsURL": "<string>",
"status": "in_progress",
"statusURL": "<string>",
"succeeded": 123,
"total": 123,
"updatedAt": "<string>",
"webhookURL": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}Enrichment
Find emails
Asynchronous. Starts a job that finds work emails for up to 500 people and returns 202 with the job; poll GET /enrichment/jobs/{jobID} until status is completed or failed (with webhookURL, each person's result is also posted as it is ready), then page through GET /enrichment/jobs/{jobID}/results. On succeeded results the found value is in payload.email.
Consumes credits: your account's email price per person found. A value your account obtained in the last 30 days, through the API or the app, is returned free and is not reserved or charged; an older value is looked up again and charged if found. For every other person the job reserves that price upfront, and at completion charges only the people found; the rest of the reservation is released.
Input, two mutually exclusive modes: (1) personIDs - IDs returned by POST /search; (2) people - objects with either linkedinURL (e.g. "https://www.linkedin.com/in/example-profile") or firstName + lastName + a company signal (companyDomain such as "salesforge.ai" is preferred over a company name such as "Salesforge"). Max 500 items. Each result echoes the linkedinURL, firstName, lastName and company you sent in inputLinkedinURL, inputFirstName, inputLastName and inputCompany, and externalID as is, for correlation (companyDomain is not echoed). In personIDs mode, IDs that match no person are skipped and do not count in total; if none match, the request fails with 400.
People entries are deduplicated by normalized linkedinURL, by case-insensitive firstName + lastName + companyDomain (or company when no domain is given), and when they resolve to the same person; only one result is returned per unique person, and charged once; that result carries the externalID of the first matching entry, with linkedinURL entries taking precedence, so send unique people if you need every externalID back. Each person may carry an optional externalID (max 128 chars), a passthrough value persisted with the result and echoed back in the webhook payload and the results; it is not supported in personIDs mode. A linkedinURL that is not a valid profile URL is ignored: the entry is matched by firstName + lastName + company when you sent them, and is returned not_found otherwise.
Example with people: {"people": [{"linkedinURL": "https://www.linkedin.com/in/example-profile", "externalID": "crm-42"}, {"firstName": "Jane", "lastName": "Smith", "companyDomain": "salesforge.ai"}], "webhookURL": "https://example.com/webhook"}. Example with personIDs: {"personIDs": ["6f1e2d3c-4b5a-5968-8776-a5b4c3d2e1f0", "0a9b8c7d-6e5f-5a4b-9c3d-2e1f0a9b8c7d"]}.
Idempotency-Key: a repeat with the same key for the same channel returns the existing job as is, in whatever status and whatever its body, for as long as that job exists; the body must still be valid, or the repeat gets 400. Send a repeat only after the previous attempt has returned or timed out. A repeat does not count against the concurrent jobs limit, but it is still subject to the rate limit and can get 429; retry it with the same key.
Webhook: one POST per person as their result is recorded, with the result object (as in GET /enrichment/jobs/{jobID}/results) as the body. Webhooks can start arriving right after the 202 response, so accept one for a jobID you have not stored yet. There is no job-level webhook, so poll the job for its final status. A delivery that fails with a 5xx, 429 or network error is retried immediately and then redelivered in the background for up to 24h; other 4xx responses are not retried. Each attempt waits up to 8 seconds for a response. Redirects are not followed: a 3xx response is a failed delivery and is not retried. Every attempt for a result carries the same X-Webhook-Delivery-Id header (one ID per result) so repeated deliveries can be deduplicated; also deduplicate on jobID + personID and keep the latest. A result is readable through GET /enrichment/jobs/{jobID}/results by the time its webhook is sent. 2xx = delivered. webhookURL must be a public http or https URL with a domain name, not an IP address, or the request fails with 400; use https, since webhook bodies carry personal data.
POST
/
enrichment
/
emails
Find emails
curl --request POST \
--url https://api.leadsforge.ai/public/v1/enrichment/emails \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"clientRequestID": "my-request-123",
"people": [
{
"company": "Salesforge",
"companyDomain": "salesforge.ai",
"externalID": "crm-contact-42",
"firstName": "John",
"lastName": "Doe",
"linkedinURL": "https://www.linkedin.com/in/example-profile"
}
],
"personIDs": [
"<string>"
],
"saveToList": false,
"webhookURL": "https://example.com/webhook"
}
'const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientRequestID: 'my-request-123',
people: [
{
company: 'Salesforge',
companyDomain: 'salesforge.ai',
externalID: 'crm-contact-42',
firstName: 'John',
lastName: 'Doe',
linkedinURL: 'https://www.linkedin.com/in/example-profile'
}
],
personIDs: ['<string>'],
saveToList: false,
webhookURL: 'https://example.com/webhook'
})
};
fetch('https://api.leadsforge.ai/public/v1/enrichment/emails', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientRequestID: 'my-request-123',
people: [
{
company: 'Salesforge',
companyDomain: 'salesforge.ai',
externalID: 'crm-contact-42',
firstName: 'John',
lastName: 'Doe',
linkedinURL: 'https://www.linkedin.com/in/example-profile'
}
],
personIDs: ['<string>'],
saveToList: false,
webhookURL: 'https://example.com/webhook'
})
};
fetch('https://api.leadsforge.ai/public/v1/enrichment/emails', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.leadsforge.ai/public/v1/enrichment/emails';
const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientRequestID: 'my-request-123',
people: [
{
company: 'Salesforge',
companyDomain: 'salesforge.ai',
externalID: 'crm-contact-42',
firstName: 'John',
lastName: 'Doe',
linkedinURL: 'https://www.linkedin.com/in/example-profile'
}
],
personIDs: ['<string>'],
saveToList: false,
webhookURL: 'https://example.com/webhook'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));import requests
url = "https://api.leadsforge.ai/public/v1/enrichment/emails"
payload = {
"clientRequestID": "my-request-123",
"people": [
{
"company": "Salesforge",
"companyDomain": "salesforge.ai",
"externalID": "crm-contact-42",
"firstName": "John",
"lastName": "Doe",
"linkedinURL": "https://www.linkedin.com/in/example-profile"
}
],
"personIDs": ["<string>"],
"saveToList": False,
"webhookURL": "https://example.com/webhook"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.leadsforge.ai/public/v1/enrichment/emails"
payload := strings.NewReader("{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.leadsforge.ai/public/v1/enrichment/emails")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.leadsforge.ai/public/v1/enrichment/emails");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<api-key>");
request.AddJsonBody("{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.leadsforge.ai/public/v1/enrichment/emails",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'clientRequestID' => 'my-request-123',
'people' => [
[
'company' => 'Salesforge',
'companyDomain' => 'salesforge.ai',
'externalID' => 'crm-contact-42',
'firstName' => 'John',
'lastName' => 'Doe',
'linkedinURL' => 'https://www.linkedin.com/in/example-profile'
]
],
'personIDs' => [
'<string>'
],
'saveToList' => false,
'webhookURL' => 'https://example.com/webhook'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api.leadsforge.ai/public/v1/enrichment/emails")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"clientRequestID\": \"my-request-123\",\n \"people\": [\n {\n \"company\": \"Salesforge\",\n \"companyDomain\": \"salesforge.ai\",\n \"externalID\": \"crm-contact-42\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"linkedinURL\": \"https://www.linkedin.com/in/example-profile\"\n }\n ],\n \"personIDs\": [\n \"<string>\"\n ],\n \"saveToList\": false,\n \"webhookURL\": \"https://example.com/webhook\"\n}"
response = http.request(request)
puts response.read_body{
"channel": "email",
"clientRequestID": "<string>",
"completedAt": "<string>",
"consumedCredits": 123,
"createdAt": "<string>",
"failed": 123,
"jobID": "<string>",
"processed": 123,
"reservedCredits": 123,
"resultsURL": "<string>",
"status": "in_progress",
"statusURL": "<string>",
"succeeded": 123,
"total": 123,
"updatedAt": "<string>",
"webhookURL": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}{
"code": "<string>",
"data": "<unknown>",
"message": "<string>"
}Authorizations
Headers
Body
application/json
Find request
Find request
Response
Job created
Was this page helpful?
