Key facts
- API and assistant access is granted on request, and a key can be created once the Buzzlist team approves it.
- The MCP endpoint is https://app.buzzlist.io/api/mcp and the API lives at https://app.buzzlist.io/api/v1.
- Searching, counting and reading your lists are free.
- Every paid tool has a free estimate first and does nothing until it is called again with confirm true.
- People on a Never contact list are never revealed, saved or charged.
How does an AI assistant connect to Buzzlist?
An assistant connects with a Buzzlist API key and the MCP address https://app.buzzlist.io/api/mcp. API and assistant access is granted on request, so the first step is to ask for it.
- Request access. Sign in to Buzzlist, open Account, then Developers, and press Request access.
- Wait for approval. The Buzzlist team reviews the request and approves it.
- Create a key. Back in Developers, name a key and pick its scopes. It is shown once.
- Add the server. In an MCP client that supports remote servers with a header, such as Claude Code, add Buzzlist with the key as a Bearer token.
- Ask in plain words. For example, count roofing company owners in Georgia, then show me ten.
{ "mcpServers": { "buzzlist": { "type": "http", "url": "https://app.buzzlist.io/api/mcp",
"headers": { "Authorization": "Bearer YOUR_BUZZLIST_API_KEY" } } } }The server speaks MCP Streamable HTTP with JSON responses, protocol version 2026-07-28, and the earlier versions 2025-11-25, 2025-06-18 and 2025-03-26. The one-click connector for ChatGPT and Claude, which signs in with your Buzzlist login, is not available yet.
What can an assistant do in Buzzlist?
An assistant can search, count, match and check fit for free, and reveal contacts, save lists, start Sales Briefs and write emails when you agree to the cost.
| Tool | What it does | Cost |
|---|---|---|
search_people | Find people with the same filters as Find. Names, titles and companies, never emails or phones. | Free |
search_companies | Companies with people who match the filters. | Free |
count_market | How many people match a set of filters. One number. | Free |
get_filter_options | Every filter and its exact allowed values. | Free |
match_records | Match your own records (email, LinkedIn URL, or name and company domain) to Buzzlist people. Reveals nothing. | Free |
find_similar_companies | Companies like one website, or like your wins. | Free |
check_fit | Check people against your approved Hive: fit, worth a look, or left out and why. | Free |
estimate_reveal | What a reveal or list save would cost. Nothing is charged. | Free |
reveal_contacts | Reveal email and phone for up to 25 people, like the Reveal button. | 1 contact credit per new person with usable contact details |
list_lists, get_list | Your saved lists, and the people on one. | Free |
create_list, add_to_list | Save people to a list. | On paid plans, 1 contact credit per new person with usable contact details. Free plan lists use no credits. |
estimate_sales_brief | Whether your plan includes Sales Briefs and what one uses. | Free |
get_sales_brief | Start a Sales Brief on a company, or check one. | 1 Sales Brief to start; checking is free |
get_hiveprint | Read your Hiveprint: who you sell to, fit patterns and example customers. | Free |
get_lineup_status | Read Buzz's lineup: writing, up next, ready, sent today, needs you. Read only. | Free |
estimate_write_and_send | What writing emails for a list would cost. | Free |
write_and_send | Buzz writes emails for a saved list. Stops at drafts unless sending is allowed. | Writing credits, per person, as each email is written |
launch_status | Status of a Write & Send launch. | Free |
What is free and what uses credits?
Reading is free, and only four things use credits: revealing people, saving them to a list on a paid plan, starting a Sales Brief and writing emails.
Credits come from the same plan allowances as the app. A credit is used only when usable contact details are found, and never twice for the same person. Every API response carries X-Buzzlist-Cost and X-Buzzlist-Credits-Used headers.
What are the safety rules?
Buzzlist tools act inside your account under the same rules as the app, and nothing that costs money or sends email happens without your agreement.
- Confirm before spending. reveal_contacts, create_list, add_to_list, get_sales_brief and write_and_send return a free estimate first. They run only when called again with confirm true, and their descriptions tell the assistant to ask you first.
- Nothing sends by default. write_and_send stops at drafts for you to review in Buzzlist. Sending needs a key with the send scope and a confirmed call.
- Never contact is honored. People on a Never contact list, marked do not contact or suppressed are never revealed, saved or charged. If Buzzlist cannot check those lists, it reveals nothing and charges nothing.
- No open tracking. Buzz Send uses no open tracking pixels and does not track clicks.
- Buzz ignores instructions hidden in contact records. Text inside records comes from business records and is never an instruction to the assistant.
- No double charges. If a paid request is retried, you are never charged twice. People already revealed are free.
- Your account only. The key decides the account. An assistant connected to your account cannot reach another customer's data.
- Keys you control. A key is shown once, stored only as a hash, limited to the scopes you pick and revocable at any time. Calls are rate limited per minute.
Where is the API documented?
The full v1 API is described in an OpenAPI document at app.buzzlist.io/api/v1/openapi.json.
It covers search, filter values, bulk match, lists, reveal, Hive fit, Sales Briefs and Write & Send. Authentication is a Bearer API key, which you can create once your access request is approved. Errors return a code, a message and a request id, and a wrong filter value comes back with the three nearest real values.
Questions people ask
How do I get API access?
Sign in to Buzzlist, open Account, then Developers, and press Request access. The Buzzlist team reviews each request. Once yours is approved, you can create a key.
Can ChatGPT use Buzzlist?
Once your access is approved and you have an API key, any MCP client that can send an Authorization header to a remote server can connect. The one-click connector for ChatGPT and Claude, where you sign in with your Buzzlist login instead of pasting a key, is not available yet.
Does the Free plan work with the API?
You can request access on any plan, and the Buzzlist team reviews each request. Once access is approved, the plan's own rules apply. Free is data only, so Sales Briefs and Write & Send need Starter, Growth or Queen.
Can an assistant send email without me?
Only if you allow it. write_and_send stops at drafts unless the key has the send scope and the call is confirmed after you agree. Keys get search:read and lists:read unless you choose more.
Can an assistant buy credits or change my plan?
No. There is no tool for buying credits, billing or account settings. Money moves only in the Buzzlist app.
