smb-sales-boost

Find, preview and export the best local businesses (SMBs) to reach out to for outbound sales from the SMB Sales Boost database through its REST API - search by keyword, location and buying signals, preview for free, export CSV/JSON/XLSX, re-download past exports, enrich lists of website URLs.

Note for AI agents: This file and the other files in this skill folder may be truncated when opened. Always read them fully, in chunks if necessary, so that no rule, parameter or example is missed. Full parameter and field tables are in REFERENCE.md in this folder.

SMB Sales Boost Skill

SMB Sales Boost is a B2B lead database of small and medium-sized businesses in the United States, built for sales teams that want to reach growing local businesses. Every lead carries a Last Buying Signal: the date something changed that makes the business worth contacting now (it was newly added, got a new primary phone, phone list, primary email, Tier 1 or Tier 2 email list or full address, or added or changed a social profile). Buying Signal Type says which of these happened.

This skill lets you search, preview and export those leads, re-download past exports, enrich lists of website URLs, manage the account, and connect the user's CRM or automation tools so leads flow there automatically, all through the REST API with the bundled smb_api.py script.

• Base URL: https://smbsalesboost.com/api/v1
• One database: every request is served from the Main database (other). Any database value you send resolves to it, so you never need to choose one.
• Who can use it: accounts with an active or trialing Starter, Growth, Scale, Platinum or Enterprise subscription. Anyone else gets 403 forbidden. New customers can subscribe through the API (see Signing up through the API).
• Reference files: REFERENCE.md (every parameter, field, status and error), openapi.json (the published OpenAPI 3.1 spec; where it differs from this skill, follow this skill, which was checked against the live API).

Setup

1. The user creates an API key in the dashboard (Dashboard > API, https://smbsalesboost.com/dashboard?tab=api). Keys start with smbk_.
2. The key must be in the SMB_SALES_BOOST_API_KEY environment variable. If it is not set, ask the user to set it. Do not ask them to paste the key into the chat, and never print, log or write the key to a file.
3. Run every call through the bundled script (Python 3.8 or newer, standard library only, nothing to install):

bash

python3 smb_api.py METHOD ENDPOINT [--params '{json}'] [--body '{json}'] [options]

Run it from this skill's folder, or use its full path (for example python3 ~/.claude/skills/smb-sales-boost/smb_api.py GET /me). The script prints JSON to stdout and notes (rate-limit headers, warnings) to stderr. Do not hand-build curl commands; the script encodes parameters correctly, saves files safely and enforces the confirmation rules below.

Quoting user text safely: --params and --body take JSON inside single quotes. If any value contains a single quote (for example a company name like Joe's Bakery), write the JSON to a file with your file tool and pass --params-file PATH or --body-file PATH instead. Never paste user text into a shell command unquoted.

Windows: run the script with py -3 smb_api.py (or python smb_api.py) and always pass JSON through --params-file or --body-file. Command Prompt does not treat single quotes as quotes, and Windows PowerShell 5.1 removes the inner double quotes, so inline JSON fails there. The script reads UTF-8 files (with or without a byte-order mark) and UTF-16 files that start with a byte-order mark.

Rules for every session

1. Real money: confirm first. These calls charge, or authorize charges to, the card on file: POST /purchase (subscription checkout), POST /purchase-credits, POST /subscription/change-plan (an upgrade or an early trial activation charges immediately), and PATCH /auto-top-up or PATCH /overage-budget with enabled: true (automatic future charges). Before any of them, tell the user exactly what will happen and what it costs (amount and date), and wait for an explicit yes. All charges are final; there are no refunds. The script refuses these calls unless you add --confirm; add it only after the user has approved that exact action. Adding credits (a purchase, an upgrade, an early trial activation or a trial switch to a larger plan) or enabling the overage budget also restarts every email schedule that was paused for insufficient credits (with the overage budget, their leads can be billed to the card), so check GET /email-schedules and tell the user first.
2. Credits: preview first, cap every spend. GET /leads, POST /leads/export and POST /enrichments spend credits. Run GET /leads/preview first (it is free) to check the match count and quality, keep limit small (on GET /leads the script accepts only one whole number from 1 to 1000; it refuses 0, which the API reads as 100, and a limit given twice), and always pass maxCredits (a whole number of 0 or more). The script refuses GET /leads and POST /leads/export without maxCredits unless you add --confirm (only after the user agreed to an uncapped spend), and it refuses a maxCredits of null, a negative number, a decimal, true/false or text, because the API would treat those as "no cap". After GET /leads or POST /leads/export, tell the user creditsUsed and the remaining balance: creditsRemaining, or totalCreditsRemaining from GET /me when the page came back empty (the field then shows 0). POST /enrichments returns neither: report credits.total from GET /enrichments/{id} (final once credits.final is true) and the balance from GET /me.
3. Email to real people: confirm first. An active email schedule emails real recipients and spends credits, and POST /email-schedules/{id}/trigger sends immediately. Create schedules with "isActive": false, review them with the user, then activate. The script requires --confirm for creating an active schedule, activating one, triggering one, and changing the recipients, preset or maxLeadsPerEmail of a schedule that is not paused in the same call. Editing a keyword list (PUT /keyword-lists/{id}) or turning on auto-refine also changes what the schedules whose preset uses that list send, so check GET /filter-presets and pause those schedules first.
4. Destructive calls: confirm first. POST /ai/generate-keywords deletes all of the user's keyword lists before generating new ones. Every DELETE is permanent. Deleting a filter preset also deletes every email schedule that uses it, so first list those schedules (GET /email-schedules, the ones whose filterPresetId is the preset's id) and name them to the user. When the user only wants something to stop, offer to pause it instead of deleting it: a paused email schedule (PATCH /email-schedules/{id} with {"isActive": false}) keeps its list of recipients who unsubscribed, and a paused integration (PATCH /integrations/{id} with {"status": "disabled"}) keeps its delivery log, its signing secret and its dashboard label; both can be resumed later. POST /subscription/cancel cancels the subscription. The script requires --confirm for all of these.
5. Lead data to third parties: confirm first. An integration sends lead data (business names, phone numbers, email addresses and the other lead fields) to a system outside SMB Sales Boost (a CRM, an automation tool or any webhook URL), and it keeps doing so automatically on every subscribed event, for leads the user gets through the dashboard, the API or email schedules (and when a lead export history refresh finds newer data for a lead), until it is disabled or deleted. Before you create a webhook integration, start a CRM connection, point an integration at a new URL, add or re-activate events, re-enable it, change the header apiKey it sends, push a lead, send a test event, retry a delivery or change or test a CRM field mapping, describe the destination (provider, host, which events and which data) and wait for the user's explicit yes. The script requires --confirm for all of these. When an API key creates an integration, connects a CRM, changes where an integration sends data, adds events or re-enables one, the account owner is emailed for each change. During bursts of more than 10 changes in an hour, further changes are combined into summary emails. Tell the user to expect it. The signingSecret returned when a webhook integration is created is shown only once: give it to the user, and never log it, save it to a file or repeat it elsewhere. See Integrations.
6. Never blindly repeat a call that may have charged or sent data. If GET /leads, POST /leads/export, POST /enrichments, a schedule trigger, a plan change, a credit purchase, creating a webhook integration or pushing a lead fails with a 5xx, a timeout or a dropped connection, it may still have completed. The long-running calls (POST /leads/export, a schedule trigger, POST /ai/suggest-categories and the three POST /lead-export-history/... calls) carry an idempotency key that the script prints: re-running the exact same command with --idempotency-key set to that value returns the same job instead of exporting or sending again (see Long-running calls). Otherwise follow the advice field the script prints (check GET /me, GET /export-history, GET /enrichments, GET /email-schedules, GET /integrations or GET /integrations/{id}/deliveries first). The script retries a 429 or 503 by itself (after Retry-After, up to 60 seconds), except on calls that change or send through an integration (every call under /integrations other than a GET): it returns those errors with advice, so check GET /integrations or the delivery log, then repeat the call once if the change or delivery is not there. A 503 provider_unavailable is never worth repeating.
7. Protect personal data. Results and files contain business phone numbers and email addresses. Keep files in the output folder, do not paste full lead lists into public channels, and only show the user what they asked for.
8. Stay on documented endpoints. Use only the endpoints in this skill and REFERENCE.md. API key management, billing details and undoing a cancellation are dashboard-only (see Not available through the API).
9. Data accuracy. Contact details come from public sources and are not verified; revenue, employee and similar figures are estimates. Say so if the user is about to rely on them.

Plans and credits

Every plan is credit-based. One credit buys one new lead.

Plan	Price / month	Monthly credits	Extra credits	Max credits per purchase	14-day free trial
Starter	$49	500	$0.10 each	2,500	Yes, 250 trial credits
Growth	$149	2,000	$0.075 each	10,000	Yes, 1,000 trial credits
Scale	$499	10,000	$0.05 each	50,000	Yes, 5,000 trial credits
Platinum	$1,999	100,000	$0.03 each	500,000	No
Enterprise	$4,999	250,000	$0.02 each	1,250,000	No

How charging works:

• 1 credit per new lead returned by GET /leads or exported by POST /leads/export.
• Free: leads you have already received through any channel (dashboard, API, email schedules, enrichments), and new leads that share a primary phone or primary email with a lead you already received. Previews are always free.
• Automatic cap: on every charged call, new leads come first and are cut to min(maxCredits, your spendable balance); already-received leads fill the remaining slots for free. If your balance was the limit, the response has the header X-Credits-Capped: true (the script prints a note). Leads cut by a cap are dropped, not moved to the next page (exception: on POST /leads/export with maxLeads, they go to the reservoir and are added to your next maxLeads export, where new leads cost credits).
• Spending order: temporary (promotional) credits, then the monthly allowance, then permanent credits (rolled-over and purchased), then the optional overage budget (billed to the card daily).
• Unused monthly credits roll over into the permanent balance while the subscription stays active. Downgrading makes the whole remaining balance expire at the next renewal; cancelling forfeits it when the subscription ends.
• Auto top-up (if the user enabled it) buys credits automatically when the permanent balance drops below a threshold, which charges the card.
• GET /me is the authoritative balance: totalCreditsRemaining (temporary + monthly remaining + permanent), plus monthlyCredits, monthlyCreditsUsed, monthlyCreditsRemaining, permanentCredits, temporaryCreditsRemaining and creditOverageRate (cents per credit).

Free trial: Starter, Growth and Scale start with a 14-day free trial. A payment method is required and nothing is charged until day 14 (the user's bank may show a temporary authorization that disappears within a few days); on day 14 the plan price is charged automatically unless the subscription is cancelled first. Trial credits are 50% of the plan's allowance and the full allowance is granted when the trial converts. One trial per person, checked by email address and payment method. During a trial the API works normally, except that auto top-up and the overage budget cannot be enabled. While GET /me shows trial.isTrialing: true, the plan price has not been charged yet (credits bought with POST /purchase-credits during the trial are charged immediately); trial.firstChargeAmountCents (the plan's list price; a discount on the account can make the actual charge lower) is charged on trial.endsAt unless the user cancels first.

Finding leads: the standard workflow

1. Translate the request into filters. Use several wildcard keyword variations (they are OR'ed): "dentists in Texas" becomes positiveKeywords: ["*dental*", "*dentist*", "*orthodont*"] and stateInclude: ["TX"].
2. Preview (free): GET /leads/preview. Read data.pagination.total for the match count and look at a few results (contacts are masked).
3. Agree on the spend: tell the user how many leads match and that each new lead costs 1 credit.
4. Get the leads: either GET /leads (results come back in the response, one page at a time) or POST /leads/export (a CSV, JSON or XLSX file; better for more than a few dozen leads). Always pass maxCredits (the script refuses these calls without it unless you add --confirm). GET /leads does not apply the user's export blacklist (preview and export do), so leads from blacklisted domains can come back and are charged like any other new lead. If the user keeps an export blacklist, use POST /leads/export.
5. Report: show results in a short table and state creditsUsed and the balance (creditsRemaining, or GET /me if the page was empty).

bash

# 1-2. Preview: free, contacts masked
python3 smb_api.py GET /leads/preview --params '{"positiveKeywords":["*dental*","*dentist*","*orthodont*"],"stateInclude":["TX"],"limit":10}' --compact

# 4a. Search: returns up to 25 leads, never spends more than 25 credits
python3 smb_api.py GET /leads --params '{"positiveKeywords":["*dental*","*dentist*","*orthodont*"],"stateInclude":["TX"],"limit":25,"maxCredits":25}' --compact --out tx-dentists

# 4b. Export: a CSV file of up to 500 leads, never more than 500 credits
python3 smb_api.py POST /leads/export --body '{"filters":{"positiveKeywords":["*dental*","*dentist*","*orthodont*"],"stateInclude":["TX"]},"maxResults":500,"maxCredits":500}'

--compact prints only the key fields of each lead; --out NAME also saves the full response as NAME.json in the output folder. Use both for larger searches so the full records do not flood the conversation.

Search parameters

GET /leads and GET /leads/preview take the same filters as query parameters. With the script, give lists as real JSON arrays; it encodes each parameter in the format the API expects. The most useful ones:

Parameter	What it does
positiveKeywords	Keywords to include (OR). Matched as case-insensitive substrings against Registered URL, Crawled URL, Company Name and AI Categories. * is a wildcard: *auto*repair* matches "auto body repair" and "automotive repair". In URL columns, spaces also act as wildcards.
negativeKeywords	Keywords to exclude: a lead is dropped if any of them matches any of those columns.
orColumns	Columns the keywords search. Default ["wOgrequestedUrl","wSimpleCrawledUrl","wCompanyName","aiCategoryEstimation"]. Adding "wProfileDescriptionShort" also searches the short description, but it moves keyword searches onto the slow path (up to about 110 seconds); keyword searches stay fast only while every orColumns entry is one of the four defaults. To search AI categories only, use ["aiCategoryEstimation"].
nameIncludeTerms / nameExcludeTerms	Company-name terms. While wCompanyName is in orColumns (the default), include terms are OR'ed with positiveKeywords, so adding them to a keyword search widens it instead of narrowing it; each include term becomes required only when wCompanyName is left out of orColumns. Exclude terms always remove matching leads.
urlIncludeTerms / urlExcludeTerms, crawledUrlIncludeTerms / crawledUrlExcludeTerms	Website URL terms. Same rule as company-name terms, with wOgrequestedUrl (Registered URL) and wSimpleCrawledUrl (Crawled URL) in orColumns.
descriptionIncludeTerms / descriptionExcludeTerms	Short-description terms. Each include term is required (AND) unless wProfileDescriptionShort is in orColumns.
stateInclude / stateExclude	Two-letter uppercase state codes, exact match: ["TX","OK"].
cityInclude / cityExclude	City names, substring match: ["Austin"].
zipInclude / zipExclude	ZIP codes, exact match.
lastBuyingSignalFrom / lastBuyingSignalTo	Last Buying Signal date range, inclusive: ISO 8601 (2026-09-01, 2026-09-30T23:59:59Z) or relative (rel:7d; units h, d, w, m = months, y). A date-only To means the start of that day, so to include all of September 30 send 2026-09-30T23:59:59Z. An invalid date fails with 500, so check the format.
buyingSignalTypeFilter	Only leads whose latest buying signal is one of these types (exact, case-sensitive): Newly Added, Phone Primary, Total Phones, Email Primary, Tier 1 Emails, Tier 2 Emails, Address Full, Instagram, LinkedIn, Facebook, YouTube, TikTok, X (Twitter), Google Maps, Yelp, Pinterest, Other Social.
phonePrimaryEmptyFilter, emailPrimaryEmptyFilter	exclude_empty keeps only leads that have that contact detail (a lead without contacts still costs a credit), only_empty the opposite.
minRatingValue / maxRatingValue, minReviewCount / maxReviewCount, minNumLocations / maxNumLocations	Numeric ranges.
registrationDateFrom / registrationDateTo	Domain registration date as a plain YYYY-MM-DD, for newly launched businesses (it is compared as text, so a rel: value in registrationDateFrom leaves out the boundary day; see REFERENCE.md).
websiteSchemaFilter	Website schema types, for example ["LocalBusiness","Dentist"]. GET /leads/other/schema-types lists the values (the first call can be slow).
redirectFilter	yes or no: whether the registered domain redirects elsewhere.
search	Plain substring search over company name, both URLs, short description, city and primary phone (not a wildcard search).
sortBy / sortOrder	Default lastBuyingSignal / desc (newest buying signals first).
page / limit	Default 1 / 100; limit is at most 1000. On GET /leads the script requires limit, when given, to be one whole number from 1 to 1000 (the API reads 0 as 100).
maxCredits / maxResults	GET /leads (and the POST /leads/export body); preview ignores both. On GET /leads they cap the credits spent and the leads returned by that one call, and each page is a separate call. maxCredits: 0 returns only leads you already have, free.
excludePurchased	GET /leads/preview (and the POST /leads/export body); GET /leads ignores it. true hides leads flagged contactExported. On preview it is applied after paging, so a page can hold fewer than limit leads and pagination.total still counts the hidden ones.

At least one positive filter is required: positiveKeywords, nameIncludeTerms, urlIncludeTerms, crawledUrlIncludeTerms or descriptionIncludeTerms. Without one, GET /leads and preview return no leads, charge nothing and set requiresKeywords: true, and POST /leads/export returns 400 bad_request. Location, date, signal and other filters only narrow a search; they cannot start one. Never send an empty keyword ([""]): it matches everything.

There are many more filters (Tier 1-6 emails, Total Phones, founders, software and ad-pixel columns, email provider and security, employee counts, NAICS, open positions and more). See REFERENCE.md for the complete list and formats. Unknown or misspelled parameters are ignored silently, which makes a search broader, so double-check names.

Speed: keyword, company-name, URL, state and city filters with the default sort answer in about a second. Other filters can take up to about 110 seconds (the script prints a note when a query took the slow path). Previewing first warms a 20-second cache, so an identical GET /leads right after it is fast.

Results

json

{"data": {
  "leads": [ { "id": 2841123, "Company Name": "Bright Smile Dental", "City": "Austin", "State": "TX",
               "Phone Primary": "[phone]", "Email Primary": "[e-mail]",
               "Last Buying Signal": "2026-10-03T09:14:52.118Z", "Buying Signal Type": ["Phone Primary"], "...": "..." } ],
  "pagination": { "page": 1, "limit": 25, "total": 1834, "pages": 74 },
  "databaseType": "other", "creditsUsed": 18, "creditsRemaining": 4982, "maxCredits": 25 }}

• Each lead has 61 fields with display names (Company Name, Phone Primary, Total Phones, Email Primary, Tier 1 Emails, AI Categories, Registered URL, Description Short, Founder Name(s) and more; full list in REFERENCE.md). Last Updated is a deprecated duplicate of Last Buying Signal.
• pagination.total is the full match count before credit caps.
• creditsRemaining does not include overage headroom and shows 0 when a page is empty; check GET /me for the real balance.
• Preview masks contacts ((512) ***-**42, hel*@brightsmiledentaltx.com) except on leads you already have, which come back unmasked with "contactExported": true. Preview also flags a lead this way when one of its Total Phones or Tier 1-6 emails matches the primary phone or primary email of a lead you received before; GET /leads and exports still charge 1 credit for such a lead, so contactExported: true does not guarantee the lead is free. Preview never charges.

Exporting files

POST /leads/export creates a file from a search and saves it to the output folder automatically.

bash

python3 smb_api.py POST /leads/export --body '{"filters":{"positiveKeywords":["*med*spa*","*aesthet*","*botox*"],"stateInclude":["FL"],"lastBuyingSignalFrom":"rel:30d"},"maxResults":1000,"maxCredits":300}'

• Body: filters (the same filters as search, as real JSON arrays, except search, page and limit: the export ignores those three without an error, so a search term that narrowed your preview does not narrow the export, and the export can then match and charge for more leads; and never put maxCredits, maxResults or excludePurchased inside filters, where they are ignored), plus optional top-level maxCredits, maxResults, maxLeads, excludePurchased, formatId and inline. Use selectedIds (lead ids) instead of filters to export specific leads. The script converts list filters given as strings or numbers into real arrays (the export ignores other forms of most list filters), moves a misplaced maxCredits, maxResults, maxLeads, excludePurchased, formatId or inline out of filters, and refuses filters.search, filters.page and filters.limit.
• Without maxCredits an export can spend your entire balance (plus any overage budget). Always set it; the script refuses an export without it unless you add --confirm after the user agreed to an uncapped spend, and it refuses "maxCredits": null (the export treats null as no cap).
• maxResults caps the total leads in the file. maxLeads also caps it, but keeps the leads that did not fit (including those cut by maxCredits) in a "reservoir" that is merged into your next maxLeads export whatever its filters are, and new leads among them cost 1 credit each. The reservoir is one pool per account, shared with email schedules and capped at the plan's monthly credit allowance; leads that do not fit are not kept. Prefer maxResults unless the user wants that carry-over.
• excludePurchased: true exports only leads you do not have yet.
• Formats: without formatId the export uses your default export format (the one with isDefault: true in GET /export-formats, which can be XLSX), or the built-in CSV when you have none; a wrong formatId also falls back to it. JSON and XLSX come from a saved export format. There is no file-type option in the request, so to be sure of CSV, pass the id of a CSV format.
• XLSX limit: at most 20,000 rows in any one file (a single file, a split part, or the includeTotal file), and the 400 export_too_large error arrives after the credits were charged. For bigger exports use a CSV format, or an XLSX format with splitFiles: true, splitMode: "max_rows", maxRowsPerFile of 20,000 or less and includeTotal: false. If it happens, do not simply repeat the request (an export always picks new leads first, so a repeat can charge for different leads): re-run it with a CSV format, maxCredits: 0 and no excludePurchased, which returns only leads you already have at no cost, or re-export the charged leads from the lead export history (below).
• Size: up to 100,000 leads per export. 5 export requests per minute.
• Response: the script saves each file and prints leadCount, creditsUsed, creditsRemaining, exportId and the saved paths. A large export can keep running on the server after about 75 seconds; the script then follows it until it is done (see Long-running calls), and the files are in the export history either way. The default file contains 59 columns, including Last Buying Signal and Buying Signal Type.
• inline: false (or --params '{"inline":false}') returns download links instead of file contents; the script then downloads the files itself. Use it for very large exports: the response stays small, also while the server keeps it for a long-running export.

Re-downloading: every export file is kept for 90 days.

bash

python3 smb_api.py GET /export-history --params '{"limit":10}'     # newest first: id, fileName, leadCount, expiresAt, downloadAvailable
python3 smb_api.py GET /export-history/412/download                 # saves the file

After 90 days (or for files exported before 26 September 2026, or whose upload failed) the download answers 410 gone. The leads can still be re-exported free from the lead-level history:

bash

python3 smb_api.py GET /lead-export-history --params '{"limit":50}'                    # every lead you received, with its tracking id
python3 smb_api.py POST /lead-export-history/re-export --body '{"trackingIds":[55123,55124]}'

re-export rebuilds a file from the stored copies (up to 5,000 tracking ids, no credits). POST /lead-export-history/refresh and /refresh-and-export first replace the stored copies with the current data (free, but the original copies are overwritten). A refresh that finds newer data for a lead sends lead.updated to your integrations, unless the lead is on your export blacklist. An invalid date or filter value returns 400, and refresh-and-export checks everything before it changes any entry. A big selection can keep running on the server; the script follows it and saves the file (a file that finished in the background is kept for pickup for up to 60 minutes and is never added to the export history). See REFERENCE.md.

Enriching a list of websites

POST /enrichments looks up a list of website URLs. URLs already in the database return the full lead record; others are fetched live from the website.

Pricing: 1 credit for a URL found in the database that you have not bought before; 0.1 credit for a URL fetched live; 0 for a URL you already have, one that returned no data, or one without the contact details you asked for. A URL found in the database is never fetched live. Submitted URLs and results are never added to the database. There is no pricing dialog through the API, so state these prices and agree on maxCredits with the user first (the script requires --confirm).

bash

python3 smb_api.py POST /enrichments --body-file urls.json --confirm
# urls.json: {"urls": ["https://brightsmiledentaltx.com/contact", "acme-plumbing.com"], "maxCredits": 50, "contactTypes": "either", "emailResults": false}

python3 smb_api.py GET /enrichments/412             # poll: status queued, matching, scraping, merging, delivering, then completed / partial / failed
python3 smb_api.py GET /enrichments/412/download    # once completed or partial: saves the CSV (one row per usable URL with a Status column; duplicates and unparseable URLs are only counted)

• Up to 100,000 URLs per run (after removing duplicates). Send full URLs; a deep link can carry better contact data. Put the most important URLs first, because a credit limit trims from the end of the list.
• Options (exact names, top level of the body; a misspelled name is ignored and removes your limit): maxCredits (whole number of at least 1; when omitted the run can spend up to your current credit balance but never the overage budget, while a maxCredits above your balance lets it draw on the overage budget, which is billed to the card), databaseMatchPercent (0-100, default 100), contactTypes (phone, email or either, the default), emailResults (default: the account setting; set false to skip the notification email). Never send null for an option.
• Runs are asynchronous. Poll GET /enrichments/{id} every 30-60 seconds at first, then every few minutes; large lists can take hours. partial means the file is ready but a credit limit stopped the run early. failed never produces a file.
• Each POST creates a new run and there is no undo. If a submit fails or times out, check GET /enrichments before sending it again.

Saved searches, keyword lists and email schedules

Filter presets exist to drive email schedules. POST /filter-presets takes {"name": "...", "filters": {"hash": "..."}}, where hash uses the dashboard's search format (ni company-name terms, ui URL terms, si states, ci cities and so on; see REFERENCE.md). A preset without a positive filter in that format (a company-name, URL or description term, or one of the user's own positive keyword lists) never sends anything. A hash has no key for positiveKeywords: ni, ui, cli and di each match only their own column and none of them searches AI Categories, while keywords from a positive keyword list in nkl are searched like positiveKeywords (Registered URL, Crawled URL, Company Name and AI Categories). To make a schedule send the same leads as a positiveKeywords search you previewed, first create a positive keyword list with those keywords (POST /keyword-lists), then put its id in nkl together with the location keys (for example "#" + urllib.parse.urlencode({"nkl": "42", "si": "OH"})); a negative list in nkl works like negativeKeywords. Presets cannot be edited, and deleting one also deletes its email schedules (check GET /email-schedules for schedules with that filterPresetId and name them to the user first).

Keyword lists (/keyword-lists) store keyword sets. Create with {"name": "...", "type": "positive" or "negative", "keywords": ["*dental*"]}. Lists are not applied to API searches automatically: read a list's keywords and pass them as positiveKeywords or negativeKeywords.

Email schedules (/email-schedules) email new matching leads on an interval and spend credits for new leads. Required: name, filterPresetId (number), intervalValue (whole number 1-720), intervalUnit (hours or days) and recipients ([{"email": "[e-mail]"}], up to 50). Always create with "isActive": false, review with the user, then activate with PATCH /email-schedules/{id} and {"isActive": true} (needs --confirm). An active schedule sends its first email within about 15 minutes, including every lead that currently matches (up to 10,000). Options include maxLeadsPerEmail (new leads over this cap, and new leads your credits could not cover, are kept in the account's shared lead reservoir while it has room and sent with a later email; on credit plans, already-received leads over the cap are not kept), distributionMode (full_copy or split_evenly; fullCopyRecipients only receive mail when at least 2 recipients are active) and combined-file settings (REFERENCE.md). There is no time-of-day setting: a daily schedule sends about 24 hours after the previous send, so the time drifts. POST /email-schedules/{id}/trigger sends right away; a big send keeps running on the server and the script follows it. A trigger is never sent twice when you re-run it with the --idempotency-key the script printed (the server remembers it for 24 hours), and 409 schedule_run_in_progress means the schedule's regular run is sending it at that moment (nothing was sent by your call). A 200 does not prove an email went out; compare lastSent and totalSentCount in GET /email-schedules before and after. To stop a schedule, pause it with {"isActive": false} rather than deleting it: deleting also deletes its list of recipients who unsubscribed.

AI helpers

• POST /ai/suggest-categories with companyName, companyDescription and productService (optional companyWebsite, excludeCategories) returns 4-12 suggested customer categories for the user's business. Nothing is saved or charged. With a website to analyse it can take a while; the script follows the call until the suggestions are ready. Turn the suggestions into keywords yourself (for example "Dentists" becomes ["*dental*","*dentist*"]).
• POST /ai/generate-keywords deletes every existing keyword list and regenerates lists from the account's target categories, which can only be set in the dashboard. If GET /me shows an empty targetCategories, it deletes the lists and generates nothing. Filter presets that point at keyword lists by id (nkl, ukl, ckl or dkl in the hash, which dashboard-saved presets also use) silently lose those keywords and exclusions when the lists are deleted, and the same applies to DELETE /keyword-lists/{id}: their email schedules can stop sending, or start emailing a broader set of leads and spending credits on them. Check GET /filter-presets first and pause any affected schedules. Only use it when the user explicitly wants all lists replaced (needs --confirm). Check progress with GET /ai/keyword-status.
• POST /ai/auto-refine/enable / disable with {"listId": 42} turn on or off the AI refinement of a keyword list and its paired list; GET /ai/auto-refine/status?listId=42 shows progress. Enabling resets the list's score history, and the refinement rewrites the list's keywords, which changes what any email schedule using the list sends (pause those schedules first if the user wants to review). A 200 does not guarantee the run started: if autoRefineEnabled is true but refinementStatus stays null, call enable again a few minutes later.

Integrations: sending leads to a CRM or automation tool

Integrations deliver lead data to the user's own systems: HubSpot, Salesforce and Pipedrive (CRM connections through the provider's sign-in page), and Zapier, n8n, Make, Pipedream, Clay or any HTTPS webhook URL. Rule 5 applies to every call that sets one up or sends data through it. Full request and response details are in REFERENCE.md section 17.

• What gets sent: once an integration is connected, every subscribed event goes out automatically: lead.created (one event per lead the user receives for the first time through the dashboard, the API, an email schedule or a push), lead.updated, export.completed, email_schedule.sent and credit.low_balance. 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 /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. 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. export.completed and email_schedule.sent carry the lead count and sampleLeads (up to 5 leads, each with id, companyName, website, email, phone, city and state). HubSpot, Salesforce and Pipedrive integrations take only lead.created and lead.updated; a subscription to any other event returns 400 validation_error. Lead events carry the business contact details. Webhooks are signed (X-SMB-Signature: t=<unix-ts>,v1=<hex>, an HMAC-SHA256 of "<ts>." + rawBody with the signing secret).
• Reading is free and needs no confirmation: GET /integrations/providers (which providers are available now), GET /integrations, GET /integrations/{id}, GET /integrations/{id}/deliveries (newest 50 attempts), and the CRM field and pipeline lists.
• Webhook integration: POST /integrations/webhook with provider (zapier, n8n, make, pipedream, clay or generic_webhook), targetUrl (a public https URL), events and optional displayName (and apiKey for Clay, passed with --body-file). It needs --confirm. The response has the integration and a signingSecret that is never shown again: give it to the user so their endpoint can verify signatures, and do not log or store it. If the call fails or times out, the integration may have been created: check GET /integrations before trying again. 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. The signing secret cannot be shown again, so if the integration exists but the user did not get its signingSecret: read it with GET /integrations/{id}, show the user its provider, destination URLs and events, and with their yes delete it and create it again with the same values (both calls need --confirm; the new integration gets a new secret, and events that went to different URLs are restored with a PATCH of subscriptions).
• CRM connection: POST /integrations/{provider}/connect (hubspot, salesforce with optional {"environment": "sandbox"}, or pipedrive; needs --confirm) returns an authorizationUrl. The user opens it in a browser within 10 minutes and approves; the CRM account they sign in to is the one connected. Then the integration appears in GET /integrations with these events: HubSpot lead.created (its lead.updated subscription exists but starts switched off), Salesforce lead.created, Pipedrive lead.created and lead.updated. HubSpot 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; Salesforce writes Lead records matched by email. If the API key that asked for the link is revoked before the user approves, the connection fails (key_revoked) and nothing is created. If HubSpot does not confirm which account the user signed in to, nothing is connected or changed: ask for a new link a minute later. A provider that is not set up yet answers 503 provider_unavailable; an account that already has 25 integrations gets 409 integration_limit, unless it already has an integration of that provider (the sign-in may then be a reconnect, see below; signing in to a new account then fails and nothing is created); any other provider name is 404.
• Reconnecting a CRM: 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. Use the same POST /integrations/{provider}/connect call (for a Salesforce sandbox integration with {"environment": "sandbox"}) when a CRM integration is needs_attention because its access was removed or expired, and tell the user to sign in to the same CRM account (a different account connects as a new integration). The dashboard has a Reconnect button for each CRM integration too. Treat it like a connect (Rule 5, --confirm): when it brings a needs_attention integration back, the owner is emailed as for a re-enable.
• Changing an integration: PATCH /integrations/{id}. Renaming (displayName) and pausing ({"status": "disabled"}) need no confirmation. status accepts only connected and disabled (needs_attention is set by the system; sending it is a 400, unless the integration already has it). Changing subscriptions (this replaces the whole list), defaultTargetUrl, pipedriveDeals or the header apiKey, or re-enabling with {"status": "connected"} (from disabled or needs_attention), sends data to a new place or resumes sending, so it needs the user's yes and --confirm. defaultTargetUrl (webhook integrations only) sent alone re-points every existing subscription, inactive ones included; to move only some events, send subscriptions. A header apiKey (Clay) is sent only to the active destination URLs it was set for (a URL on a switched-off subscription never gets it, even after that subscription is switched on, until the owner edits the integration in the dashboard or apiKey is sent again), so pointing an integration that has one at any new destination URL (even on the same host: Zapier, Make and Clay put every customer's hooks on one host) needs apiKey in the same request (a new value, or null to stop sending it), otherwise 400 bad_request; pass it with --body-file. apiKey works only on Clay integrations and on webhook integrations that already send one (400 bad_request otherwise, and on a CRM); null or "" stops sending it. The integration and its subscriptions are saved together, but a 500 may come after the change was saved: check GET /integrations/{id} before repeating a PATCH. A re-point onto a URL that another integration of the same provider already uses gives 409 integration_exists. If the integration changes while the update is being applied (for example the owner pauses it at that moment), the update is applied again on top of that change; a 409 conflict means it changed again and nothing changed: read it again with GET /integrations/{id}, check the change still makes sense with the user, then retry. A 401 "This API key has been revoked" means the key was revoked in that moment and nothing was applied: tell the user and do not retry with that key. DELETE /integrations/{id} removes it for good, with its delivery log (needs --confirm); to stop it without losing anything, pause it instead.
• Sending on demand: POST /integrations/{id}/push-lead with {"leadId": 123} sends one lead now to this integration (once). A lead the user already received is free, even at a zero balance; a new lead costs 1 credit (402 insufficient_credits without credits) and then counts as received, so the user's other integrations subscribed to lead.created also get it; re-pushing a lead the user already received sends lead.updated to their other integrations subscribed to lead.updated only when the lead changed since the user last received it (a newer Last Buying Signal); the target itself gets the lead only once, from the push. {"lead": {...}} sends the user's own data, free and untracked. 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"}. Every push is recorded in the integration's deliveries and counts toward needs_attention like any other delivery; a push refused before anything is sent (for example "No active subscription for this integration", answered with status: "failed", tracked: false and creditsUsed: 0) is not recorded, not charged and not added to the export history. POST /integrations/{id}/test sends a synthetic test event to the real destination (a CRM gets a real test record that is not removed). POST /integrations/{id}/deliveries/{deliveryId}/retry re-sends a past delivery, with the same event data, to the URL it originally went to; a failed retry is recorded and counts toward needs_attention. Test and retry refuse a paused (disabled) integration with 400 (re-enable it first); a successful test or retry of a needs_attention integration switches it back to connected (the owner is emailed). All three need --confirm.
• CRM field mapping: GET /integrations/{id}/field-mapping shows which SMB Sales Boost field goes to which CRM field; PATCH changes it, DELETE resets it to the defaults and POST .../field-mapping/test does a dry run that creates and then deletes test records in the CRM. PATCH replaces the whole mapping (a scope you leave out is cleared), takes only the provider's own scopes (HubSpot contact, company; Salesforce lead; Pipedrive person, organization; another scope is a 400 validation_error), and needs at least one scope (to reset, use DELETE). All but the GET need --confirm. For Pipedrive, GET /integrations/{id}/pipedrive/pipelines and /pipedrive/deal-fields help set up automatic deals.
• Owner safeguards: the dashboard labels each integration with the API key that created or last re-pointed it. A dashboard change replaces that label only when it adds a destination URL the integration never had; pausing it (also when its key is revoked), and resuming it, switching on more events or switching on a URL it already had in the dashboard, keep it. When an API key creates a webhook integration, connects a CRM, changes where an integration sends data, adds events or re-enables one, the account owner is emailed for each change. During bursts of more than 10 changes in an hour, further changes are combined into summary emails. If the user did not expect that email, they should delete the integration in the Integrations tab and revoke the key in Dashboard > API, where revoking can also pause every integration the key set up.
• Limits: at most 25 integrations per account (409 integration_limit; reconnecting a CRM account that is already connected does not count as a new one) and 20 event subscriptions per integration; the same provider and URL twice gives 409 integration_exists. Integration calls share 60 requests per minute per account with the dashboard and the MCP server (connect: 30 per minute), then 429. 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. After 5 failed deliveries in a row an integration switches to needs_attention and stops until it is re-enabled (for a CRM whose access was removed or expired, reconnect it instead). 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.

Account, credits and billing

• GET /me: profile, plan, subscriptionStatus, the credit balance fields, the trial object, and the autoTopUp and overageBudget settings. PATCH /me updates firstName, lastName, companyName and companyWebsite.
• POST /purchase-credits (needs --confirm): buy permanent credits with the card on file, charged immediately. Send creditCount (at least 100, at most 5x the plan's monthly credits) or dollarAmount (at least 1). Price per credit is the plan's rate in the table above. The script sends an idempotency key and prints it; if the call times out, re-run it within 24 hours with --idempotency-key set to that value, so it is not charged twice (after 24 hours, check permanentCredits in GET /me before buying again). Works during a trial, and is charged immediately. If the user moved to a lower plan in the current paid billing period (not a plan switch during a free trial), that downgrade is still pending and credits bought now expire at the next renewal together with the rest of the balance (auto top-up pauses for this reason, a manual purchase does not). GET /me does not show a pending downgrade, so ask the user before buying, and say so when you confirm the price.
• GET /auto-top-up, PATCH /auto-top-up: automatic credit purchases when the permanent balance falls below a threshold. Enabling requires triggerType, triggerAmount, purchaseType and purchaseAmount (and optional capType, capAmount), replaces the whole configuration (send every field you want to keep) and needs --confirm. {"enabled": false} turns it off and always works. Not available during a trial.
• GET /overage-budget, PATCH /overage-budget: lets usage continue after the balance reaches zero, billed to the card once a day at the plan's rate, up to a per-cycle budget ({"enabled": true, "budgetType": "dollars", "budgetAmount": 50}; budgetType defaults to dollars). Needs --confirm to enable. Not available during a trial.
• POST /subscription/change-plan (needs --confirm) with {"targetPlan": "starter" | "growth" | "scale"}:
  • Upgrade: charges the new plan's full price now, restarts the billing cycle, keeps every unused credit and grants the new allowance immediately.
  • Downgrade: no charge now. At the next renewal the entire remaining balance (unused, rolled-over and purchased credits) expires before the lower allowance is granted. Warn the user. Moving back to the original plan (or higher) before renewal cancels the pending downgrade and keeps the credits, but it is billed like an upgrade: that plan's full price is charged now and the billing cycle restarts. Confirm the amount with the user first. While a downgrade is pending, a move to a plan between the current plan and the original one (for example Scale, then Starter, then Growth) is not an upgrade: nothing is charged and the whole balance still expires at renewal. GET /me does not show whether a downgrade is pending, so ask the user whether they moved to a lower plan in this billing period before you describe the cost.
  • During a free trial, mode decides: switch_trial (the default) changes the trial plan with no charge and keeps the trial end date (credits already used stay used); activate_now ends the trial, charges the target plan's full price now and grants its full allowance. A declined card returns 402 payment_declined with trialStillActive: true: nothing changed and the trial continues.
  • Platinum and Enterprise changes go through support. A 409 means nothing changed; show its message (see REFERENCE.md for the codes).
• POST /subscription/cancel (needs --confirm): cancels at the end of the current billing period, and access continues until then. During a trial the card is never charged, but the free trial is used up. It can only be undone in the dashboard before the period ends. Remaining credits are forfeited when the subscription ends. A confirmation email is sent.

Signing up through the API

New customers can subscribe without the website:

bash

python3 smb_api.py POST /purchase --body '{"email":"[e-mail]","plan":"growth"}' --confirm

• Plans: starter, growth, scale (14-day free trial by default), platinum, enterprise (no trial, charged at checkout). "trial": false skips the trial and charges at checkout.
• The response has a Stripe checkoutUrl (valid 24 hours) and a trial block (eligible, days, credits, endsAt, note, and reason when not eligible). Before the user opens the link, tell them the plan price and exactly when it is charged: at checkout, or automatically when the trial ends.
• After checkout the API key is emailed to that address. If the address already has an account, the purchase must first be confirmed from an email sent to it, and the key follows. Do not use POST /claim-key; it belongs to an older flow and cannot succeed.
• An address with an active or trialing subscription gets 409 already_subscribed (a trialing account should use change-plan instead). Each call creates a new checkout; never open two. Limited to 5 per hour.

Long-running calls

POST /leads/export, POST /email-schedules/{id}/trigger, POST /ai/suggest-categories and POST /lead-export-history/refresh, /refresh-and-export and /re-export run as background jobs on the server. When the work finishes within about 75 seconds they answer as usual. Otherwise the server answers 202 with a jobId, keeps working, and the script follows the job with GET /jobs/{jobId} (progress goes to stderr) until it has the final answer, which it then handles exactly like the original call: exports and files are saved the same way, and errors look the same.

• Each of these calls sends an idempotency key and the script prints it. If a call times out or the connection drops, re-run the exact same command with --idempotency-key set to that value: the server returns the same job (still running, or its result) instead of exporting or sending again. The key stays with the job for up to about 25 hours after it finishes (about 48 hours for a schedule trigger); a server restart forgets it. A 409, 429 or 503 answer, and an export's 402 insufficient_credits, does not use up the key. Any other answer, an error included, comes back again for that key: after an error answer, or to change any argument, run the command without --idempotency-key so the script sends a new key.
• --async asks the server to answer 202 at once and prints the jobId; --no-wait prints the jobId instead of following a 202. Get the result later with python3 smb_api.py GET /jobs/{jobId}, which waits for it and saves any file. --job-timeout SEC (default 3600) is how long the script follows a job before printing its jobId instead.
• The result of a finished job is normally kept 60 minutes (24 hours for a schedule trigger), sooner under heavy load or after a server restart. After that GET /jobs/{jobId} answers 410 job_result_expired for about a day, with a message that says where to look, and then 404 job_not_found (the script adds advice). Never repeat an export or a schedule trigger then: check what it already did first. Exports: the files are in GET /export-history for 90 days and the leads in GET /lead-export-history; a re-run with maxCredits 0 (without excludePurchased) returns leads already paid for at no charge. Schedule sends: lastSent and totalSentCount in GET /email-schedules. A server restart also interrupts a running job; what it already saved stays saved, and leads you already received are never charged twice.
• To get the result of a running export use GET /jobs/{jobId}, never the export again: a new export after it finished (or with other arguments) picks new leads first and charges for them; an identical export while it runs returns the same job.

Rate limits, errors and retries

Limit	Applies to
600 requests per minute per API key	Every authenticated endpoint
5 per minute per API key, shared	POST /leads/export, the three POST /lead-export-history/... calls and POST /email-schedules/{id}/trigger
5 per minute per API key, shared	POST /ai/suggest-categories, POST /ai/generate-keywords, POST /ai/auto-refine/enable
10 lead searches at a time per account	GET /leads, GET /leads/preview, POST /leads/export (more returns 429 lead_query_capacity_busy)
3 exports, 5 schedule triggers, 3 category suggestions and 2 of each lead-export-history call running at once per account	The long-running calls (more returns 429 job_capacity_busy, Retry-After: 30)
60 per minute per account, shared with the dashboard and the MCP server	Every /integrations call; POST /integrations/{provider}/connect also 30 per minute
5 per hour / 30 per hour per IP	POST /purchase / POST /claim-key

Failed requests count toward the limits. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (an ISO timestamp) and, on a 429 or 503, Retry-After (seconds).

Status	Meaning	What to do
202	A long-running call is still working; the body has a jobId	The script follows it (see Long-running calls); with --async or --no-wait, run GET /jobs/{jobId} later. Do not repeat the original call without its idempotency key
400	Bad request (bad_request, validation_error with details, invalid_request); export_too_large comes after the credits were charged	Fix the request; for export_too_large follow XLSX limit under Exporting files and do not repeat the export
401	Missing, invalid or revoked API key	Ask the user to check SMB_SALES_BOOST_API_KEY
402	insufficient_credits (rare: credits ran out between check and charge), or a card problem (payment_failed, payment_declined, authentication_required)	Read error; for a card problem the user updates their card in the dashboard. An export's 402 charged nothing and does not use up its idempotency key: after the user buys credits, re-run it with the same --idempotency-key
403	No active subscription, or a feature not available on this account or during a trial	Explain; do not retry
404	Unknown endpoint or id; job_not_found from GET /jobs/{jobId} (unknown id, a job that finished more than about a day ago, or a job a server restart interrupted)	Check the id; for a lost job, check what it already did (export history, lead export history, lastSent) before running it again
409	Conflict (plan_change_in_progress, already_subscribed, not_ready, integration_exists, integration_limit, conflict, idempotency_key_reused, schedule_run_in_progress and others); nothing changed	Show the message; retry only when it says so (for an integration conflict, read the integration again first; for idempotency_key_reused, the key belongs to a different request: drop --idempotency-key)
410	gone: export file expired or not stored; plan_retired from POST /purchase; job_result_expired: a finished job's result is no longer kept	For gone, re-export free via /lead-export-history/re-export; for plan_retired, pick a current plan; for job_result_expired (answered for about a day, then 404 job_not_found), follow its message and do not repeat the call
429	Rate limit, lead_query_capacity_busy, job_capacity_busy (too many long-running calls at once) or charge_in_progress (from GET /leads or an export: another export, search or push of the account is still being charged); nothing was charged	Wait Retry-After (the script retries by itself, up to 60 s, except on integration calls other than GET, where it returns the error with advice)
500	Server error	On charging calls and integration changes do NOT repeat blindly (see Rule 6); a 500 from push-lead may have taken a credit, so check GET /me and the deliveries first
502	provider_error: a connected CRM's API failed (field lists, pipelines, mapping test)	Try again later; check the CRM connection in GET /integrations/{id}
503	service_unavailable or schema_types_warming (right after a server restart), temporary; provider_unavailable: that integration provider is not available yet (no Retry-After)	For service_unavailable retry after Retry-After (the script does this, except on integration calls other than GET: check GET /integrations or the deliveries first, then repeat once); for provider_unavailable tell the user and do not retry
524	Network edge timeout after about 100 seconds; the server may still finish	Long-running calls answer 202 instead, so this is rare; re-run with the printed --idempotency-key, otherwise treat it like a 500 on charging calls

Errors look like {"error": "code", "message": "Human-readable text"}; the script adds httpStatus, and advice where a failure may have had an effect.

Natural language examples

User says	Call
"Find new dental practices in Texas"	Preview, then GET /leads with positiveKeywords: ["*dental*","*dentist*","*orthodont*"], stateInclude: ["TX"], limit, maxCredits
"Med spas in Florida with a buying signal this week"	positiveKeywords: ["*med*spa*","*medical*spa*","*aesthet*","*botox*"], stateInclude: ["FL"], lastBuyingSignalFrom: "rel:7d"
"Auto repair shops in Chicago that just got a new phone number"	positiveKeywords: ["*auto*repair*","*mechanic*","*body*shop*"], cityInclude: ["Chicago"], buyingSignalTypeFilter: ["Phone Primary"]
"Pet groomers in California, no boarding or kennels"	positiveKeywords: ["*pet*groom*","*dog*groom*"], negativeKeywords: ["*boarding*","*kennel*"], stateInclude: ["CA"]
"Only leads with an email address"	add emailPrimaryEmptyFilter: "exclude_empty"
"Well-reviewed restaurants in Atlanta"	positiveKeywords: ["*restaurant*","*grill*","*bistro*"], cityInclude: ["Atlanta"], minRatingValue: 4.5, minReviewCount: 50
"Businesses that registered their domain in the last 3 months"	a keyword filter plus registrationDateFrom set to the date 3 months ago as YYYY-MM-DD
"How many bakeries are in New York?"	GET /leads/preview, read data.pagination.total
"Show me only leads I already bought"	GET /lead-export-history (every lead you received, paged with limit and offset, free). To limit it to one search, run GET /leads with that search's filters and maxCredits: 0 on every page, because each page only keeps the already-received leads among that page's matches
"Export the results but spend at most 50 credits"	POST /leads/export with maxCredits: 50
"Export only leads I don't have yet"	POST /leads/export with excludePurchased: true and a maxCredits agreed with the user (every lead in this export costs 1 credit)
"Download my export from last week"	GET /export-history, then GET /export-history/{id}/download
"Get me the contact details for these 200 websites"	POST /enrichments (state the prices, agree on maxCredits, --confirm)
"Email me new HVAC leads in Ohio every morning"	Create a positive keyword list with the HVAC keywords, then a preset whose hash has nkl set to that list's id and si=OH, create the schedule with intervalValue: 1, intervalUnit: "days" and isActive: false, review, then activate. There is no time-of-day setting: the first email goes out within about 15 minutes of activation and later ones about a day after the previous send, so the time drifts. Tell the user this instead of promising a fixed time
"How many credits do I have?"	GET /me, totalCreditsRemaining
"Buy 1,000 more credits"	Confirm the price, then POST /purchase-credits with creditCount: 1000 and --confirm
"Upgrade to Scale"	Confirm price and timing, then POST /subscription/change-plan with targetPlan: "scale" and --confirm
"I want to sign up for Growth"	Explain the trial and charge date, then POST /purchase with --confirm
"Send every new lead to my Zapier webhook"	Describe the destination host, events and data, get a yes, then POST /integrations/webhook with provider: "zapier", the URL and events: ["lead.created"] and --confirm; hand the signingSecret to the user once
"Connect my HubSpot"	Explain what will flow to HubSpot, get a yes, then POST /integrations/hubspot/connect with --confirm, give the user the authorizationUrl to open within 10 minutes, then check GET /integrations
"Which integrations do I have, and are they working?"	GET /integrations (status, consecutiveFailures, lastSuccessAt), then GET /integrations/{id}/deliveries
"My HubSpot integration stopped working"	GET /integrations/{id} and its deliveries; if it is needs_attention because HubSpot access was removed or expired, get a yes, then POST /integrations/hubspot/connect with --confirm and have the user sign in to the same HubSpot account (its events, field mapping and delivery history are kept)
"Stop sending leads to Make for now"	PATCH /integrations/{id} with {"status": "disabled"} (no --confirm needed); re-enabling later needs the user's yes

smb_api.py reference

Option	Purpose
--params JSON / --params-file PATH	Query parameters (any method). Lists as JSON arrays. - reads stdin.
--body JSON / --body-file PATH	JSON body for POST, PATCH and PUT.
--confirm	Required for calls that charge money, authorize future charges, send email, spend credits on enrichment, search or export without maxCredits, send lead data to an outside destination (integration create, connect, re-point, re-enable, header apiKey change, test, push, delivery retry, field-mapping change or test), cancel or delete. Add only after the user approves. python3 smb_api.py --help lists every gated call.
--dry-run	Show the request (URL, body, whether --confirm is needed) without sending it.
--compact	Print only key fields of each lead.
--out NAME	Also save the full JSON response as NAME.json in the output folder.
--output-dir DIR	Where files are saved. Default: $SMB_SALES_BOOST_OUTPUT_DIR, else /mnt/user-data/outputs if it exists, else ./smb-sales-boost-files.
--idempotency-key KEY	Reuse the key a timed-out call printed: POST /purchase-credits (within 24 hours) or a long-running call (the same job comes back instead of a second export or send).
--async / --no-wait	Long-running calls: answer 202 at once / do not follow a 202; both print the jobId for a later GET /jobs/{jobId}.
--job-timeout SEC	How long to follow a long-running call before printing its jobId instead (default 3600).
--timeout SEC	Network timeout (default 180).
--no-retry / --no-fetch	Do not retry 429/503 (integration calls other than GET are never retried) / print a download link instead of downloading.

File handling: exports, /export-history/{id}/download, /export-history/{id}/download-url, the lead-export-history files, /enrichments/{id}/download and the files in a GET /jobs/{jobId} result are saved automatically as new files (never overwriting; mode 600), and the script prints the paths. Short-lived download links are used directly and not printed, unless you pass --no-fetch (the printed link then works without an API key for a few minutes, so do not share or log it). Exit codes: 0 success (also a long-running call printed as still running), 1 API error (or an unexpected client error), 2 usage error or confirmation required (nothing was sent), 3 network error or timeout, 4 local file error (the script creates the output folder before sending, so a folder problem stops it before anything is charged).

Security

• No shell injection: the script sends structured JSON over HTTPS with Python's standard library; user text never becomes part of a shell command when you use --params-file / --body-file for text with quotes.
• Fixed destination: requests go only to https://smbsalesboost.com/api/v1; endpoints are validated (no .., no other hosts), redirects are never followed, and the key is never sent to /purchase or /claim-key. Download links are fetched without the key, over HTTPS, and only from Amazon S3 (amazonaws.com) hosts.
• Safe files: file names from the server are reduced to a plain base name, limited to .csv, .json and .xlsx, and written only inside the output folder as new files readable only by the user.
• Key handling: read from SMB_SALES_BOOST_API_KEY and sent only in the Authorization header. It is never printed, logged or written to a file. Passing it as the first argument still works but exposes it to other local processes; prefer the environment variable.
• Confirmation gate: money, email, deletion, enrichment, uncapped search and export, and integration calls that send lead data outside SMB Sales Boost are refused without --confirm. Paths are matched without regard to case, so /Integrations/5/Push-Lead is gated like /integrations/5/push-lead.
• One-time secrets: the script never saves the response of POST /integrations/webhook with --out, because it holds the one-time signingSecret. Pass a body that contains a Clay apiKey (on create or on PATCH /integrations/{id}) with --body-file, not --body.

Not available through the API

These are managed in the dashboard (https://smbsalesboost.com/dashboard): creating or revoking API keys (when revoking a key, the user can choose to also pause every integration that key set up); updating the card or viewing invoices; undoing a cancellation; target categories for keyword generation; the default "email enrichment results" setting. A remote MCP server is also available at https://smbsalesboost.com/mcp (details: https://smbsalesboost.com/.well-known/mcp/server-card.json).