lemlist People Database API
Search the lemlist B2B people and company database, list its filters, and manage saved personas.
OpenAPI Specification
openapi: 3.0.0
info:
title: lemlist People Database API
version: 1.0.0
description: The People Database operations of the lemlist API, split by tag from the OpenAPI lemlist
publishes at https://developer.lemlist.com/api-reference/openapi/v2.json. Operation content is carried
verbatim from the provider spec.
servers:
- url: https://api.lemlist.com/api
security:
- basicAuth: []
tags:
- name: People Database
paths:
/database/filters:
get:
summary: Get Database Filters
tags:
- People Database
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatabaseFilter'
example:
- filterId: country
description: Filter by country
mode:
- leads
- companies
type: text
helper: Use free text search
- filterId: department
description: Filter by department
mode:
- leads
type: select
helper: 'Allowed values: Sales, Customer service, Engineering, Marketing, Operations,
Human Resources, Finance / Legal / Admin, Other'
'400':
description: Bad team
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
parameters: []
/database/people:
post:
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.
The `department` filter accepts the following values: `Sales`, `Customer service`, `Engineering`,
`Marketing`, `Operations`, `Human Resources`, `Finance / Legal / Admin`, `Other`.'
operationId: searchPeopleDatabase
tags:
- People Database
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
parameters: []
/database/companies:
post:
summary: Search Companies Database
description: Search the lemlist Companies database using structured filters with pagination support.
Returns comprehensive company data including technologies used, location, employee count, and
other business intelligence.
tags:
- People Database
requestBody:
content:
application/json:
schema:
type: object
properties:
filters:
type: array
description: Array of filter objects to narrow down search results. Each filter has
a filterId and inclusion/exclusion criteria.
items:
type: object
properties:
filterId:
type: string
description: The identifier of the filter to apply (e.g., 'currentCompanyTechnologies',
'companySize', 'industry')
in:
type: array
description: Array of values to include in the filter
items:
type: string
out:
type: array
description: Array of values to exclude from the filter
items:
type: string
page:
type: integer
description: 'Page number for pagination (default: 1)'
size:
type: integer
description: 'Number of results per page (default: 100, max: 500)'
example:
filters:
- filterId: currentCompanyTechnologies
in:
- Postman
out:
- Haskell
page: 1
size: 2
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
$ref: '#/components/schemas/CompaniesSchema'
total:
type: integer
description: Total number of companies matching the search criteria
took:
type: integer
description: Time taken for the search in milliseconds
page:
type: integer
description: Current page number
size:
type: integer
description: Number of results per page
search:
type: string
description: Search session identifier
limitation:
type: integer
description: Result limitation applied
team:
type: string
description: Team identifier
example:
results:
- company_id: '88945664'
company_website_url: http://acme-tech.example.com
company_name: Acme Technologies
company_linkedin_url: https://www.linkedin.com/company/acme-technologies
last_updated: 2025-09-07 02:11:32 UTC
company_headquarters_city: Example City
company_headquarters_country: India
company_logo_url: https://example.com/logo1.png
company_description: "Acme, established on Aug-2015 with the idea \"Make Your Imagination\
\ Come True\". Which means anyone who came up with their idea, we will give a closely\
\ realistic solutions to them. \nAcme Technologies is a new Generation Software Company,\
\ with young people with creative mind and immersive energy. We are a team of dedicated\
\ and highly skilled software professionals focused on providing world class IT solutions.\
\ We offer a variety of services in the area of:\nWebsite Designing & Development,\
\ Web Maintenance, E-Business Solutions, Android & iOS app, Blockchain Development,\
\ Software Development, Hosting Services."
company_employee_count: '31'
company_type: Public Company
company_founded: '2015'
company_followers_count: '3958'
company_size: 11-50
company_domain: acme-tech.example.com
employees_count_growth: -3
techno_used_array:
- Apache HTTP Server
- Lightbox
- LinkedIn Sales Navigator
- Atlassian Jira
- LiteSpeed Cache
- Underscore.js
- Remix
- jsDelivr
- jQuery
- Google Fonts API
- Google Tag Manager
- X-Content-Type-Options
- Facebook
- PWA
- jQuery CDN
- ZURB Foundation
- HSTS
- WhatsApp Business
- X-XSS-Protection
- Google Analytics
- Flickity
- HTML
- LiteSpeed
- Ethereum
- Cloudinary
- OceanWP
- Goober
- jQuery Migrate
- Tailwind CSS
- Postman
- LinkedIn
- Webpack
- GSAP
- Essential Addons for Elementor
- Font Awesome
- Android
- PixelYourSite
- jQuery UI
- MUI
- IPFS
- Upwork
- cdnjs
- FlexSlider
- Elementor
- ZoomInfo
- Swiper
- Microsoft IIS
- Node.js
- Ethers
- Solidity
- React
- Priority Hints
- iOS
- OWL Carousel
- MySQL
- Facebook Pixel
- Open Graph
- Laravel
- Emotion
- Lucide
- PHP
- Blockchain
- Next.js
- RSS
- Google Maps
- Windows Server
- WordPress
- WPForms
- JavaScript
- Chainlink
- Apache
- Bootstrap
business_business_customer: B2B
company_quality_score: '3'
company_industry: Technology, Information and Media
company_subindustry: Technology, Information and Internet
company_subsubindustry: Software Development
company_location: 123 Example Street, Suite 100, Example City, Example Country
company_location_geopoint_array:
- 73.92
- 18.64
company_occ_lead: '60'
_score: 10.002095
_id: '88945664'
- company_id: '9903838'
company_website_url: http://www.acme-care.example.com
company_name: Acme Care
company_linkedin_url: https://www.linkedin.com/company/acme-care
last_updated: 2025-09-04 14:24:45 UTC
company_headquarters_city: San Francisco, California
company_headquarters_country: United States
company_logo_url: https://example.com/logo2.png
company_description: Acme Care provides an automated platform for team-based care management.
To learn more, write us at contact@acme-care.example.com.
company_employee_count: '33'
company_type: Privately Held
company_founded: '2013'
company_followers_count: '2651'
company_size: 11-50
revenue_bucket: $5M - $10M
company_domain: acme-care.example.com
employees_count_growth: 6
last_funding_round_at: More than 6 months
techno_used_array:
- Google Cloud
- Heap
- Envoy
- Google Cloud CDN
- X-Content-Type-Options
- Piwik
- WP Engine
- React
- cdnjs
- Fullstory
- Cloudflare Bot Management
- Twitter
- JSON-LD
- C3.js
- Python
- Google Analytics
- MediaElement.js
- SafeBase
- Emotion
- Nginx
- Atlassian Jira
- PayPal
- MUI
- Gravity Forms
- Zendesk
- MySQL
- Webpack
- PHP
- Facebook Pixel
- Google Fonts API
- OneTrust
- jQuery
- Gravatar
- Google Hosted Libraries
- Yoast SEO
- Jamf
- Cloudflare CDN
- Angular
- Postman
- Cloudflare
- HubSpot
- Java
- HTTP/3
- Moment.js
- X-XSS-Protection
- Open Graph
- JazzHR
- Workramp
- Algolia
- SSL.com
- Autoptimize
- Font Awesome
- oEmbed
- Bootstrap
- Facebook
- HSTS
- Ruby
- Twemoji
- WordPress
- Lightbox
- Adobe Fonts
- RequireJS
- Ruby on Rails
- Lodash
- reCAPTCHA
- LinkedIn Ads
- Hotjar
- Google Tag Manager
business_business_customer: B2B
company_quality_score: '3'
company_industry: Technology, Information and Media
company_subindustry: Technology, Information and Internet
company_subsubindustry: Software Development
company_location: San Francisco, California, US
company_location_geopoint_array:
- -122.42
- 37.78
company_occ_lead: '117'
_score: 9.972561
_id: '9903838'
total: 12102
took: 17
page: 1
size: 2
search: lsh_8LBpZPgGpxGswp5G7
limitation: 1998
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
parameters: []
/database/personas:
get:
summary: List Personas
description: 'Lists the personas saved by your team. A persona is a named, reusable set of People
Database filters; its id can then be referenced elsewhere in the API, for example through the
`persona` filter of a Signal Agent.
Personas are team-shared: every member sees the same list. Results are sorted by creation date,
most recent first, and capped at 200. The auto-generated persona lemlist derives from your AI
business context is never returned; only the personas your team created are.
This endpoint is in closed beta and answers `403` unless the beta is enabled for your team.'
operationId: listPersonas
tags:
- People Database
parameters:
- name: mode
in: query
required: false
description: Restrict the list to personas of one search mode. Omit to return every persona of
the team.
schema:
type: string
enum:
- leads
- companies
example: leads
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaListResponse'
example:
data:
- _id: pdp_ExAmPlE1234567890a
name: SaaS founders
mode: leads
filters:
- filterId: currentTitle
in:
- Founder
out: []
- filterId: country
in:
- France
out: []
createdAt: '2026-07-31T09:12:00.000Z'
updatedAt: '2026-07-31T09:12:00.000Z'
'400':
description: Validation error - invalid query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Parameter "mode" must be "leads" or "companies"; user personas currently accept
"leads" only
code: PEOPLE_DATABASE_PERSONA_API_INVALID_MODE
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Route unauthorized
code: ROUTE_UNAUTHORIZED
'403':
description: The personas beta is not enabled for your team
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Beta is not enabled
code: BETA_NOT_ENABLED
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Internal error
code: INTERNAL_ERROR
post:
summary: Create Persona
description: 'Creates a persona for your team from a name and a set of People Database filters.
Use [Get Database Filters](/api-reference/endpoints/people-database/get-database-filters) to discover
the valid `filterId` values. Filters carry no `type` property: it is derived from `filterId` server-side.
Filters that require a plan your team does not have are dropped silently, so the persona is stored
with the subset your plan allows.
Only the created id is returned. The stored `name` and `filters` are sanitized and plan-gated
server-side, so echoing the request payload back would misreport what was persisted; call [List
Personas](/api-reference/endpoints/people-database/list-personas) to read the stored persona.
This endpoint is in closed beta and answers `403` unless the beta is enabled for your team.'
operationId: createPersona
tags:
- People Database
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- filters
- mode
properties:
name:
type: string
minLength: 1
description: Display name. Non-empty, and unique within your team.
example: SaaS founders
filters:
type: array
description: People Database filters defining the persona
items:
$ref: '#/components/schemas/PersonaFilter'
mode:
type: string
description: Search mode the filters target. Only `leads` is accepted today.
enum:
- leads
- companies
example: leads
example:
name: SaaS founders
mode: leads
filters:
- filterId: currentTitle
in:
- Founder
out: []
- filterId: country
in:
- France
out: []
responses:
'201':
description: Persona created
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaCreateResponse'
example:
data:
_id: pdp_ExAmPlE1234567890a
'400':
description: Validation error - invalid name, mode, or filters
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
examples:
invalidName:
value:
error: Parameter "name" must be a non-empty string; provide the persona display name
code: PEOPLE_DATABASE_PERSONA_API_INVALID_NAME
invalidFilters:
value:
error: Parameter "filters" must be an array of { filterId, in?, out?, exactMatch?
} objects; call GET /api/database/filters for the valid filter ids
code: PEOPLE_DATABASE_PERSONA_API_INVALID_FILTERS
modeNotSupported:
value:
error: User personas support only the "leads" mode for now; create or update the persona
in leads mode
code: PEOPLE_DATABASE_PERSONA_MODE_NOT_SUPPORTED
unknownFilter:
value:
error: You have no valid filters with the current search mode
code: SEARCH_FILTERS_INVALID
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Route unauthorized
code: ROUTE_UNAUTHORIZED
'403':
description: The personas beta is not enabled for your team
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Beta is not enabled
code: BETA_NOT_ENABLED
'409':
description: A persona with this name already exists for your team
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: A persona with this name already exists for the team; choose a different name
code: PEOPLE_DATABASE_PERSONA_NAME_ALREADY_EXISTS
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Internal error
code: INTERNAL_ERROR
/database/personas/{personaId}:
delete:
summary: Delete Persona
description: 'Permanently deletes one of your team''s personas. There is no undo.
An unknown id, a persona belonging to another team, and the persona lemlist auto-generates from
your AI business context all answer the same `404`: they are indistinguishable by design.
This endpoint is in closed beta and answers `403` unless the beta is enabled for your team.'
operationId: deletePersona
tags:
- People Database
parameters:
- name: personaId
in: path
required: true
description: Id of the persona to delete
schema:
type: string
minLength: 1
example: pdp_ExAmPlE1234567890a
responses:
'200':
description: Persona deleted
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaDeleteResponse'
example:
data:
_id: pdp_ExAmPlE1234567890a
deleted: true
'400':
description: Validation error - malformed personaId
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Wrong param people database persona id
code: WRONG_PARAM_PEOPLE_DATABASE_PERSONA_ID
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Route unauthorized
code: ROUTE_UNAUTHORIZED
'403':
description: The personas beta is not enabled for your team
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Beta is not enabled
code: BETA_NOT_ENABLED
'404':
description: No such persona for your team
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: No editable persona found for this id and team (it may not exist or be the system
persona)
code: PEOPLE_DATABASE_PERSONA_NOT_FOUND
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/PersonaError'
example:
error: Internal error
code: INTERNAL_ERROR
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
schemas:
CompaniesSchema:
type: object
description: A company record from lemlist's Companies database.
additionalProperties: true
properties:
company_id:
type: string
description: Unique company identifier
company_website_url:
type: string
format: uri
description: Official company website URL
company_name:
type: string
description: Company name
company_linkedin_url:
type: string
format: uri
description: LinkedIn company profile URL
last_updated:
type: string
description: La
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lemlist/refs/heads/main/openapi/lemlist-people-database-api-openapi.yml