Lemlist Developer Docs

Add and update contact

curl --request POST \
  --url https://api.lemlist.com/api/contacts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "linkedinUrl": "https://linkedin.com/in/janesmith",
  "jobTitle": "Product Manager",
  "companyDomain": "acme.com"
}
'

import requests

url = "https://api.lemlist.com/api/contacts"

payload = {
    "email": "jane.smith@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "linkedinUrl": "https://linkedin.com/in/janesmith",
    "jobTitle": "Product Manager",
    "companyDomain": "acme.com"
}
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: 'jane.smith@example.com',
    firstName: 'Jane',
    lastName: 'Smith',
    linkedinUrl: 'https://linkedin.com/in/janesmith',
    jobTitle: 'Product Manager',
    companyDomain: 'acme.com'
  })
};

fetch('https://api.lemlist.com/api/contacts', 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/contacts")

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\": \"jane.smith@example.com\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"linkedinUrl\": \"https://linkedin.com/in/janesmith\",\n  \"jobTitle\": \"Product Manager\",\n  \"companyDomain\": \"acme.com\"\n}"

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lemlist.com/api/contacts",
  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' => 'jane.smith@example.com',
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'linkedinUrl' => 'https://linkedin.com/in/janesmith',
    'jobTitle' => 'Product Manager',
    'companyDomain' => 'acme.com'
  ]),
  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;
}

{
  "success": true,
  "data": {
    "_id": "ctc_xW8Ou6C03Csv8vatp",
    "teamId": "tea_8QvkOiBfPdb2ZRhHi",
    "emails": [
      {
        "value": "jane.smith@example.com"
      }
    ],
    "fields": {
      "firstName": "Jane",
      "lastName": "Smith",
      "jobTitle": "Product Manager"
    },
    "ownerId": "usr_ahfFktBBHUIxbVG5P",
    "source": "api",
    "createdAt": "2025-10-28T00:40:37.917Z",
    "createdBy": "usr_ahfFktBBHUIxbVG5P",
    "unsubscribed": false,
    "created": false,
    "updated": true,
    "companyLinked": false
  }
}

POST

contacts

Add and update contact

curl --request POST \
  --url https://api.lemlist.com/api/contacts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "linkedinUrl": "https://linkedin.com/in/janesmith",
  "jobTitle": "Product Manager",
  "companyDomain": "acme.com"
}
'

import requests

url = "https://api.lemlist.com/api/contacts"

payload = {
    "email": "jane.smith@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "linkedinUrl": "https://linkedin.com/in/janesmith",
    "jobTitle": "Product Manager",
    "companyDomain": "acme.com"
}
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: 'jane.smith@example.com',
    firstName: 'Jane',
    lastName: 'Smith',
    linkedinUrl: 'https://linkedin.com/in/janesmith',
    jobTitle: 'Product Manager',
    companyDomain: 'acme.com'
  })
};

fetch('https://api.lemlist.com/api/contacts', 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/contacts")

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\": \"jane.smith@example.com\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"linkedinUrl\": \"https://linkedin.com/in/janesmith\",\n  \"jobTitle\": \"Product Manager\",\n  \"companyDomain\": \"acme.com\"\n}"

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lemlist.com/api/contacts",
  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' => 'jane.smith@example.com',
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'linkedinUrl' => 'https://linkedin.com/in/janesmith',
    'jobTitle' => 'Product Manager',
    'companyDomain' => 'acme.com'
  ]),
  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;
}

{
  "success": true,
  "data": {
    "_id": "ctc_xW8Ou6C03Csv8vatp",
    "teamId": "tea_8QvkOiBfPdb2ZRhHi",
    "emails": [
      {
        "value": "jane.smith@example.com"
      }
    ],
    "fields": {
      "firstName": "Jane",
      "lastName": "Smith",
      "jobTitle": "Product Manager"
    },
    "ownerId": "usr_ahfFktBBHUIxbVG5P",
    "source": "api",
    "createdAt": "2025-10-28T00:40:37.917Z",
    "createdBy": "usr_ahfFktBBHUIxbVG5P",
    "unsubscribed": false,
    "created": false,
    "updated": true,
    "companyLinked": false
  }
}

Creates a new contact in your CRM, or updates an existing one if a contact with the same email, linkedinUrl, or linkedinUrlSalesNav already exists (upsert). On update, the updateStrategy query parameter decides what the existing record keeps (see below). By default, sent values replace stored ones and empty values are ignored.

Upsert matching

At least one identifier is required:

Identifier	Description
`contactId`	Existing contact ID — updates a specific contact directly, bypassing email/LinkedIn matching
`email`	Primary email address — used as the main unique key
`linkedinUrl`	LinkedIn profile URL — used as an alternative unique key
`linkedinUrlSalesNav`	LinkedIn Sales Navigator profile URL — used as an alternative unique key

If a contact with the same email, linkedinUrl, or linkedinUrlSalesNav already exists, the endpoint updates it instead of creating a duplicate. Creating a contact requires the “Create contacts” permission on the API key’s user, otherwise the request fails with 403 CONTACT_CREATE_NOT_ALLOWED and nothing is written. Updating an existing contact does not require it. The error names that user (The user jane@acme.com does not have the permission to create contacts); when the API key’s user is no longer in the team, it fails with 403 API_USER_NOT_IN_TEAM instead. When contactId is provided, the contact is matched by its ID directly — email and linkedinUrl are not required and are not used for matching (they are stored as data if provided).

contactId can only be used to update an existing contact. It cannot be used to create a new contact — use email or linkedinUrl for creation.

Update strategy

The updateStrategy query parameter decides what an existing contact keeps:

Value	Stored value	Empty string sent
`overwriteIgnoreEmpty` (default)	Replaced	Ignored
`overwrite`	Replaced	Cleared
`fillEmptyOnly`	Kept	Ignored

null and absent keys never touch a field. Identifiers (email, linkedinUrl, linkedinUrlSalesNav) are never cleared. Under fillEmptyOnly, the company link, the owner and the status are kept when set and filled when missing. A new contact receives every value sent. Any other value answers 400 INVALID_UPDATE_STRATEGY.

curl -X POST "https://api.lemlist.com/api/contacts?updateStrategy=fillEmptyOnly" \
  -u ":YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "jobTitle": "Founder", "phone": "+33600000000"}'

Kept values are reported: warnings carries a FIELDS_KEPT entry with the field names in params.fields. It appears under fillEmptyOnly on a stored value, and under the default when an empty string is ignored on a filled field, never for an identical value.

{
  "success": true,
  "data": { "_id": "ctc_2aB3cD4eF5gH6iJ7k", "jobTitle": "CEO", "phone": "+33600000000", "created": false, "updated": true, "companyLinked": false },
  "warnings": [
    { "code": "FIELDS_KEPT", "message": "Fields kept: the record already holds a different value, left unchanged by the update strategy", "params": { "fields": ["jobTitle"] } }
  ]
}

Linking to a company

You can link the contact to a company that already exists in your lemlist CRM using one of the following fields (in order of priority):

Field	Description
`companyId`	Direct company ID — takes priority over the others
`companyDomain`	Company domain (e.g. `lemlist.com`) — used if `companyId` is not provided
`companyLinkedinUrl`	Company LinkedIn URL — used as a last resort

When a company is successfully linked, the response includes companyLinked: true and the companyId.

Linking to a CRM record

Send crmId with the id of a record in your connected CRM to link the 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).

crmId is in closed beta. Unless the CRM ID remap beta is enabled for your team, it is refused like any unknown field, with 400 INVALID_FIELD. It also requires an admin API key.

CRM	Accepted id
HubSpot, Pipedrive, Zoho	Numeric record id. Send a Zoho id as a string: its 19 digits are too long for a JSON number.
Attio	Record id (UUID)
Salesforce	Contact (`003…`) or Lead (`00Q…`) id, 15 or 18 characters. A 15-character id is stored as 18.

What happens depends on the contact and on who already holds the id:

Situation	Result
New contact, the id is linked to no lemlist contact	The contact is created already linked to that record (`201`).
Existing contact, named by `contactId` or found by its email or LinkedIn URL	Its link moves to that record (`200`). The previous CRM record stops being synced: updates queued for it are cancelled. When your mapping includes the “synced with lemlist” field, it is set to false there; when it includes the Lemlist Contact ID, that field is cleared there.
The id is already linked to a lemlist contact, and at least one of the body’s `email` (its primary email), `linkedinUrl` or `linkedinUrlSalesNav` is that contact’s	The `crmId` finds the contact and that identifier confirms it: the body updates it (`200`) and its link stays as it is. The body’s other identifiers are written to the contact, unless they already belong to another contact: `409 CONTACT_IDENTIFIER_CONFLICT`. Sending the same payload twice is safe.
The id is already linked to a lemlist contact, and none of the body’s identifiers is that contact’s	Refused, nothing written: `409 CRM_ID_ALREADY_LINKED`, `error.conflictingRecord` names that contact. Another of its email addresses is not enough: only its primary email confirms it.

The crmSync block of the response shows the link the contact ends up with.

curl -X POST "https://api.lemlist.com/api/contacts" \
  -u ":YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "firstName": "John", "crmId": "123456789"}'

Every check runs before anything is written, so a refused call leaves the contact as it was:

Status	Code	When
`400`	`INVALID_CRM_ID`	The id does not have the format of your CRM, or points to another kind of record (a Salesforce Account id for a contact).
`400`	`NO_CRM_CONNECTED`	Your team has no CRM connected.
`403`	`CRM_ID_UPDATE_NOT_ALLOWED`	The API key does not belong to a team admin.
`409`	`CRM_ID_ALREADY_LINKED`	Another lemlist contact holds the id (see above); `error.conflictingRecord` names it.
`422`	`CRM_RECORD_NOT_FOUND`	No record with this id exists in the CRM, or it was deleted.
`422`	`CRM_RECORD_MERGED`	The record was merged into another one; `error.survivorId` is the id to send.
`422`	`CRM_RECORD_CONVERTED`	The Salesforce Lead was converted; `error.convertedContactId` is the Contact id to send.
`422`	`CRM_ID_LEADS_NOT_SYNCED`	A Salesforce Lead id, while your team does not sync Leads.
`503`	`CRM_RECORD_UNREACHABLE`	The CRM could not be reached to check the record. Retry.

{
  "success": false,
  "error": {
    "code": "CRM_ID_ALREADY_LINKED",
    "message": "This CRM id is already used by another lemlist record",
    "conflictingRecord": { "contactId": "ctc_A1B2C3D4E5F6G7H8i", "email": "jane@example.com", "name": "Jane Smith" }
  }
}

A Salesforce Lead id sent with the email of a contact already linked to the Contact of the same person, without contactId, keeps the existing link: the response is 200 with a CRM_ID_NOT_APPLIED entry in warnings. Send the contactId to move the link.

Owner assignment

You can assign an owner to the contact using the contactOwner field. Accepted formats:

Format	Example
User ID	`usr_2aB3cD4eF5gH6iJ7k`
Team member email	`john@yourcompany.com`

If the provided value does not match a team member (invalid format, unknown email, or unknown user ID), the contact is still written and the response carries an OWNER_NOT_FOUND or INVALID_OWNER_FORMAT entry in warnings. On creation, the contact defaults to the API key owner; on update, the current owner is unchanged.

On an existing contact, updateStrategy decides the owner:

Strategy	Current owner set	No current owner
`overwriteIgnoreEmpty` (default) and `overwrite`	Replaced by `contactOwner`	Set to `contactOwner`
`fillEmptyOnly`	Kept, reported as `ownerId` under `warnings` (`FIELDS_KEPT`)	Set to `contactOwner`

Without contactOwner, the owner is never touched.

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Query Parameters

updateStrategy

enum<string>

default:overwriteIgnoreEmpty

What an existing record keeps. overwriteIgnoreEmpty (default): sent values replace stored ones, empty values are ignored. overwrite: an empty string clears the field. fillEmptyOnly: only empty fields are filled, identifiers, links, owner and status kept. A new record receives every value sent. Other values: 400 INVALID_UPDATE_STRATEGY.

Available options:

overwrite,

overwriteIgnoreEmpty,

fillEmptyOnly

Body

application/json

contactId

string

Existing contact ID. Updates a specific contact by ID, bypassing email/LinkedIn matching. Can only be used to update an existing contact, not to create a new one. When provided, email and linkedinUrl are not required. At least one of contactId, email, linkedinUrl, or linkedinUrlSalesNav is required.

string

Contact email address. Used as a unique key for upsert matching. At least one of contactId, email, linkedinUrl, or linkedinUrlSalesNav is required.

linkedinUrl

string

LinkedIn profile URL. Used as an alternative unique key for upsert matching. At least one of contactId, email, linkedinUrl, or linkedinUrlSalesNav is required.

linkedinUrlSalesNav

string

LinkedIn Sales Navigator profile URL. Used as an alternative unique key for upsert matching.

additionalEmails

string[]

Additional email addresses for the contact. Each must be a valid email address.

firstName

string

Contact first name.

lastName

string

Contact last name.

phone

string

Contact phone number.

jobTitle

string

Contact job title. If a company is linked, this is saved as part of the job data.

jobDescription

string

Contact job description. If a company is linked, this is saved as part of the job data.

picture

string

URL of the contact's profile picture.

timezone

string

Contact timezone.

industry

string

Contact industry.

languages

string

Contact languages.

location

string

Contact location.

skills

string

Contact skills.

summary

string

Contact summary or bio.

tagline

string

Contact tagline.

peopleDbSeniority

string

Seniority of the person, from the People Database.

peopleDbDepartment

string

Department of the person, from the People Database.

peopleDbConnectionCount

string

LinkedIn connections count of the person, from the People Database. 500 usually means 500 or more.

contactOwner

string

Owner of the contact. Can be a user ID (e.g. usr_...) or a team member's email address. If the provided value does not match a team member, the contact is still written with an OWNER_NOT_FOUND or INVALID_OWNER_FORMAT entry in warnings: the owner defaults to the API key owner on creation and is unchanged on update. On update it replaces the current owner, except under fillEmptyOnly where it is only set when the contact has none.

source

string

default:api

Origin of the contact record. Set on creation only and cannot be updated afterwards. Defaults to api.

companyId

string

ID of a company already existing in lemlist to link to this contact. Takes priority over companyDomain and companyLinkedinUrl.

companyDomain

string

Domain of a company already existing in lemlist to link to this contact (e.g. lemlist.com). Used if companyId is not provided.

companyLinkedinUrl

string

LinkedIn URL of a company already existing in lemlist to link to this contact. Used if companyId and companyDomain are not provided.

crmId

string

Closed beta: refused as an unknown field (400 INVALID_FIELD) unless the CRM ID remap beta is enabled for your team. Id of the record of the connected CRM to link the 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. A new contact is created already linked; an existing one has its link moved to this record. An id another contact holds updates that contact when the body carries its email or LinkedIn URL, and is refused otherwise. See the endpoint page for the refusals.

Example:

"123456789"

{key}

any

Any additional key is treated as a custom field. Custom fields must be registered in the team's CRM field registry beforehand.

Response

Existing contact updated (upsert matched by email or LinkedIn URL)

success

boolean

data

object

Same shape as the 201 response, with created: false and updated: true.

warnings

object[]

Non-blocking notices: owner or company not resolved, or FIELDS_KEPT when the update strategy kept values you sent (params.fields names them).

Show child attributes

Getting started

Popular Resources

Endpoints

Objects & Definitions

Add and update contact

Upsert matching

Update strategy

Linking to a company

Linking to a CRM record

Owner assignment

Authorizations

Query Parameters

Body

Response

​Upsert matching

​Update strategy

​Linking to a company

​Linking to a CRM record

​Owner assignment

Authorizations

Query Parameters

Body

Response

Upsert matching

Update strategy

Linking to a company

Linking to a CRM record

Owner assignment