Surmado API: Integration Overview

Quick answer: Surmado API is live and production-ready. Every report (Signal, Scan, Solutions) includes an Intelligence Token providing instant API access to structured JSON data. No authentication required for Intelligence Tokens. RESTful design, standard HTTP GET requests, JSON responses. Perfect for workflow automation (Zapier, Make, n8n), custom dashboards, AI agent integration, and programmatic analysis. Rate limits: currently unlimited, future 100 req/min per token.

Reading time: 11 minutes

What you’ll learn:

• How Intelligence Tokens work with the API: every Surmado report includes token (format SIG-2025-11-XXXXX), token = instant API access at https://api.surmado.com/intelligence/{TOKEN}, no authentication required (token itself is the secret), RESTful JSON responses with structured data (presence_rate, authority_score, ghost_influence, competitors array, platform_variance breakdown), numeric values ready for computation (0.42 not “42%”), currently unlimited requests (future 100 req/min per token)
• Four primary integration patterns with use cases: workflow automation (Zapier/Make/n8n extracting tokens from emails → auto-populate Google Sheets tracking sheet every report), custom dashboards (Notion/Retool/web apps fetching metrics via API for live visibility display), AI agent integration (LangChain agents using Surmado data for strategic recommendations without human intervention), competitive monitoring (tracking 5 competitors quarterly with alerts if they improve faster than you)
• Real implementation examples with code: Zapier workflow (trigger on hi@surmado.com email → extract token → HTTP GET → parse JSON → add row to Google Sheets), Python tracking class (stores quarterly tokens, fetches metrics, calculates trend improvements like 42% → 48% = +6%), LangChain AI agent tool (agent queries Surmado API, analyzes 28% Presence Rate + 68% Ghost Influence, recommends “fix schema markup first” based on data)
• API roadmap showing what’s available now vs future: currently available Intelligence Token API (GET /intelligence/{token} with unlimited requests), launching 2025 (report creation API for programmatic report generation, webhook notifications when reports complete, batch operations for agencies running 20+ client reports), future 2026+ (trend analysis across multiple tokens, AI agent-optimized endpoints with strategic recommendations)
• Best practices for production use: cache responses since Intelligence Token data is immutable (report = snapshot in time, no need to re-fetch), implement error handling with exponential backoff retry logic, use async batch fetching for multiple tokens in parallel (aiohttp example fetches 10 tokens concurrently), monitor usage to prepare for future rate limits, store tokens in tracking sheet immediately to prevent loss

API is ready. Start integrating today.

---

Why We Built an API-First Product

The Integration Gap

Traditional tools (Gumshoe, Semrush, consultants):

• Manual report downloads (PDF only)
• No programmatic access to data
• Copy-paste metrics into spreadsheets
• Can’t automate workflows
• Not AI agent friendly

Surmado approach:

• Every report includes Intelligence Token = instant API access
• JSON data included (not just PDF)
• Automate everything (Zapier, Make, custom scripts)
• AI agents can query directly
• Integration-first design

We’re AI agent ready because we’re API-first.

---

Intelligence Token API (Available Now)

Endpoint

Base URL: https://api.surmado.com/intelligence/

Full endpoint: https://api.surmado.com/intelligence/{TOKEN}

Example:

curl https://api.surmado.com/intelligence/SIG-2025-11-A1B2C

Authentication: None required (token itself is the secret)

Response format: JSON

Rate limits: Currently unlimited (future: 100 req/min per token)

---

Response Structure

Signal token example:

{
  "product": "signal",
  "token": "SIG-2025-11-A1B2C",
  "created_at": "2025-11-10T14:23:11Z",
  "business": {
    "name": "Phoenix Cool Air",
    "industry": "HVAC",
    "location": "Phoenix, AZ"
  },
  "metrics": {
    "presence_rate": 0.42,
    "authority_score": 78,
    "ghost_influence": 0.28,
    "category_share": 0.046,
    "market_rank": 6,
    "total_competitors": 40
  },
  "competitors": [
    {
      "name": "Competitor A",
      "presence_rate": 0.54,
      "rank": 1
    },
    {
      "name": "Competitor B",
      "presence_rate": 0.38,
      "rank": 3
    }
  ],
  "platform_variance": {
    "chatgpt": {
      "presence_rate": 0.52,
      "mentions": 28
    },
    "claude": {
      "presence_rate": 0.38,
      "mentions": 21
    },
    "gemini": {
      "presence_rate": 0.41,
      "mentions": 22
    },
    "perplexity": {
      "presence_rate": 0.64,
      "mentions": 35
    }
  }
}

All numeric values (not percentages) for easy computation in code.

---

Quick Start (5 Minutes)

Step 1: Run any Surmado report

• Signal Essential/Pro: $25 or $50
• Scan Essential/Pro: $25 or $50
• Solutions: $50

Step 2: Get Intelligence Token from email

• Format: SIG-2025-11-XXXXX (Signal)
• Format: SCAN-2025-11-XXXXX (Scan)
• Format: SOLUTIONS-2025-11-XXXXX (Solutions)

Step 3: Make HTTP GET request

curl https://api.surmado.com/intelligence/SIG-2025-11-A1B2C

Step 4: Parse JSON response

import requests

token = "SIG-2025-11-A1B2C"
response = requests.get(f"https://api.surmado.com/intelligence/{token}")
data = response.json()

presence_rate = data["metrics"]["presence_rate"] * 100
print(f"Presence Rate: {presence_rate}%")

You’re done. No API keys, no OAuth, no authentication complexity.

---

Integration Patterns

Pattern 1: Workflow Automation (Zapier, Make, n8n)

Use case: Automatic quarterly tracking

Zapier workflow:

1. Trigger: New email from hi@surmado.com (Signal report delivered)
2. Extract: Parse email for Intelligence Token (SIG-2025-11-XXXXX pattern)
3. HTTP GET: https://api.surmado.com/intelligence/{token}
4. Parse JSON: Extract metrics (Presence Rate, Authority Score, etc.)
5. Action: Add row to Google Sheets tracking sheet

Result: Every Signal report automatically populates tracking spreadsheet (zero manual work).

Full Zapier guide →

---

Pattern 2: Custom Dashboard

Use case: Internal metrics dashboard (Notion, Retool, custom web app)

Implementation:

// Fetch latest Signal data
async function getLatestSignalMetrics(token) {
  const response = await fetch(`https://api.surmado.com/intelligence/${token}`);
  const data = await response.json();

  return {
    presenceRate: data.metrics.presence_rate * 100,
    authorityScore: data.metrics.authority_score,
    ghostInfluence: data.metrics.ghost_influence * 100,
    rank: data.metrics.market_rank,
    lastUpdated: data.created_at
  };
}

// Display in dashboard
const metrics = await getLatestSignalMetrics("SIG-2025-11-A1B2C");
dashboard.update(metrics);

Result: Live dashboard showing current AI visibility metrics (refresh anytime, no manual updates).

---

Pattern 3: AI Agent Integration

Use case: AI agent making strategic recommendations

Agent workflow:

1. Agent receives task: “Analyze our AI visibility and recommend next steps”
2. Agent fetches data: HTTP GET to Intelligence Token API
3. Agent analyzes: Presence Rate 28%, Ghost Influence 68%, Authority Score N/A
4. Agent recommends: “High Ghost Influence indicates attribution gap. Prioritize schema markup and content attribution over general visibility efforts.”

Example AI agent code (LangChain):

from langchain.agents import Tool
import requests

def fetch_surmado_metrics(token: str) -> dict:
    """Fetch Surmado Signal metrics for analysis"""
    response = requests.get(f"https://api.surmado.com/intelligence/{token}")
    return response.json()

surmado_tool = Tool(
    name="Surmado Signal Data",
    func=fetch_surmado_metrics,
    description="Fetches AI visibility metrics (Presence Rate, Authority Score, Ghost Influence) for strategic analysis"
)

# AI agent can now use Surmado data in decision-making
agent.tools.append(surmado_tool)

Result: AI agents can query your Surmado data programmatically (no human copy-paste required).

---

Pattern 4: Competitive Monitoring

Use case: Track 5 competitors quarterly, alert if they improve faster than you

Implementation:

import requests

# Your tokens (quarterly tracking)
your_tokens = {
    "Q1": "SIG-2025-02-A1B2C",
    "Q2": "SIG-2025-05-D3E4F",
    "Q3": "SIG-2025-08-G5H6J",
    "Q4": "SIG-2025-11-K7L8M"
}

# Competitor tokens (you ran Signal on them)
competitor_tokens = {
    "Competitor A": "SIG-2025-11-N9P0Q",
    "Competitor B": "SIG-2025-11-R1S2T",
    "Competitor C": "SIG-2025-11-U3V4W"
}

# Fetch all metrics
def get_presence_rate(token):
    response = requests.get(f"https://api.surmado.com/intelligence/{token}")
    return response.json()["metrics"]["presence_rate"] * 100

# Compare
your_current = get_presence_rate(your_tokens["Q4"])
competitor_rates = {name: get_presence_rate(token) for name, token in competitor_tokens.items()}

# Alert if competitor ahead
for name, rate in competitor_rates.items():
    if rate > your_current:
        print(f"ALERT: {name} has {rate}% Presence Rate (you have {your_current}%)")

Result: Automated competitive monitoring (no manual report comparisons).

---

AI Agent Ready Features

Why Surmado is AI Agent Friendly

1. RESTful JSON API (not HTML scraping):

• Agents can parse JSON natively
• Structured data (not unstructured text)
• Consistent schema across all responses

2. No authentication complexity for Intelligence Tokens:

• No OAuth flows (agents don’t need human intervention)
• No API key management (token is self-contained)
• No rate limiting (currently unlimited)

3. Semantic data structure:

• Field names are descriptive (presence_rate, not pr)
• Numeric values ready for computation (0.42, not “42%”)
• Timestamps in ISO 8601 format (standard parsing)

4. Error handling:

• Standard HTTP status codes (200, 404, 500)
• JSON error responses with clear messages
• Retry-friendly (idempotent GET requests)

---

AI Agent Use Cases

Strategic analysis agent:

Agent task: "Analyze our Q4 AI visibility and recommend Q1 priorities"

Agent actions:
1. Fetch Signal data via Intelligence Token API
2. Analyze: Presence Rate 28%, Ghost Influence 68%
3. Research: Check schema markup status (Scan API)
4. Recommend: "Q1 priority: Add LocalBusiness + Service schema (addresses Ghost Influence root cause)"

Competitive intelligence agent:

Agent task: "Monitor 3 competitors weekly, alert if significant changes"

Agent actions:
1. Store competitor Intelligence Tokens
2. Weekly: Fetch latest metrics via API
3. Compare: Current week vs previous week
4. Alert if: Presence Rate change > 5% or new competitor enters top 3

Content optimization agent:

Agent task: "Identify which personas need content optimization"

Agent actions:
1. Fetch Signal Pro data (persona-level breakdown)
2. Identify: Personas with <30% Presence Rate
3. Generate: Content brief for each weak persona
4. Output: Prioritized content calendar

---

Full API Roadmap (What’s Coming)

Currently Available

Intelligence Token API (GET /intelligence/{token})

• Signal, Scan, Solutions data access
• Unlimited requests (for now)
• No authentication required
• JSON responses

---

Launching 2025

Report creation API:

POST /v1/reports/signal
Authorization: Bearer sur_live_YOUR_KEY
Content-Type: application/json

{
  "company_name": "Phoenix Cool Air",
  "email": "you@company.com",
  "industry": "HVAC",
  "location": "Phoenix, AZ",
  "personas": [
    "Emergency AC repair Phoenix same-day",
    "AC installation Phoenix financing"
  ]
}

Response:

{
  "report_id": "rpt_1234567890",
  "status": "processing",
  "intelligence_token": "SIG-2025-11-A1B2C",
  "estimated_completion": "2025-11-10T14:35:00Z"
}

Use case: Programmatically create reports (agencies running 50+ reports/month via script).

---

Webhook notifications:

{
  "event": "report.completed",
  "report_id": "rpt_1234567890",
  "intelligence_token": "SIG-2025-11-A1B2C",
  "product": "signal",
  "created_at": "2025-11-10T14:28:45Z"
}

Use case: Real-time notifications when report completes (no polling required).

---

Batch operations:

POST /v1/reports/batch
Authorization: Bearer sur_live_YOUR_KEY

{
  "reports": [
    {"type": "signal", "company_name": "Client A", ...},
    {"type": "signal", "company_name": "Client B", ...},
    {"type": "scan", "url": "https://client-c.com", ...}
  ]
}

Use case: Agencies running reports for 20 clients in one API call.

---

Future (2026+)

Advanced querying:

GET /v1/analytics/trends?token=SIG-2025-11-A1B2C,SIG-2025-08-G5H6J,SIG-2025-05-D3E4F

Response: Trend analysis across multiple Intelligence Tokens (automatic quarter-over-quarter comparison).

---

AI agent endpoints (optimized for agent use):

POST /v1/agent/analyze
Authorization: Bearer sur_live_YOUR_KEY

{
  "intelligence_token": "SIG-2025-11-A1B2C",
  "analysis_type": "strategic_recommendations",
  "context": "We're a local HVAC company focused on emergency service"
}

Response: AI-optimized strategic recommendations (designed for agent consumption, not human PDF reports).

---

Integration Examples

Example 1: Zapier (No-Code)

Workflow: Signal report → Google Sheets

Steps:

1. Trigger: Gmail - New email from hi@surmado.com
2. Filter: Only emails with subject containing “Signal Report”
3. Formatter: Extract text matching SIG-\d{4}-\d{2}-[A-Z0-9]{5}
4. Webhooks: GET https://api.surmado.com/intelligence/{token}
5. Formatter: Parse JSON (extract metrics.presence_rate, metrics.authority_score)
6. Google Sheets: Add row

Result: Automatic tracking sheet updated every time you run Signal.

Full Zapier guide →

---

Example 2: Make.com (Visual Automation)

Workflow: Weekly competitor monitoring

Modules:

1. Schedule: Every Monday 9 AM
2. HTTP: GET competitor Intelligence Tokens (3 requests)
3. Tools: Aggregate responses
4. Google Sheets: Update “Competitor Tracking” sheet
5. Gmail: Send alert if any competitor’s Presence Rate > yours

Result: Weekly competitive intelligence email (zero manual work).

---

Example 3: Python Script (Custom Logic)

Use case: Quarterly tracking with custom analysis

import requests
from datetime import datetime

class SurmadoTracker:
    def __init__(self):
        self.base_url = "https://api.surmado.com/intelligence"
        self.tokens = []

    def add_token(self, token, quarter):
        """Store Intelligence Token with metadata"""
        self.tokens.append({"token": token, "quarter": quarter})

    def fetch_metrics(self, token):
        """Fetch metrics from API"""
        response = requests.get(f"{self.base_url}/{token}")
        return response.json()

    def analyze_trend(self):
        """Analyze trend across quarters"""
        results = []
        for item in self.tokens:
            data = self.fetch_metrics(item["token"])
            results.append({
                "quarter": item["quarter"],
                "presence_rate": data["metrics"]["presence_rate"] * 100,
                "authority_score": data["metrics"]["authority_score"],
                "ghost_influence": data["metrics"]["ghost_influence"] * 100
            })

        # Calculate improvements
        if len(results) >= 2:
            latest = results[-1]
            previous = results[-2]
            improvement = latest["presence_rate"] - previous["presence_rate"]
            print(f"Presence Rate: {previous['presence_rate']:.1f}% → {latest['presence_rate']:.1f}% ({improvement:+.1f}%)")

        return results

# Usage
tracker = SurmadoTracker()
tracker.add_token("SIG-2025-02-A1B2C", "Q1")
tracker.add_token("SIG-2025-05-D3E4F", "Q2")
tracker.add_token("SIG-2025-08-G5H6J", "Q3")
tracker.add_token("SIG-2025-11-K7L8M", "Q4")

trend = tracker.analyze_trend()
# Output: Presence Rate: 42.0% → 48.0% (+6.0%)

---

Example 4: AI Agent (LangChain)

Use case: Strategic analysis agent

from langchain.agents import initialize_agent, Tool
from langchain.llms import OpenAI
import requests

def get_surmado_metrics(token: str) -> str:
    """Fetch Surmado metrics and return formatted summary"""
    response = requests.get(f"https://api.surmado.com/intelligence/{token}")
    data = response.json()

    return f"""
    AI Visibility Metrics:
    - Presence Rate: {data['metrics']['presence_rate'] * 100:.1f}%
    - Authority Score: {data['metrics'].get('authority_score', 'N/A')}
    - Ghost Influence: {data['metrics'].get('ghost_influence', 'N/A') * 100:.1f}%
    - Market Rank: #{data['metrics']['market_rank']} of {data['metrics']['total_competitors']}
    - Top Competitor: {data['competitors'][0]['name']} ({data['competitors'][0]['presence_rate'] * 100:.1f}%)
    """

surmado_tool = Tool(
    name="Surmado AI Visibility Data",
    func=get_surmado_metrics,
    description="Fetches current AI visibility metrics including Presence Rate, Authority Score, and competitive positioning. Use this to understand how AI platforms currently recommend the business."
)

llm = OpenAI(temperature=0)
agent = initialize_agent([surmado_tool], llm, agent="zero-shot-react-description", verbose=True)

# Agent can now use Surmado data
result = agent.run("Analyze our AI visibility and recommend the top 3 priorities for improving our Presence Rate")

Agent output:

Based on your Surmado data:
- 28% Presence Rate (below competitive average of 42%)
- 68% Ghost Influence (high attribution gap)
- Ranked #6 of 40 (moderate competitive position)

Top 3 priorities:
1. Fix Ghost Influence (68% → <30% target): Add schema markup + content attribution
2. Improve persona-specific content: Create FAQ pages matching your submitted personas
3. Get authoritative citations: Publish in local media (currently no citations found)

Estimated impact: 28% → 40-45% Presence Rate in 90 days

---

Rate Limits and Best Practices

Current Limits

Intelligence Token API:

• Requests per minute: Unlimited (for now)
• Requests per day: Unlimited
• Concurrent requests: Unlimited

Future limits (when public API launches):

• 100 requests/minute per token
• 10,000 requests/day per token
• Standard HTTP 429 (Too Many Requests) if exceeded

---

Best Practices

1. Cache responses (data doesn’t change):

• Intelligence Token data is immutable (report is snapshot in time)
• Cache API response locally (no need to fetch every time)
• Refresh only when new report generated (quarterly, monthly)

2. Handle errors gracefully:

import requests
from time import sleep

def fetch_with_retry(token, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(f"https://api.surmado.com/intelligence/{token}", timeout=10)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            if attempt < max_retries - 1:
                sleep(2 ** attempt)  # Exponential backoff
                continue
            raise e

3. Use batch fetching (if fetching multiple tokens):

import asyncio
import aiohttp

async def fetch_token(session, token):
    async with session.get(f"https://api.surmado.com/intelligence/{token}") as response:
        return await response.json()

async def fetch_all_tokens(tokens):
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_token(session, token) for token in tokens]
        return await asyncio.gather(*tasks)

# Fetch 10 tokens in parallel
tokens = ["SIG-2025-11-A1B2C", "SIG-2025-11-D3E4F", ...]
results = asyncio.run(fetch_all_tokens(tokens))

4. Monitor usage (future-proofing):

• Track API calls in your application
• Log response times
• Alert if approaching rate limits (when they’re implemented)

---

Getting Started

Step 1: Get Your First Intelligence Token

Run any Surmado report:

• Signal Essential ($25)
• Signal Pro ($50)
• Scan Essential ($25)
• Scan Pro ($50)
• Solutions ($50)

Receive Intelligence Token in email (format: PRODUCT-YYYY-MM-XXXXX)

---

Step 2: Test API Access

cURL:

curl https://api.surmado.com/intelligence/YOUR_TOKEN

Python:

import requests
response = requests.get("https://api.surmado.com/intelligence/YOUR_TOKEN")
print(response.json())

JavaScript:

fetch('https://api.surmado.com/intelligence/YOUR_TOKEN')
  .then(response => response.json())
  .then(data => console.log(data));

---

Step 3: Build Your Integration

Choose your path:

• No-code: Zapier, Make.com workflows
• Low-code: Google Sheets Apps Script, Notion API
• Custom code: Python, Node.js, AI agents
• AI agents: LangChain, Meta AIIndex, custom agents

All paths use the same API (RESTful, JSON, standard HTTP).

---

Frequently Asked Questions

Is the API free?

Yes. Intelligence Token API is included free with every report.

Costs:

• Signal Essential/Pro: $25 or $50 (includes Intelligence Token + API access)
• Scan Essential/Pro: $25 or $50 (includes Intelligence Token + API access)
• Solutions: $50 (includes Intelligence Token + API access)

No additional fees for API usage.

When will report creation API launch?

2025. Exact date TBD.

Early access: Email hi@surmado.com to join waitlist (agencies and high-volume users prioritized).

Can I use Intelligence Tokens in production applications?

Yes. Intelligence Token API is production-ready.

Use cases:

• Customer dashboards (show clients their AI visibility metrics)
• Internal tools (automated tracking, competitive monitoring)
• AI agents (programmatic analysis and recommendations)

Stability: API schema is stable (breaking changes will be versioned).

What if I lose my Intelligence Token?

Contact hi@surmado.com with report details (business name, approximate date).

Support can look up token from records.

Prevention: Store tokens in tracking sheet immediately upon receiving report.

Can AI agents use Surmado API without human intervention?

Yes. That’s the point of “AI agent ready”.

Requirements:

• Agent has Intelligence Token (from previous report)
• Agent can make HTTP GET requests
• Agent can parse JSON

No human intervention needed for API access (no OAuth flows, no API key management).

Example: Agent runs weekly competitive analysis by fetching Intelligence Tokens programmatically.

---

Ready to integrate? Start with Intelligence Token guide → or Zapier automation →. API documentation and code examples available at api.surmado.com (launching 2025).