# 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](#introduction) | [Programmatic Purchase](#programmatic-purchase) | [Authentication](#authentication) | [Rate Limits](#rate-limits) | [User Profile](#user-profile) | [Leads](#leads) | [Filter Presets](#filter-presets) | [Keyword Lists](#keyword-lists) | [Email Schedules](#email-schedules) | [Export Formats](#export-formats) | [Export History](#export-history) | [Account Settings](#account-settings) | [AI Features](#ai-features) | [Export Blacklist](#export-blacklist) | [Error Handling](#error-handling) | [Credits & Subscription](#credits-subscription) | [MCP Server](#mcp-server) | [Integrations](#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 for users on any paid plan (**Starter**, **Growth**, **Scale**, **Platinum**, or **Enterprise**). [View plans](/#pricing) 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: 1. `PATCH /api/v1/me` \- Set your company name and website 2. `POST /api/v1/ai/suggest-categories` \- Get AI-powered category suggestions 3. `POST /api/v1/ai/generate-keywords` \- Generate targeting keywords 4. `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. `GET /api/v1/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 /api/v1/leads. ### 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. ### Schedule Object Fields Each schedule includes: id, name, filterPresetId, exportFormatId, intervalValue, intervalUnit, isActive, pauseReason (null, "user", or "insufficient\_credits"), recipients (array of objects with email and optional splitParts), distributionMode, fullCopyRecipients, maxLeadsPerEmail, lastSentAt, totalSentCount, createdAt. ### 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. ### Export Format Fields Each format includes: id, name, fileType, startRow, fieldMappings, isDefault, splitFiles, splitMode, maxRowsPerFile, numberOfParts, includeTotal, includeHeaders, databaseType, combinedAssigneeColumnName, combinedFileNameColumnName, createdAt. ### 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 an smbType field with value "home\_improvement" or "other". Incompatible email schedules are auto-paused. ### GET Response Fields currentDatabase (current database type), canSwitch (boolean), daysRemaining (days until switch allowed), lastSwitchedAt (ISO timestamp or null). ### Database Switching Notes Switching databases may pause email schedules that are incompatible with the new database type. The response includes a pausedSchedules count. --- ## 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 7.5¢/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 every 5 minutes. [Get Started](/?utm%5Fsource=content&utm%5Fmedium=cta)