Skip to main content
POST
Push external signals
Create the external-signal agent from the lemlist app (Signal Agents → external signal) or with Create Signal Agent (type externalSignalContact or externalSignalCompany). Its field mapping tells lemlist which key of your JSON body fills which field: push one flat JSON object keyed by those source keys, with Basic auth (empty username, API key as password) or ?access_token=<API key> when your tool cannot set headers. The contact / company format below only applies to an agent without a field mapping. External signals are free (creditsConsumed is always 0) and capped by the agent’s daily limit (default 50/day); over the cap, or when no matching entity is found, the signal is returned with status: "ignored".

Authorizations

Authorization
string
header
required

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

Path Parameters

watchListId
string
required

Id of the Signal Agent to push the signal to. Must be an externalSignalContact or externalSignalCompany agent.

Body

application/json

When the agent has a field mapping (externalSignalFieldMapping, always set for agents created in the app or through the API), send one flat JSON object keyed by the mapped source keys, e.g. { "linkedin_profile": "https://www.linkedin.com/in/john-doe", "plan": "enterprise" }; the contact / company / customFields format below is then ignored. That format only applies to agents without a field mapping.

contact
object

The contact the signal is about. Required for externalSignalContact agents; ignored otherwise.

company
object

The company the signal is about. Required for externalSignalCompany agents; ignored otherwise.

customFields
object

Optional key/value metadata stored on the signal. Max 20 keys; all values must be strings.

Example:

Response

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.

status
enum<string>

processed when a signal was created, ignored otherwise

Available options:
processed,
ignored
signalId
string

Id of the created signal. Present when status is processed.

Example:

"wls_ExAmPlE1234567890a"

reason
enum<string>

Why the signal was ignored. Present when status is ignored.

Available options:
no_entity_match,
daily_limit_reached
creditsConsumed
integer

Always 0 - external signals are free.

Example:

0

entity
object

The matched entity. Present when status is processed.