> ## 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.
> Searches the people database using filters, keywords, and pagination.
# Search people database
To know which filters you are able to use, refer to the [GET Filters](/api-reference/endpoints/people-database/get-database-filters) section.
If you need more details about the schema of the people returned as a results array, refer to the [GET People Schema section](/api-reference/endpoints/people-database/get-people-schema) section.
## OpenAPI
````yaml post /database/people
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:
/database/people:
post:
tags:
- People Database
summary: Search People Database
description: >-
This endpoint allows you to query our People database. To do so, you may
use the following parameters: filters (required), page (optional), size
(optional), and excludes (optional). Each filter should have the
following properties: filterId (filter identifier), in (list of the
values you want to include), and out (list of the values you want to
exclude). To know which filters you are able to use, refer to the GET
Filters section.
operationId: searchPeopleDatabase
parameters: []
requestBody:
description: >-
Search criteria. Provide one or more filters and optionally control
pagination with page/size
content:
application/json:
schema:
type: object
properties:
filters:
type: array
description: Array of filters (required)
items:
type: object
properties:
filterId:
type: string
description: Filter identifier
in:
type: array
items:
type: string
description: List of the values you want to include
out:
type: array
items:
type: string
description: List of the values you want to exclude
page:
type: integer
minimum: 1
description: Page (optional)
size:
type: integer
minimum: 1
maximum: 100
description: Size of the results, number between 1 and 100 (optional)
excludes:
type: array
items:
type: string
description: Array of properties to exclude from the results (optional)
search:
type: string
description: >-
Free-text query across common people fields (e.g., name,
title, company, location)
example:
filters:
- filterId: country
in:
- France
out:
- India
page: 1
size: 25
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: Results array
items:
$ref: '#/components/schemas/PeopleSchema'
total:
type: integer
description: Total number of results
took:
type: integer
description: Duration of the elastic-search query in milliseconds
page:
type: integer
description: Current page number
size:
type: integer
description: Size of the results (asked through parameters)
search:
type: string
description: Unique identifier of the current search
limitation:
type: integer
description: >-
Remaining calls for the POST People database and POST
Companies database (search is limited to a number of
queries every 24 hours)
team:
type: string
description: Unique identifier of the current team
example:
results:
- lead_id: 434482354
canonical_shorthand_name: alexdoe
connections_count: 500
country: France
full_name: Alex Doe
education: []
experience_count: 3
experiences:
- company_shorthand_name: lemlist
company_id: 11750398
company_name: lemlist
company_website_url: https://www.lemlist.com
company_linkedin_url: https://www.linkedin.com/company/lemlist
company_employee_count: 151
company_size: 51-200
company_domain: lemlist.com
company_industry: Technology, Information and Media
title: Account Executive
title_normalized: Account Executive
date_from: September 2025
duration: 1 month
location: Ville de Paris, Île-de-France, France
current_exp_bucket: Less than 6 months
interests: []
languages:
- language: Français
proficiency: Native or bilingual proficiency
- language: Anglais
proficiency: Professional working proficiency
lead_linkedin_url: https://www.linkedin.com/in/alex-doe
linkedin_short: alex-doe
skills: []
summary: >-
Passionate about helping sales teams book more meetings
@lemlist
headline: Helping RevOps scale outbound @lemlist
lead_quality_score: 3
department: Sales
connections_count_bucket: 500+
years_of_exp_bucket: 2 to 5 years
location: Paris, Ile-de-France, France
state: Ile-de-France
current_exp_company_name: lemlist
_score: 21.294434
_id: '434482354'
total: 91
took: 24
page: 1
size: 1
search: lsh_Lra0u9F7WXn3XKzB9
limitation: 1999
team: tea_8QvkOiBfPdb2ZRhHi
'400':
description: 'Possible errors: Bad team / Parameter filters is invalid'
content:
text/plain:
example: Bad team
'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:
PeopleSchema:
type: object
description: A person record from lemlist's People database.
additionalProperties: true
properties:
lead_id:
type: integer
description: Numeric identifier for the person in the People database
canonical_shorthand_name:
type: string
connections_count:
type: integer
country:
type: string
full_name:
type: string
education:
type: array
items:
type: object
additionalProperties: true
properties:
activities_and_societies:
type: string
created:
type: string
date_from:
type: string
date_to:
type: string
deleted:
type: string
description:
type: string
id:
type: string
last_updated:
type: string
member_id:
type: string
school_url:
type: string
format: uri
subtitle:
type: string
title:
type: string
experience_count:
type: integer
experiences:
type: array
items:
type: object
additionalProperties: true
properties:
company_id:
type: integer
company_description:
type: string
company_employee_count:
type: integer
company_followers_count:
type: integer
company_founded:
type: integer
company_headquarters_city:
type: string
company_headquarters_country:
type: string
company_industry:
type: string
company_linkedin_url:
type: string
format: uri
company_logo_url:
type: string
format: uri
company_name:
type: string
company_size:
type: string
company_type:
type: string
company_url:
type: string
company_website_url:
type: string
format: uri
revenue_bucket:
type: string
company_domain:
type: string
employees_count_growth:
type: integer
last_funding_round_at:
type: string
business_business_customer:
type: string
current_exp_bucket:
type: string
created:
type: string
date_from:
type: string
date_to:
type: string
description:
type: string
duration:
type: string
id:
type: string
last_updated:
type: string
location:
type: string
member_id:
type: string
order_in_profile:
type: integer
title:
type: string
title_normalized:
type: string
main_in_profile:
type: boolean
interests:
type: array
items:
type: object
properties:
interest:
type: string
interest_id:
type: string
languages:
type: array
items:
type: object
properties:
language:
type: string
proficiency:
type: string
last_updated:
type: string
lead_industry:
type: string
lead_linkedin_url:
type: string
format: uri
lead_logo_url:
type: string
format: uri
linkedin_short:
type: string
location:
type: string
skills:
type: array
items:
type: object
properties:
skill:
type: string
skill_id:
type: string
summary:
type: string
title:
type: string
lead_quality_score:
type: integer
seniority:
type: string
department:
type: string
connections_count_bucket:
type: string
years_of_exp_bucket:
type: string
current_exp_company_name:
type: string
geopoint:
type: array
items:
type: number
minItems: 2
maxItems: 2
_score:
type: number
_id:
type: string
securitySchemes:
basicAuth:
type: http
scheme: basic
````