REST API v1

BasedOnB API Reference

Automate Google Maps lead scraping, manage webhooks, and integrate with your CRM or workflow automation tools.

Quick Start

curl https://www.basedonb.com/api/v1/account \
  -H "Authorization: Bearer bdb_live_YOUR_KEY_HERE"

Authentication

All API requests (except GET /api/v1/health) require an API key. Generate one from Settings → API Keys.

Pass your key in one of two ways:

Authorization header (recommended)

Authorization: Bearer bdb_live_...

X-API-Key header

X-API-Key: bdb_live_...

Base URL

https://www.basedonb.com/api/v1

Rate Limits

100 requests / minute per API key. Exceeding this returns 429 Too Many Requests.

Endpoints

Health

Account

Scrapes

Geodata

Look up the country / state / city values accepted by the Scrapes API. States follow the GeoNames dotted code format (US.TX, TR.34, DE.02). Countries without a state subdivision return an empty states array — submit those jobs with only country.

Credits & Billing

Webhooks

Webhooks deliver real-time event notifications to your endpoint. Each request includes an X-Webhook-Signature: sha256=<hex> header for verification.

Webhook Payload

Example scrape.done payload delivered to your endpoint:

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Event-Type: scrape.done
User-Agent: BasedOnB-Webhook/1.0

{
  "event": "scrape.done",
  "created_at": "2026-01-15T10:05:00Z",
  "data": {
    "scrape_id": "job-uuid",
    "query": "restaurants",
    "city": "Istanbul",
    "country": "Turkey",
    "leads_found": 47,
    "credits_charged": 47
  }
}

Verifying Webhook Signatures

Verify the X-Webhook-Signature header to ensure requests come from BasedOnB. Find your webhook secret in Settings → Webhooks.

import { createHmac } from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
  return expected === signature;
}

// In your endpoint handler:
const body = await req.text();
const sig = req.headers.get("X-Webhook-Signature") ?? "";
if (!verifyWebhook(body, sig, process.env.WEBHOOK_SECRET!)) {
  return new Response("Unauthorized", { status: 401 });
}

API Key Management

Error Codes

HTTP Status	Code	Description
401	unauthorized	Missing or invalid API key
403	forbidden	API key valid but not allowed for this resource
404	not_found	Resource not found
400	bad_request	Invalid request parameters
402	insufficient_credits	Not enough credits to start a scrape
429	rate_limited	Too many requests. Retry after 1 minute
500	internal_error	Unexpected server error

Error response format:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. You have 3 but need 50."
  }
}

Ready to build?

Generate your first API key in Settings and start scraping in minutes.

Get API Key View Integrations