lemlist Signal Agents API

openapi: 3.2.0
info:
  title: Lemlist Signal Agents API
  version: 1.0.0
  description: 'Operations tagged Signal Agents across 2 of this provider''s published API definitions: lemlist-openapi-v2.json, lemlist-openapi.yml. Each path carries the servers of the definition it was published in.'
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
    servers:
    - url: https://api.lemlist.com/api
  /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
    servers:
    - url: https://api.lemlist.com/api
  /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
    servers:
    - url: https://api.lemlist.com/api
  /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
    servers:
    - url: https://api.lemlist.com/api
  /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
    servers:
    - url: https://api.lemlist.com/api
  /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
    servers:
    - url: https://api.lemlist.com/api
  /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
    servers:
    - url: https://api.lemlist.com/api
components:
  schemas:
    WatchListSchema:
      type: object
      description: A Signal Agent (watch list) configuration.
      properties:
        _id:
          type: string
          description: Unique Signal Agent identifier
        name:
          type: string
          description: Display name
        type:
          type: string
          description: Signal type monitored by this Signal Agent
          enum:
          - companyIsHiring
          - companyRaisedFunds
          - recruitmentCampaign
          - jobChange
          - newHire
          - companyEmployeeVisitedMyWebsite
          - customSignals
          - competitorConnections
          - competitorReactions
          - companyFollowers
          - technologyChange
          - linkedinPeopleProfile
          - linkedinCompanyProfile
          - mergersAcquisitions
          - promotion
          - linkedinKeywords
          - externalSignalContact
          - externalSignalCompany
          - buyingIntent
        status:
          type: string
          description: Lifecycle status
          enum:
          - active
          - inactive
          - draft
          - insufficient_credits
          - empty_crm_lists
          - error
          - delete
        entity:
          type: string
          description: Entity kind the agent tracks
          enum:
          - contact
          - company
        segmentType:
          type: string
          description: How the monitored entities are sourced
          enum:
          - all
          - list
          - csv
        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
        filters:
          type: array
          description: Filters narrowing which entities/events are tracked
          items:
            $ref: '#/components/schemas/WatchListFilter'
        emoji:
          type: string
          description: Emoji shown next to the agent name
    WatchListConfigHistoryEntry:
      type: object
      description: A past configuration version of a Signal Agent, active during [startDate, endDate).
      properties:
        _id:
          type: string
          description: History entry identifier
        startDate:
          type: string
          description: When this configuration version became active
          format: date-time
        endDate:
          type: string
          description: When this configuration version was replaced
          format: date-time
        createdBy:
          type: string
          description: User id that made the change
        name:
          type: string
          description: Signal Agent name at capture time
        emoji:
          type: string
          description: Emoji at capture time
        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
        entity:
          type: string
          description: Entity kind
          enum:
          - contact
          - company
        segmentType:
          type: string
          description: Segment sourcing
          enum:
          - all
          - list
          - csv
        filters:
          type: array
          items:
            $ref: '#/components/schemas/WatchListFilter'
        signalProcessingType:
          type: string
          description: Signal processing type
          enum:
          - manual
          - create_opportunity
          - push_to_campaign
        stats:
          type: object
          description: Signal/campaign stats computed for the window [startDate, endDate).
          properties:
            signalsCount:
              type: integer
              description: Number of signals detected in the window
            campaigns:
              type: array
            

# --- 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