curl --request POST \
--url https://api.lemlist.com/api/campaigns/{campaignId}/leads/ \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "support@lemlist.com",
"firstName": "John",
"lastName": "Doe",
"companyName": "lemlist",
"jobTitle": "Developer",
"linkedinUrl": "https://www.linkedin.com/in/johndoe",
"phone": "+33 123456789",
"timezone": "Europe/Paris",
"contactOwner": "login_email@lemlist.com",
"companySize": "50-100",
"customVariable1": "any value you want"
}
'import requests
url = "https://api.lemlist.com/api/campaigns/{campaignId}/leads/"
payload = {
"email": "support@lemlist.com",
"firstName": "John",
"lastName": "Doe",
"companyName": "lemlist",
"jobTitle": "Developer",
"linkedinUrl": "https://www.linkedin.com/in/johndoe",
"phone": "+33 123456789",
"timezone": "Europe/Paris",
"contactOwner": "login_email@lemlist.com",
"companySize": "50-100",
"customVariable1": "any value you want"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'support@lemlist.com',
firstName: 'John',
lastName: 'Doe',
companyName: 'lemlist',
jobTitle: 'Developer',
linkedinUrl: 'https://www.linkedin.com/in/johndoe',
phone: '+33 123456789',
timezone: 'Europe/Paris',
contactOwner: 'login_email@lemlist.com',
companySize: '50-100',
customVariable1: 'any value you want'
})
};
fetch('https://api.lemlist.com/api/campaigns/{campaignId}/leads/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));require 'uri'
require 'net/http'
url = URI("https://api.lemlist.com/api/campaigns/{campaignId}/leads/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"support@lemlist.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"lemlist\",\n \"jobTitle\": \"Developer\",\n \"linkedinUrl\": \"https://www.linkedin.com/in/johndoe\",\n \"phone\": \"+33 123456789\",\n \"timezone\": \"Europe/Paris\",\n \"contactOwner\": \"login_email@lemlist.com\",\n \"companySize\": \"50-100\",\n \"customVariable1\": \"any value you want\"\n}"
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lemlist.com/api/campaigns/{campaignId}/leads/",
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([
'email' => 'support@lemlist.com',
'firstName' => 'John',
'lastName' => 'Doe',
'companyName' => 'lemlist',
'jobTitle' => 'Developer',
'linkedinUrl' => 'https://www.linkedin.com/in/johndoe',
'phone' => '+33 123456789',
'timezone' => 'Europe/Paris',
'contactOwner' => 'login_email@lemlist.com',
'companySize' => '50-100',
'customVariable1' => 'any value you want'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}Create Lead in Campaign
Creates a new lead and adds it to a specific campaign. Never updates an existing lead.
curl --request POST \
--url https://api.lemlist.com/api/campaigns/{campaignId}/leads/ \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "support@lemlist.com",
"firstName": "John",
"lastName": "Doe",
"companyName": "lemlist",
"jobTitle": "Developer",
"linkedinUrl": "https://www.linkedin.com/in/johndoe",
"phone": "+33 123456789",
"timezone": "Europe/Paris",
"contactOwner": "login_email@lemlist.com",
"companySize": "50-100",
"customVariable1": "any value you want"
}
'import requests
url = "https://api.lemlist.com/api/campaigns/{campaignId}/leads/"
payload = {
"email": "support@lemlist.com",
"firstName": "John",
"lastName": "Doe",
"companyName": "lemlist",
"jobTitle": "Developer",
"linkedinUrl": "https://www.linkedin.com/in/johndoe",
"phone": "+33 123456789",
"timezone": "Europe/Paris",
"contactOwner": "login_email@lemlist.com",
"companySize": "50-100",
"customVariable1": "any value you want"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'support@lemlist.com',
firstName: 'John',
lastName: 'Doe',
companyName: 'lemlist',
jobTitle: 'Developer',
linkedinUrl: 'https://www.linkedin.com/in/johndoe',
phone: '+33 123456789',
timezone: 'Europe/Paris',
contactOwner: 'login_email@lemlist.com',
companySize: '50-100',
customVariable1: 'any value you want'
})
};
fetch('https://api.lemlist.com/api/campaigns/{campaignId}/leads/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));require 'uri'
require 'net/http'
url = URI("https://api.lemlist.com/api/campaigns/{campaignId}/leads/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"support@lemlist.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"lemlist\",\n \"jobTitle\": \"Developer\",\n \"linkedinUrl\": \"https://www.linkedin.com/in/johndoe\",\n \"phone\": \"+33 123456789\",\n \"timezone\": \"Europe/Paris\",\n \"contactOwner\": \"login_email@lemlist.com\",\n \"companySize\": \"50-100\",\n \"customVariable1\": \"any value you want\"\n}"
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lemlist.com/api/campaigns/{campaignId}/leads/",
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([
'email' => 'support@lemlist.com',
'firstName' => 'John',
'lastName' => 'Doe',
'companyName' => 'lemlist',
'jobTitle' => 'Developer',
'linkedinUrl' => 'https://www.linkedin.com/in/johndoe',
'phone' => '+33 123456789',
'timezone' => 'Europe/Paris',
'contactOwner' => 'login_email@lemlist.com',
'companySize' => '50-100',
'customVariable1' => 'any value you want'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}400 LEAD_ALREADY_IN_CAMPAIGN (409 from December 1, 2026, same message), nothing written; use PATCH /campaigns/{campaignId}/leads/{leadId} instead. With deduplicate=true, a contact with a lead in another campaign is refused with 409 LEAD_ALREADY_IN_OTHER_CAMPAIGN; only this parameter drives that check, not the campaign’s “remove duplicates” setting. POST /campaigns/{campaignId}/leads/{leadIdOrEmail} behaves the same, with the email in the path.400 (The lead's contact doesn't belong to the ABM campaign's company), nothing written. They hold at most 199 leads; past that, the request fails with 400 CAMPAIGN_LEADS_LIMIT_REACHED ({"error": "You can't add more than 199 leads to an ABM campaign"}).403 ({"error": "The user jane@acme.com does not have the permission to create companies"}) and nothing is written. A company already in lemlist is linked as usual.Likewise, when its contact is not in lemlist yet, that user needs the “Create contacts” permission, otherwise the request fails with 403 ({"error": "The user jane@acme.com does not have the permission to create contacts"}) and nothing is written, company included. A contact already in lemlist is updated as usual.When the API key’s user is no longer in the team, they hold no permission there: the error says so ({"error": "The user jane@acme.com is no longer in this team: ask a current member to create a new API key or reconnect"}).updateStrategy decides what they keep. overwrite (default): sent values replace stored ones, an empty value clears. overwriteIgnoreEmpty: same, empty values ignored. fillEmptyOnly: only empty fields are filled, identifiers, company link, owner and status kept, and the lead takes the values the contact kept. Kept values are listed in warnings (FIELDS_KEPT, params.fields, company fields prefixed with company).{{yourVariableName}}.In the example, companySize and customVariable1 are custom variables.Naming rules: only letters, digits, _, -, space and # are kept — any other character (e.g. . or $) is replaced by _. Values are stored as text.companyName, companyDomain, companyIndustry, any company-prefixed key — reach the company record the lead is matched to, the same record every other lead linked to it reads, not that lead alone. Creating a lead with its company is the intended flow; to edit a company on purpose, use Upsert Company.Linking to a CRM record
SendcrmId with the id of a record in your connected CRM to link the lead’s contact to that record. lemlist links it without searching the CRM, then runs a first sync that follows your field mapping (the CRM wins conflicts by default). The response’s hubspotLeadId, salesforceContactId, salesforceLeadId, pipedriveLeadId or attioLeadId shows the record the contact is linked to.
crmId is reserved for this link: it is never stored as a custom variable. It requires an admin API key. Among the lead endpoints, only this one reads it as a link: Update Lead, Add Lead Variables and Update Lead Variables store crmId as a variable like any other key.003…) or Lead (00Q…) id.
This call adds a lead: it never moves a link, and never refuses the lead because of its crmId.
| Situation | Result |
|---|---|
| No lemlist contact matches the lead | The contact is created already linked to that record. |
| The contact the lead matches has no CRM link | It is linked to that record. |
| The contact the lead matches is already linked to that record | The link stays as it is. |
| The contact the lead matches is linked to another record | It keeps its link: warnings carries CRM_ID_NOT_APPLIED, params.crmId names the id sent. To move the link, send the contact’s contactId and the crmId to Upsert Contact, or change it from the contact page. |
| Another lemlist contact, which the lead’s email and LinkedIn URLs do not match, holds the id | The lead is added without the link: warnings carries CRM_ID_ALREADY_LINKED, params.conflictingContactId names that contact. |
warnings (see the 200 response).Authorizations
Query Parameters
What the matched contact and company keep (the lead is always created). overwrite (default): sent values replace stored ones, an empty string clears. overwriteIgnoreEmpty: empty values ignored. fillEmptyOnly: only empty fields filled, identifiers, links, owner and status kept. Other values: 400.
overwrite, overwriteIgnoreEmpty, fillEmptyOnly Body
Reserved for this link, never stored as a custom variable. Id of the record of the connected CRM to link the lead's contact to: a HubSpot, Pipedrive or Zoho numeric id (send a Zoho id as a string: its 19 digits are too long for a JSON number), an Attio record id, or a Salesforce Contact (003…) or Lead (00Q…) id of 15 or 18 characters. Requires an admin API key. Never refuses the lead: a new contact is created already linked, a contact without a link is linked, a contact linked to another record keeps it, and an id that cannot be applied comes back in warnings. See the endpoint page.
"123456789"
Response
Success
Was this page helpful?