Skip to main content
GET
/
contacts
Get Many Contacts
curl --request GET \
  --url https://api.lemlist.com/api/contacts \
  --header 'Authorization: Basic <encoded-value>'
[
  {
    "_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
  },
  {
    "_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
  }
]

Documentation Index

Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Query modes

This endpoint supports two query modes:
ModeParametersResponse format
By IDs/emailsidsOrEmailsArray of contacts
Search/filtersearch, email, listId, and/or notInAnyCampaignPaginated object with contacts, total, limit, offset
At least one of idsOrEmails, search, email, listId, or notInAnyCampaign is required.

​
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.

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. At least one of idsOrEmails, search, email, listId, or notInAnyCampaign is required.

​
search
string

Search contacts by name or other text fields. Must be at least 2 characters. At least one of idsOrEmails, search, email, listId, or notInAnyCampaign is required.

​
email
string<email>

Search contacts by exact email address. At least one of idsOrEmails, search, email, listId, or notInAnyCampaign is required.

​
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.

​
limit
integer
default:20

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

Required range: 1 <= x <= 100
​
offset
integer
default:0

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

Required range: x >= 0

Response

Success

​
_id
string

Unique contact identifier

​
teamId
string

Team identifier the contact belongs to

​
fullName
string

Contact's calculated full name

​
email
string<email>

Contact's primary email address

​
fields
object

Custom fields associated with the contact

​
campaigns
object[]

List of campaigns the contact is associated with

​
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.