Skip to main content

​
Overview

This guide walks through a complete integration: configuring signal types, polling the feed, handling signal events, and routing them to your CRM or outreach system.

​
Step 1 — Audit Your Signal Types

Start by listing your existing signal types to understand what’s already configured: 
curl -s -H "Authorization: Bearer pk_live_abc123" \
  "https://app.getlima.ai/api/v1/signals/types"
Built-in types (Hiring, Funding, LinkedIn Posts, etc.) are already active. Review their keywords and scoring_criteria — customizing these significantly improves signal quality for your ICP.

​
Step 2 — Tune Built-in Signal Types

Update the Hiring signal to focus on roles relevant to your buyers: 
curl -s -X PATCH \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["hiring", "now hiring", "we are growing", "join our team"],
    "scoring_criteria": "Score highest for VP+ engineering and technical leadership roles at B2B SaaS companies with 50-500 employees. Penalize roles at consumer companies or companies outside our ICP.",
    "config": {
      "roles": ["VP Engineering", "CTO", "Head of Engineering", "Director of Engineering"],
      "seniority": ["VP", "C-Suite", "Director"],
      "work_type": "Any",
      "locations": []
    }
  }' \
  "https://app.getlima.ai/api/v1/signals/types/HIRING_TYPE_ID"

​
Step 3 — Create a Custom Signal Type

Add a custom signal type for your specific use case: 
curl -s -X POST \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Tech Stack Mentions",
    "description": "Track when companies discuss their sales tools and processes",
    "keywords": ["CRM", "Salesforce", "HubSpot", "sales stack", "outbound"],
    "search_instructions": "Look for posts, articles, or job descriptions where companies discuss their sales technology stack or outbound sales processes.",
    "scoring_criteria": "Score higher for companies actively evaluating or switching CRM tools. Penalize generic mentions with no purchase intent.",
    "sources": ["linkedin_posts", "reddit", "news"],
    "enabled": true
  }' \
  "https://app.getlima.ai/api/v1/signals/types"

​
Step 4 — Poll the Signal Feed

Set up a polling job to pull new signals periodically: 
import requests
import time

PUFFLE_API_KEY = "pk_live_abc123"
BASE_URL = "https://app.getlima.ai/api/v1"

def poll_signals(min_score: int = 70, limit: int = 100):
    """Fetch high-quality signals and process them."""
    headers = {"Authorization": f"Bearer {PUFFLE_API_KEY}"}
    cursor = None

    while True:
        params = {"limit": limit, "min_score": min_score}
        if cursor:
            params["cursor"] = cursor

        resp = requests.get(f"{BASE_URL}/signals", headers=headers, params=params)
        resp.raise_for_status()
        data = resp.json()

        for signal in data["signals"]:
            process_signal(signal)

        pagination = data["pagination"]
        if not pagination["has_more"]:
            break
        cursor = pagination["cursor"]

def process_signal(signal: dict):
    """Route signal to CRM or outreach system."""
    print(f"[{signal['score']}] {signal['signal_type_label']}: {signal['headline']}")
    # TODO: push to CRM, trigger outreach sequence, etc.
For real-time delivery without polling, use webhooks — subscribe to the signal.detected event.

​
Step 5 — Dismiss Processed Signals

After routing a signal to your CRM, dismiss it to keep the feed clean: 
def process_signal(signal: dict):
    push_to_crm(signal)

    # Dismiss so it doesn't reappear
    requests.post(
        f"{BASE_URL}/signals/{signal['id']}/dismiss",
        headers={"Authorization": f"Bearer {PUFFLE_API_KEY}"}
    )

​
Step 6 — Submit Feedback

Improve signal quality over time by submitting feedback: 
def mark_irrelevant(signal_id: str, reason: str):
    requests.post(
        f"{BASE_URL}/signals/{signal_id}/feedback",
        headers={"Authorization": f"Bearer {PUFFLE_API_KEY}", "Content-Type": "application/json"},
        json={"rating": "not_relevant", "notes": reason}
    )

​
Architecture Pattern

Puffle Signal Feed (poll every 15 min or webhook)
         ↓
Signal Router (filter by type, score, source)
         ↓
    ┌────┴────┐
    ↓         ↓
CRM Record  Outreach Trigger
(update)    (enroll in sequence)
For high-volume use cases, push signals to a queue (SQS, Pub/Sub) and process them asynchronously to avoid blocking your polling job.