How Do Intelligence Tokens Work?

Every Surmado report includes an Intelligence Token (format: SIG-2025-11-XXXXX, SCAN-2025-11-XXXXX, or SOLUTIONS-2025-11-XXXXX) that unlocks structured JSON data for programmatic access, automation, and integrations.

Reading time: 10 minutes

What you’ll learn:

• How to access JSON data via direct URL (https://api.surmado.com/intelligence/TOKEN) without authentication
• Five common automation use cases: time-series tracking (chart 6-month Presence Rate trends), Zapier workflows (auto-add to Google Sheets), Notion dashboards, client reporting for agencies, and alert systems (notify if metrics drop)
• The specific JSON structure for each product (Signal: presence_rate/authority_score objects, Scan: issues array with severity, Solutions: recommendations with priority)
• Example Python/JavaScript code snippets for fetching and parsing Intelligence Token data programmatically
• Security considerations: tokens don’t expire (permanent access), are read-only, and should be treated like passwords (don’t commit to public repos)

What you get: PDF for humans, JSON for machines. Same data, different formats.

---

What Intelligence Tokens Are

Intelligence Token = Unique code giving you access to your report’s structured data.

Format examples:

• Signal: SIG-2025-11-A7K3M
• Scan: SCAN-2025-11-B9X2P
• Solutions: SOLUTIONS-2025-11-C4Y1Q

Where you find it:

• Top of PDF report (header)
• Email receipt after purchase
• Account dashboard (surmado.com/reports)

What it unlocks: JSON file containing all report data in structured, parseable format.

---

Why Intelligence Tokens Exist

Problem: PDF reports are human-readable but not machine-readable.

Example scenario:

• You run monthly Signal reports to track AI visibility over time
• You want to chart Presence Rate trends (Jan: 45%, Feb: 52%, Mar: 58%)
• PDF format requires manual copy-paste to spreadsheet (tedious, error-prone)

Solution: Intelligence Token gives you JSON file you can parse programmatically.

Result: Automated data extraction, trend analysis, dashboard integration.

---

How to Use Intelligence Tokens

Step 1: Get Your Token

After running report, you receive:

1. PDF report (emailed + downloadable)
2. Intelligence Token (in PDF header + email)

Example Intelligence Token: SIG-2025-11-A7K3M

---

Step 2: Access JSON Data

Two methods:

Method 1: Direct URL (simplest)

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

Returns: JSON file with all report data

Method 2: Account dashboard

• Login to surmado.com/reports
• Click report
• Download JSON button

---

Step 3: Parse JSON Data

Example Signal JSON structure:

{
  "token": "SIG-2025-11-A7K3M",
  "report_type": "signal",
  "generated_at": "2025-11-09T14:32:00Z",
  "business": {
    "name": "Acme HVAC",
    "website": "acmehvac.com",
    "category": "Home Services - HVAC"
  },
  "metrics": {
    "presence_rate": 0.58,
    "authority_score": 72,
    "ghost_influence": 0.32
  },
  "platforms": [
    {
      "name": "ChatGPT",
      "presence_rate": 0.72,
      "authority_score": 78,
      "mentions": 18
    },
    {
      "name": "Claude",
      "presence_rate": 0.45,
      "authority_score": 68,
      "mentions": 12
    }
    // ... 5 more platforms
  ],
  "competitors": [
    {
      "name": "Competitor A",
      "mentions": 22,
      "avg_ranking": 1.4
    },
    {
      "name": "Competitor B",
      "mentions": 18,
      "avg_ranking": 2.1
    }
    // ... more competitors
  ],
  "personas": [
    {
      "id": "persona_1",
      "query": "Emergency AC repair Phoenix same-day",
      "mentions": 8,
      "ranking": 2
    }
    // ... more personas
  ]
}

---

Common Use Cases

Use Case 1: Time-Series Tracking (Trend Analysis)

Goal: Track Presence Rate over 6 months.

Process:

1. Run Signal monthly (Jan, Feb, Mar, Apr, May, Jun)
2. Get 6 Intelligence Tokens
3. Fetch JSON for each token
4. Extract metrics.presence_rate from each
5. Plot trend: Jan 45% → Feb 48% → Mar 52% → Apr 55% → May 57% → Jun 58%

Example script (Python):

import requests
import matplotlib.pyplot as plt

tokens = [
    "SIG-2025-01-XXXXX",
    "SIG-2025-02-YYYYY",
    "SIG-2025-03-ZZZZZ",
    "SIG-2025-04-AAAAA",
    "SIG-2025-05-BBBBB",
    "SIG-2025-06-CCCCC"
]

presence_rates = []
months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]

for token in tokens:
    response = requests.get(f"https://api.surmado.com/intelligence/{token}")
    data = response.json()
    presence_rates.append(data["metrics"]["presence_rate"] * 100)

plt.plot(months, presence_rates, marker='o')
plt.ylabel('Presence Rate (%)')
plt.title('AI Visibility Trend (6 Months)')
plt.show()

Output: Chart showing 45% → 58% improvement over 6 months.

---

Use Case 2: Zapier Integration (Automated Workflows)

Goal: When new Signal report generated, add data to Google Sheets.

Zapier workflow:

Trigger: Email received (from hi@surmado.com with subject “Your Signal report”) Action 1: Extract Intelligence Token from email body Action 2: HTTP GET request to https://api.surmado.com/intelligence/{token} Action 3: Parse JSON response Action 4: Add row to Google Sheet with:

• Date
• Presence Rate
• Authority Score
• Ghost Influence
• Top 3 competitors

Result: Automated tracking without manual data entry.

---

Use Case 3: Notion Dashboard Integration

Goal: Display latest Signal metrics in Notion workspace.

Process:

1. Run Signal report monthly
2. Use Notion API to create database entry
3. Populate fields from Intelligence Token JSON:
   • Presence Rate: 58%
   • Authority Score: 72
   • Ghost Influence: 32%
   • Top Competitor: Competitor A (22 mentions)

Example Notion database:

Date	Presence Rate	Authority Score	Ghost Influence	Top Competitor
Nov 2025	58%	72	32%	Competitor A (22)
Oct 2025	52%	68	38%	Competitor A (24)
Sep 2025	48%	65	42%	Competitor B (26)

Update monthly with latest Intelligence Token data.

---

Use Case 4: Client Reporting (Agencies)

Goal: Auto-generate client reports with Surmado data.

Agency workflow:

1. Run Signal for Client A, B, C monthly
2. Get 3 Intelligence Tokens
3. Fetch JSON for each client
4. Populate client report template (Google Slides, PowerPoint) with:
   • Client A: Presence Rate +6% this month
   • Client B: Authority Score up 12 points
   • Client C: Ghost Influence reduced 40% → 28%

Example automation (Google Apps Script):

function updateClientReports() {
  const tokens = {
    "Client A": "SIG-2025-11-AAAAA",
    "Client B": "SIG-2025-11-BBBBB",
    "Client C": "SIG-2025-11-CCCCC"
  };

  for (const [client, token] of Object.entries(tokens)) {
    const url = `https://api.surmado.com/intelligence/${token}`;
    const response = UrlFetchApp.fetch(url);
    const data = JSON.parse(response.getContentText());

    // Update Google Slides template
    const slide = SlidesApp.openById("SLIDE_ID").getSlides()[0];
    slide.replaceAllText("{{PRESENCE_RATE}}", `${data.metrics.presence_rate * 100}%`);
    slide.replaceAllText("{{AUTHORITY_SCORE}}", data.metrics.authority_score);
  }
}

Result: Client reports auto-updated monthly with latest Surmado data.

---

Use Case 5: Alert System (Monitoring Drops)

Goal: Get notified if Presence Rate drops below threshold.

Process:

1. Run Signal weekly
2. Fetch JSON via Intelligence Token
3. Check if metrics.presence_rate < 0.50 (50% threshold)
4. If true, send Slack alert: “Warning: AI Presence Rate dropped to 48% (below 50% target)”

Example script (Python + Slack webhook):

import requests

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

presence_rate = data["metrics"]["presence_rate"]
threshold = 0.50

if presence_rate < threshold:
    slack_webhook = "https://hooks.slack.com/services/YOUR/WEBHOOK"
    message = {
        "text": f"Warning: AI Presence Rate dropped to {presence_rate * 100}% (below {threshold * 100}% target)"
    }
    requests.post(slack_webhook, json=message)

Result: Real-time monitoring, proactive alerts.

---

JSON Schema Details

Signal Intelligence Token Schema

Top-level fields:

• token: Intelligence Token ID
• report_type: “signal”
• generated_at: ISO 8601 timestamp
• business: Object with name, website, category
• metrics: Object with presence_rate, authority_score, ghost_influence
• platforms: Array of platform objects
• competitors: Array of competitor objects
• personas: Array of persona objects

Platform object:

{
  "name": "ChatGPT",
  "presence_rate": 0.72,
  "authority_score": 78,
  "mentions": 18,
  "ranking_avg": 2.3
}

Competitor object:

{
  "name": "Competitor A",
  "mentions": 22,
  "avg_ranking": 1.4,
  "co_mention_rate": 0.68
}

Persona object:

{
  "id": "persona_1",
  "query": "Emergency AC repair Phoenix",
  "mentions": 8,
  "ranking": 2,
  "platforms": ["ChatGPT", "Perplexity", "Claude"]
}

---

Scan Intelligence Token Schema

Top-level fields:

• token: Intelligence Token ID
• report_type: “scan”
• generated_at: ISO 8601 timestamp
• url: Website tested
• overall_score: 0-100
• categories: Object with technical_seo, performance, accessibility, security scores
• issues: Array of issue objects
• core_web_vitals: Object with LCP, CLS, INP

Issue object:

{
  "category": "technical_seo",
  "severity": "high",
  "title": "Duplicate title tags",
  "description": "12 pages have identical title tags",
  "pages_affected": 12,
  "effort_estimate": "2-4 hours"
}

---

Solutions Intelligence Token Schema

Top-level fields:

• token: Intelligence Token ID
• report_type: “solutions”
• generated_at: ISO 8601 timestamp
• question: Original strategic question
• recommendations: Array of recommendation objects
• perspectives: Object with CFO, COO, Market Realist, Game Theorist, Chief Strategist, Wildcard analyses

Recommendation object:

{
  "priority": "high",
  "action": "Renegotiate rev-share to tiered model",
  "rationale": "Flat 30% compresses margins at scale",
  "supporting_perspectives": ["CFO", "COO"]
}

---

Intelligence Token Security

Token access:

• Tokens are not publicly guessable (random alphanumeric)
• Tokens don’t expire (permanent access to your report)
• Tokens are read-only (can’t modify data)

Who can access:

• Anyone with the token (treat like password)
• Don’t share tokens publicly unless you want data public

Best practices:

• Store tokens in secure location (password manager, env variables)
• Don’t commit tokens to public GitHub repos
• Revoke access by not sharing token (no public revocation needed since tokens aren’t tied to account)

---

Future: Full REST API

Current state: Intelligence Tokens (manual report generation, programmatic data access)

Coming 2025: Full REST API for automation

Planned endpoints:

• POST /signal - Generate Signal report programmatically
• GET /reports/:id - Retrieve report by ID
• GET /reports - List all reports
• Webhooks - Get notified when report completes

Early access: Email api@surmado.com to join waitlist

---

The Bottom Line

Intelligence Tokens give you programmatic access to Surmado report data via structured JSON. You can:

• Track trends over time (automate data extraction)
• Integrate with tools (Zapier, Notion, Google Sheets)
• Build dashboards (visualize metrics)
• Monitor alerts (get notified if metrics drop)

Every report includes token. PDF for reading, JSON for automation.

---

Frequently Asked Questions

Do Intelligence Tokens cost extra?

No. Included free with every report:

• Signal ($50) = PDF + Intelligence Token
• Scan ($25 or $50) = PDF + Intelligence Token
• Solutions ($50-75) = PDF + Intelligence Token

No additional charge for JSON access.

How long do Intelligence Tokens last?

Forever. Tokens don’t expire. You can access JSON data months or years after report generation.

Example: Run Signal Jan 2025, get token SIG-2025-01-XXXXX. In Dec 2025, still access same JSON via that token.

Can I access someone else’s report with their token?

Yes, if they share token with you. Tokens are access credentials.

Use case: Client shares Intelligence Token with agency. Agency builds automated reporting dashboard.

Security note: Don’t share tokens publicly unless you want data public.

What if I lose my Intelligence Token?

Retrieve from:

1. PDF report (top of first page)
2. Email receipt (search inbox for “surmado.com”)
3. Account dashboard (surmado.com/reports)

If all lost: Email hi@surmado.com with report date and business name. Support can look up token.

Can I use Intelligence Tokens without coding?

Yes, via no-code tools:

Zapier:

• Trigger on email (new report)
• Extract token from email
• Fetch JSON via HTTP request
• Send to Google Sheets, Notion, Airtable

Make (formerly Integromat):

• Similar workflow to Zapier
• HTTP module fetches JSON
• Parse and route to destination

Google Sheets (with IMPORTDATA function):

• Not ideal (JSON parsing complex)
• Better to use Zapier/Make

Notion API:

• Fetch JSON
• Create database entry
• Populate properties with metrics

What data format is the JSON in?

Standard JSON (RFC 8259 compliant):

• UTF-8 encoding
• Numbers as integers or floats (not strings)
• Booleans as true/false
• Arrays and objects properly nested

Parseable by:

• Python: json.loads()
• JavaScript: JSON.parse()
• PHP: json_decode()
• Ruby: JSON.parse()
• Any modern programming language

Does the JSON include everything from the PDF?

Yes. JSON has same data as PDF, just structured differently:

PDF: Human-readable narrative (“Your Presence Rate is 58%”) JSON: Machine-readable data ("presence_rate": 0.58)

Example:

• PDF: “ChatGPT mentioned you 18 times with Authority Score of 78”
• JSON: {"name": "ChatGPT", "mentions": 18, "authority_score": 78}

Same information, different format.

Can I build my own dashboard using Intelligence Tokens?

Absolutely. Common use case:

Example dashboard (React + Chart.js):

1. Store Intelligence Tokens in database
2. Fetch JSON for each token via API
3. Extract metrics (Presence Rate, Authority Score, etc.)
4. Chart trends over time
5. Display competitor comparisons
6. Show platform-specific performance

Agency use: Build white-label dashboards for clients using their Intelligence Tokens.

---

Ready to access structured data from your reports? Every Surmado report includes an Intelligence Token for programmatic JSON access. No extra cost, no expiration.