> ## Documentation Index
> Fetch the complete documentation index at: https://lemlist-docs-watch-list-public-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Retrieves paginated signals detected by your Signal Agents with filtering and sorting capabilities.
# Get Signal Agent signals
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.
;
};
This endpoint allows you to fetch signals detected by your Signal Agents with support for filtering by type, status, date range, and Signal Agent ID.
## OpenAPI
````yaml get /watchlist/signals
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:
/watchlist/signals:
get:
tags:
- Signal Agents
summary: Get Signal Agent signals
parameters:
- name: page
in: query
required: false
description: Page number to retrieve
example: '1'
schema:
type: integer
minimum: 1
- name: limit
in: query
required: false
description: 'Number of signals to retrieve. Maximum value: 100'
example: '50'
schema:
type: integer
minimum: 1
maximum: 100
- name: sortBy
in: query
required: false
description: The field by which to sort signals
example: receivedAt
schema:
type: string
enum:
- receivedAt
- createdAt
- name: sortOrder
in: query
required: false
description: The sort direction
example: desc
schema:
type: string
enum:
- asc
- desc
- name: type
in: query
required: false
description: >-
Filter by signal type(s). Can be a single value or array using
type[] notation. Valid values from
WATCH_LIST_SIGNAL_CONFIGURATIONS_TYPES_STANDARD_KEYS
example: jobChange
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: status
in: query
required: false
description: >-
Filter by signal status(es). Can be a single value or array using
status[] notation. Valid values from
WATCH_LIST_SIGNAL_COMPUTED_STATUSES
example: new
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: receivedAtFrom
in: query
required: false
description: Filter signals received on or after this date (ISO date string)
example: '2024-01-01T00:00:00.000Z'
schema:
type: string
format: date-time
- name: receivedAtTo
in: query
required: false
description: >-
Filter signals received on or before this date (ISO date string).
Must be greater than receivedAtFrom if both are provided
example: '2024-12-31T23:59:59.999Z'
schema:
type: string
format: date-time
- name: watchListId
in: query
required: false
description: Filter signals by specific Signal Agent ID
example: wl_abc123
schema:
type: string
minLength: 1
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiFetchSignalsResponse'
'400':
description: >-
Validation error - invalid query parameters, pagination conflict, or
invalid date range
content:
text/plain:
examples:
invalidPagination:
value: page must be a positive integer
invalidLimit:
value: limit must be between 1 and 100
invalidSort:
value: sortBy must be either receivedAt or createdAt
invalidType:
value: 'Invalid type values: invalid_type'
invalidStatus:
value: 'Invalid status values: invalid_status'
invalidDate:
value: receivedAtFrom must be a valid ISO date string
invalidDateRange:
value: receivedAtFrom must be before receivedAtTo
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'404':
description: Watchlist not found
content:
text/plain:
example: Watchlist not found
'405':
description: Method not allowed - only GET is supported
content:
text/plain:
example: Method not allowed
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
components:
schemas:
WatchListApiFetchSignalsResponse:
type: object
description: Paginated response containing signals detected by Signal Agents
properties:
data:
type: array
description: Signals matching the query parameters
items:
$ref: '#/components/schemas/SignalSchema'
meta:
$ref: '#/components/schemas/WatchListListMeta'
SignalSchema:
type: object
description: >-
A signal detected by a Signal Agent representing a tracked event
(hiring, LinkedIn activity, website visit, etc.)
required:
- _id
- teamId
- watchListId
- type
- status
- receivedAt
- createdAt
- signalData
properties:
_id:
type: string
description: Unique signal identifier
teamId:
type: string
description: Team ID that owns this signal
watchListId:
type: string
description: ID of the Signal Agent associated with this signal
watchListName:
type: string
description: Name of the Signal Agent associated with this signal
type:
type: string
description: Signal type
enum:
- companyIsHiring
- companyRaisedFunds
- recruitmentCampaign
- jobChange
- newHire
- companyEmployeeVisitedMyWebsite
- customSignals
- competitorConnections
- competitorReactions
- companyFollowers
- technologyChange
- linkedinPeopleProfile
- linkedinCompanyProfile
- mergersAcquisitions
- promotion
- linkedinKeywords
- externalSignalContact
- externalSignalCompany
- buyingIntent
status:
type: string
description: Signal status (computed based on user actions)
enum:
- new
- old
- handled
- ignored
receivedAt:
type: string
format: date-time
description: When the signal was received
createdAt:
type: string
format: date-time
description: When the signal was created in the database
contact:
type: object
description: Contact associated with this signal (if entity type is 'contact')
properties:
_id:
type: string
description: Contact ID
firstName:
type: string
description: Contact first name
lastName:
type: string
description: Contact last name
email:
type: string
description: Contact primary email
jobTitle:
type: string
description: Contact job title
phone:
type: string
description: Contact phone number
linkedinUrl:
type: string
description: Contact LinkedIn profile URL
picture:
type: string
description: Contact profile picture URL
company:
type: object
description: Company associated with this signal
properties:
_id:
type: string
description: Company ID
name:
type: string
description: Company name
domain:
type: string
description: Company website domain
linkedinUrl:
type: string
description: Company LinkedIn URL
industry:
type: string
description: Company industry
picture:
type: string
description: Company logo URL
signalData:
type: object
description: >-
Signal-specific data that varies by signal type. Each field is
prefixed with the signal type(s) that populate it.
properties:
jobTitle:
type: string
description: '[companyIsHiring] Job posting title'
jobDescription:
type: string
description: '[companyIsHiring] Job posting description'
jobLocation:
type: string
description: '[companyIsHiring] Job posting location'
jobUrl:
type: string
description: '[companyIsHiring] Job posting URL'
jobStatus:
type: string
description: '[companyIsHiring] Job posting status'
recruiterName:
type: string
description: '[companyIsHiring] Recruiter name'
recruiterTitle:
type: string
description: '[companyIsHiring] Recruiter title'
recruiterLinkedinUrl:
type: string
description: '[companyIsHiring] Recruiter LinkedIn URL'
recruiterEmail:
type: string
description: '[companyIsHiring] Recruiter email'
websiteVisited:
type: string
description: '[companyEmployeeVisitedMyWebsite] Page URL that was visited'
visitorWebsite:
type: string
description: '[companyEmployeeVisitedMyWebsite] Visitor''s company website'
visitorCountry:
type: string
description: '[companyEmployeeVisitedMyWebsite] Visitor country'
visitorDuration:
type: integer
description: >-
[companyEmployeeVisitedMyWebsite] Visit duration in seconds
(session-cumulative)
startDate:
type: string
description: >-
[jobChange/newHire/competitorConnections/companyFollowers] Start
date at the tracked company
previousCompany:
type: string
description: '[jobChange] Previous company name'
previousCompanyLinkedinUrl:
type: string
description: '[jobChange] Previous company LinkedIn URL'
trackedCompanyUrl:
type: string
description: >-
Tracked company LinkedIn URL (competitorConnections,
companyFollowers, ...)
linkedinPeopleProfilePostUrl:
type: string
description: '[linkedinPeopleProfile] Post URL'
linkedinPeopleProfilePostContent:
type: string
description: '[linkedinPeopleProfile] Post content'
linkedinPeopleProfilePostCreatorName:
type: string
description: '[linkedinPeopleProfile] Post creator name'
linkedinPeopleProfileType:
type: string
description: '[linkedinPeopleProfile] Activity type (post, comment, like)'
linkedinPeopleProfileMentionContent:
type: string
description: '[linkedinPeopleProfile] Mention content'
linkedinPeopleProfileTrackedContactUrl:
type: string
description: '[linkedinPeopleProfile] Tracked contact LinkedIn URL'
linkedinPeopleProfileDate:
type: string
description: '[linkedinPeopleProfile] Activity date'
linkedinCompanyProfilePostUrl:
type: string
description: '[linkedinCompanyProfile] Post URL'
linkedinCompanyProfilePostContent:
type: string
description: '[linkedinCompanyProfile] Post content'
linkedinCompanyProfilePostCreatorName:
type: string
description: '[linkedinCompanyProfile] Post creator name'
linkedinCompanyProfileType:
type: string
description: '[linkedinCompanyProfile] Activity type'
linkedinCompanyProfileMentionContent:
type: string
description: '[linkedinCompanyProfile] Mention content'
linkedinCompanyProfileTrackedCompanyUrl:
type: string
description: '[linkedinCompanyProfile] Tracked company LinkedIn URL'
linkedinCompanyProfileDate:
type: string
description: '[linkedinCompanyProfile] Activity date'
linkedinKeywordsPostUrl:
type: string
description: '[linkedinKeywords] Post URL'
linkedinKeywordsPostContent:
type: string
description: '[linkedinKeywords] Post content'
linkedinKeywordsPostCreatorName:
type: string
description: '[linkedinKeywords] Post creator name'
linkedinKeywordsType:
type: string
description: '[linkedinKeywords] Activity type'
linkedinKeywordsMentionContent:
type: string
description: '[linkedinKeywords] Mention content'
linkedinKeywordsMatchedKeywords:
type: string
description: '[linkedinKeywords] Matched keywords'
linkedinKeywordsLocation:
type: string
description: '[linkedinKeywords] Location'
linkedinKeywordsDate:
type: string
description: '[linkedinKeywords] Activity date'
linkedinKeywordsPostCreatorUrl:
type: string
description: '[linkedinKeywords] Post creator LinkedIn URL'
linkedinKeywordsPostCreatorCompanyUrl:
type: string
description: '[linkedinKeywords] Post creator company LinkedIn URL'
customSignalTitle:
type: string
description: '[customSignals] Signal title'
customSignalQuestion:
type: string
description: '[customSignals] Question asked'
customSignalAnswer:
type: string
description: '[customSignals] Short answer'
customSignalConfidence:
type: number
description: '[customSignals] Confidence score'
customSignalLongAnswer:
type: string
description: '[customSignals] Detailed answer'
customSignalHeadlines:
type: string
description: '[customSignals] Headlines'
customSignalSources:
type: string
description: '[customSignals] Sources'
fundingType:
type: string
description: '[companyRaisedFunds] Funding type'
fundingStage:
type: string
description: '[companyRaisedFunds] Funding stage'
fundingAmountUsd:
type: number
description: '[companyRaisedFunds] Amount raised (USD)'
fundingAmountNative:
type: number
description: '[companyRaisedFunds] Amount raised (native currency)'
fundingCurrency:
type: string
description: '[companyRaisedFunds] Native currency'
fundingInvestors:
type: string
description: '[companyRaisedFunds] Investors'
fundingSourceUrl:
type: string
description: '[companyRaisedFunds] Source URL'
buyingIntentTopics:
type: string
description: '[buyingIntent] Matched topics'
buyingIntentTopTopic:
type: string
description: '[buyingIntent] Top matched topic'
competitorReactionsTrackedContactUrl:
type: string
description: '[competitorReactions] Tracked contact LinkedIn URL'
competitorReactionsPostUrl:
type: string
description: '[competitorReactions] Post URL'
competitorReactionsPostContent:
type: string
description: '[competitorReactions] Post content'
competitorReactionsPostCreatorName:
type: string
description: '[competitorReactions] Post creator name'
competitorReactionsEngagementType:
type: string
description: '[competitorReactions] Engagement type (like, comment)'
competitorReactionsMentionContent:
type: string
description: '[competitorReactions] Mention content'
competitorReactionsDate:
type: string
description: '[competitorReactions] Engagement date'
acquisitionType:
type: string
description: '[mergersAcquisitions] Acquisition type'
acquirerName:
type: string
description: '[mergersAcquisitions] Acquirer name'
acquirerWebsite:
type: string
description: '[mergersAcquisitions] Acquirer website'
acquireeName:
type: string
description: '[mergersAcquisitions] Acquiree name'
acquireeWebsite:
type: string
description: '[mergersAcquisitions] Acquiree website'
dealPriceUsd:
type: number
description: '[mergersAcquisitions] Deal price (USD)'
dealCurrency:
type: string
description: '[mergersAcquisitions] Deal currency'
announcementDate:
type: string
description: '[mergersAcquisitions] Announcement date'
acquirerCrunchbaseUrl:
type: string
description: '[mergersAcquisitions] Acquirer Crunchbase URL'
acquireeCrunchbaseUrl:
type: string
description: '[mergersAcquisitions] Acquiree Crunchbase URL'
technologyChangeName:
type: string
description: '[technologyChange] Technology name'
technologyChangeSourceType:
type: string
description: '[technologyChange] Source type'
technologyChangeFirstSeenAt:
type: string
description: '[technologyChange] First seen at'
technologyChangeLastSeenAt:
type: string
description: '[technologyChange] Last seen at'
technologyChangeCompanyName:
type: string
description: '[technologyChange] Company name'
technologyChangeCompanyDomain:
type: string
description: '[technologyChange] Company domain'
promotionJobTitle:
type: string
description: '[promotion] New job title'
promotionFormerJobTitle:
type: string
description: '[promotion] Former job title'
promotionStartDate:
type: string
description: '[promotion] Promotion start date'
externalSignalCustomFields:
type: object
description: '[externalSignalContact/externalSignalCompany] Custom fields map'
additionalProperties:
type: string
WatchListListMeta:
type: object
properties:
pagination:
type: object
properties:
page:
type: integer
description: Current page number
limit:
type: integer
description: Number of records per page
totalRecords:
type: integer
description: Total records matching the filter
totalPages:
type: integer
description: Total number of pages
securitySchemes:
basicAuth:
type: http
scheme: basic
````