Skip to main content
POST
Create Signal Agent
A Signal Agent is created as a draft by default. Pass segmentType, signalProcessingType and activate: true to run the full setup and start monitoring immediately. filters are validated against the chosen type — use List allowed filters to discover which filters a type accepts.
Pass campaignId with signalProcessingType: "push_to_campaign" to link the new agent to that campaign as its signal trigger in the same call — same effect as Add Signal Agent trigger. If the call is refused (400, 404 or 409), no agent is created. campaignId is not accepted by Update Signal Agent: to link an existing agent, use Add Signal Agent trigger.
For an external-signal agent (externalSignalContact / externalSignalCompany), map the keys your tool will push with the externalSignalFieldMapping filter, in being an array of { sourceKey, targetKey } objects: contact.linkedinUrl is required for a contact agent, company.domain and company.name for a company agent. Extra keys to keep on each signal go in externalSignalCustomFieldMapping. Then push events with Push external signals.
For a companyRunningAds agent (companies advertising on LinkedIn, Meta, Google, TikTok or Apple), maxIdentificationsPerDay (in, one value, default 10) is required. Optional in filters: adPlatforms (linkedin, facebook for every Meta surface, google, tiktok — EEA, UK and Switzerland only —, apple; empty means all), adFormats (empty means all), adTargetCountries (country names), adSearchTerms (keywords matched on the ad title and description). companyLocation, companyIndustries (Pubrio vertical names, not the industries of the other company types: resolve them with Autocomplete filter values using type=companyRunningAds and a query, and send the returned names verbatim — an unmatched value is a 400 WATCH_LIST_API_INVALID_FILTERS, a Pubrio outage during validation a 503 WATCH_LIST_API_TAXONOMY_UNAVAILABLE) and companySizes accept in and out; companyLinkedinUrls is out only. crmListIds is not accepted: attach CRM lists with Associate CRM lists — a CRM list or CSV monitors the listed companies’ domains only. Each signal costs 100 credits and a company is reported at most once per 30 days per agent; the agent moves to insufficient_credits when the team runs out and resumes on refill.
For a marketExpansion agent (companies entering a new country market), targetMarkets (in, country names) and maxIdentificationsPerDay (in, one value, default 20) are required. Optional in filters: originMarkets (country names, the companies’ home market), expansionStages (exploring, committing, expanding, scaling; empty means all), expansionSignalStrengths (low, medium, high, very_high; empty means all, no default is applied). companyLocation, companyIndustries (Pubrio vertical names, resolved as for companyRunningAds with Autocomplete filter values using type=marketExpansion and a query) and companySizes accept in and out; companyLinkedinUrls is out only. crmListIds is not accepted: attach CRM lists with Associate CRM lists — a CRM list or CSV monitors the listed companies’ domains only. Each signal covers one target market and costs 100 credits; a company is reported at most once per 30 days per agent, whatever the market; the agent moves to insufficient_credits when the team runs out and resumes on refill.
For a personBuyingIntent agent (people showing buying signals in their LinkedIn activity and their visits across a network of websites), personIntentTopics (in, up to 25) is required: resolve the topic names with Autocomplete filter values using filterId=personIntentTopics and a query of 3 characters or more, and send the returned names verbatim — a name outside the topic taxonomy is a 400 WATCH_LIST_API_INVALID_FILTERS. maxIdentificationsPerDay (in, one integer, default 20) is required. Optional in filters, up to 25 values each: title and companyIndustries (200 characters at most), companyLocation and location (country names; a region such as North America is expanded into its countries on companyLocation and refused on location), companySizes (the six ranges Autocomplete filter values returns with type=personBuyingIntent: 1-10, 11-50, 51-200, 201-1000, 1001-5000, 5001+). lookbackDays (in, one integer from 1 to 30, 30 when absent) is the number of days of past activity delivered once, at the first activation: a later change does not reach a running agent. No filter takes out, and crmListIds is not accepted: attach CRM lists with Associate CRM lists. Each signal costs 100 credits.

Authorizations

Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json
name
string
required

Display name

type
enum<string>
required

Signal type to monitor

Available options:
companyIsHiring,
companyRaisedFunds,
recruitmentCampaign,
newHire,
companyEmployeeVisitedMyWebsite,
customSignals,
competitorConnections,
competitorReactions,
warmIntros,
technologyChange,
linkedinPeopleProfile,
linkedinCompanyProfile,
mergersAcquisitions,
promotion,
linkedinKeywords,
republishedJobOffers,
externalSignalContact,
externalSignalCompany,
buyingIntent,
newProductLaunch,
companyAward,
newPartnership,
newOffice,
closingOffice,
costCutting,
outagesAndSecurityBreaches,
lawsuitsAndLegalIssues,
githubStargazer,
linkedinProfileViews,
companyRunningAds,
marketExpansion,
personBuyingIntent
filters
object[]

Filters to apply (validated against the signal type)

emoji
string

Emoji shown next to the agent name (defaults to a random emoji)

segmentType
enum<string>

Entity sourcing. Only all is accepted here; to monitor CRM lists or a CSV, create a draft (activate: false) and call POST /watchlist/crm-lists. Required together with signalProcessingType when activate is true.

Available options:
all
signalProcessingType
enum<string>

How detected signals are processed

Available options:
manual,
create_opportunity,
push_to_campaign
signalOpportunityTemplate
object

Task/opportunity template applied to each signal when signalProcessingType is create_opportunity.

personaId
string

Persona (pdp_xxx) used to source contacts from the People Database. Only for a company Signal Agent with signalProcessingType = push_to_campaign whose signal type does not already ship its own contact (those company signals carry no contact, so the persona is the only way to know who to reach). Optional; rejected on any other configuration.

campaignId
string

Campaign (cam_xxx) to link as this Signal Agent's signal trigger, in the same call: every new signal pushes its contact into that campaign as a lead. Only with signalProcessingType = push_to_campaign. A campaign set up as manual in the lemlist app is refused (409). Optional; on any refusal no agent is created.

Example:

"cam_ExAmPlE4k8Qz2Wn7R"

activate
boolean

Fully set up and activate the agent. Requires segmentType and signalProcessingType.

Response

Created

data
object

A Signal Agent (watch list) configuration.