> ## 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 from your CRM. Use `idsOrEmails` to fetch specific contacts by ID or email in a single request (max 100), `crmIds` to find them from their record id in your connected CRM, or omit them to search/list contacts 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 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`.
## 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: []
tags:
- name: Enrichment Providers
description: >-
The data providers lemlist can call to find an email or a phone.
Internal providers are paid with lemlist credits and always available.
External providers run on your own account: connect one by saving its API
key, and it becomes available to your waterfalls. `GET
/enrichments/providers` is the catalog of provider ids accepted by the
waterfall endpoints.
- name: Enrichment Waterfalls
description: >-
Control which data providers lemlist calls when enriching a contact, and
in which order.
A waterfall is an ordered list of providers for one enrichment `type`
(`email` or `phone`). Providers are tried one after the other until one
returns a result.
Every team has exactly one default waterfall per type (`isDefault: true`).
While its `editor` is `lemlist` it follows the lemlist behaviour:
providers you connected with your own API key are tried first, then
internal providers in a random order. Once a team member edits its
provider list, `editor` becomes that user's id and the list is followed as
is; resetting it hands it back to `lemlist`.
Custom waterfalls (`isDefault: false`) carry `conditions` on the contact
being enriched, keyed by contact property; every key present must match.
When a contact is enriched, lemlist runs a single waterfall: the custom
waterfall of the requested type whose conditions match the contact, or the
default waterfall when none does. If several match, the one with the most
condition keys wins, then the most recently updated. Only that waterfall
runs; when it finds nothing, the enrichment ends without falling back to
another one.
paths:
/contacts:
get:
tags:
- Contacts
summary: Get Many Contacts
description: >-
Retrieves contacts by IDs/emails or by CRM record ids, 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 `crmIds`, looks the contacts up by their record id in the
connected CRM (HubSpot, Salesforce, or Pipedrive) and returns an array
of the contacts found, each with the matched id under
`crmSync.crmRecordId`. `idsOrEmails` takes precedence over `crmIds`; a
lookup ignores the search filters and the pagination.
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.
A lookup returns full contacts (`Contact`); the list returns
`ContactListItem` objects.
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. Maximum 100 values.
example: ctc_xW8Ou6C03Csv8vatp,riley@example.com
schema:
type: string
style: form
explode: false
- name: crmIds
in: query
required: false
description: >-
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.
example: 123456789,987654321
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: withPrimaryCompany
in: query
required: false
description: >-
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`).
example: false
schema:
type: boolean
- name: fieldRejectionReason
in: query
required: false
description: >-
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).
example: enrichment_duplicate_linkedin_url
schema:
type: string
enum:
- 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_value_oscillating
- crm_sync_owner_sync_loop
- crm_sync_unmapped_user
- crm_sync_value_incompatible
- crm_sync_unknown_error
- 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` 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`.
content:
application/json:
schema:
oneOf:
- title: Lookup by idsOrEmails or crmIds
type: array
items:
$ref: '#/components/schemas/Contact'
- title: List
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContactListItem'
total:
type: integer
limit:
type: integer
offset:
type: integer
required:
- data
- total
- limit
- offset
examples:
lookup:
summary: idsOrEmails or crmIds
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
crmSync:
provider: hubspot
crmRecordId: '123456789'
syncDisabled: false
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
list:
summary: List
value:
data:
- _id: ctc_xW8Ou6C03Csv8vatp
teamId: tea_8QvkOiBfPdb2ZRhHi
fullName: John Doe
email: support@lemlist.com
firstName: John
lastName: Doe
jobTitle: Growth Engineer
ownerId: usr_ahfFktBBHUIxbVG5P
companyId: cpn_Hk2Wd9LmQx7RtB4sN
createdAt: '2025-10-28T00:40:37.917Z'
createdBy: usr_ahfFktBBHUIxbVG5P
unsubscribed: false
campaignCount: 1
fieldRejections: []
total: 1
limit: 100
offset: 0
'400':
description: >-
Either a plain `{ "error": "..." }` (`Bad team`, search query too
short, invalid `listId` format, invalid `withPrimaryCompany`,
`limit` below 1, more than 100 `idsOrEmails` values), or a
validation envelope. Possible error codes: `INVALID_CRM_ID` (a
`crmIds` list with no usable value, or a value longer than 25
characters), `TOO_MANY_CRM_IDS` (more than 100 `crmIds` values),
`MULTIPLE_COMPANY_FILTERS`, `INVALID_COMPANY_ID`,
`INVALID_FIELD_REJECTION_REASON`.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiErrorMessage'
- $ref: '#/components/schemas/ApiErrorEnvelope'
examples:
search-too-short:
value:
error: Search query must be at least 2 characters
too-many-ids-or-emails:
value:
error: Too many ids or emails (max 100)
invalid-crm-id:
value:
success: false
error:
code: INVALID_CRM_ID
message: Invalid crmId value
too-many-crm-ids:
value:
success: false
error:
code: TOO_MANY_CRM_IDS
message: crmIds exceeds the maximum of 100 values
'401':
description: The authentication you supplied is incorrect
content:
text/plain:
example: The authentication you supplied is incorrect
'404':
description: No contact matches the `idsOrEmails` values.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorMessage'
example:
error: Contact not found
'405':
description: Method not allowed
components:
schemas:
Contact:
type: object
description: >-
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.
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: >-
Contact fields, standard (`firstName`, `lastName`, `phone`,
`jobTitle`...) and custom
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
linkedinUrl:
type: string
description: Contact's LinkedIn profile URL
linkedinUrlSalesNav:
type: string
description: Contact's LinkedIn Sales Navigator URL
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.
phonesStatuses:
type: array
description: Verification status of each verified phone number.
items:
type: object
properties:
phone:
type: string
description: The phone number, as stored in `fields`
status:
type: string
enum:
- valid
- invalid
crmSync:
type: object
description: >-
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.
properties:
provider:
type: string
enum:
- hubspot
- salesforce
- pipedrive
description: Active CRM provider for the team.
crmRecordId:
type: string
nullable: true
description: >-
Identifier of the contact record on the CRM side. `null` when
the lemlist contact has not been synced yet.
syncDisabled:
type: boolean
description: When `true`, automatic sync is paused for this contact.
errors:
type: array
description: >-
List of recent sync errors. Empty when the contact is synced
cleanly.
items:
type: object
properties:
type:
type: string
description: >-
Coarse error category (e.g. `CONNECT_FAILED`,
`CREATE_FAILED`, `UPDATE_FAILED`).
reason:
type: string
description: >-
Specific error reason (e.g. `UNIQUE_INDEX_ERROR_CONTACT`,
`INVALID_EMAIL`, `PROPERTY_DOESNT_EXIST`).
raisedAt:
type: string
format: date-time
description: Timestamp when the error was last raised.
metadata:
type: object
additionalProperties: true
description: >-
Extra context. For `UNIQUE_INDEX_ERROR_COMPANY`, contains
`alreadyExistingCompanyId` — the lemlist company that
already occupies the conflicting CRM record. Use it to
remap contacts onto the right lemlist company before
deleting the duplicate.
fieldRejections:
type: array
description: >-
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=...`.
items:
$ref: '#/components/schemas/FieldRejection'
ContactListItem:
type: object
description: >-
A contact as the list (`GET /contacts` with filters or no parameter)
returns it, with the main fields flattened. Properties with no value are
omitted.
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
firstName:
type: string
description: Contact's first name
lastName:
type: string
description: Contact's last name
phone:
type: string
description: Contact's phone number
jobTitle:
type: string
description: Contact's job title
linkedinUrl:
type: string
description: Contact's LinkedIn profile URL
linkedinUrlSalesNav:
type: string
description: Contact's LinkedIn Sales Navigator URL
ownerId:
type: string
description: ID of the user who owns this contact
companyId:
type: string
description: ID of the company the contact is attached to (`cpn_xxx`)
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.
campaignCount:
type: integer
description: Number of campaigns the contact is in
fieldRejections:
type: array
description: >-
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=...`.
items:
$ref: '#/components/schemas/FieldRejection'
ApiErrorMessage:
type: object
description: Error answered as a plain message by the contact and company endpoints.
properties:
error:
type: string
description: Human-readable explanation.
required:
- error
ApiErrorEnvelope:
type: object
description: Error envelope of the contact and company endpoints.
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
description: Machine-readable error code, stable across releases.
message:
type: string
description: Human-readable explanation.
required:
- code
- message
required:
- success
- error
FieldRejection:
type: object
description: >-
A value lemlist refused to write on a Contact or Company, with the
reason why. Surfaced under `fieldRejections[]` on those objects; filter
a list endpoint to only flagged records via the `fieldRejectionReason`
query param.
properties:
field:
type: string
description: >-
The record field the rejected value targeted (e.g. `emails`,
`linkedinUrl`, `domain`).
reason:
type: string
description: >-
Why the value was rejected, prefixed by its origin — `enrichment_*`
(raised while enriching) or `crm_sync_*` (raised during CRM sync).
Same values accepted by the `fieldRejectionReason` query param.
source:
type: string
description: >-
Where the rejection came from — an enrichment source (`lemrich`) or
a CRM provider (`hubspot`, `salesforce`, `pipedrive`).
conflictingRecordId:
type: string
description: >-
The lemlist record that already holds the value, when the rejection
identifies one — use it to merge or remap before resolving the
duplicate. Always a lemlist id (`ctc_…` for a contact, `cpn_…` for a
company), never a CRM record id. Omitted otherwise.
rejectedValue:
type: string
description: The value that was refused.
rejectedAt:
type: string
format: date-time
description: When the rejection was recorded.
securitySchemes:
basicAuth:
type: http
scheme: basic
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.