Margo
API Documentation

Margo API Reference

Integrate Margo's lead generation into your apps, agents, and workflows. Generate verified local business leads with a single API call.

Base URL: https://margoleads.io/apiv1 — Stable

Getting Started

The Margo API lets you programmatically generate local business leads. To get started:

  1. Create a Margo account and subscribe to the Business plan (API access is exclusive to Business)
  2. Go to Dashboard → API Keys and generate a key
  3. Make your first API call using the example below
bash
curl -X POST https://margoleads.io/api/v1/leads/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "dentist",
    "state": "US",
    "city": "Miami",
    "maxResults": 10
  }'

Authentication

All API requests require a Bearer token in the Authorization header.

http
Authorization: Bearer margo_sk_xxxxxxxxxxxxxxxxxxxx

Security: Never expose your API key in client-side code. Store it in environment variables (e.g. MARGO_API_KEY) and make API calls from your backend.

Managing Keys

Create, view, and revoke API keys from the API Keys page in your dashboard. Keys are shown only once at creation — store them securely.

Generate Leads

POST/api/v1/leads/generate

Generate local business leads by category and location. Returns verified contact details, social profiles, and review data.

Request Body

categorystringrequired

Business type to search for. Examples: "dentist", "restaurant", "plumber", "hair_salon"

statestringrequired

Country code (ISO 3166-1 alpha-2). Examples: "US", "GB", "DE", "AU"

citystring

City or region name to narrow results. Examples: "Miami", "London", "Berlin"

keywordstring

Additional keyword filter for more specific results. Example: "endodontist", "matcha"

maxResultsnumber

Maximum number of leads to return. Default: 25. Max: 100.

Supported Business Categories

accountantarchitectbakerybankbarbeauty_saloncafecar_dealercar_repaircleaning_serviceclothing_storeconsultantcontractordentistdoctorelectricianelectronics_storeentertainmentevent_servicefinancial_advisorfurniture_storegymhair_salonhotelhvacinsurance_agencyit_serviceslandscapinglawyermarketing_agencymedia_productionmedical_specialistpet_storephotographerplumberreal_estate_agencyrestaurantschoolspatherapistveterinarianweb_designeryoga_studio

Supported Countries

US, GB, AU, CA, NZ, AE, AR, BE, BR, ES, IE, KR, MX, NL, PL, SE, TH, TR, FR, IT, IN, JP, DE

Response Format

Successful responses return a JSON object with a leads array:

json
{
  "leads": [
    {
      "businessName": "Bright Smile Dental",
      "contactName": "Dr. Sarah Johnson",
      "email": "[email protected]",
      "phone": "+1 (305) 555-0123",
      "address": "1234 Ocean Drive, Miami, FL 33139",
      "website": "https://brightsmile.com",
      "emailVerified": true,
      "rawData": {
        "facebook": "https://facebook.com/brightsmile",
        "instagram": "https://instagram.com/brightsmile",
        "linkedin": "https://linkedin.com/company/brightsmile",
        "google_maps_url": "https://maps.google.com/?cid=...",
        "review_score": 4.8,
        "reviews_number": 234,
        "google_business_categories": ["dentist", "cosmetic_dentist"]
      }
    }
  ],
  "count": 1,
  "source": "database",
  "creditsUsed": 1,
  "creditsRemaining": 9999
}

Lead Object Fields

businessNamestring

Name of the business

contactNamestring

Contact person name (if available)

emailstring | null

Business email address

phonestring | null

Phone number

addressstring

Full street address

websitestring | null

Business website URL

emailVerifiedboolean | null

Whether the email has been verified

rawData.facebookstring | null

Facebook page URL

rawData.instagramstring | null

Instagram profile URL

rawData.linkedinstring | null

LinkedIn company page URL

rawData.google_maps_urlstring | null

Google Maps listing URL

rawData.review_scorenumber | null

Google review score (0–5)

rawData.reviews_numbernumber | null

Total number of Google reviews

rawData.google_business_categoriesstring[]

Google Business categories

Skill Manifest (AI Agents)

Margo provides a machine-readable skill manifest that AI agents can use to discover and interact with the API. Download it with:

bash
curl -o margo-skill.json https://margoleads.io/api/v1/skill

The manifest describes available endpoints, parameters, authentication, and response schemas. Import it into your AI agent framework (e.g. OpenClaw, LangChain, CrewAI) to enable lead generation capabilities.

Tip: You can also download the skill file from the API Keys page in your dashboard.

Rate Limits & Quotas

API usage is tied to your subscription plan. Each lead returned counts as one credit against your monthly quota.

PlanLeads/MonthRate LimitPrice
Starter500—$29/mo
Professional2,500—$59/mo
Business10,000120 req/min$99/mo

When you exceed your monthly quota, the API returns a 429 status. Upgrade your plan or wait for the next billing cycle.

Error Handling

The API uses standard HTTP status codes:

CodeMeaningResolution
200Success—
400Bad RequestCheck required parameters (category, state)
401UnauthorizedInvalid or missing API key
403ForbiddenAPI access not available on your plan
429Rate Limited / Quota ExceededWait or upgrade your plan
500Server ErrorRetry after a moment; contact support if persistent
json
{
  "error": "Monthly lead quota exceeded",
  "code": "QUOTA_EXCEEDED",
  "limit": 500,
  "used": 500,
  "resetDate": "2026-03-01T00:00:00Z"
}

Examples

Python

python
import requests
import os

response = requests.post(
    "https://margoleads.io/api/v1/leads/generate",
    headers={
        "Authorization": f"Bearer {os.environ['MARGO_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "category": "restaurant",
        "state": "GB",
        "city": "London",
        "maxResults": 25,
    },
)

data = response.json()
for lead in data["leads"]:
    print(f"{lead['businessName']} — {lead['email']} — {lead.get('rawData', {}).get('instagram', 'N/A')}")

JavaScript / Node.js

javascript
const response = await fetch("https://margoleads.io/api/v1/leads/generate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MARGO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    category: "plumber",
    state: "US",
    city: "New York",
    maxResults: 10,
  }),
});

const { leads } = await response.json();
leads.forEach(lead => {
  console.log(`${lead.businessName} | ${lead.email} | ${lead.phone}`);
});

cURL

bash
curl -X POST https://margoleads.io/api/v1/leads/generate \
  -H "Authorization: Bearer $MARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"gym","state":"AU","city":"Sydney","maxResults":20}'

Plans & Pricing

API access is exclusive to the Business plan. Your monthly lead quota determines how many leads you can generate via both the dashboard and the API.

Starter

$29/mo

Dashboard only

500 leads/mo

Professional

$59/mo

Dashboard only

2,500 leads/mo

Business

$99/mo

Dashboard + API access

10,000 leads/mo

View full plan comparison →

Support

Need help with the API?

Response times: Free plan — 48h, Starter — 24h, Professional — 12h, Business — Priority support.