Buying Signals

Automated B2B buying-signal detection via the Alavida platform. Analyzes companies across web/news, landing pages, and social media — then scores them by buying intent.

Freshness check: If more than 30 days have passed since the last-updated date above, check if the API or data models have changed.

Overview

Submit a list of companies to the Alavida platform. The service detects buying signals from multiple sources, classifies them with AI, validates findings, and scores each company by buying intent.

What it detects:

• Funding announcements (seed through Series C+)
• Y Combinator batch participation
• Product/stealth launches
• Job postings (creative and marketing roles)
• Founder pain posts on social media
• Partnership announcements
• Conference speaking engagements

Output:

• Per-company tier assignment (Hot / Warm / Cool / Cold)
• Scored and classified signals with source URLs
• Personalization recommendations for outreach

Setup

1. Get an Alavida API key from your account at https://app.alavida.ai

2. Configure the key:

   <skill-path>/scripts/client.js setup --key <your-api-key>
   

   Or set the environment variable: export ALAVIDA_API_KEY=<your-api-key>

3. Requirements: Node.js 18+ (uses native fetch). No other dependencies.

Config priority (highest to lowest):

1. ALAVIDA_API_KEY environment variable
2. ~/.config/alavida/config.json

Handling “API key not found” errors

CRITICAL: When you receive an “API key not found” error:

1. Tell the user to run the setup command — The setup is interactive and requires user input:

   <skill-path>/scripts/client.js setup
   

2. Stop and wait — Do not continue without a valid API key. Wait for the user to complete setup and confirm before proceeding.

3. DO NOT attempt to:

   • Search for API keys in config files or environment
   • Grep through directories
   • Construct complex shell commands to find credentials
   • Prepare job files before setup is complete

Note for agents: All script paths in this document (e.g., ./scripts/client.js) are relative to the skill directory where this SKILL.md file is located.

Signal Types

Notes:

• Higher weights = stronger buying intent
• Signals outside recency window are discarded
• Multiple signals compound to higher scores

Tier System

Common Actions

Workflow

Follow this workflow when analyzing companies:

1. Check configuration first:

   ./scripts/client.js config:show
   

   If no API key configured, run setup.

2. Verify service is available:

   ./scripts/client.js health
   

3. Prepare input file (JSON format — see Input File Format)

4. Submit and wait for results:

   ./scripts/client.js run companies.json --poll
   

   Flags:

   • --poll: Wait for job completion (recommended)
   • --timeout <seconds>: Polling timeout (default: 600s)
   • --json: Output raw JSON

5. Or submit and check later:

   ./scripts/client.js run companies.json
   # returns job_id
   ./scripts/client.js status <job_id>
   

6. Review results — The CLI displays:

   • Job status and progress
   • Per-company tier assignments and scores
   • Signal details by type with source URLs
   • Outreach recommendations

Commands Reference

Input File Format

JSON file with an array of companies, each optionally containing people:

Minimal example:

{
  "companies": [
    {
      "company_id": "comp_123",
      "company_name": "Acme Corp",
      "domain": "acme.com",
      "website_url": "https://acme.com"
    }
  ]
}

Full example:

{
  "companies": [
    {
      "company_id": "comp_123",
      "company_name": "Acme Corp",
      "domain": "acme.com",
      "website_url": "https://acme.com",
      "funding_stage": "Series A",
      "funding_total": 10000000,
      "employee_count": 50,
      "detected_verticals": ["B2B SaaS", "Developer Tools"],
      "icp_score": 0.85,
      "company_linkedin_url": "https://linkedin.com/company/acme",
      "company_twitter_handle": "@acmecorp",
      "people": [
        {
          "full_name": "Jane Doe",
          "job_title": "CEO & Founder",
          "role_type": "decision_maker",
          "linkedin_url": "https://linkedin.com/in/janedoe",
          "twitter_handle": "@janedoe"
        }
      ]
    }
  ]
}

Company fields:

• company_id (required): Unique identifier
• company_name (required): Company name
• domain (required): Domain (e.g., “acme.com”)
• website_url (required): Full website URL
• funding_stage: e.g., “Seed”, “Series A”
• funding_total: Total funding raised in USD
• employee_count: Number of employees
• detected_verticals: Industry verticals (array)
• icp_score: ICP match score 0.0-1.0
• company_linkedin_url: Company LinkedIn URL
• company_twitter_handle: Twitter handle with @

Person fields:

• full_name (required): Person’s full name
• job_title (required): Job title
• role_type (required): “decision_maker” or “champion”
• linkedin_url: LinkedIn profile URL
• twitter_handle: Twitter handle with @

Data Models

Job Submission Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Job Status Response

{
  "job_id": "550e8400-...",
  "status": "completed",
  "progress": 100,
  "credits_used": 500,
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-10T12:01:30Z",
  "result": {
    "companies": [
      {
        "company_name": "Acme Corp",
        "company_id": "comp_123",
        "tier": "HOT",
        "total_score": 270,
        "signal_count": 8,
        "recommendation": "Strong buying intent. Prioritize for outreach.",
        "reasoning": "Multiple signals across funding, hiring, and social.",
        "signals": [
          {
            "type": "funding_announcement",
            "source_url": "https://techcrunch.com/...",
            "snippet": "Acme raised $10M Series A...",
            "confidence": 0.95,
            "pipeline": "web_news"
          }
        ]
      }
    ],
    "summary": {
      "total_companies": 3,
      "hot": 1,
      "warm": 1,
      "cool": 1,
      "cold": 0
    }
  }
}

Pricing

Buying signals uses a credit-based pricing model:

• Base cost: 500 credits per run
• Typical range: 400-800 credits depending on signal density
• Credits are deducted after job completion

If your account has insufficient credits, the platform returns a 402 error before any work begins. Top up at https://app.alavida.ai/credits.

Error Handling

Common Errors

“API key not found”

• Run ./scripts/client.js setup to configure your API key

“Authentication failed” (401)

• Your API key is invalid or expired
• Get a new key from https://app.alavida.ai

“Insufficient credits” (402)

• Your account doesn’t have enough credits
• Top up at https://app.alavida.ai/credits

“Service unavailable” (503)

• The buying-signals service is temporarily down
• Try again in a few minutes

“Job failed”

• Check the error message in ./scripts/client.js status <job_id>
• Some pipelines may fail while others succeed — partial results are still returned

Partial Failures

The service uses partial failure tolerance:

• If one analysis source fails, others continue
• Results include both successful signals and notes about failures
• Credits are charged proportionally for partial results

Examples

Setup

./scripts/client.js setup --key ak_xxxxx

Show configuration

./scripts/client.js config:show

Check service health

./scripts/client.js health

Analyze companies and wait for results

./scripts/client.js run companies.json --poll

Submit and check later

./scripts/client.js run companies.json
# => Job ID: 550e8400-e29b-41d4-a716-446655440000

./scripts/client.js status 550e8400-e29b-41d4-a716-446655440000

Get raw JSON output

./scripts/client.js run companies.json --poll --json > results.json

Tips

• Start with health check: Always run health before submitting jobs
• Test with one company first: Validate your setup before batch processing
• Use –poll: Most useful for interactive analysis — submit and get results in one command
• Personalization: Use the recommendation field in results for outreach messaging
• Top signals: Review per-company signals for the best conversation hooks

Integration with Claude Code

When asked to analyze prospects:

1. User provides company list or asks to analyze specific companies
2. Create input JSON file with company data
3. Run analysis: ./scripts/client.js run <file> --poll
4. Review results and provide recommendations based on tiers and signals
5. Suggest outreach strategies based on top signals