SMB Sales Boost REST API Documentation

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

Response Format: JSON (application/json)

Authentication: Bearer token (API key)

Introduction

The SMB Sales Boost API provides RESTful access to our lead database, export tools, filter management, and AI features. All API endpoints return JSON responses and require authentication via Bearer token.

Quick Start

Base URL: https://smbsalesboost.com/api/v1
Response Format: JSON (application/json)
Authentication: Bearer token (API key)
Protocol: HTTPS only

Plan Requirement

API access is available for users on any paid plan (Starter, Growth, Scale, Platinum, or Enterprise). View plans to get started.

Programmatic Purchase

Purchase a subscription entirely via API - no web signup or onboarding required. This is ideal for AI agents and automated workflows that need programmatic access to SMB Sales Boost.

How It Works

(1) Call POST /api/v1/purchase with your email and desired plan → (2) Complete payment at the returned Stripe Checkout URL → (3) Call POST /api/v1/claim-key with your email and claim token to retrieve your API key. Your API key is also emailed to you automatically.

Step 1: Initiate Purchase

POST /api/v1/purchase: Create a new subscription purchase session. Returns a Stripe Checkout URL and a claim token. No authentication required. Rate limited to 5 requests per hour per IP.

Parameters: email (required, string), plan (required, string - "starter", "growth", "scale", "platinum", or "enterprise").

Step 2: Complete Payment

Open the checkoutUrl in a browser to complete payment on Stripe's hosted checkout page. After successful payment, the system automatically provisions your account and generates an API key.

Step 3: Claim Your API Key

POST /api/v1/claim-key: Retrieve your API key after payment is completed. No authentication required. Rate limited to 30 requests per hour per IP. If payment is still processing, returns a pending status - poll every 5-10 seconds.

Parameters: email (required, string - email used during purchase), claimToken (required, string - claim token from the purchase response).

Account Setup (Highly Recommended)

Programmatic purchases skip the onboarding wizard. To get the most out of SMB Sales Boost, configure your account via the API before searching or exporting leads:

PATCH /api/v1/me - Set your company name and website
POST /api/v1/ai/suggest-categories - Get AI-powered category suggestions
POST /api/v1/ai/generate-keywords - Generate targeting keywords
POST /api/v1/settings/switch-database - Select your lead database

Authentication

All API requests require a valid API key sent as a Bearer token in the Authorization header. Generate your API key from the Dashboard → API tab (available on all paid plans).

Example Request

curl -H "Authorization: Bearer smbk_your_api_key_here" \
  https://smbsalesboost.com/api/v1/me

API Key Format

All API keys are prefixed with smbk_ for easy identification.

Security Best Practice

Never expose your API key in client-side code, public repositories, or browser requests. Store it securely as an environment variable.

Rate Limits

API requests are rate-limited to ensure fair usage. Rate limit information is included in response headers.

Rate Limit Tiers

General Endpoints: 60 requests per minute
Export Endpoints: 1 request per 5 minutes
AI Endpoints: 5 requests per minute

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429)

User Profile

Manage your user profile including subscription details and account settings.

Endpoints

GET /api/v1/me: Retrieve your user profile including subscription details and account settings.
PATCH /api/v1/me: Update your profile. Only the fields provided will be updated. Allowed fields: firstName, lastName, companyName, companyWebsite.

Response Fields

The user profile response includes: id, email, firstName, lastName, companyName, companyWebsite, smbType, subscriptionPlan, subscriptionStatus, isSubscribed, freeLeadsUsed, onboardingCompleted, targetCategories, targetLocations, monthlyCredits, monthlyCreditsUsed, monthlyCreditsRemaining, permanentCredits, totalCreditsRemaining, and creditOverageRate.

Leads

Search, filter, and export leads from our database. Supports keyword filtering, location filtering, industry filtering, and pagination.

How Search Works: Two-Phase Query Model

Phase 1 - Include (OR Logic)

All positive keywords and include terms are combined with OR logic. A lead matches if any positive keyword matches in any of the OR group search columns.

Home Improvement: Business Name, Categories, Profile URL
Other: Registered URL, Crawled URL, Company Name, Categories (AI Enrichment)

Phase 2 - Exclude (AND Logic)

Negative keywords are checked against the same columns as positive keywords. A lead is excluded if any negative keyword matches in any of those columns.

URL Space-to-Wildcard

For URL columns, spaces in search terms are automatically replaced with % wildcards. For example, "dental clinic" becomes %dental%clinic% to match URLs like example.com/dental-clinic.

AI Category Estimation (Other Database)

Leads in the Other database are progressively enriched by AI with estimated business type categories. Each lead may include an aiCategoryEstimation field containing an array of 1-3 category names, or null if not yet classified.

Endpoints

GET /api/v1/leads: Search and filter leads. Requires at least one positive filter (positiveKeywords, nameIncludeTerms, etc.).
POST /api/v1/leads/export: Export filtered leads to CSV, JSON, or XLSX. Subject to export rate limits. Supports credit-optimized ordering via maxCredits and maxResults parameters.

Key Parameters

positiveKeywords (required), negativeKeywords, orColumns, stateInclude, stateExclude, cityInclude, cityExclude, zipInclude, zipExclude, minStars, maxStars, minReviewCount, maxReviewCount, sortBy, sortOrder, page, limit, database, and various column-specific include/exclude terms.

Credit-Optimized Export Parameters

The export endpoint supports additional parameters for controlling credit usage:

maxLeads: Cap total leads exported. Overflow stored in lead reservoir for the next export.
maxResults: Cap total results returned (both new and previously-exported leads). New leads are prioritized first, then previously-exported leads fill remaining slots.
maxCredits: Cap credits spent on this export. Only new (credit-consuming) leads count toward this cap. Set to 0 to only receive previously-exported leads at no credit cost.

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

Filter Presets

Save and manage reusable filter configurations. Create, update, delete, and list your saved filter presets for quick access to your most-used search criteria.

Endpoints

GET /api/v1/filter-presets: List all your saved filter presets.
POST /api/v1/filter-presets: Create a new filter preset. Requires a name and filters object.
DELETE /api/v1/filter-presets/:id: Delete a filter preset by ID.

Preset Object

Each preset includes: id, name, filters (containing positiveKeywords, stateInclude, etc.), and createdAt timestamp.

Keyword Lists

Manage keyword lists for targeted lead searching. Create lists of include and exclude keywords to refine your lead searches and automate filtering.

Endpoints

GET /api/v1/keyword-lists: List all your keyword lists.
POST /api/v1/keyword-lists: Create a new keyword list. Requires name, type (positive/negative), and keywords array.
PUT /api/v1/keyword-lists/:id: Update an existing keyword list.
DELETE /api/v1/keyword-lists/:id: Delete a keyword list by ID.

Keyword List Object

Each list includes: id, name, type (positive or negative), keywords array, and createdAt timestamp.

Email Schedules

Set up automated email delivery of leads matching your saved filters. Configure delivery frequency, filter presets, export format preferences, and multi-recipient splitting.

Endpoints

GET /api/v1/email-schedules: List all your email export schedules.
POST /api/v1/email-schedules: Create a new email schedule. Requires name, filterPresetId, and intervalValue.
PATCH /api/v1/email-schedules/:id: Update an existing email schedule. All fields are optional.
DELETE /api/v1/email-schedules/:id: Delete an email schedule by ID.
POST /api/v1/email-schedules/:id/trigger: Manually trigger an email schedule to send immediately.

Combined File Feature

When file splitting is enabled, you can configure a combined file that includes an assignee column and file name column, sent to dedicated combined recipients.

Export Formats

Customize which columns are included in your lead exports. Create and manage export format templates for consistent data delivery. Supports CSV, JSON, and XLSX file types.

Endpoints

GET /api/v1/export-formats: List all your export format templates.
GET /api/v1/export-formats/:id: Get a specific export format by ID.
POST /api/v1/export-formats: Create a new export format with field mappings.
PATCH /api/v1/export-formats/:id: Update an existing export format.
DELETE /api/v1/export-formats/:id: Delete an export format by ID.
POST /api/v1/export-formats/:id/set-default: Set an export format as the default.

File Splitting Options

max_rows: Split by max rows per file (requires maxRowsPerFile, min 10)
equal_parts: Split into equal parts (requires numberOfParts, min 2)
parts_max_rows: Number of parts with max rows each (requires both)

Export History

View your past exports with details including date, row count, filters used, and export format. Track your export activity and re-download previous exports.

Endpoints

GET /api/v1/export-history: List your export history with file details including fileName, fileType, leadCount, fileSize, formatName, databaseType, createdAt, and expiresAt.
GET /api/v1/export-history/:id/download: Download a previously exported file by its history ID. Files expire after 7 days.

Account Settings

Manage your account settings including database type selection. Switch between the Home Improvement and Other lead databases.

Endpoints

GET /api/v1/settings/database: Get your current database type setting (home_improvement or other).
POST /api/v1/settings/switch-database: Switch between database types. Requires a database field with value "home_improvement" or "other".

Database Switching Notes

Switching databases may pause email schedules that are incompatible with the new database type. Filter presets, export formats, and email schedules are tagged with a database type.

AI Features

Access AI-powered tools including keyword suggestions, category recommendations, and website analysis. Leverage machine learning to optimize your prospecting strategy.

Rate limit: AI endpoints are limited to 5 requests per minute.

Endpoints

POST /api/v1/ai/suggest-categories: Get AI-powered category suggestions based on your business type and target market. Requires companyName, companyDescription, and productService.
POST /api/v1/ai/generate-keywords: Trigger AI keyword generation based on your account's target categories and business profile. This is an asynchronous operation - keywords will be generated in the background and saved to your keyword lists.

Category Suggestion Parameters

Required: companyName, companyDescription, productService. Optional: companyWebsite, smbType, excludeCategories.

Export Blacklist

Manage your export blacklist to prevent specific domains or Yelp profiles from appearing in exports. Add and remove entries to prevent duplicate outreach.

Endpoints

GET /api/v1/export-blacklist: List all your blacklist entries with entryType (domain or yelp_profile), value, and createdAt.
POST /api/v1/export-blacklist: Add entries to your export blacklist. Requires an entries array with entryType and value for each entry.
DELETE /api/v1/export-blacklist/:id: Remove a blacklist entry by ID.

Entry Types

domain: Block all leads from a specific domain (e.g., competitor.com)
yelp_profile: Block a specific Yelp business profile URL

Error Handling

All errors follow a consistent format with an error code and a human-readable message.

Error Response Format

{
  "error": "bad_request",
  "message": "No valid fields provided. Allowed: firstName, lastName, companyName, companyWebsite"
}

HTTP Status Codes

Status	Meaning
200	OK - Request succeeded
201	Created - Resource created successfully
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
403	Forbidden - API access not available on your plan
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Credits & Subscription

Starter, Growth, and Scale plans use a credit-based system where each lead queried or exported costs 1 credit. Use these endpoints to purchase additional permanent credits or manage your subscription.

Credit balance: Your current credit balance is always available via GET /api/v1/me - see the monthlyCredits, monthlyCreditsRemaining, permanentCredits, and totalCreditsRemaining fields.

Endpoints

POST /api/v1/purchase-credits: Purchase additional permanent credits using your saved payment method (charged off-session via Stripe). Minimum 100 credits. Pricing: Starter 10¢/credit, Growth 8¢/credit, Scale 5¢/credit. Only available for Starter, Growth, and Scale plans.
POST /api/v1/subscription/cancel: Cancel your subscription at the end of the current billing period. Your access continues until the period ends.

Purchase Credits Parameters

creditCount (required, integer) - Number of credits to purchase (minimum 100).

MCP Server

SMB Sales Boost provides a remote Model Context Protocol (MCP) server that lets AI assistants and LLMs interact with your account directly. All API v1 endpoints are available as MCP tools, enabling AI-powered lead search, export, and management workflows.

What is MCP?

The Model Context Protocol is an open standard that enables AI models to securely access tools and data sources. With our MCP server, you can connect Claude, ChatGPT, or any MCP-compatible AI assistant to search, filter, and export leads through natural language.

Connection Details

Endpoint: https://smbsalesboost.com/mcp
Transport: Streamable HTTP (stateless)
Method: POST
Auth: Bearer token (your API key) in Authorization header

Client Configuration

Add this to your MCP client configuration (e.g., Claude Desktop, Cursor, or any MCP-compatible tool):

{
  "mcpServers": {
    "smb-sales-boost": {
      "type": "streamable-http",
      "url": "https://smbsalesboost.com/mcp",
      "headers": {
        "Authorization": "Bearer smbk_your_api_key_here"
      }
    }
  }
}

Available Tools (36)

Every REST API endpoint is available as an MCP tool. Key tools include: get_profile, update_profile, search_leads, export_leads, list_filter_presets, create_filter_preset, list_keyword_lists, create_keyword_list, list_email_schedules, create_email_schedule, list_export_formats, create_export_format, list_export_history, switch_database, ai_suggest_categories, ai_generate_keywords, list_export_blacklist, and more.

Requirements

MCP access uses the same API key authentication as the REST API. An active paid subscription (Starter, Growth, Scale, Platinum, or Enterprise) is required. All rate limits and usage tracking apply.

Integrations

Connect SMB Sales Boost with your existing tools and workflows. The following integrations are on our roadmap:

Zapier: Automate workflows with thousands of apps (Coming Soon)
n8n: Self-hosted workflow automation (Coming Soon)
Salesforce: Sync leads directly to your CRM (Coming Soon)
HubSpot: Push leads into your HubSpot pipeline (Coming Soon)

Ready to Find Your Next Customers? Get access to newly registered business leads updated daily. Get Started

SMB Sales Boost REST API Documentation

Table of Contents

Introduction

Quick Start

Plan Requirement

Programmatic Purchase

How It Works

Step 1: Initiate Purchase

Step 2: Complete Payment

Step 3: Claim Your API Key

Account Setup (Highly Recommended)

Authentication

Example Request

API Key Format

Security Best Practice

Rate Limits

Rate Limit Tiers

Rate Limit Headers

User Profile

Endpoints

Response Fields

Leads

How Search Works: Two-Phase Query Model

Phase 1 - Include (OR Logic)

Phase 2 - Exclude (AND Logic)

URL Space-to-Wildcard

AI Category Estimation (Other Database)

Endpoints

Key Parameters

Credit-Optimized Export Parameters

Filter Presets

Endpoints

Preset Object

Keyword Lists

Endpoints

Keyword List Object

Email Schedules

Endpoints

Combined File Feature

Export Formats

Endpoints

File Splitting Options

Export History

Endpoints

Account Settings

Endpoints

Database Switching Notes

AI Features

Endpoints

Category Suggestion Parameters

Export Blacklist

Endpoints

Entry Types

Error Handling

Error Response Format

HTTP Status Codes

Credits & Subscription

Endpoints

Purchase Credits Parameters

MCP Server

What is MCP?

Connection Details

Client Configuration

Available Tools (36)

Requirements

Integrations