BasedOnB + n8n
n8n talks to BasedOnB directly. Call the REST API from an HTTP Request node to build deterministic lead pipelines, or hand the whole API to an AI Agent through the MCP endpoint and let it choose what to search for.
Prerequisites
- A BasedOnB account and an API key from API & Webhooks
- n8n Cloud or a self-hosted instance — both work the same way
- Somewhere to put the leads (Google Sheets, HubSpot, Airtable, your own database)
Three ways to connect
REST API
HTTP RequestDeterministic pipelines. You fix the niche, the city and the filters, and the workflow runs the same way every time.
MCP
MCP Client ToolAI Agent workflows. The agent picks the tools and arguments itself from a plain-language request such as finding dentists in a city that have no website.
Webhooks
Webhook triggerYou already start searches somewhere else and only want n8n to react when one finishes.
REST API setup
Create the credential once
In n8n, add a Bearer Auth credential holding your API key. Every BasedOnB node in the workflow reuses it, so the key never sits in a node parameter and never travels in an exported workflow.
Scopes needed: scrapes:read, scrapes:write
Start a search
POST to /api/v1/scrapes. Send an Idempotency-Key header so an automatic retry can never be billed twice.
POST https://www.basedonb.com/api/v1/scrapes
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: n8n-<workflow-id>-<execution-id>
{
"query": "dentist",
"city": "Manchester",
"country": "GB",
"target_leads": 25
}country is a two-letter ISO code. The response is the job itself, including its id and status.
Wait for it to finish
Poll the job until its status is done. The statuses are pending, submitted, running, done, failed and cancelled.
Two things that catch people out
The n8n Wait node defaults its unit to hours. Set it to seconds explicitly, or a loop that looks like a 15-second poll will actually wait fifteen hours.
A search whose data is already in the shared pool can come back done on the very first response, so let the workflow go straight to the results rather than always waiting a cycle first.
Fetch the leads
GET the job's results endpoint, then use a Split Out node on the results field to get one n8n item per business.
Before the job has finished, that endpoint answers 200 with an empty array rather than an error. That is exactly why step 3 gates on the status instead of simply retrying here.
The shape of a working pipeline
Form or Schedule trigger | Validate the input reject bad input before spending credits | Start BasedOnB search HTTP Request - POST /scrapes | Check status --- done? --- no --> Wait 15s --> poll again | give up after 15 minutes yes | Fetch leads HTTP Request - GET the results endpoint | Split Out on "results" | Filter for example, keep businesses with no website | Google Sheets, HubSpot, or your own CRM
Bound the loop twice: stop on a failed or cancelled job, and give up after a wall-clock timeout so a stuck job can never loop forever.
AI Agent setup with MCP
The MCP endpoint hands an AI Agent ten BasedOnB tools: starting and cancelling searches, reading status and results, browsing countries, states and cities, and checking the account balance. The agent chooses which to call, which suits open-ended research that has no fixed shape.
- Endpoint: https://www.basedonb.com/api/mcp
- Node: MCP Client Tool, version 1.2 or newer
- Transport: HTTP Streamable
- Auth: MCP OAuth2, with Dynamic Client Registration left enabled
n8n discovers the OAuth metadata and stores the rotating refresh token, so the credential is created once and then left alone. Bearer Auth with an API key carrying the mcp scope works too. Both paths spend the same account credits as the REST API.
How credits are charged
A search costs credits equal to the target_leads you ask for, and they are taken when the job is submitted — not when the results come back, and not per row that survives your filters. Asking for 100 leads and keeping 12 of them still costs 100. Build and test with small numbers first.
What a lead looks like
{
"id": "job-uuid",
"status": "done",
"results": [
{
"place_id": "0x14cab9...",
"title": "Example Dental Practice",
"category": "Dentist",
"address": "12 High Street, Manchester",
"phone": "+44 161 000 0000",
"website": null,
"rating": 4.3,
"reviews_count": 168,
"email": null,
"socials": null,
"tech_stack": null
}
],
"page": { "limit": 500, "next_cursor": null, "has_more": false, "total": 1 }
}A website of null is the signal web design agencies filter on. Email, socials and tech stack are filled in asynchronously after the job finishes, and only a business that has a website can have an email discovered — so for no-website prospects, phone is the contact channel.
Ready-made templates
Published in the n8n template library. Import one into your own instance, add your credentials, and it runs.
Find local businesses without websites and save them to Google Sheets
A form asks for a niche, a city and a country. The workflow searches Google Maps business data, drops every business that already lists a website, and appends the rest to a spreadsheet — a phone-ready prospect list for web design and local marketing agencies.
View on n8n.ioFrequently Asked Questions
Do I need n8n Cloud, or does self-hosted work?
Both work identically. The REST API and the MCP endpoint are ordinary HTTPS, so there is nothing to install on either side and no community node to add.
Should I use the REST API or MCP?
Use REST when the job always has the same shape — a niche, a city, a filter, a destination — because a deterministic workflow is easier to debug and cheaper to run. Use MCP when the request is open-ended and you want an agent to decide what to search for.
My polling loop never finishes. What is wrong?
Check the Wait node's unit. n8n defaults it to hours, so a node set to 15 with no unit waits fifteen hours instead of fifteen seconds. Set the unit to seconds explicitly.
How do I avoid being charged twice when a node retries?
Send an Idempotency-Key header when you start the search. Repeating the same key returns the original job instead of creating and billing a second one.
What happens if I ask for more leads than the area has?
The job finishes with whatever was found, and you are charged for what you requested. Keep target_leads close to what the area can realistically return.
Is there a rate limit?
100 requests per minute per API key. Polling a job every 15 seconds uses four of those a minute, so ordinary workflows never come close.