SMB Sales Boost REST API Documentation

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

Response Format: JSON (application/json)

Authentication: Bearer token (API key)

Table of Contents

Introduction | Authentication | Rate Limits | User Profile | Leads | Filter Presets | Keyword Lists | Email Schedules | Export Formats | Export History | Account Settings | AI Features | Export Blacklist | Error Handling | Integrations

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 exclusively for users on a Pro, Platinum, Enterprise, or Agency plan. Free plan users do not have access to the API. Upgrade your plan to get started.

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 Pro, Platinum, Enterprise, and Agency 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

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, and targetLocations.

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.

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.

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.

3-Category Limit

Each keyword list targets up to 3 categories (stored in the sourceCategories field). This is intentional — the AI produces better-focused keyword lists for tightly scoped category sets. If you need more categories, create separate keyword lists for each group of up to 3.

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. Optionally include sourceCategories (max 3).

PUT /api/v1/keyword-lists/:id

Update an existing keyword list. You can update keywords, name, and sourceCategories (max 3).

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, sourceCategories (up to 3 target categories), autoRefineEnabled, refinementStatus, pairedListId, 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.

Distribution Modes

Control how leads are distributed among recipients with the distributionMode field: full_copy (default, all leads to all recipients) or split_evenly (leads divided among recipients). When using split_evenly, use fullCopyRecipients for managers who need the complete list.

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, auto-refine optimization, 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 (up to 3 per list) and business profile. This is an asynchronous operation — keywords are generated as wildcard patterns and saved to your keyword lists with auto-refine enabled by default.

GET /api/v1/ai/keyword-status

Check the status of keyword generation jobs, including refinement progress.

GET /api/v1/ai/auto-refine/status

Get auto-refine status for all keyword lists or a specific list. Returns refinement progress, quality scores, and timing.

POST /api/v1/ai/auto-refine/enable

Enable AI auto-refine for a keyword list and start the optimization process. Requires listId.

POST /api/v1/ai/auto-refine/disable

Disable AI auto-refine for a keyword list. Pauses any in-progress refinement.

Category Suggestion Parameters

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

AI Auto Refine

The auto-refine system uses a single-pass, 4-phase process to optimize keyword lists. Phase 1 validates each positive keyword individually (50% applicability threshold). Phase 1B discovers up to 15 new positive keywords (5-added target). Phase 2 checks each negative keyword for collateral damage (40% threshold). Phase 2B discovers up to 5 new negative keywords from sampled results. High-volume keywords use multi-sample scoring (3×50 leads, median). A final quality score (1-10) is computed, with retry on low scores. Auto-refine turns off when complete. Each keyword list uses its sourceCategories (max 3 per list) for accurate AI scoring.

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

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. Start Free Trial