REST API v1

Référence API BasedOnB

Automatisez le scraping de prospects Google Maps, gérez les webhooks et intégrez vos outils CRM ou d'automatisation de flux.

Démarrage rapide

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

Authentification

Toutes les requêtes API (sauf GET /api/v1/health) nécessitent une clé API. Générez-en une depuis Paramètres → Clés API.

Transmettez votre clé de l'une des deux façons :

En-tête Authorization (recommandé)

Authorization: Bearer bdb_live_...

En-tête X-API-Key

X-API-Key: bdb_live_...

URL de base

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

Délai de réponse

100 requêtes / minute par clé API. Un dépassement renvoie 429 Too Many Requests.

Points de terminaison

Santé

Compte

Scrapes

Géodonnées

Recherchez les valeurs pays / état / ville acceptées par l'API Scrapes. Les états suivent le format de code en points GeoNames (US.TX, TR.34, DE.02). Les pays sans subdivision renvoient un tableau states vide — soumettez ces tâches avec uniquement country.

Crédits & Facturation

Webhooks

Les webhooks livrent des notifications d'événements en temps réel à votre endpoint. Chaque requête inclut un en-tête X-Webhook-Signature: sha256=<hex> pour la vérification.

Charge utile du webhook

Exemple de charge utile scrape.done livrée à votre 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
  }
}

Vérifier les signatures des webhooks

Vérifiez l'en-tête X-Webhook-Signature pour vous assurer que les requêtes proviennent de BasedOnB. Trouvez votre secret webhook dans Paramètres → 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 });
}

Gestion des clés API

Codes d'erreur

Statut HTTP	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

Format de réponse d'erreur :

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

Prêt à construire ?

Générez votre première clé API dans Paramètres et commencez à scraper en quelques minutes.

Obtenir une clé API Voir les intégrations