Lemlist Developer Docs

Get Many Contacts

curl --request GET \
  --url https://api.lemlist.com/api/contacts \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

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::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

[
  {
    "_id": "ctc_xW8Ou6C03Csv8vatp",
    "teamId": "tea_8QvkOiBfPdb2ZRhHi",
    "fullName": "John Doe",
    "email": "support@lemlist.com",
    "fields": {
      "firstName": "John",
      "jobTitle": "Growth Engineer",
      "lastName": "Doe",
      "industry": "Technology",
      "isActiveInCampaigns": false,
      "lastCampaign": "NEW TO DELETE",
      "lastLeadMarkedAsInterestedDate": "2025-10-28T02:12:31.971Z",
      "leadStatus": "Marked as not Interested by api"
    },
    "campaigns": [
      {
        "campaignId": "cam_bSn8EORHQxbWPjHvu",
        "campaignState": "running",
        "leadState": "review",
        "leadId": "lea_fiDpiGV585wy3Oii2"
      }
    ],
    "ownerId": "usr_ahfFktBBHUIxbVG5P",
    "createdAt": "2025-10-28T00:40:37.917Z",
    "createdBy": "usr_ahfFktBBHUIxbVG5P",
    "unsubscribed": false,
    "crmSync": {
      "provider": "hubspot",
      "crmRecordId": "123456789",
      "syncDisabled": false,
      "searching": false,
      "notFoundAt": null,
      "errors": []
    }
  },
  {
    "_id": "ctc_a9RxJNa7pmMd85H9b",
    "teamId": "tea_8QvkOiBfPdb2ZRhHi",
    "fullName": "Casey",
    "email": "riley@example.com",
    "fields": {
      "firstName": "Casey",
      "isActiveInCampaigns": false
    },
    "campaigns": [
      {
        "campaignId": "cam_jwm7THjgGFE3ylR85",
        "campaignState": "running",
        "leadState": "done",
        "leadId": "lea_XKjAytuJhBKZhxhWh"
      },
      {
        "campaignId": "cam_eF4DlNERV0CW1TwRd",
        "campaignState": "running",
        "leadState": "done",
        "leadId": "lea_fJcS9D3UtEqZcDcAG"
      },
      {
        "campaignId": "cam_UBbMt30jHq0vNJKJr",
        "campaignState": "running",
        "leadState": "done",
        "leadId": "lea_GlaMfjxlUYuwEDL0w"
      },
      {
        "campaignId": "cam_pijDVnytN5S7frriD",
        "campaignState": "running",
        "leadState": "review",
        "leadId": "lea_Bs9aMGCcjdzTDvixY"
      }
    ],
    "ownerId": "usr_Emu1g29BMtBixhMSP",
    "createdAt": "2024-10-01T09:00:13.831Z",
    "createdBy": "usr_Emu1g29BMtBixhMSP",
    "unsubscribed": true
  }
]

GET

contacts

Get Many Contacts

curl --request GET \
  --url https://api.lemlist.com/api/contacts \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

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::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

[
  {
    "_id": "ctc_xW8Ou6C03Csv8vatp",
    "teamId": "tea_8QvkOiBfPdb2ZRhHi",
    "fullName": "John Doe",
    "email": "support@lemlist.com",
    "fields": {
      "firstName": "John",
      "jobTitle": "Growth Engineer",
      "lastName": "Doe",
      "industry": "Technology",
      "isActiveInCampaigns": false,
      "lastCampaign": "NEW TO DELETE",
      "lastLeadMarkedAsInterestedDate": "2025-10-28T02:12:31.971Z",
      "leadStatus": "Marked as not Interested by api"
    },
    "campaigns": [
      {
        "campaignId": "cam_bSn8EORHQxbWPjHvu",
        "campaignState": "running",
        "leadState": "review",
        "leadId": "lea_fiDpiGV585wy3Oii2"
      }
    ],
    "ownerId": "usr_ahfFktBBHUIxbVG5P",
    "createdAt": "2025-10-28T00:40:37.917Z",
    "createdBy": "usr_ahfFktBBHUIxbVG5P",
    "unsubscribed": false,
    "crmSync": {
      "provider": "hubspot",
      "crmRecordId": "123456789",
      "syncDisabled": false,
      "searching": false,
      "notFoundAt": null,
      "errors": []
    }
  },
  {
    "_id": "ctc_a9RxJNa7pmMd85H9b",
    "teamId": "tea_8QvkOiBfPdb2ZRhHi",
    "fullName": "Casey",
    "email": "riley@example.com",
    "fields": {
      "firstName": "Casey",
      "isActiveInCampaigns": false
    },
    "campaigns": [
      {
        "campaignId": "cam_jwm7THjgGFE3ylR85",
        "campaignState": "running",
        "leadState": "done",
        "leadId": "lea_XKjAytuJhBKZhxhWh"
      },
      {
        "campaignId": "cam_eF4DlNERV0CW1TwRd",
        "campaignState": "running",
        "leadState": "done",
        "leadId": "lea_fJcS9D3UtEqZcDcAG"
      },
      {
        "campaignId": "cam_UBbMt30jHq0vNJKJr",
        "campaignState": "running",
        "leadState": "done",
        "leadId": "lea_GlaMfjxlUYuwEDL0w"
      },
      {
        "campaignId": "cam_pijDVnytN5S7frriD",
        "campaignState": "running",
        "leadState": "review",
        "leadId": "lea_Bs9aMGCcjdzTDvixY"
      }
    ],
    "ownerId": "usr_Emu1g29BMtBixhMSP",
    "createdAt": "2024-10-01T09:00:13.831Z",
    "createdBy": "usr_Emu1g29BMtBixhMSP",
    "unsubscribed": true
  }
]

Query modes

This endpoint supports the following query modes:

Mode	Parameters	Response format
By IDs/emails	`idsOrEmails`	Array of `Contact`
By CRM record ids	`crmIds`	Array of `Contact`, the ones found
Search/filter	`search`, `email`, `listId`, and/or `notInAnyCampaign`	Paginated object with `data`, `total`, `limit`, `offset`, where `data` holds `ContactListItem` objects

A request uses one lookup at most: idsOrEmails takes precedence over crmIds. A lookup ignores the search filters and the pagination.

Response shapes

A lookup (idsOrEmails, crmIds) returns full Contact objects: fields under fields, campaigns with their lead id, and crmSync when the contact has a record in the connected CRM.
The list returns ContactListItem objects.

When nothing matches, idsOrEmails answers 404 and crmIds answers 200 with an empty array.

Finding a contact from your CRM

Use crmIds (up to 100, comma-separated) with the record ids of your connected CRM, for example GET /contacts?crmIds=123456789 with a HubSpot contact id; for Salesforce, pass the 18-character Contact or Lead id. Each contact found carries the matched id under crmSync.crmRecordId; ids that match nothing are skipped.

Filtering by contact list

Use the listId parameter to retrieve contacts belonging to a specific list. Get valid list IDs from GET /contacts/lists. You can combine listId with search or email to further narrow results within a list.

Filtering contacts not in any campaign

Use notInAnyCampaign=true to find contacts that are not part of any campaign (orphan contacts). This can be used alone or combined with other filters like search, email, or listId.

Filtering by CRM sync state

Use crmSyncStatus to list the contacts in a given sync state on your connected CRM: for example GET /contacts?crmSyncStatus=error for every contact the CRM sync refused, or crmSyncStatus=contact_blocked_by_company_without_name for one root cause. A CRM must be connected, otherwise the request answers 400 NO_CRM_CONNECTED. It can be combined with the other filters.

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

idsOrEmails

string

A comma separated string of either valid contact IDs (MongoDB ObjectId) or valid email addresses. Optional — when omitted, returns the paginated list of all contacts of the team. Maximum 100 values.

crmIds

string

Comma-separated record ids of contacts in the CRM connected to the team (HubSpot, Salesforce, or Pipedrive); for Salesforce, the 18-character Contact or Lead id. Returns an array of the contacts found, each with the matched id under crmSync.crmRecordId; ids that match nothing are skipped, and the array is empty when no CRM is connected. Duplicates are removed; an empty value is ignored. Maximum 100 values (TOO_MANY_CRM_IDS); a value over 25 characters answers INVALID_CRM_ID. Ignored when idsOrEmails is provided.

string

Search contacts by name or other text fields. Must be at least 2 characters.

string<email>

Search contacts by exact email address.

listId

string

Filter contacts by contact list ID (clt_xxx format). Can be combined with search or email, or used alone to list all contacts in a list. Get valid IDs from GET /contacts/lists.

Pattern: ^clt_[a-zA-Z0-9]+$

notInAnyCampaign

boolean

When set to true, only returns contacts that are not part of any campaign (orphan contacts). Can be used alone or combined with other filters such as search, email, or listId.

companyId

string

Filter contacts by attached company ID (cpn_xxx format). Use this when you already know the lemlist company id (for example after fetching GET /companies?crmSyncStatus=unique_index_error_company). Mutually exclusive with companyDomain, companyLinkedinUrl, and companySalesnavUrl.

Pattern: ^cpn_[a-zA-Z0-9]+$

companyDomain

string

Filter contacts by their company's website domain. Resolved to a companyId against the Companies collection. If no company matches, the endpoint returns an empty list (total: 0). Mutually exclusive with the other company* filters.

companyLinkedinUrl

string

Filter contacts by their company's LinkedIn URL. Resolved to a companyId against the Companies collection. If no company matches, the endpoint returns an empty list (total: 0). Mutually exclusive with the other company* filters.

companySalesnavUrl

string

Filter contacts by their company's LinkedIn Sales Navigator URL. Resolved to a companyId against the Companies collection. If no company matches, the endpoint returns an empty list (total: 0). Mutually exclusive with the other company* filters.

withPrimaryCompany

boolean

When set to true, only returns contacts linked to a company; when set to false, only returns contacts without a company. Omit for no filter. Mutually exclusive with the company* filters (companyId, companyDomain, companyLinkedinUrl, companySalesnavUrl).

fieldRejectionReason

enum<string>

Filter contacts to those carrying a field rejection with this reason — a value lemlist refused to write, prefixed by its origin (enrichment_* while enriching, crm_sync_* during CRM sync). Returns an empty list (total: 0) when no contact matches. Each returned contact exposes the full detail under fieldRejections[] (which field, why, and conflictingRecordId for duplicates). Only applies to the paginated list — ignored when idsOrEmails is provided (that path returns the exact contacts requested, unfiltered).

Available options:

enrichment_duplicate_linkedin_url,

enrichment_duplicate_linkedin_url_sales_nav,

enrichment_duplicate_email,

crm_sync_duplicate_linkedin_url,

crm_sync_duplicate_linkedin_url_sales_nav,

crm_sync_invalid_linkedin_url,

crm_sync_invalid_url,

crm_sync_invalid_email,

crm_sync_invalid_phone,

crm_sync_linkedin_url_not_contact,

crm_sync_duplicate_contact_blocked,

crm_sync_duplicate_company_blocked,

crm_sync_company_data_rejected,

crm_sync_unsub_state_protected,

crm_sync_unsub_channel_empty,

crm_sync_value_oscillating,

crm_sync_owner_sync_loop,

crm_sync_unmapped_user,

crm_sync_value_incompatible,

crm_sync_unknown_error

crmSyncStatus

enum<string>

Filter contacts by their CRM sync state against the team's active CRM provider. Requires a CRM (Hubspot, Salesforce, or Pipedrive) to be connected — otherwise the request returns 400 NO_CRM_CONNECTED. Values:

synced — the contact has a CRM record and no sync errors.
not_synced — the contact has no CRM record yet.
searching — a CRM search (Search & connect, Create in CRM) is queued or running for the contact.
not_found — the last CRM search found no record for the contact.
error — at least one sync error is currently raised, whatever its reason.
A specific error reason (lowercase form), to filter by root cause:
- invalid_email — the CRM refused the contact's email.
- property_doesnt_exist — a mapped property does not exist in the CRM.
- required_field_missing — a field the CRM requires is missing.
- unique_index_error_contact — the CRM record is already synced with another lemlist contact.
- contact_already_exists_with_name, contact_already_exists_with_linkedin_url, contact_already_exists_with_email — a CRM contact already exists with the same first and last name, LinkedIn URL or email.
- contact_blocked_by_company — contact not created: its company already exists in the CRM.
- contact_blocked_by_company_search — contact not created: the company search is incomplete, retried later.
- contact_blocked_by_company_without_name — contact not created: its company needs a name to be found in the CRM.
- contact_blocked_by_company_without_key — contact not created: its company needs a domain or LinkedIn URL to be found in the CRM.
- contact_blocked_by_company_already_synced — contact not created: its company is already synced with another lemlist company.

Only applies to the paginated list — ignored when idsOrEmails or crmIds is provided.

Available options:

synced,

not_synced,

error,

searching,

not_found,

invalid_email,

property_doesnt_exist,

required_field_missing,

unique_index_error_contact,

contact_already_exists_with_name,

contact_already_exists_with_linkedin_url,

contact_already_exists_with_email,

contact_blocked_by_company,

contact_blocked_by_company_search,

contact_blocked_by_company_without_name,

contact_blocked_by_company_without_key,

contact_blocked_by_company_already_synced

limit

integer

default:100

Maximum number of contacts to return (1–500). Defaults to 100.

Required range: 1 <= x <= 500

offset

integer

default:0

Number of contacts to skip for pagination. Defaults to 0.

Required range: x >= 0

Response

Success. When using idsOrEmails or crmIds, returns an array of contacts (empty when no crmIds value matches). Otherwise, returns a paginated object with data (ContactListItem items), total, limit, and offset.

Lookup by idsOrEmails or crmIds · object[]
List · object

A contact record in your CRM, as the lookups (GET /contacts?idsOrEmails=, GET /contacts?crmIds=, GET /contacts/{idOrEmail}) return it. Not to be confused with a lead which is a contact specifically added to a campaign.

_id

string

Unique contact identifier

teamId

string

Team identifier the contact belongs to

fullName

string

Contact's calculated full name

string<email>

Contact's primary email address

fields

object

Contact fields, standard (firstName, lastName, phone, jobTitle...) and custom

campaigns

object[]

List of campaigns the contact is associated with

Show child attributes

linkedinUrl

string

Contact's LinkedIn profile URL

linkedinUrlSalesNav

string

Contact's LinkedIn Sales Navigator URL

ownerId

string

ID of the user who owns this contact

createdAt

string<date-time>

Contact creation timestamp

createdBy

string

ID of the user who created the contact

unsubscribed

boolean

Whether the contact is globally unsubscribed. When true, no outreach will be sent to this contact.

phonesStatuses

object[]

Verification status of each verified phone number.

Show child attributes

crmSync

object

CRM sync status for the contact, resolved against the team's active CRM provider (Hubspot, Salesforce, or Pipedrive). Only present when a CRM is connected and the contact has a record in it. crmRecordId maps a crmIds lookup back to the ids sent.

Show child attributes

fieldRejections

object[]

Values lemlist refused to write on this contact, each with its reason. Empty when none. Filter the list endpoint to only flagged contacts via GET /contacts?fieldRejectionReason=....

Show child attributes

Getting started

Popular Resources

Endpoints

Objects & Definitions

Get Many Contacts

Query modes

Response shapes

Finding a contact from your CRM

Filtering by contact list

Filtering contacts not in any campaign

Filtering by CRM sync state

Authorizations

Query Parameters

Response