> ## 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.
> Retrieves contacts by IDs/emails, or searches by name, email, contact list, or campaign membership.
# Get Many Contacts
export const SnippetObjectReference = ({objectName, objectPath = null}) => {
const lowerCaseObjectName = objectName.toLowerCase();
if (lowerCaseObjectName === 'lead' || lowerCaseObjectName === 'leads') {
return
This endpoint uses the {objectName} object. Make sure to also check the {lowerCaseObjectName === 'lead' ? 'Contact' : 'Lead'} object to understand the distinction between the two.
;
}
return
This endpoint uses the {objectName} object.
;
};
## Query modes
This endpoint supports two query modes:
| Mode | Parameters | Response format |
| ----------------- | ------------------------------------------------------ | -------------------------------------------------------- |
| **By IDs/emails** | `idsOrEmails` | Array of contacts |
| **Search/filter** | `search`, `email`, `listId`, and/or `notInAnyCampaign` | Paginated object with `data`, `total`, `limit`, `offset` |
### 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`.
## OpenAPI
````yaml get /contacts
openapi: 3.0.0
info:
title: lemlist API
version: 1.0.0
description: >-
Welcome to the lemlist Developer Documentation.
lemlist is very customizable and open. You'll find on this page all the API
and integration you can do with lemlist.
# Rate Limit
lemlist's API rate limits requests in order to prevent abuse and overload of
our services.
Rate limits are applied on all routes and per API key performing the
request.
The rate limits are **20** requests per **2** seconds.
The response provides any information you may need about it:
| Header | Description |
| --- | --- |
| Retry-After | The number of seconds in which you can retry |
| X-RateLimit-Limit | The maximum requests in that time |
| X-RateLimit-Remaining | The number of remaining requests you can make |
| X-RateLimit-Reset | The date when the rate limit will reset |
_Example of values for the rate limit headers_
``` json
{
"Retry-After": 2,
"X-RateLimit-Limit": 20,
"X-RateLimit-Remaining": 7,
"X-RateLimit-Reset" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)"
}
```
# Definitions
## Team
A team is the entity of lemlist that can handle users and billing.
## Credits
Credits are the coins a team uses to enrich emails, LinkedIn URLs, etc. via
the enrich route. Each enrichment feature needs a certain amount of credits
to run.
## User
You use a user account to connect to lemlist and send messages via the
connected emails or LinkedIn account.
## Campaign
A campaign is the entity to automate outreach. A campaign has multiple
sequences composed of steps.
## Lead
A lead is a person that you try to contact via a campaign.
## Activity
An activity is the history of all the steps.
## Unsubscribe
An unsubscribe occurs when a person decides they don't want to receive
emails from you anymore.
# Authentication
All API routes use the dedicated subdomain `api.lemlist.com`.
lemlist uses API keys to allow access to the API. You can get your lemlist
API key at our [integration
page](https://app.lemlist.com/settings/integrations).
You need to add the `Authorization` header using the `Basic` authentication
type. `login:password` **where the login is always empty and the password is
the API key**.
⚠️ **Don't forget to add the semicolon (**`:`**) before your API key in curl
command.**
> To authorize, use this code:
``` shell
curl https://api.lemlist.com/api/team \
--user ":YourApiKey"
```
**Make sure to replace** **`YourApiKey`** **with your API key.**
# Give feedback
If you want to report a bug, ask for data, or share with us a use case,
please fill this [form](https://lemlist.typeform.com/to/mfVlkyGf). It will
help us centralize your needs!
servers:
- url: https://api.lemlist.com/api
security:
- basicAuth: []
paths:
/contacts:
get:
tags:
- Contacts
summary: Get Many Contacts
description: >-
Retrieves contacts by IDs/emails, or searches/lists contacts by name,
email, contact list, campaign membership, or company link.
When using `idsOrEmails`, returns an array of matching contacts
directly.
When using `search`, `email`, `listId`, `notInAnyCampaign`, any of the
`company*` filters, or no filter at all, returns a paginated response
with `data`, `total`, `limit`, and `offset` fields. You can combine
filters together to narrow results (e.g. `listId` with `search`, or
`notInAnyCampaign` with `companyId`). Calling the endpoint without any
filter returns all contacts of the team, paginated.
The `company*` filters (`companyId`, `companyDomain`,
`companyLinkedinUrl`, `companySalesnavUrl`) are mutually exclusive — use
only one at a time. `companyDomain` / `companyLinkedinUrl` /
`companySalesnavUrl` are resolved to a `companyId` through the Companies
collection; if no matching company exists, the endpoint returns an empty
list with `total: 0` (not an error), which keeps automation flows
simple.
parameters:
- name: idsOrEmails
in: query
required: false
description: >-
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.
example: ctc_xW8Ou6C03Csv8vatp,riley@example.com
schema:
type: string
style: form
explode: false
- name: search
in: query
required: false
description: >-
Search contacts by name or other text fields. Must be at least 2
characters.
schema:
type: string
- name: email
in: query
required: false
description: Search contacts by exact email address.
schema:
type: string
format: email
- name: listId
in: query
required: false
description: >-
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`.
example: clt_abc123def456ghi78
schema:
type: string
pattern: ^clt_[a-zA-Z0-9]+$
- name: notInAnyCampaign
in: query
required: false
description: >-
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`.
schema:
type: boolean
- name: companyId
in: query
required: false
description: >-
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`.
example: cpn_A1B2C3D4E5F6G7H8I
schema:
type: string
pattern: ^cpn_[a-zA-Z0-9]+$
- name: companyDomain
in: query
required: false
description: >-
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.
example: acme.com
schema:
type: string
- name: companyLinkedinUrl
in: query
required: false
description: >-
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.
example: https://www.linkedin.com/company/acme
schema:
type: string
- name: companySalesnavUrl
in: query
required: false
description: >-
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.
example: https://www.linkedin.com/sales/company/12345678
schema:
type: string
- name: limit
in: query
required: false
description: Maximum number of contacts to return (1–500). Defaults to 100.
schema:
type: integer
minimum: 1
maximum: 500
default: 100
- name: offset
in: query
required: false
description: Number of contacts to skip for pagination. Defaults to 0.
schema:
type: integer
minimum: 0
default: 0
responses:
'200':
description: >-
Success. When using `idsOrEmails`, returns an array of contacts.
Otherwise, returns a paginated object with `data`, `total`, `limit`,
and `offset`.
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: '#/components/schemas/Contact'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
total:
type: integer
limit:
type: integer
offset:
type: integer
required:
- data
- total
- limit
- offset
example:
- _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
'400':
description: >-
Possible errors: Bad team / search query too short / invalid listId
format
content:
text/plain:
example: Search query must be at least 2 characters
'401':
description: The authentication you supplied is incorrect
content:
text/plain:
example: The authentication you supplied is incorrect
'405':
description: Method not allowed
components:
schemas:
Contact:
type: object
description: >-
A contact record in your CRM. Not to be confused with a lead which is a
contact specifically added to a campaign.
properties:
_id:
type: string
description: Unique contact identifier
teamId:
type: string
description: Team identifier the contact belongs to
fullName:
type: string
description: Contact's calculated full name
email:
type: string
format: email
description: Contact's primary email address
fields:
type: object
description: Custom fields associated with the contact
additionalProperties: true
campaigns:
type: array
description: List of campaigns the contact is associated with
items:
type: object
properties:
campaignId:
type: string
campaignState:
type: string
leadState:
type: string
leadId:
type: string
ownerId:
type: string
description: ID of the user who owns this contact
createdAt:
type: string
format: date-time
description: Contact creation timestamp
createdBy:
type: string
description: ID of the user who created the contact
unsubscribed:
type: boolean
description: >-
Whether the contact is globally unsubscribed. When true, no outreach
will be sent to this contact.
securitySchemes:
basicAuth:
type: http
scheme: basic
````