Note for AI agents: This file and other files in this skill folder may be truncated when opened. Always read files fully in chunks if necessary to ensure no instructions, endpoints, or examples are missed.

SMB Sales Boost Skill

This skill enables natural language interaction with the SMB Sales Boost API — a B2B lead generation platform providing access to newly registered small and medium businesses across the United States.

Setup

The user must provide their API key. Keys have a smbk_ prefix and are generated from the Dashboard > API tab. The key is passed as a Bearer token in the Authorization header of every request.

Base URL: https://smbsalesboost.com/api/v1

Important: API access requires a Starter, Growth, Scale, Platinum, or Enterprise subscription plan. New users can purchase a subscription entirely via API using the Programmatic Purchase endpoints (no web signup required).

Data Sensitivity: Exported leads contain business contact information including phone numbers and email addresses (PII). Exported files are saved to the agent's output directory by default. Handle exported files with appropriate care — do not share them in public channels or store them in unsecured locations.

Export File Location: By default, smb_api.py saves exported files to the --output-dir path (defaults to /mnt/user-data/outputs). You can override this with the --output-dir flag to save files to a preferred secure location.

Authentication

All requests must include:

Authorization: Bearer <API_KEY>

If the user hasn't provided their API key yet, ask them for it before making any requests. Store it in a variable for reuse throughout the session.

Credit-Based System

Starter, Growth, and Scale plans use a credit-based model for both querying and exporting leads:

• Each new lead returned by GET /leads (query) costs 1 credit
• Each net-new lead exported by POST /leads/export costs 1 credit
• Previously-exported leads are free to re-query or re-export (do not consume credits)
• Both endpoints support maxCredits (cap credit spending) and maxResults (cap total leads) for credit-optimized ordering: new leads are sorted first, then previously-exported leads fill remaining slots
• Set maxCredits=0 on either endpoint to only receive previously-exported leads at no credit cost
• Platinum and Enterprise plans are not credit-limited

Credit Pricing (per credit):

Credit balance fields (from GET /me): monthlyCredits, monthlyCreditsUsed, monthlyCreditsRemaining, permanentCredits, totalCreditsRemaining, creditOverageRate

Additional profile fields (from GET /me): totalLeadsExported (all-time count), monthlyLeadsExported (current billing cycle), autoTopUp (nested object with enabled, triggerType, triggerAmount, purchaseType, purchaseAmount, capType, capAmount)

Users can purchase additional permanent credits via POST /purchase-credits or configure automatic top-ups via GET/PATCH /auto-top-up.

Rate Limits

• General endpoints: 60 requests per minute
• Export endpoints: 1 per 5 minutes
• AI endpoints: 5 per minute
• Programmatic purchase: 5 per hour per IP
• Claim key: 30 per hour per IP

Rate limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. If rate limited, check the Retry-After header for seconds to wait.

Two Database Types

SMB Sales Boost has two separate databases with different contact information available:

1. home_improvement — Home improvement/contractor businesses with phone numbers, star ratings, review counts, review snippets, profile URLs, and categories
2. other — General newly registered businesses with phone numbers and email addresses, registered URLs, crawled URLs, short/long descriptions, redirect status, and AI-enriched category estimations

The Home Improvement database provides phone numbers as the primary contact method. The Other database provides both phone numbers and email addresses, making it ideal for cold email and multi-channel outreach campaigns.

Some filter parameters only work with one database type. The user's account has a default database setting. Always check which database the user wants to query.

Core Endpoints

1. Search Leads — GET /leads

The primary endpoint. Translates natural language queries into filtered lead searches. Each new lead returned costs 1 credit (previously-exported leads are free to re-query). Supports maxCredits and maxResults parameters for credit-optimized ordering.

Key Parameters:

Understanding "Last Updated" — this is critical for finding the freshest leads:

• Home Improvement leads: Last Updated means a new phone number was detected
• Other leads: Last Updated means any of the 5 contact/address fields changed: primary phone, secondary phone, primary email, secondary email, or full address
• Both databases also include newly added records in this date
• Many businesses launch a website before adding contact info, so the Last Updated date captures when that information first becomes available — making it the primary way to identify the most actionable leads

Wildcard Keyword Tips:

• Use * to match any characters: "*dental*" matches "dental clinic", "pediatric dentistry", etc.
• Combine wildcards for compound terms: "*auto*repair*" matches "auto body repair", "automotive repair shop", etc.
• Use multiple keyword variations for broader coverage: ["*dental*", "*dentist*", "*orthodont*"]
• Keywords without wildcards still perform substring matching by default
• URL Space-to-Wildcard: For URL columns (registered URL, crawled URL, profile URL