Smb Sales Boost

> 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 

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): | Plan | Cost per Credit | Monthly Credits | Max Purchase per Transaction | |------|----------------|----------------|------------------------------| | Starter | $0.10 | 500 | 2,500 | | Growth | $0.075 | 2,000 | 10,000 | | Scale | $0.05 | 10,000 | 50,000 | | Platinum | $0.03 | 100,000 | 500,000 | | Enterprise | $0.02 | 250,000 | 1,250,000 |

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:

| Parameter | Type | Description | |-----------|------|-------------| | page | integer | Page number (default: 1) | | limit | integer | Results per page (max 1000, default 100) | | database | string | home_improvement or other | | positiveKeywords | JSON array string | Keywords to include (OR logic). Supports * wildcard for pattern matching (e.g., ["*dental*", "*ortho*"]). Without wildcards, performs substring matching by default. | | negativeKeywords | JSON array string | Keywords to exclude (AND logic). Also supports * wildcard (e.g., ["*franchise*"]). | | orColumns | JSON array string | Column names to search keywords against | | search | string | Full-text search across all fields | | stateInclude | string | Comma-separated state codes: CA,NY,TX | | stateExclude | string | Comma-separated state codes to exclude | | cityInclude | JSON array string | Cities to include | | cityExclude | JSON array string | Cities to exclude | | zipInclude | JSON array string | ZIP codes to include | | zipExclude | JSON array string | ZIP codes to exclude | | nameIncludeTerms | JSON array string | Business name include terms | | nameExcludeTerms | JSON array string | Business name exclude terms | | lastUpdatedFrom | date string | Filter by Last Updated date (after this date). Supports ISO 8601 or relative format (e.g., rel:7d, rel:6m). | | lastUpdatedTo | date string | Filter by Last Updated date (before this date) | | updateReasonFilter | string | Comma-separated update reasons to filter by (e.g., "Newly Added", "Phone Primary") |

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

| Parameter | Type | Description | |-----------|------|-------------| | countryInclude | JSON array string | Countries to include | | countryExclude | JSON array string | Countries to exclude | | sortBy | string | Field to sort by | | sortOrder | string | asc or desc (default: desc) |

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), spaces in search terms are automatically replaced with % wildcards. For example, "dental clinic" becomes %dental%clinic% to match URLs like example.com/dental-clinic

Home Improvement Only:

| Parameter | Type | Description | |-----------|------|-------------| | minStars / maxStars | number | Star rating range | | minReviewCount / maxReviewCount | integer | Review count range | | categoriesIncludeTerms / categoriesExcludeTerms | JSON array string | Category filters | | reviewSnippetIncludeTerms / reviewSnippetExcludeTerms | JSON array string | Review text filters | | profileUrlIncludeTerms / profileUrlExcludeTerms | JSON array string | Profile URL filters |

Other Database Only:

| Parameter | Type | Description | |-----------|------|-------------| | urlIncludeTerms / urlExcludeTerms | JSON array string | Registered URL filters | | crawledUrlIncludeTerms / crawledUrlExcludeTerms | JSON array string | Crawled URL filters | | descriptionIncludeTerms / descriptionExcludeTerms | JSON array string | Short description filters | | descriptionLongIncludeTerms / descriptionLongExcludeTerms | JSON array string | Long description filters | | emailPrimaryInclude / emailPrimaryExclude | JSON array string | Primary email filters | | emailSecondaryInclude / emailSecondaryExclude | JSON array string | Secondary email filters | | phonePrimaryInclude / phonePrimaryExclude | JSON array string | Primary phone filters | | phoneSecondaryInclude / phoneSecondaryExclude | JSON array string | Secondary phone filters | | redirectFilter | string | yes or no — filter by redirect status | | registrationDateFrom / registrationDateTo | date string | Filter by domain registration date (ISO 8601 or relative format e.g., rel:6m) | | timeScrapedFrom / timeScrapedTo | date string | Filter by when leads were scraped (ISO 8601 or relative format e.g., rel:30d) | | websiteSchemaFilter | string | Comma-separated website schema types (e.g., LocalBusiness,Organization). Use GET /leads/other/schema-types for available values. |

Credit Control Parameters (also available on export):

| Parameter | Type | Description | |-----------|------|-------------| | maxResults | integer | Cap total leads returned (new + previously-exported). New leads prioritized first, then previously-exported fill remaining slots. | | maxCredits | integer | Cap credits spent on this query. Set to 0 to only receive previously-exported leads at no cost. |

When maxCredits or maxResults is specified, credit-optimized ordering is applied: new (credit-consuming) leads sorted first, then previously-exported leads, each group sorted by lastUpdated descending (or your custom sort).

Important: At least one positive filter is required (positiveKeywords or any column-specific include terms).

Response includes: leads array, totalCount, page, limit, databaseType, creditsUsed, creditsRemaining (credit-plan users only), maxResults, maxCredits (echoed when specified)

Error 402 Payment Required: Returned when credit-plan users have insufficient credits. Use maxCredits or maxResults to limit credit usage, or purchase more credits.

Lead fields use display-name keys (with spaces). The two databases return different schemas:

• HomeImprovementLead: id, Company Name, Phone, Stars, Review Count, Categories, Profile URL, Review Snippet, Address Full, Street, Address City, Address State, Address Zip, Address Country, Last Updated, Time Scraped
• OtherLead: id, Company Name, Phone Primary, Phone Secondary, Email Primary, Email Secondary, Registered URL, Registration Date, Redirect, Crawled URL, AI Categories, Website Schema, Description Short, Description Long, Address Full, Street, City, State, Zip, Country, Last Updated, Time Scraped

Contact fields (phone/email) are masked for free users. The Last Updated field indicates when contact information was last detected or updated — the best indicator of lead freshness and actionability.

AI Categories (Other Database): Leads in the Other database may include an AI Categories field containing an array of 1-3 AI-estimated category names, or null if not yet classified. This progressive enrichment classifies businesses into 957+ categories.

2. Preview Leads — GET /leads/preview

Preview leads matching your filters with masked contact information — does NOT consume any credits. Use this to test filters and evaluate result quality before committing credits on the full GET /leads endpoint.

How it differs from GET /leads:

• Contact fields are returned in masked format (e.g., (5**) ***-**89, j***@***.com)
• No credits are consumed regardless of plan
• No maxCredits or maxResults parameters (not needed since preview is free)
• Contact-field filters are not available: emailPrimaryInclude, emailPrimaryExclude, emailSecondaryInclude, emailSecondaryExclude, phonePrimaryInclude, phonePrimaryExclude, phoneSecondaryInclude, phoneSecondaryExclude
• All other filters are identical to GET /leads (keywords, location, company name, URLs, descriptions, ratings, dates, etc.)

Response includes: leads array (with masked contacts), pagination (page, limit, total, pages), databaseType, preview: true flag

When to use preview:

• User wants to check how many results match before spending credits
• User wants to evaluate filter quality
• User says "preview", "test my filters", "how many leads match", or similar

3. Website Schema Types — GET /leads/other/schema-types

Returns a sorted list of all distinct website schema types found in the Other leads database. Use these values with the websiteSchemaFilter parameter on GET /leads.

4. Export Leads — POST /leads/export

Export filtered leads as CSV, JSON, or XLSX files.

Request body:

{
  "database": "home_improvement" | "other",
  "filters": { /* same filter params as GET /leads */ },
  "selectedIds": [1, 2, 3],  // alternative to filters
  "formatId": 123,  // optional export format template ID
  "maxLeads": 500,  // optional: cap leads per export, overflow stored in reservoir
  "maxResults": 1000,  // optional: total leads (new + previously-exported)
  "maxCredits": 100  // optional: credit spending cap (0 = only previously-exported leads)
}

Credit system (Starter/Growth/Scale plans):

• Each net-new lead exported deducts 1 credit
• Previously-exported leads are included for free
• Use maxCredits to control spending, maxLeads to limit volume
• Set maxCredits: 0 to only receive previously-exported leads at no cost

Response: files array (with base64-encoded data), leadCount, exportId, databaseType, creditsUsed, creditsRemaining, overflowCount

Error 402 Payment Required: Returned when credit-plan users have insufficient credits.

Rate limited: 1 export per 5 minutes, max 10,000 leads per export.

5. Filter Presets — /filter-presets

• GET /filter-presets — List all saved presets
• POST /filter-presets — Create a preset (requires name and filters object)
• DELETE /filter-presets/{id} — Delete a preset

6. Keyword Lists — /keyword-lists

Keyword lists now support typed lists (positive or negative) with paired list management and source categories.

• GET /keyword-lists — List all keyword lists
• POST /keyword-lists — Create (requires name, optional keywords array, sourceCategories array max 3)
• PUT /keyword-lists/{id} — Update
• DELETE /keyword-lists/{id} — Delete

Keyword list properties: name, keywords (wildcard patterns e.g., *dentist*), type (positive/negative), pairedListId (linked positive/negative pair), sourceCategories (max 3), autoRefineEnabled, refinementStatus (running/completed/paused)

7. Email Schedules — /email-schedules

Email schedules now sup

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Tomsonx232
• Source: Tomsonx232/smb-sales-boost-skill
• License: MIT
• Homepage: https://smbsalesboost.com

Install and usage instructions live in the source repository linked above.