lemlist Signal Agents API
Signal Agents (watch lists) - create and configure watches, list the available signal types and filters, read detected signals, and push external signals.
OpenAPI Specification
openapi: 3.0.0
info:
title: lemlist Signal Agents API
version: 1.0.0
description: The Signal Agents 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: Signal Agents
paths:
/watchlist/signals:
get:
summary: Get Signal Agent signals
tags:
- Signal Agents
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
/watchlist/{watchListId}/external-signals:
post:
summary: Push external signals
tags:
- Signal Agents
parameters:
- name: watchListId
in: path
required: true
description: Id of the Signal Agent to push the signal to. Must be an externalSignalContact or
externalSignalCompany agent.
example: wli_ExAmPlE1234567890a
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
contact:
type: object
description: The contact the signal is about. Required for externalSignalContact agents;
ignored otherwise.
required:
- linkedinUrl
properties:
linkedinUrl:
type: string
description: LinkedIn profile URL. Required.
example: https://www.linkedin.com/in/john-doe
email:
type: string
description: Contact email
example: john@example.com
firstName:
type: string
description: Contact first name
example: John
lastName:
type: string
description: Contact last name
example: Doe
company:
type: object
description: The company the signal is about. Required for externalSignalCompany agents;
ignored otherwise.
required:
- domain
- name
properties:
domain:
type: string
description: Company domain. Required.
example: acme.com
name:
type: string
description: Company name. Required.
example: Acme Inc
linkedinUrl:
type: string
description: LinkedIn company URL
example: https://www.linkedin.com/company/acme
customFields:
type: object
description: Optional key/value metadata stored on the signal. Max 20 keys; all values
must be strings.
additionalProperties:
type: string
example:
plan: enterprise
source: webinar
responses:
'200':
description: Signal processed or ignored. `status` is `processed` when a signal was created,
or `ignored` when no matching entity was found or the agent's daily limit was reached. External
signals are free, so `creditsConsumed` is always 0.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalSignalPushResponse'
examples:
processed:
value:
status: processed
signalId: wls_ExAmPlE1234567890a
creditsConsumed: 0
entity:
type: contact
id: lea_ExAmPlE1234567890a
enriched: true
ignoredNoMatch:
value:
status: ignored
reason: no_entity_match
creditsConsumed: 0
ignoredDailyLimit:
value:
status: ignored
reason: daily_limit_reached
creditsConsumed: 0
'400':
description: Validation error - invalid contact, company, or custom fields
content:
text/plain:
examples:
invalidContact:
value: Contact must have a valid LinkedIn profile URL (e.g. https://www.linkedin.com/in/...)
invalidCompany:
value: Company must have a domain and a name; linkedinUrl (when provided) must be a
valid LinkedIn company URL (e.g. https://www.linkedin.com/company/...)
invalidCustomFields:
value: Custom fields must have 20 keys or less with string values
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'404':
description: Watch list not found or not configured for external signals
content:
text/plain:
example: Watch list not found or not configured for external signals
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
/watchlist:
get:
summary: List Signal Agents
tags:
- Signal Agents
parameters:
- name: page
in: query
required: false
description: Page number to retrieve
schema:
type: integer
minimum: 1
example: '1'
- name: limit
in: query
required: false
description: 'Number of records to retrieve. Maximum value: 100'
schema:
type: integer
minimum: 1
maximum: 100
example: '50'
- name: type
in: query
required: false
description: Filter by signal type(s). Comma-separated list of signal types.
schema:
type: string
example: jobChange
- name: status
in: query
required: false
description: Filter by lifecycle status(es). Comma-separated list. Defaults to every status except
`delete`.
schema:
type: string
example: active
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiListWatchListsResponse'
'400':
description: Validation error - invalid query parameters
content:
text/plain:
example: Invalid type values
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
post:
summary: Create Signal Agent
tags:
- Signal Agents
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- type
properties:
name:
type: string
description: Display name
type:
type: string
description: Signal type to monitor
enum:
- companyIsHiring
- companyRaisedFunds
- recruitmentCampaign
- jobChange
- newHire
- companyEmployeeVisitedMyWebsite
- customSignals
- competitorConnections
- competitorReactions
- companyFollowers
- technologyChange
- linkedinPeopleProfile
- linkedinCompanyProfile
- mergersAcquisitions
- promotion
- linkedinKeywords
- externalSignalContact
- externalSignalCompany
- buyingIntent
filters:
type: array
description: Filters to apply (validated against the signal type)
items:
$ref: '#/components/schemas/WatchListFilter'
emoji:
type: string
description: Emoji shown next to the agent name (defaults to a random emoji)
segmentType:
type: string
description: Entity sourcing. Only `all` is supported via the API. Required together
with signalProcessingType when activate is true.
enum:
- all
signalProcessingType:
type: string
description: How detected signals are processed
enum:
- manual
- create_opportunity
- push_to_campaign
signalOpportunityTemplate:
type: object
description: Task/opportunity template applied to each signal when signalProcessingType
is create_opportunity.
properties:
ownerType:
type: string
description: Who the created opportunity is assigned to
enum:
- contact_owner
- specific_owner
ownerId:
type: string
description: Owner user id, when ownerType is specific_owner
type:
type: string
description: Opportunity channel
enum:
- email
- phone
- linkedinSend
- whatsappMessage
- manual
priority:
type: integer
description: Opportunity priority
enum:
- 0
- 1
- 2
data:
type: object
properties:
title:
type: string
description: Opportunity title
subject:
type: string
description: Email subject (email channel)
emailTemplateId:
type: string
description: Email template id
message:
type: string
description: Message body
activate:
type: boolean
description: Fully set up and activate the agent. Requires segmentType and signalProcessingType.
example:
name: New hires at target accounts
type: newHire
filters:
- filterId: companyIndustries
in:
- Software
out: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiWatchListResponse'
'400':
description: Validation error - invalid body, filters, or activate prerequisites
content:
text/plain:
example: activate requires both segmentType and signalProcessingType
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'402':
description: Insufficient credits to activate the agent
content:
text/plain:
example: Insufficient credits
'429':
description: Monitored-entity limit exceeded
content:
text/plain:
example: Monitoring limit exceeded
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
patch:
summary: Update Signal Agent
tags:
- Signal Agents
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- watchListId
properties:
watchListId:
type: string
description: Signal Agent id to update
name:
type: string
description: New display name
filters:
type: array
description: Replacement filters (validated against the agent's signal type)
items:
$ref: '#/components/schemas/WatchListFilter'
emoji:
type: string
description: New emoji
signalProcessingType:
type: string
description: New signal processing type
enum:
- manual
- create_opportunity
- push_to_campaign
example:
watchListId: wl_Example000000001
name: Renamed agent
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiWatchListResponse'
'400':
description: Validation error - invalid body or filters
content:
text/plain:
example: name must be a non-empty string
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'404':
description: Signal Agent not found
content:
text/plain:
example: Watch list not found
'409':
description: Signal Agent type cannot be changed after creation
content:
text/plain:
example: Watch list type cannot be changed after creation
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
delete:
summary: Delete Signal Agent
tags:
- Signal Agents
parameters:
- name: watchListId
in: query
required: true
description: Signal Agent id to delete
schema:
type: string
minLength: 1
example: wl_Example000000001
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiDeleteWatchListResponse'
'400':
description: Validation error - invalid watchListId
content:
text/plain:
example: watchListId must be a valid watch list ID
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
/watchlist/history:
get:
summary: Get Signal Agent configuration history
tags:
- Signal Agents
parameters:
- name: watchListId
in: query
required: true
description: Signal Agent id whose history to fetch
schema:
type: string
minLength: 1
example: wl_Example000000001
- name: page
in: query
required: false
description: Page number to retrieve
schema:
type: integer
minimum: 1
example: '1'
- name: limit
in: query
required: false
description: 'Number of records to retrieve. Maximum value: 100'
schema:
type: integer
minimum: 1
maximum: 100
example: '50'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiHistoryResponse'
'400':
description: Validation error - invalid query parameters
content:
text/plain:
example: page must be a positive integer
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'404':
description: Signal Agent not found or access denied
content:
text/plain:
example: WatchList not found or access denied
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
/watchlist/library:
get:
summary: List available signal types
tags:
- Signal Agents
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiLibraryResponse'
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
/watchlist/filters:
get:
summary: List allowed filters per signal type
tags:
- Signal Agents
parameters:
- name: type
in: query
required: false
description: Restrict the response to a single signal type. Omit to return filters for every type.
schema:
type: string
enum:
- companyIsHiring
- companyRaisedFunds
- recruitmentCampaign
- jobChange
- newHire
- companyEmployeeVisitedMyWebsite
- customSignals
- competitorConnections
- competitorReactions
- companyFollowers
- technologyChange
- linkedinPeopleProfile
- linkedinCompanyProfile
- mergersAcquisitions
- promotion
- linkedinKeywords
- externalSignalContact
- externalSignalCompany
- buyingIntent
example: companyIsHiring
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiFiltersResponse'
'400':
description: Validation error - invalid type
content:
text/plain:
example: Invalid type values
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
/watchlist/filter-values:
get:
summary: Autocomplete filter values
tags:
- Signal Agents
parameters:
- name: filterId
in: query
required: true
description: Filter to resolve values for
schema:
type: string
enum:
- title
- description
- location
- visitLocation
- website
- pagesTracked
- minVisitDuration
- minPageViewed
- internalTraffic
- linkedinUrls
- companyLinkedinUrls
- companyNames
- companyLocation
- companyIndustries
- companySizes
- maxIdentificationsPerDay
- excludedVisitorIps
- reactionTypes
- linkedinTopics
- bomboraTopics
- watcherWatchKey
- questions
- fundraisingMinAmount
- fundraisingMaxAmount
- fundraisingInvestmentTypes
- fundraisingInvestors
- technologies
- detectionMode
- maDealTypes
- maMinAmount
- persona
- externalSignalFieldMapping
- externalSignalCustomFieldMapping
- seniority
- crmListIds
- minJobCount
- timeframe
example: companyIndustries
- name: query
in: query
required: false
description: Search text (required for autocomplete filters). 1-100 characters.
schema:
type: string
minLength: 1
maxLength: 100
example: software
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiFilterValuesResponse'
'400':
description: Validation error - invalid filterId or query
content:
text/plain:
example: filterId is not a supported watch list autocomplete filter
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'502':
description: Failed to fetch filter values from the search backend
content:
text/plain:
example: Failed to fetch filter values from search backend
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
schemas:
ExternalSignalPushResponse:
type: object
properties:
status:
type: string
enum:
- processed
- ignored
description: '`processed` when a signal was created, `ignored` otherwise'
signalId:
type: string
description: Id of the created signal. Present when status is processed.
example: wls_ExAmPlE1234567890a
reason:
type: string
enum:
- no_entity_match
- daily_limit_reached
description: Why the signal was ignored. Present when status is ignored.
creditsConsumed:
type: integer
description: Always 0 - external signals are free.
example: 0
entity:
type: object
description: The matched entity. Present when status is processed.
properties:
type:
type: string
enum:
- contact
- company
id:
type: string
description: Entity id or watch key
example: lea_ExAmPlE1234567890a
enriched:
type: boolean
description: Whether the entity was enriched from lemlist data
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:
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lemlist/refs/heads/main/openapi/lemlist-signal-agents-api-openapi.yml