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 | Programmatic Purchase | Authentication | Rate Limits | User Profile | Enrichments | Leads | Filter Presets | Keyword Lists | Email Schedules | Export Formats | Export History | Lead Export History | Account Settings | AI Features | Export Blacklist | Error Handling | Credits & Subscription | MCP Server | Integrations

Introduction

The SMB Sales Boost API provides RESTful access to our lead database, enrichments, export tools, filter management, AI features, credits and billing, and CRM and webhook integrations. The same API key also works with our MCP server. All API endpoints return JSON (file downloads aside) and, apart from the purchase endpoints, 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 checkout at the returned Stripe Checkout URL, (3) receive your API key by email at that address. The API never returns the key itself.

If that email already has an SMB Sales Boost account, the purchase must first be confirmed from the email sent to that address; the API key is emailed after that.

14-Day Free Trial

Starter, Growth and Scale start with a 14-day free trial by default. A payment method is required, nothing is charged until the trial ends, and the trial includes 50% of the plan's monthly credits; the plan price is then charged automatically unless the subscription is cancelled first. Send "trial": false to skip the trial and pay at checkout. Platinum and Enterprise never trial. One trial per person: the email is checked at purchase and the payment method after checkout. All charges are final; there are no refunds.

Step 1: Initiate Purchase

POST /api/v1/purchase

Create a new subscription purchase session. Returns { data: { checkoutUrl, expiresAt, plan, trial, message } }. The API key is not returned: it is emailed to the purchase address once checkout is complete. 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"), trial (optional, boolean, default true - only false skips the free trial and charges the plan price at checkout).

The trial object in the response reports eligible, days, credits, endsAt, note and, when there is no trial, a reason: not_requested, plan_not_eligible, trial_already_used or currently_subscribed.

Errors: 400 invalid_email or invalid_plan, 403 forbidden or disposable_email, 409 already_subscribed (also while that email is on a free trial; use change-plan instead), 410 plan_retired, 503 when payment processing is unavailable.

Step 2: Complete Checkout

Open the checkoutUrl in a browser to complete checkout on Stripe's hosted page. The session expires after 24 hours. After checkout, the system automatically provisions your account and generates an API key.

Step 3: Receive Your API Key by Email

Your API key (prefixed smbk_) is emailed to the purchase address once checkout is complete. Store it securely. If that address already has an SMB Sales Boost account, confirm the purchase from the email sent to that address first; the key follows.

POST /api/v1/claim-key is kept for backward compatibility only. It needs a claim token, which current purchases no longer issue, so wait for the emailed API key instead.

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

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

600 requests per minute per API key

Export Endpoints

5 requests per minute per API key

AI Endpoints

5 requests per minute per API key

Integration endpoints (/api/v1/integrations) also share one budget per account of 60 requests per minute, counted together with the dashboard's Integrations tab and every API key of the account (REST and MCP). Starting a CRM connection is also limited to 30 per minute per account.

The MCP endpoint (POST /mcp) accepts up to 60 requests per minute per client IP address. Each MCP tool call also counts against the limits of the REST endpoints it calls.

Rate Limit Headers

The X-RateLimit-* headers describe the most specific limit that applies to the request: the 5 per minute limit on export and AI endpoints, the per-account integration budget on integration endpoints (60 per minute, or 30 on CRM connect), and the 600 per minute limit on every other request made with an API key. On a rate-limit 429 (error Rate limit exceeded) they describe the limit that was hit. The 600 per minute limit still counts every request made with an API key. The purchase endpoints, which take no API key, have their own per-IP limits instead (see Programmatic Purchase).

429 Responses

A rate-limited request gets {"error": "Rate limit exceeded", "message": "...", "retryAfter": 42}, where retryAfter matches the Retry-After header. The lead search endpoints (GET /api/v1/leads, GET /api/v1/leads/preview, POST /api/v1/leads/export and the email schedule trigger) can also return 429 lead_query_capacity_busy with Retry-After: 10 when search capacity is busy. Both 429s carry the X-RateLimit-* headers, so tell them apart by the body's error field (Rate limit exceeded or lead_query_capacity_busy). Both are refused before anything is charged, so retry after the delay.

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 (always "other", the Main database), subscriptionPlan, subscriptionStatus, isSubscribed, freeLeadsUsed, onboardingCompleted, targetCategories, targetLocations, monthlyCredits, monthlyCreditsUsed, monthlyCreditsRemaining, permanentCredits, totalCreditsRemaining, and creditOverageRate.

Enrichments

Enrich a list of website URLs you already have. Each URL is checked against our database first; anything we do not already have is fetched live. We never add the URLs you submit, or the results we find for them, to our lead database, which we keep curated so it stays clean and focused on high-quality leads.

What each URL costs

1 credit

A URL in our database that you have not bought before, including its buying signals and category enrichments.

0.1 credit

A URL we do not have and fetch live for you.

0 credits

A URL you have already exported, one we got no data for, or one without the contact details you asked for.

A URL found in our database is never fetched live, so lowering databaseMatchPercent cannot be used to buy database records at the live price.

Starting a run

POST /api/v1/enrichments with { "urls": [...] }, up to 100,000 URLs after deduplication by host. Send the full URL including any path - a deep link often carries better contact data than the root.

maxCredits

Most credits this run may spend. Omit to allow your whole available balance, which is the default.

databaseMatchPercent

0-100, default 100. Caps what share of maxCredits may go to NEW database matches. Unused database budget flows to live fetching, never the reverse. Records you have already paid for are always returned free and are not affected by this.

contactTypes

phone, email or either: the minimum contact details a result must carry to be delivered and charged. phone returns every result with a phone number, including those that also have an email; email returns every result with an email, including those that also have a phone number. Default either, meaning a phone number OR an email - the widest setting, not the most restrictive.

emailResults

Email you a download link when the file is ready. Defaults to your account setting. The file is always downloadable, so there is no flag to disable the download.

Runs are asynchronous

Submitting returns a run id immediately and a large list can take hours. Poll GET /api/v1/enrichments/:id until status is completed or partial, then call GET /api/v1/enrichments/:id/download for a short-lived presigned URL.

Credits are charged in two stages - database matches when they are matched, live results when the file is published - so credits.final tells you whether the total is settled.

Every URL is accounted for

The file has one row per URL you submitted, each with a status column. Only the first two cost anything.

matched_paid

In our database, new to you. 1 credit.

scraped

Fetched live. 0.1 credit.

matched_free

In our database, you already bought it. Free.

scrape_failed

No data came back for it - unreachable, or nothing usable found. Free.

skipped_db_budget

A database match outside your credit limit. Free.

skipped_scrape_budget

A live result outside your credit limit. Free.

matched_no_contact

Matched, but without the contact type you asked for. Free.

scraped_no_contact

Fetched, but without the contact type you asked for. Free.

skipped_invalid

Not a usable URL. Free.

Leads

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

Lead Database

Every lead comes from the Main database (API value other), which covers small and medium businesses of all types. Contact info includes both phone numbers and email addresses. The database parameter is optional. Every value is accepted and resolves to the Main database, so existing integrations keep working unchanged.

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.

Default OR group columns

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

Leads in the Main 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.).

GET /api/v1/leads/preview

Preview leads with masked contact info (masked, not hashed: for example (512) ***-**42 and hel*@domain.com). Accepts the same filters as GET /api/v1/leads, including the contact term filters (emailPrimaryInclude, phonePrimaryInclude and the rest) and the company-column include, exclude and empty filters. Does not consume credits. Leads you already purchased come back unmasked (contactExported: true); pass excludePurchased=true to return only not-yet-purchased leads.

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. Pass excludePurchased=true to export only not-yet-purchased leads. Each file's data is plain UTF-8 text for csv and json files and base64 for xlsx files. Pass inline=false (body field or ?inline=false) to omit each file's body and receive a per-file exportId plus downloadUrl instead - the recommended shape for large exports. XLSX is capped at 20,000 rows per file; for larger runs use a csv export format, or an xlsx format with splitFiles true, splitMode max_rows, maxRowsPerFile of 20,000 or less and includeTotal false. Any xlsx export that would put more than 20,000 rows in one file (a single file, a split part, or the includeTotal file, which holds every lead) returns 400 export_too_large after the leads are charged and recorded as received. Do not simply repeat it: an export picks new leads first, so a repeat can charge for different leads. Re-run it with maxCredits 0 (and without excludePurchased) and a fixed format, which returns the leads you already have at no cost, or re-export them with POST /api/v1/lead-export-history/re-export.

GET /api/v1/leads/other/schema-types

Returns a sorted list of all distinct website schema types found in the Main 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, streetInclude, streetExclude, minNumLocations, maxNumLocations, minRatingValue, maxRatingValue, minReviewCount, maxReviewCount (numeric ranges), buyingSignalTypeFilter, lastBuyingSignalFrom, lastBuyingSignalTo, sortBy, sortOrder, page, limit, database, and various column-specific include/exclude terms. Empty/non-empty filters per column are also supported via streetEmptyFilter, cityEmptyFilter, stateEmptyFilter, zipEmptyFilter plus phonePrimaryEmptyFilter, phoneTotalEmptyFilter, emailPrimaryEmptyFilter, emailTier1EmptyFilter through emailTier6EmptyFilter, descriptionEmptyFilter, and the new firmographic and technology columns such as employeeCountEmptyFilter, foundingDateEmptyFilter, isChainEmptyFilter, priceRangeEmptyFilter, legalNameEmptyFilter, industryNaicsEmptyFilter, dunsEmptyFilter, founderEmptyFilter, founderEmailEmptyFilter, founderPhoneEmptyFilter, openingHoursEmptyFilter, areaServedEmptyFilter, offersEmptyFilter, brandEmptyFilter, sloganEmptyFilter, logoUrlEmptyFilter, socialProfilesEmptyFilter, platformEmptyFilter, bookingOpsCrmSoftwareEmptyFilter, reputationChatSoftwareEmptyFilter, marketingEmailSoftwareEmptyFilter, adPixelsEmptyFilter, paymentFinancingSoftwareEmptyFilter, emailPrimaryMxEmptyFilter, emailDomainMxEmptyFilter, emailSecurityEmptyFilter, addressSourceEmptyFilter. The firmographic and technology columns from employeeCount through paymentFinancingSoftware also support include/exclude term filters (e.g. employeeCountInclude/employeeCountExclude, founderEmailInclude/founderEmailExclude); founder email and phone values stay masked until a lead is unlocked or exported. The Email Primary Provider, Website Email Provider, Website Email Security, and Address Source columns have no include/exclude terms; they use exact-value multi-choice matching via emailPrimaryMxValues, emailDomainMxValues, emailSecurityValues, and addressSourceValues - each a JSON array of exact values matched with IN semantics. Number of Job Postings uses minOpenPositions/maxOpenPositions, and the short description uses descriptionIncludeTerms/descriptionExcludeTerms. Each empty filter accepts 'any' | 'only_empty' | 'exclude_empty'.

Buying Signal Type Filtering

Every lead carries a Buying Signal Type list describing why its Last Buying Signal timestamp last changed. Filter on it with buyingSignalTypeFilter (comma-separated values). Values: Newly Added, Phone Primary, Total Phones, Email Primary, Tier 1 Emails, Tier 2 Emails, Address Full, plus per-source social profile signals - Instagram, LinkedIn, Facebook, YouTube, TikTok, X (Twitter), Google Maps, Yelp, Pinterest, and Other Social - recorded when a social profile for that source is added or changed for a business. Social profile changes also bump the lead's Last Buying Signal timestamp, so recently-active businesses surface under lastBuyingSignalFrom / lastBuyingSignalTo date filters. Last Buying Signal is also the default sort (sortBy=lastBuyingSignal).

The former names updateReasonFilter, lastUpdatedFrom, lastUpdatedTo and sortBy=lastUpdated are still accepted (ignored when the new name is also sent), and lead responses still include a deprecated Last Updated key with the same value as Last Buying Signal. Default-format export files (POST /api/v1/leads/export, Export History downloads, email schedule attachments) name these columns Last Buying Signal and Buying Signal Type in their CSV/XLSX headers and JSON keys; they no longer have Last Updated / Update Reason columns. To keep the old header names, export with a custom export format (formatId) that maps lastUpdated and lastUpdatedReason to the names you need.

Credit-Optimized Export Parameters

The export endpoint supports additional parameters for controlling credit usage:

maxLeads

Cap total leads exported. Leads over the cap, and new leads cut because credits ran short, are counted in the response's overflowCount and kept in the lead reservoir while it has room (one pool per account, shared with your email schedules, up to your plan's monthly credit allowance; leads that do not fit are not kept), then added to your next export that also sets maxLeads.

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. The export is also capped at your spendable balance, so the effective cap is the smaller of the two. Set to 0 to only receive previously-exported leads at no credit cost.

excludePurchased

When true, export only leads you have not purchased yet (already-exported leads, matched by lead id or shared contact point, are skipped). Credit and dedup math are unchanged. Default false.

On credit plans, GET /api/v1/leads and POST /api/v1/leads/export always return leads in credit-optimized order: new leads (credit-consuming) sorted first, then previously-exported leads, each group sorted by Last Buying Signal descending (or your custom sort). New leads are cut to the smaller of maxCredits and your spendable balance (credit balance plus any overage-budget headroom); when the balance was the limit the response has the X-Credits-Capped: true header, so omitting maxCredits caps the request at your balance instead of failing. 402 insufficient_credits only happens if a concurrent request spends the balance between the check and the charge.

What Costs a Credit

Each new lead returned by GET /api/v1/leads or POST /api/v1/leads/export costs 1 credit. Charging is sticky: a lead you have already received through any channel (dashboard, API, MCP or email schedule) is never charged again, even if its data changed later, and a new lead that shares a primary phone or primary email with a lead you already received is also free.

Purchased-Lead Reveal on Preview

The preview endpoint reveals leads you have already purchased: any preview lead that matches a prior export (by lead id or by a shared phone or email contact point) is returned unmasked with contactExported: true, the same as on the dashboard. Leads you have not bought stay masked. Pass excludePurchased=true on preview to return only not-yet-purchased leads. A shared contact point here includes the lead's Total Phones and Email Tier values, while charging compares primary phone and primary email only, so a lead revealed only through one of those lists can still cost a credit.

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 (trimmed, 1-255 characters), type (positive/negative) and keywords (a non-empty array of strings); sourceCategories is optional (an array of strings, or null). Any other field is ignored, and invalid input returns 400 validation_error.

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, intervalValue (a whole number from 1 to 720), intervalUnit and recipients. isActive defaults to true: an active schedule sends its first email within about 15 minutes; send false to create it paused.

PATCH /api/v1/email-schedules/:id

Update an existing email schedule. All fields are optional; intervalValue must be a whole number from 1 to 720.

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, lastSent, totalSentCount, createdAt.

Max Leads Per Email

maxLeadsPerEmail (optional, 1-100,000, null for no cap) limits how many leads one email carries. New leads that do not fit, and new leads your credits could not cover, are kept in the lead reservoir (one pool per account, shared by your schedules and API exports, up to your plan's monthly credit allowance; when it is full, more leads are not kept) and sent with a later email. On credit plans, leads you already received that do not fit are not kept. Schedules pause only when no credits are left to spend.

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 (always "other", the Main database), 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)

XLSX files hold at most 20,000 rows each. An export that would put more than 20,000 rows in one xlsx file (a single file, a split part, or the includeTotal file, which holds every lead) returns 400 export_too_large, so an xlsx format for large exports needs splitFiles true, splitMode max_rows, maxRowsPerFile of 20,000 or less and includeTotal false.

Export History

View your past exports with details including date, row count, filters used, and export format. Each export file is kept for 90 days and can be downloaded again at any time in that window. After that, re-export the leads from your lead-level export history at no credit cost.

Endpoints

GET /api/v1/export-history

List your export history with file details including fileName, fileType, leadCount, fileSize, formatName, databaseType, createdAt, expiresAt (when the file stops being downloadable), downloadAvailable, and unavailableReason.

GET /api/v1/export-history/:id/download

Download a previously exported file by its history ID. Returns the raw file. Files can be downloaded for 90 days after the export; an expired or unavailable file returns 410.

GET /api/v1/export-history/:id/download-url

Get a short-lived direct download link for the file (valid for 15 minutes). Fetch the link without an Authorization header.

Lead Export History

Lead Export History has one entry per lead you have received, through any channel, with a snapshot of the lead's data from its most recent export or refresh. Refreshing and re-exporting these leads is always free: no credits are charged for leads you already received, even if their data has changed since.

Sticky export rule: once a lead is in your export history, it is free to re-export or refresh at any time. Credits are charged only for leads that are new to you (see Credits & Subscription).

Endpoints

GET /api/v1/lead-export-history

List your entries, newest export first, with pagination and optional filters. Each entry is one lead, with the time and channel of its most recent export and its stored snapshot (fields below). An invalid limit, offset or date returns 400.

GET /api/v1/lead-export-history/ids

Every tracking id matching the filters (databaseType, dateFrom, dateTo, exportMethod), newest first, with no pagination: {"data": [1001, 1002], "totalCount": 2}. Use it to select entries for a bulk refresh or re-export.

POST /api/v1/lead-export-history/refresh

Replace the stored snapshots with the latest live data. No credits charged. Send trackingIds or a filters object (databaseType, dateFrom, dateTo, exportMethod) to refresh every matching entry, at most 5,000 entries per request (a filters object that matches more than 5,000 entries, or none, returns 400). An invalid filters value also returns 400 bad_request: a dateFrom or dateTo that is not a valid date with a year from 1 to 9999 (for example 'filters.dateFrom must be a valid date (e.g. 2026-08-18)'), or a databaseType or exportMethod that is not a string. When a trackingIds array is sent, the filters are ignored and not checked. Returns {"data": {"results": [...], "refreshed": 2}}. In each result, changed says whether the lead was updated since its snapshot (by its last-updated date), changedFields lists the changed fields (kept until a refresh-and-export clears them), and refreshed is false for an id that is not in your history or a lead that is no longer in the database. A refresh that finds newer data for a lead sends lead.updated to your integrations, unless the lead is on your export blacklist.

POST /api/v1/lead-export-history/re-export

Download the selected entries again as one file built from their stored snapshots (live data only for an entry that has no snapshot; nothing is refreshed). No credits charged. trackingIds is required (up to 5,000); formatId is optional (one of your export formats; omitted or not found means a CSV with the default columns). Returns the file itself, not a JSON envelope.

POST /api/v1/lead-export-history/refresh-and-export

Refresh the snapshots with live data, clear their changed-field markers, then download them as one file. No credits charged. Send trackingIds or a filters object (at most 5,000 entries, with the same 400 for an invalid filters value, as for refresh), plus an optional formatId (as for re-export). Everything is checked before any entry changes: a 400 or 404 response leaves the entries unchanged (snapshots, leadLastUpdated and lastChangedFields). Like refresh, it sends lead.updated to your integrations for each lead it finds newer data for, unless the lead is on your export blacklist. Returns a file like re-export; its name starts with refreshed-export-.

List Parameters

Example Response

{
  "data": [
    {
      "id": 1001,
      "userId": "usr_abc123",
      "leadId": 42,
      "databaseType": "other",
      "exportedAt": "2026-05-01T10:00:00.000Z",
      "leadLastUpdated": "2026-04-28T08:00:00.000Z",
      "exportMethod": "crm_push",
      "leadSnapshot": {
        "wCompanyName": "Acme Roofing",
        "wPhonePrimary": "(555) 123-4567",
        "wEmailPrimary": "[email protected]"
      },
      "lastChangedFields": null,
      "lead": {
        "wCompanyName": "Acme Roofing",
        "wPhonePrimary": "(555) 123-4567",
        "wEmailPrimary": "[email protected]"
      }
    }
  ],
  "totalCount": 245,
  "limit": 50,
  "offset": 0
}

Entry Fields

• id - the tracking id that the ids, refresh, re-export and refresh-and-export endpoints use
• userId, leadId, databaseType - your account, the lead and its database
• exportedAt, exportMethod - when and through which channel the lead was most recently exported
• leadLastUpdated - the lead's last-updated date as of the snapshot (refresh compares it to spot changes)
• leadSnapshot - the lead's data as stored at its most recent export or refresh (can be null on older entries); it uses the database field names (for example wCompanyName), not the names GET /api/v1/leads returns, and is shortened in the example
• lead - the snapshot, or the live lead data when no snapshot is stored (null if neither exists)
• lastChangedFields - the lead fields a refresh found changed, or null

Notes

• One entry per lead: a later export of the same lead (including an integration push) updates its exportedAt, exportMethod and snapshot instead of adding an entry.
• Re-export and refresh-and-export return 404 when none of the ids match an entry with lead data, and 400 when some selected entries come from an older export that cannot be combined with the rest (export those separately).
• Re-export sends nothing to your integrations. Refresh and refresh-and-export send one lead.updated for each lead they find newer data for, to your integrations subscribed to it, unless the lead is on your export blacklist (see Integrations).
• The three POST endpoints count against the export rate limit (5 per minute per API key; see Rate Limits).

Account Settings

Every account uses the Main database (API value other). The database settings endpoint is kept for backward compatibility with existing integrations.

Endpoints

GET /api/v1/settings/database

Get the lead database your account uses. currentDatabase is always "other" (the Main database).

Response Fields

currentDatabase (always "other"), canSwitch (boolean), daysRemaining (number), lastSwitchedAt (ISO timestamp or null).

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, excludeCategories. Suggestions are drawn from the Main database's categories.

Export Blacklist

Manage your export blacklist to keep specific domains out of your exports and out of integration pushes: pushing a blacklisted database lead (POST /api/v1/integrations/:id/push-lead with a leadId, or the MCP tool push_lead_to_integration) returns 400 before anything is charged or sent, and a Lead Export History refresh sends no lead.updated for a blacklisted lead. Your own data pushed with {"lead": {...}} is not checked. Add and remove entries to prevent duplicate outreach.

Endpoints

GET /api/v1/export-blacklist

List all your blacklist entries with entryType (domain), 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)

Error Handling

All errors follow a consistent format with an error code and a human-readable message. Validation errors (400 validation_error, or 400 invalid_request from POST /api/v1/enrichments) can also include a details array with one entry per problem, each with a path (the field, as an array of keys such as ["status"]) and a message.

Error Response Format

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

HTTP Status Codes

Credits & Subscription

All paid plans (Starter, Growth, Scale, Platinum, and Enterprise) use a credit-based system where each new lead queried or exported costs 1 credit. Charging is sticky: a lead you have already received through any channel (dashboard, API, MCP or email schedule) is never charged again, even if its data changed later, and a new lead that shares a primary phone or primary email with a lead you already received is also free. Lead searches and exports are always capped at your spendable balance (credit balance plus any overage-budget headroom) instead of failing, with the X-Credits-Capped: true header when the balance was the limit; for them, 402 insufficient_credits only happens if a concurrent request spends the balance between the check and the charge. Pushing a database lead to an integration (POST /api/v1/integrations/:id/push-lead with a leadId, or the MCP tool push_lead_to_integration) is not capped; the same sticky rules apply. A lead you already received is free, even at a 0 balance. A new lead costs 1 credit, taken from your balance or, when the balance is 0 and your overage budget is enabled with room left, billed as overage; if neither can cover it, the push returns 402 insufficient_credits and nothing is pushed. A pushed lead counts as received (exportMethod crm_push in Lead Export History), so it is never charged again. On all plans, unused credits roll over each billing cycle and never expire while your subscription is active - but the remaining balance is forfeited when your subscription ends, and expires when a plan downgrade takes effect at renewal. Use these endpoints to purchase additional 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 credits using your saved payment method (charged off-session via Stripe). Purchased credits roll over month to month while your subscription is active, but the remaining balance is forfeited when your subscription ends and expires when a plan downgrade takes effect at renewal. Minimum 100 credits. Pricing: Starter 10¢/credit, Growth 7.5¢/credit, Scale 5¢/credit, Platinum 3¢/credit, Enterprise 2¢/credit. Available on all paid plans.

GET /api/v1/overage-budget

Get your overage budget configuration and usage: an opt-in spending limit that lets lead usage continue past a zero credit balance. Extra credits accrue at your plan's overage rate and are charged to your card on file once per day. The budget applies per billing cycle and resets at renewal.

PATCH /api/v1/overage-budget

Enable, disable, or edit the overage budget. budgetType is 'dollars' (default) or 'credits'; budgetAmount is a whole number of dollars or credits per billing cycle (max 5x your plan's monthly credit allocation, or its dollar equivalent). Requires an active credit plan and a payment method on file. Disabling clears the config; accrued unbilled overage is still collected by the daily billing runs once it reaches Stripe's $0.50 minimum (smaller remaining balances are written off).

POST /api/v1/subscription/cancel

Cancel your subscription at the end of the current billing period. Your access continues until the period ends. Any remaining credit balance is forfeited when the subscription ends.

Purchase Credits Parameters

creditCount (integer, minimum 100) or dollarAmount (number, minimum 1) - send one, not both. idempotencyKey (optional, 8-64 letters, digits, _ or -; also accepted as the Idempotency-Key header) - reuse it when retrying the same purchase so the card is not charged twice.

MCP Server

SMB Sales Boost provides a remote Model Context Protocol (MCP) server that lets AI assistants and LLMs interact with your account directly. The REST API endpoints are available as MCP tools (pushing your own lead data to an integration is REST only), enabling AI-powered lead search, export, account management and integration workflows such as connecting a CRM (when available), creating webhooks and sending leads to them.

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, and to send them to your CRM or webhooks, 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 (71)

The AI assistant can call these tools on your behalf using natural language. 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, ai_suggest_categories, ai_generate_keywords, list_export_blacklist, purchase_credits, get_auto_top_up, update_auto_top_up, get_overage_budget, update_overage_budget, and more.

Integration tools (17):

• list_integration_providers - List integration providers (CRMs and webhook tools) and whether each is available
• list_integrations - List your integrations with their events and who created or last changed them
• get_integration - Get one integration
• create_webhook_integration - Create a webhook (Zapier, n8n, Make, Pipedream, Clay or any public HTTPS URL) that receives the events you subscribe it to; returns a signing secret once and emails the account owner
• update_integration - Rename, pause or re-enable an integration, or change its event subscriptions (the list you send replaces the current one), destination URLs, header API key or Pipedrive deal settings; a HubSpot, Salesforce or Pipedrive integration takes only lead.created and lead.updated. Re-enabling it, adding or re-activating an event, or changing where data goes emails the account owner
• delete_integration - Permanently delete an integration with its subscriptions and delivery history; nothing new is sent to it. Records already sent stay in the destination, and CRM access is not revoked inside the CRM. To stop sending without deleting, pause it with update_integration
• list_integration_deliveries - List the 50 newest deliveries of an integration
• retry_integration_delivery - Send a past delivery again, once, as a new event to the URL it first went to (or to the connected CRM); no credits charged. A paused integration returns 400; a success on a needs_attention integration turns it back on and emails the account owner
• test_integration - Send one test lead.created event (a sample lead for Acme Test Co) to the real destination; on a CRM this creates real records that are not removed. No credits charged. A paused integration returns 400; a success on a needs_attention integration turns it back on and emails the account owner
• push_lead_to_integration - Push one database lead (by leadId) to a connected integration now: free if you already received it or a lead with the same primary phone or primary email, otherwise 1 credit, or overage when your balance is 0 and your overage budget has room (402 insufficient_credits if neither can pay). Pushing your own lead data is REST only
• connect_crm - Get a HubSpot, Salesforce or Pipedrive authorization URL for the account owner to open in a browser and approve within 10 minutes; once approved, a new connection sends new leads to that CRM automatically and the account owner is emailed. Approving a CRM account that is already connected re-authorizes that integration in place, keeping its events, field mapping and delivery history
• get_integration_field_mapping - Get a CRM's field list and the current field mapping
• update_integration_field_mapping - Choose which CRM field receives each lead field (replaces the saved mapping as a whole)
• reset_integration_field_mapping - Reset a CRM field mapping to the defaults
• test_integration_field_mapping - Dry-run a field mapping (creates, then deletes, synthetic CRM records)
• list_pipedrive_pipelines - List Pipedrive pipelines and stages for deal creation
• list_pipedrive_deal_fields - List Pipedrive deal fields and the current deal field map

With the 17 integration tools (list_integration_providers through list_pipedrive_deal_fields), the assistant can send lead data (business contact details) to outside systems, so it should confirm the destination with you first. When an API key or MCP client creates a webhook, connects a new CRM account, changes where an integration sends data, adds or re-activates an event, or re-enables an integration (including a successful test or retry, or a reconnect, that turns a needs_attention integration back on), the account owner is emailed for each change. Each account gets up to 10 of these emails an hour for destination changes and 10 for other changes; past that, one alert is sent and further changes are combined into summary emails. Changes made through MCP are labeled with the channel and the API key used, for example "Created via MCP with API key smbk_AbCdEfG..." in the Integrations tab. See Integrations for the endpoints, events and error codes.

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. The MCP endpoint accepts up to 60 requests per minute per client IP address, and each tool call also counts against the rate limits of the REST endpoints it calls. Usage tracking works the same as for the REST API.

Errors

Most tools report a failed call as the API's message followed by the HTTP status and error code, for example (HTTP 409, integration_exists) or (HTTP 402, insufficient_credits), plus up to 5 validation details, so the error codes under Error Handling and Integrations apply to MCP too. When the API sends no error code, only the status is shown (a rate-limited call ends in (HTTP 429)). The purchase, claim_key, start_enrichment, re_export_lead_export_history and refresh_and_export_lead_export_history tools return the API's message only.

Integrations

SMB Sales Boost can send lead data to your CRM, automation tools, and any HTTPS endpoint. Set up destinations from the Integrations tab in your dashboard, or with the endpoints below, which are also available as MCP tools (pushing your own lead data is REST only; see MCP Server). They live under /api/v1/integrations, use the same API key (Authorization: Bearer smbk_...), paid-plan requirement and rate limits as the rest of the API, and return the usual {"data": ...} and {"error", "message"} shapes. A 400 validation_error can also include a details array (see Error Handling).

Safeguards

An integration sends business contact details to an outside system automatically, on every subscribed event, until it is paused or deleted. So that nothing changes unnoticed:

• When an API key or MCP client creates a webhook, connects a new CRM account, changes where an integration sends data, adds or re-activates an event, or re-enables an integration (including a successful test or retry, or a reconnect, that turns a needs_attention integration back on), the account owner is emailed for each change. Each account gets up to 10 of these emails an hour for destination changes and 10 for other changes; past that, one alert is sent and further changes are combined into summary emails.
• The dashboard shows which API key created or last changed each integration, for example "Created via API key smbk_AbCdEfG..." or, when the change came through the MCP server, "Created via MCP with API key smbk_AbCdEfG...". A change in the dashboard replaces that record only when it adds a destination URL the integration never had. Pausing an integration (also when you revoke its key), and resuming it, switching on more events or switching on a URL it already had in the dashboard, keep it.
• When you revoke an API key in Dashboard > API, you can also pause every integration that key created or last changed (off by default). Paused integrations can be re-enabled in the Integrations tab or with PATCH /api/v1/integrations/:id and {"status": "connected"}. A CRM connect link created with a key that is later revoked stops working: nothing is connected or changed.
• The webhook signing secret is returned only once, when the webhook is created.
• A header API key stored on a webhook (sent as X-SMB-API-Key) is only sent to the active destination URLs it was set for: it is bound to them when it is set, and editing the integration in the dashboard binds it again to the integration's active destinations on the same origin. A URL on a switched-off subscription is never bound, so switching that subscription on later does not send the key there until the owner edits the integration in the dashboard or apiKey is sent again. Pointing such a webhook at a new destination URL with an API key requires apiKey in the same request (a new value, or null to stop sending it), even when the new URL is on the same host: services like Zapier, Make and Clay put every customer's hooks on one host.

Supported providers

HubSpot (hubspot)

Per-user OAuth. Creates or updates Contacts matched by email (a lead without an email creates no Contact) and Companies matched by website domain, or by exact company name when the lead has no website of its own (none, or a social or listing page such as Facebook or Yelp), and links each Contact to its Company (available when configured)

Salesforce (salesforce)

Per-user OAuth, Production or Sandbox. Creates or updates Leads matched by Email; a lead without an email creates a new Lead each time, and Company defaults to "Unknown" when the lead has no company name (available when configured)

Pipedrive (pipedrive)

Per-user OAuth; per-company API domain handled automatically. Matches Organizations by exact name and Persons by the SMB Sales Boost lead id, then by email; adds a note with the lead id on each delivery of a lead; optional Deals, see Rules worth knowing (available when configured)

Zapier (zapier)

Webhook trigger URL with HMAC signature (Live)

n8n (n8n)

Webhook node with HMAC signature (Live)

Make.com (make)

Custom webhook trigger with HMAC signature (Live)

Pipedream (pipedream)

HTTP source workflow with HMAC signature (Live)

Clay (clay)

Clay table "Import data" webhook with HMAC-signed JSON rows (Live)

Generic Webhook (generic_webhook)

Any HTTPS endpoint, signed JSON payload (Live)

HubSpot, Salesforce and Pipedrive are available when they are configured for this deployment; otherwise connecting them, or using an already connected one, returns 503 provider_unavailable. GET /api/v1/integrations/providers shows the current availability of every provider.

Events

Subscribe destinations to one or more of these events. A webhook receives each event as a signed JSON POST (see Delivery format below).

• lead.created - one event per lead, the first time a lead reaches your account (dashboard or API export, API search, email schedule, lead reservoir or push), with that lead's business contact details. Leads you get through a URL enrichment run send no lead.created or lead.updated; the next time such a lead reaches your account it sends lead.updated.
• lead.updated - one event per lead when a lead you already received reaches your account again with a newer Last Buying Signal than when you last received it (an export or email schedule that includes it, a push to another integration, or a GET /api/v1/leads page or MCP search_leads call that returns it), or when a Lead Export History refresh finds that newer data. Receiving an unchanged lead again sends nothing. The push target itself receives the push as lead.created (see Push one lead), a refresh sends nothing for a lead on your export blacklist, and GET /api/v1/leads/preview and re-exports from Lead Export History that do not refresh send nothing. Pipedrive integrations subscribe to it by default (HubSpot has it off).
• export.completed - a lead reservoir export finished. data: count, databaseType, source and sampleLeads (up to 5 leads, each with id, companyName, website, email, phone, city and state).
• email_schedule.sent - a scheduled lead email was sent. data: scheduleId, scheduleName, leadCount, creditableLeadCount and sampleLeads (up to 5 leads, each with id, companyName, website, email, phone, city and state).
• credit.low_balance - sent after each credit charge while your total remaining credits (monthly, permanent and temporary) are at or below the larger of 50 and 10% of your monthly credit allowance, so it can arrive many times; accounts without a monthly allowance never get it. data: remainingMonthly, remainingPermanent, remainingTemporary, remainingTotal, monthlyAllowance, threshold.

HubSpot, Salesforce and Pipedrive integrations take only lead.created and lead.updated; a subscription to any other event returns 400 validation_error.

Delivery format

Each webhook delivery is an HTTPS POST with these headers:

The body is an envelope; data depends on the event (shortened here):

{
  "id": "evt_1760000000000_k3j9qz",
  "type": "lead.created",
  "occurredAt": "2026-10-08T12:00:00.000Z",
  "userId": "your-user-id",
  "integrationId": 42,
  "provider": "zapier",
  "data": {
    "id": 123456,
    "databaseType": "other",
    "source": "api",
    "companyName": "Acme Plumbing",
    "website": "https://acmeplumbing.example",
    "email": "[email protected]",
    "phone": "(512) 555-0100",
    "city": "Austin",
    "state": "TX",
    "lastBuyingSignal": "2026-10-01T00:00:00.000Z",
    "buyingSignalType": ["Newly Added"]
  }
}

A receiver that handles pushes and tests must read three lead.created shapes: the flat lead summary (live events and leadId pushes), your own data from a push, and the test event.

• Answer with a 2xx status within 8 seconds. Anything else is a failed attempt: a 3xx (redirects are not followed), a 4xx, a 5xx, a timeout or a connection error.
• A live webhook event is tried up to 5 times, waiting about 1, 2, 4 and 8 seconds (plus up to 1 second) between attempts. Every attempt sends the same body and id with a new X-SMB-Timestamp and signature, so use id to ignore duplicates. The delivery appears in GET /api/v1/integrations/:id/deliveries once its last attempt has finished.
• Tests, pushes, manual retries and deliveries to HubSpot, Salesforce and Pipedrive are one attempt each. A test's id starts with evt_test_; a manual retry sends a new id (evt_retry_...) with occurredAt set to the time of the retry.
• Each lead is its own request, and webhook requests are sent in parallel: a large export can send many at once, and events arrive in no particular order. Deliveries to HubSpot, Salesforce and Pipedrive are sent at most 3 at a time per integration, and HubSpot calls are paced to HubSpot's rate limits, so a large export reaches the CRM gradually. Pausing a CRM integration, or switching an event off, also stops the lead deliveries still waiting to be sent to it.

Verifying signatures

X-SMB-Signature is t=<Unix seconds>,v1=<hex>. t is the same value as X-SMB-Timestamp, and v1 is the hex HMAC-SHA256 of "<t>." + rawBody, keyed with your signing secret exactly as it was returned (use the string as is; do not hex-decode it). Check it against the raw request body before you parse the JSON, compare using a timing-safe comparison after checking that the lengths match, and reject a t older than 5 minutes (every attempt is signed with a fresh t).

// Node.js (Express): verify an SMB Sales Boost webhook before using it
const crypto = require("crypto");
const express = require("express");

const app = express();
const SIGNING_SECRET = process.env.SMB_SIGNING_SECRET; // exactly as returned on create
const MAX_AGE_SECONDS = 5 * 60;

// Mount this route before app.use(express.json()), which would consume the raw body.
app.post("/smb-webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!Buffer.isBuffer(req.body)) return res.status(400).send("Expected a JSON body");

  // X-SMB-Signature: t=<Unix seconds>,v1=<hex>
  const parts = {};
  for (const item of (req.get("X-SMB-Signature") || "").split(",")) {
    const i = item.indexOf("=");
    if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
  }
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return res.status(400).send("Missing signature");
  if (Math.abs(Date.now() / 1000 - t) > MAX_AGE_SECONDS) return res.status(400).send("Stale timestamp");

  // HMAC-SHA256 of "<t>." followed by the raw body bytes, keyed with the secret string
  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(parts.t + ".")
    .update(req.body)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send("Bad signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200); // answer within 8 seconds; do slow work afterwards
  console.log(event.type, event.id); // use event.id to skip duplicates
});

app.listen(3000);

Endpoints

Errors: 400 validation_error or bad_request, 402 insufficient_credits (push-lead), 404 not_found, 409 integration_exists (create, or a PATCH that re-points to a destination another integration of the same provider already uses) or integration_limit (at most 25 integrations per account; also on connect, see Connect a CRM), 409 conflict (PATCH only: when the integration changes while the update is being applied, for example the owner pauses it at the same moment, the update is applied again on top of that change; only when it changes again does the PATCH return 409, nothing changed, so read it again and retry. If the API key making the PATCH is revoked in that moment, it returns 401 unauthorized "This API key has been revoked" and nothing is applied), 429 (all integration endpoints share one budget per account of 60 requests per minute, counted together with the dashboard; connect is also limited to 30 per minute), 502 provider_error (the CRM's API failed) and 503 provider_unavailable. A 503 provider_unavailable is not temporary (no Retry-After; do not retry): it means the CRM is not configured for this deployment. It can come from the field-mapping, Pipedrive pipeline and deal-field endpoints, test, retry, push-lead and connect. An unknown provider in the connect path is a 404. A 500 internal_error on create, PATCH or push-lead may come after the change was saved (or a credit was taken), so check GET /api/v1/integrations and the deliveries before repeating it; a 503 service_unavailable only happens before anything is written.

Responses

Every success is wrapped in {"data": ...}. Test, retry and push answer HTTP 200 even when the destination fails; read data.status. When a webhook test or push gets a non-2xx answer, data.error holds the first 500 characters of your endpoint's response (HTTP <status> when it sent no body). Paths starting with .../ are under /api/v1/integrations/:id/.

Rules worth knowing

• subscriptions on PATCH replaces the integration's whole subscription set, so send the complete list you want (at most 20 items). Each item is {"eventType": "lead.created", "targetUrl": "https://...", "isActive": true, "config": {...}}: only eventType is required, isActive defaults to true and config to null. An event you leave out is removed and stops being sent, an empty list removes them all, and of two items with the same event and URL only the first is kept. Subscription ids change whenever subscriptions or defaultTargetUrl is sent. To add or switch on one event, read the integration first (GET /api/v1/integrations/:id) and send back every subscription you want to keep, with isActive: false on the ones that should stay off. For example, to switch on HubSpot lead.updated, send {"subscriptions": [{"eventType": "lead.created"}, {"eventType": "lead.updated"}]}. On a HubSpot, Salesforce or Pipedrive integration, an item with any other event returns 400 validation_error and nothing is saved (see Events).
• defaultTargetUrl is for webhook integrations only (400 on a CRM). Sent without subscriptions, it re-points every existing subscription, inactive ones too. Sent with subscriptions, it fills in each subscription that has no targetUrl. A subscription with neither keeps that event's current URL, or takes the integration's first URL for a new event.
• status on PATCH takes connected or disabled. disabled pauses all sending; connected re-enables a disabled or needs_attention integration and resets its failure count. needs_attention is set only by SMB Sales Boost, after 5 failed deliveries in a row. One failed delivery is, for example, a live webhook event whose 5 attempts all failed, a failed CRM write, a failed push, a retry that could not reach the destination, or a test the destination rejected. A successful live delivery, test, retry or push resets the count, and a disabled integration never changes to needs_attention. Sending needs_attention returns 400 (unless the integration already has that status). Events that happen while an integration is disabled or needs_attention are not queued and are never sent later. GET /api/v1/integrations/:id shows consecutiveFailures, lastFailureAt and lastSuccessAt.
• Live events never use an inactive subscription, and webhook tests and pushes do not either: they use the active subscription for the event, else any active subscription with a URL; with none they fail with "No active subscription for this integration" (a CRM test or push goes to the connected CRM). A new URL counts as a destination change (owner email) even on an inactive subscription, and so does switching on a subscription whose URL was not active before.
• apiKey on PATCH applies only to Clay integrations and to webhook integrations that already send a header API key (400 otherwise, and on a CRM). A new value replaces the key; null or an empty string stops sending it. Pointing such an integration at a new destination URL (any URL it does not already use, even on the same host) through the API or MCP requires apiKey in the same request, or the PATCH returns 400 and nothing changes. The integration and its subscriptions are saved together; a 500 may come after the change was saved, so check GET /api/v1/integrations/:id before repeating a PATCH.
• Test and retry never charge credits and never add a lead to your Lead Export History, even when the retried delivery was a push; both answer 200 with data.status (see Responses). POST /api/v1/integrations/:id/deliveries/:deliveryId/retry takes the numeric id from GET .../deliveries (not the evt_ id in the webhook body) and re-sends that delivery's stored data, to the URL it was first sent to or to the connected CRM, as a new event: a new id, occurredAt set to the time of the retry, and one attempt. A test or retry that is sent is recorded as a new delivery (the original stays), and one that fails counts toward needs_attention, whether the destination rejected it or could not be reached (for example a timeout). On a CRM, a test writes a real record for the sample company Acme Test Co that is not removed; POST .../field-mapping/test cleans up after itself. On a paused integration, test and retry return 400 ("Integration is paused. Re-enable it first (PATCH status connected)."); a successful test or retry on a needs_attention integration turns it back to connected, which counts as re-enabling it.
• Field mapping: each CRM takes its own scopes (HubSpot contact and company, Salesforce lead, Pipedrive person and organization). Each scope maps an SMB field id (the ids in smbFields) to the CRM field's internal name, for example {"contact": {"phone": "mobilephone"}}. PATCH replaces the whole saved mapping: any field or scope of this CRM that you leave out goes back to its default, so read the mapping first and send every override you want to keep. Unknown SMB field ids are dropped (the response shows what was saved). A scope of another CRM, or a PATCH with no scope at all, returns 400 validation_error and changes nothing; use DELETE to reset the mapping. POST .../field-mapping/test takes an optional {"mapping": {...}} to test a mapping before saving it; without it, the saved mapping is tested. The field-mapping endpoints return 400 on a webhook integration, and the Pipedrive endpoints on any other provider.
• pipedriveDeals on PATCH (Pipedrive only, 400 otherwise) turns on Deal creation: {"enabled": true, "pipelineId": 1, "stageId": 2, "defaultValue": 0, "defaultCurrency": "USD", "expectedCloseDays": 30, "fieldMap": {}}, where defaultValue is 0 or more, defaultCurrency 3 to 8 characters, expectedCloseDays 0 to 3650, and fieldMap maps an SMB field id to a deal field key from GET .../pipedrive/deal-fields. Fields you send are merged into the saved settings; a fieldMap you send replaces the saved one. enabled: true needs pipelineId and stageId in the same request, even when they are already saved (take them from GET .../pipedrive/pipelines). For each lead, an open Deal already linked to the lead, or else an open Deal of the Person, is updated; otherwise a new Deal is created (a won or lost Deal is never reused).
• DELETE is permanent: the integration's subscriptions, field mapping, Pipedrive deal settings and delivery history are removed and cannot be restored. Records already sent stay in the destination, and deleting a CRM integration does not remove SMB Sales Boost's access inside the CRM (revoke it there if needed). A webhook created again gets a new id and signing secret, and a CRM must be connected again in a browser. To stop sending without losing anything, PATCH {"status": "disabled"} instead.

Create a webhook integration

curl -X POST https://smbsalesboost.com/api/v1/integrations/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer smbk_your_api_key_here" \
  -d '{
    "provider": "zapier",
    "displayName": "My Zap",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/XXX/YYY",
    "events": ["lead.created", "export.completed"]
  }'

Body fields:

• provider (required): zapier, n8n, make, pipedream, clay or generic_webhook. CRMs are connected with POST /api/v1/integrations/<crm>/connect instead (see Connect a CRM).
• targetUrl (required): a public https URL, up to 2048 characters; localhost and private network addresses return 400.
• events (required): one or more event names (duplicates are ignored; at most 20 entries).
• displayName (optional): 1 to 100 characters; defaults to the provider name.
• apiKey (optional, any webhook provider, up to 500 characters): a secret sent as the X-SMB-API-Key header only to this targetUrl, for example a Clay table API key. It is stored encrypted and never returned. Set it here: a later PATCH accepts apiKey only for Clay and for webhooks that already send one.

The response is {"data": {"integration": {...}, "signingSecret": "..."}}. Store the signing secret now, because it is shown only once. If the request times out, the integration may have been created: check GET /api/v1/integrations first. Repeating the same provider and targetUrl returns 409 integration_exists; a different provider or a changed URL (even a trailing slash) creates a second integration with its own secret. If the integration exists but you did not get its signing secret, delete it (DELETE /api/v1/integrations/:id, which also deletes its delivery history) and create it again.

Connect a CRM

POST /api/v1/integrations/hubspot/connect (or salesforce, pipedrive) returns {"data": {"provider", "authorizationUrl", "expiresAt"}}. Salesforce also takes {"environment": "production"} (the default) or {"environment": "sandbox"}; sending environment for HubSpot or Pipedrive returns 400. Open authorizationUrl in a browser and approve access within 10 minutes. A new CRM integration then appears in GET /api/v1/integrations with its initial events: HubSpot lead.created on (lead.updated present but off; to turn it on, PATCH subscriptions with both events, see Rules worth knowing), Salesforce lead.created, Pipedrive lead.created and lead.updated. Only the account owner should approve it: whoever approves attaches their CRM to the account. When the account already has 25 integrations, connect returns 409 integration_limit unless one of them is an integration of that CRM that the sign-in could reconnect. The browser returns through /api/integrations/<provider>/callback, which is a redirect target, not an API endpoint.

Connecting a CRM account that is already connected re-authorizes that integration in place: it gets new access, a needs_attention integration becomes connected again, a paused one stays paused, and its events, field mapping, Pipedrive deal settings and delivery history are kept. The 25-integration limit applies only to new connections. So when a CRM integration stops working because its access was removed or expired in the CRM, reconnect it: click Reconnect on the integration in the dashboard's Integrations tab, or connect again through the API or MCP and sign in to the same CRM account (for a Salesforce Sandbox integration, send {"environment": "sandbox"}). PATCH {"status": "connected"} alone does not restore access. Signing in to a different account of the same CRM creates a new integration.

If approval does not complete, nothing is connected or changed and the dashboard URL shows <provider>_error=<reason>, for example key_revoked (the API key that created the link was revoked), integration_limit (the account has 25 integrations and the CRM account you approved is not already connected), invalid_state (the link expired or was already used; start again), already_connected (rare: two approvals of the same CRM account finished at the same moment) or the CRM's own error, such as access_denied. A HubSpot connect fails, creating nothing, when HubSpot does not confirm the account, with the message "We could not confirm which HubSpot account you signed in to, so nothing was connected or changed. Please try connecting again in a minute." Check GET /api/v1/integrations to confirm a connection.

Push one lead

POST /api/v1/integrations/:id/push-lead sends one lead to this integration now, in a single attempt with no automatic retries. Send {"leadId": 123} for a lead from the database (tracked like an export), or {"lead": {...}} for your own data (untracked and free; REST only, the MCP tool push_lead_to_integration takes leadId).

• Cost: A lead you already received is free, even at a 0 balance. A new lead costs 1 credit, taken from your balance or, when the balance is 0 and your overage budget is enabled with room left, billed as overage; if neither can cover it, the push returns 402 insufficient_credits and nothing is pushed. A new lead that shares a primary phone or primary email with a lead you already received is also free (see Credits & Subscription). The credit is taken before the lead is sent: if the destination then fails, the response is a 200 with status failed and tracked: true, the credit stays used, and because the lead now counts as received, pushing the same leadId again is free.
• Refused before anything is charged or sent: an integration whose status is not connected (a disabled or needs_attention integration returns 400 until you PATCH {"status": "connected"}; unlike test and retry, push does not work on needs_attention), a leadId that matches your export blacklist (400), an unknown leadId (404), leadId and lead sent together (400), and a webhook with no active subscription (a 200 with status failed, tracked: false and creditsUsed: 0). Your own data is not checked against the blacklist.
• Your own data: use the keys email, firstName, lastName, phone, companyName, website, industry, city and state so CRMs can map it (the database field names, such as wCompanyName and wEmailPrimary, also work: they are the names Lead Export History leadSnapshot uses, not the display names GET /api/v1/leads returns, such as Company Name). CRMs match and create records as described under Supported providers; for example HubSpot writes a Contact only when there is an email.
• What arrives: a webhook gets one lead.created event, even for a lead you received before. A leadId push to a webhook sends the same flat lead summary as a live lead.created event, with source crm_push. A push of your own data sends {"lead": <your object as sent>, "source": "manual_push"}; see Delivery format. For a leadId push, the target integration gets the lead once, from the push itself; it is left out of the background lead.created / lead.updated events. Your other integrations still get them: a lead you had not received before sends lead.created to your other integrations subscribed to lead.created, and re-pushing a lead you already received sends lead.updated to your other integrations subscribed to lead.updated only when the lead changed since you last received it (a newer Last Buying Signal). A push of your own data goes only to the target integration.
• Where it is recorded: every push is recorded in the integration's deliveries and counts toward needs_attention like any other delivery. That covers every push that is sent, through the API, MCP or the dashboard (its per-lead push, or a push of selected leads from the Leads tab, where each lead counts as one delivery), to any provider, HubSpot and Salesforce included; see GET /api/v1/integrations/:id/deliveries. A leadId push that passes the checks is recorded in Lead Export History with exportMethod crm_push, even if the delivery then fails, and adds 1 to totalLeadsExported and monthlyLeadsExported in GET /api/v1/me (a free re-push too); exportMethod shows the most recent channel, so a later search or export of the lead changes it. A push never creates a file in Export History, and a push refused before anything is sent is not charged and not recorded anywhere.
• Errors: a 503 service_unavailable only happens before anything is charged or sent, so it is safe to retry. A 500 may come after a credit was taken: check GET /api/v1/me and the deliveries before pushing the same lead again. The response shape is under Responses.

Ready to Find Your Next Customers? Get access to growing local business leads updated every 5 minutes. See plans starting at $49/mo →