Structured Data & Intelligence Tokens

15 min read

Paste this into Claude Code, Copilot, Cursor, or any AI coding agent to apply changes in your repo.

TLDR

Every Surmado report includes structured JSON for programmatic access. AI Visibility tokens contain visibility metrics and competitor data. Site Audit tokens include performance scores and technical issues. Strategy tokens have strategic recommendations and financial modeling. Integrate with Notion, Airtable, Google Sheets, Zapier, or custom tools. Track metrics over time, automate reports, build dashboards, or trigger alerts when visibility drops.

Looking for the REST API? See the API Integration Guide for creating reports, managing brands, and receiving webhooks programmatically.

Every Surmado report includes structured JSON for programmatic access.

What Are Intelligence Tokens?

Intelligence Tokens are unique identifiers for each completed report (e.g. SIG-2025-11-A7K3Q). The token is returned in the REST API response when a report completes, and for AI Visibility and Site Audit reports it unlocks a structured public_intelligence JSON payload you can integrate into:

Dashboards (Notion, Airtable, Retool, custom React apps)
Automation workflows (Zapier, Make, n8n)
Internal tools (CRMs, project management, BI platforms)
Custom agents (AI assistants, monitoring bots, Slack integrations)

Where to find them: Call GET /v1/reports/{report_id} once your report is completed. AI Visibility and Site Audit responses include a public_intelligence object with curated, machine-readable fields. Strategy reports return the token on completion but do not currently expose public_intelligence — use the generated PDF for strategy output. See the API Integration Guide for authentication and endpoint details.

Format: Standard JSON. Fields may be added over time; we aim to keep existing fields stable.

AI Visibility Intelligence Token

Token prefix: SIG-* (product slug in API paths: signal) Purpose: AI visibility metrics, competitive positioning, and ghost influence measurement.

Schema Structure (AI Visibility)

{
  "token": "SIG-2025-11-A7K3Q",
  "schema_type": "signal",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "summary": {
    "business_name": "Acme Coffee Roasters",
    "industry": "Food & Beverage",
    "location": "Portland, OR",
    "presence_score": 34.2,
    "authority_score": 42.7,
    "competitive_rank": 4,
    "total_competitors": 12,
    "top_competitor": "Blue Bottle",
    "insights_summary": [
      "Presence score: 34.2 (↑5.5 from last report)",
      "Ghost influence: 48.3% of relevant mentions don't name you",
      "Competitive rank: #4 of 12 in category"
    ]
  },
  "data": {
    "entity_context": {
      "entity_name": "Acme Coffee Roasters",
      "category": "Food & Beverage",
      "location": "Portland, OR",
      "value_proposition": "Single-origin, small-batch specialty coffee",
      "competitive_set": ["Starbucks", "Blue Bottle", "Intelligentsia"]
    },
    "visibility_metrics": {
      "presence_score": 34.2,
      "ghost_influence_percentage": 48.3,
      "attributed_mentions": 12,
      "unattributed_mentions": 17,
      "category_share": 8.1
    },
    "competitive_position": {
      "rank": 4,
      "total_competitors": 12,
      "tier": "challenger",
      "top_competitor": "Blue Bottle"
    },
    "platform_variance": {
      "chatgpt": {
        "presence_score": 42.1,
        "attributed_mentions": 5,
        "unattributed_mentions": 7,
        "sample_responses": ["..."]
      },
      "claude": {
        "presence_score": 38.5,
        "attributed_mentions": 3,
        "unattributed_mentions": 4
      },
      "gemini": { "...": "..." },
      "deepseek": { "...": "..." },
      "meta_ai": { "...": "..." },
      "grok": { "...": "..." }
    },
    "perception_analysis": {
      "primary_associations": ["specialty coffee", "local roasting", "sustainable sourcing"],
      "sentiment_distribution": {
        "positive": 67.4,
        "neutral": 28.3,
        "negative": 4.3
      },
      "strength_signals": ["ethical sourcing", "small batch quality"],
      "weakness_signals": ["limited retail presence", "higher price point"]
    },
    "strategic_signals": {
      "visibility_opportunities": [
        {
          "platform": "chatgpt",
          "gap": "Location-based queries underrepresented",
          "recommendation": "Optimize Google Business Profile with neighborhood keywords",
          "estimated_impact": "high"
        }
      ],
      "competitive_threats": [
        {
          "competitor": "Blue Bottle",
          "platform": "claude",
          "advantage": "Brand recognition in 'premium coffee' queries",
          "mitigation": "Emphasize direct trade relationships and roast-date freshness"
        }
      ]
    },
    "evidence_samples": [
      {
        "platform": "chatgpt",
        "query": "best specialty coffee roasters in Portland",
        "response_excerpt": "...",
        "attribution_type": "named",
        "rank": 3
      }
    ],
    "market_context": {
      "industry_trends": ["direct trade transparency", "micro-lot offerings"],
      "seasonal_factors": "Testing conducted during peak holiday gifting season",
      "competitive_intensity": "high",
      "total_competitors_found": 12
    },
    "baseline_metrics": {
      "previous_presence_score": 28.7,
      "change_since_last_report": "+5.5",
      "trend": "improving",
      "authority_score": 42.7
    },
    "preview_content": {
      "tldr_bullets_list": [
        "Presence score: 34.2 (↑5.5 from last report)",
        "Ghost influence: 48.3% of relevant mentions don't name you",
        "Competitive rank: #4 of 12 in category",
        "Strongest platform: ChatGPT (42.1 presence)",
        "Top opportunity: Location-based query optimization"
      ]
    }
  }
}

The curated summary object at the top is populated by the API for quick access. The deeper metrics live under data.*. Internal fields like persona_details and test_queries are blacklisted and never appear in public_intelligence.

Key Fields Explained (AI Visibility)

summary.presence_score (and data.visibility_metrics.presence_score): 0-100 score measuring how often your business appears in AI responses to relevant queries. Higher = more visible.

data.visibility_metrics.ghost_influence_percentage: Percentage of relevant mentions where AI describes your value proposition or features without naming you. High ghost influence = you’re educating the market but competitors capture attribution.

summary.competitive_rank (and data.competitive_position.rank): Your position relative to competitors in the same category. Rank 1 = most mentioned.

data.platform_variance: Breakdown by AI platform (ChatGPT, Claude, Gemini, etc.) showing where you’re strongest and weakest.

data.strategic_signals.visibility_opportunities: Actionable recommendations ranked by estimated impact.

Common Use Cases (AI Visibility)

Dashboard integration: Pull summary.presence_score, data.visibility_metrics.ghost_influence_percentage, and summary.competitive_rank to track AI visibility over time.

Alerting: Monitor data.baseline_metrics.trend and trigger alerts if presence score drops >10 points.

Competitive intelligence: Compare your data.platform_variance to competitors’ AI Visibility reports to identify platform-specific gaps.

Content strategy: Use data.perception_analysis.weakness_signals to guide content creation and FAQ optimization.

Site Audit Intelligence Token

Token prefix: SCN-* (product slug in API paths: scan) Purpose: Technical SEO audit data, performance metrics, accessibility scores, and prioritized action items.

Schema Structure (Site Audit)

{
  "schema_type": "scan",
  "scan_schema_types_count": 3,
  "scan_critical_issues_count": 8,
  "summary": {
    "seo_score": 95,
    "performance_score": 87,
    "accessibility_score": 92,
    "total_pages": 48,
    "schema_types_count": 3,
    "critical_issues_count": 8,
    "content_coverage_percentage": 87,
    "page_analysis_summary": "Homepage LCP is 2.8s (above target). Three pages have thin content.",
    "link_analysis_summary": "Internal link distribution uneven. Two orphaned pages detected.",
    "schema_strategy_summary": "FAQPage and LocalBusiness schemas missing on key pages.",
    "content_gaps_summary": "Competitors rank for brewing method and single-origin guides you don't cover.",
    "quick_wins": {
      "link_analysis": "Add internal links from homepage to two orphaned product pages.",
      "schema_strategy": "Add FAQPage schema to the top 5 traffic pages.",
      "content_gaps": "Publish a brewing-methods comparison guide."
    }
  },
  "data": {
    "metadata": {
      "url": "https://www.example.com",
      "run_id": "scan-20251108-143022",
      "product": "scan",
      "version": "1.0",
      "created_at": "2025-11-08T14:30:22.445Z"
    },
    "audit_data": {
      "site_metrics": {
      "total_pages": 48,
      "crawled_pages": 48,
      "avg_word_count": 1247,
      "pages_with_schema": 42,
      "missing_titles": 0,
      "duplicate_titles": 3,
      "images_without_alt": 15,
      "broken_links": 2,
      "redirect_chains": 1
    },
    "lighthouse": {
      "performance_score": 87,
      "seo_score": 95,
      "accessibility_score": 92,
      "best_practices_score": 88,
      "first_contentful_paint": 1.2,
      "largest_contentful_paint": 2.1,
      "cumulative_layout_shift": 0.05,
      "total_blocking_time": 150
    },
    "accessibility": {
      "pa11y_errors": 8,
      "pa11y_warnings": 23,
      "combined_score": 86,
      "critical_issues": [
        {
          "code": "WCAG2AA.Principle1.Guideline1_3.1_3_1.H49.I",
          "message": "<i> element used for icon, should use aria-label",
          "selector": ".nav-icon",
          "impact": "moderate"
        }
      ]
    },
    "enrichment": {
      "page_analysis": {
        "high_priority_pages": [
          {
            "url": "/",
            "title": "Homepage",
            "recommendations": [
              "Add FAQ schema to address common queries",
              "Optimize hero image LCP (currently 2.8s)"
            ]
          }
        ]
      },
      "link_analysis": {
        "internal_link_distribution": "uneven",
        "orphaned_pages": 2,
        "deep_pages_low_authority": 5
      },
      "schema_strategist": {
        "schemas_found": ["Organization", "WebSite", "BreadcrumbList"],
        "schemas_missing": ["FAQPage", "LocalBusiness"],
        "validation_errors": [
          {
            "type": "Organization",
            "field": "logo",
            "error": "Invalid URL format"
          }
        ]
      },
      "content_inventory": {
        "thin_content_pages": 3,
        "keyword_cannibalization": [
          {
            "keyword": "best coffee beans",
            "competing_pages": ["/shop/beans", "/blog/coffee-guide"],
            "recommendation": "Consolidate or differentiate targeting"
          }
        ]
      },
      "competitor_analysis": {
        "competitors_analyzed": ["bluebottle.com", "intelligentsia.com"],
        "your_advantages": ["Faster load times", "Better mobile UX"],
        "their_advantages": ["more thorough with 150+ checks schema", "Higher blog frequency"]
      },
      "upstream_research": {
        "industry_benchmarks": {
          "avg_performance_score": 72,
          "avg_accessibility_score": 78,
          "your_vs_average": {
            "performance": "+15",
            "accessibility": "+14"
          }
        }
      },
      "content_gap_analysis": {
        "suggested_topics": [
          "Coffee brewing methods comparison",
          "Single-origin vs blend guide",
          "Roast profile differences explained"
        ],
        "rationale": "Competitors rank for these queries but you have no content"
      }
    },
    "pages": [
      {
        "url": "https://www.example.com/",
        "title": "Homepage",
        "status_code": 200,
        "word_count": 1850,
        "meta_description": "...",
        "h1_tags": ["Acme Coffee Roasters"],
        "schema_types": ["Organization", "WebSite"],
        "performance": {
          "lcp": 2.1,
          "cls": 0.05
        },
        "issues": [
          {
            "severity": "medium",
            "type": "image_optimization",
            "message": "Hero image not lazy-loaded",
            "recommendation": "Add loading='lazy' attribute"
          }
        ]
      }
    ]
    }
  }
}

summary is the curated rollup customers use for automation. Deeper data lives under data.audit_data.*. The full audit_data.pages[] array is present in the public_intelligence response but is long; grab summary.quick_wins for the top prioritized recommendations.

Key Fields Explained (Site Audit)

summary.seo_score (and data.audit_data.site_metrics.seo_score): 0-100 SEO score rolling up technical and on-page factors.

summary.performance_score (and data.audit_data.lighthouse.performance_score): 0-100 Lighthouse performance score. Industry average: 65-75 for e-commerce sites.

data.audit_data.site_metrics.images_without_alt: Number of images missing alt text (SEO + accessibility issue).

data.audit_data.enrichment.schema_strategist: Schema.org validation and recommendations for structured data.

data.audit_data.enrichment.content_gap_analysis: Topics competitors rank for but you don’t cover. SEO opportunity areas.

data.audit_data.pages[].issues: Granular issues per page with severity and actionable recommendations.

summary.quick_wins: Prioritized, plain-English recommendations keyed by area (link_analysis, schema_strategy, content_gaps).

Common Use Cases (Site Audit)

CI/CD integration: Run a Site Audit in your deployment pipeline and fail builds if summary.performance_score < 80.

Monitoring: Track summary.seo_score, summary.performance_score, and summary.accessibility_score over time in a time-series database.

Issue tracking: Parse data.audit_data.pages[].issues and auto-create Jira/Linear tickets for dev team.

Reporting: Pull the summary object for executive dashboards showing SEO health.

Strategy Intelligence Token

Token prefix: SOL-* (product slug in API paths: solutions) Purpose: Strategic planning output, prioritized action items, adversarial debate synthesis, and decision frameworks.

Strategy reports do not currently expose a public_intelligence object via the REST API. The structure below describes what appears in the generated PDF and is included for reference — programmatic consumers should use the PDF download URL returned on the status endpoint.

Schema Structure (Strategy)

{
  "token": "SOL-2025-11-A7K3Q",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "business_name": "Acme Coffee Roasters",
  "decision": "Should we expand from local farmers markets to e-commerce?",
  "todo_list": [
    {
      "priority": 1,
      "action": "Validate e-commerce demand with 2-week pre-order test",
      "rationale": "CFO AI flagged cash flow risk of inventory investment. Test market demand before committing capital.",
      "estimated_effort": "1-3 days",
      "impact": "high",
      "owner_role": "Marketing",
      "dependencies": [],
      "success_criteria": "Achieve 50+ pre-orders to justify inventory investment"
    },
    {
      "priority": 2,
      "action": "Calculate true unit economics including shipping costs",
      "rationale": "Market Realist AI noted competitors use free shipping thresholds. Need to model margin impact.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Finance",
      "dependencies": [],
      "success_criteria": "Confirm >30% margin after shipping at $35+ order value"
    },
    {
      "priority": 3,
      "action": "Research coffee subscription platform integrations (Trade, Driftaway)",
      "rationale": "Game Theorist AI suggested partnering vs competing. Explore white-label options.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Partnerships",
      "dependencies": [],
      "success_criteria": "Identify 2-3 viable platform partnerships with <15% commission"
    },
    {
      "priority": 4,
      "action": "Audit fulfillment capacity: Can we ship 100 orders/week?",
      "rationale": "COO AI raised operational risk of overwhelming current team during peak season.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Operations",
      "dependencies": [],
      "success_criteria": "Document current capacity + identify bottlenecks"
    },
    {
      "priority": 5,
      "action": "Create content strategy for 'coffee education' blog",
      "rationale": "Upstream research showed competitors win on educational content. Build SEO moat.",
      "estimated_effort": "1 week",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [1],
      "success_criteria": "Publish 3 comprehensive guides (brewing methods, origins, roast profiles)"
    },
    {
      "priority": 6,
      "action": "Build Minimum Viable Storefront (Shopify or WooCommerce)",
      "rationale": "After validating demand (Priority 1), launch simple store. Avoid custom dev.",
      "estimated_effort": "2 weeks",
      "impact": "high",
      "owner_role": "Engineering",
      "dependencies": [1, 2],
      "success_criteria": "Live storefront with 5 SKUs, payment processing, shipping integration"
    },
    {
      "priority": 7,
      "action": "Model customer acquisition cost (CAC) for paid ads",
      "rationale": "CFO AI noted farmers market CAC is $0 (foot traffic). Need to budget for online ads.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [2],
      "success_criteria": "Target CAC <$25 with LTV >$75 (3x ratio)"
    },
    {
      "priority": 8,
      "action": "Set decision checkpoint: Launch vs pivot based on pre-order results",
      "rationale": "Chief Strategist AI synthesis: Use Priority 1 results to decide go/no-go.",
      "estimated_effort": "1 day",
      "impact": "critical",
      "owner_role": "Leadership",
      "dependencies": [1, 2, 4],
      "success_criteria": "Decision made by [specific date] based on pre-order data"
    }
  ],
  "summary": {
    "total_actions": 8,
    "high_priority": 4,
    "medium_priority": 3,
    "critical_priority": 1,
    "has_financial_analysis": true,
    "has_risk_mitigation": true,
    "estimated_total_effort": "4-6 weeks",
    "decision_framework": "Staged validation approach with clear go/no-go gates"
  },
  "adversarial_debate_summary": {
    "cfo_concerns": [
      "Inventory cash flow risk without demand validation",
      "Shipping costs erode margins below 30% threshold",
      "Customer acquisition cost unknown for paid channels"
    ],
    "coo_concerns": [
      "Current team capacity maxed at 100 orders/week",
      "Peak season overlap with farmers market commitments",
      "Fulfillment process not documented or systemized"
    ],
    "market_realist_concerns": [
      "Competitors offer free shipping (you can't at current scale)",
      "Educational content gap vs established brands",
      "Price positioning unclear (premium vs accessible)"
    ],
    "game_theorist_insights": [
      "Partnering with existing platforms reduces upfront investment",
      "Competitors may respond with farmers market presence if you succeed online",
      "First-mover advantage in 'local + online' hybrid model"
    ],
    "chief_strategist_synthesis": "Launch is feasible but only after validating demand and unit economics. Staged approach reduces risk: (1) Pre-order test, (2) MVP storefront, (3) Scale based on results. Avoid premature inventory investment."
  },
  "monte_carlo_scenarios": {
    "methodology": "10,000 simulations varying demand, CAC, and margin assumptions",
    "outcomes": {
      "success_rate": 62,
      "breakeven_12mo": 62,
      "breakeven_18mo": 28,
      "failure_24mo": 10
    },
    "key_risk_factors": [
      "Customer acquisition cost variance (if CAC >$40, failure risk jumps to 35%)",
      "Shipping cost assumptions (free shipping threshold impacts margin by 12-18%)",
      "Fulfillment bottleneck (unable to scale beyond 100 orders/week without hiring)"
    ],
    "recommendation": "Secure 18-month runway, not 12-month. Model includes 28% of scenarios requiring extended breakeven timeline."
  },
  "evidence_citations": [
    {
      "claim": "Competitors use free shipping thresholds",
      "source": "Analysis of Blue Bottle, Intelligentsia, and Stumptown pricing",
      "data": "Free shipping at $40+, $35+, and $50+ respectively"
    },
    {
      "claim": "Educational content drives SEO for coffee brands",
      "source": "SEMrush analysis of top 10 specialty coffee sites",
      "data": "Average 12 educational blog posts ranking for 'how to brew' queries"
    }
  ]
}

Key Fields Explained (Strategy)

todo_list[].priority: 1 = highest priority. Order represents logical sequence and dependencies.

todo_list[].dependencies: Array of priority numbers this action depends on. Used for project management sequencing.

adversarial_debate_summary: Condensed view of concerns raised by each AI perspective (CFO, COO, Market Realist, Game Theorist) and final synthesis.

monte_carlo_scenarios: Probabilistic stress testing results showing likelihood of success/failure under varying assumptions.

evidence_citations: Sources backing key claims and recommendations. Transparency into reasoning.

Common Use Cases (Strategy)

Strategy public_intelligence is not exposed via the REST API today. The fields below describe the PDF output — programmatic consumers should extract from the PDF or re-run the source AI Visibility / Site Audit report and work from that public_intelligence.

Project management: Import todo_list into Linear, Asana, or Notion with priorities and dependencies pre-mapped.

Decision tracking: Store Strategy tokens in your strategy repository to document why decisions were made.

Board reporting: Pull summary and monte_carlo_scenarios to show executive team how strategy was stress-tested.

Knowledge management: Index evidence_citations to build institutional memory of strategic research.

Accessing Intelligence Tokens

Via REST API

The primary path. Call GET /v1/reports/{report_id} once a report reaches completed status. The response includes the token field and, for AI Visibility and Site Audit reports, a public_intelligence object with structured metrics. See the API Integration Guide for authentication, webhooks, and full endpoint details.

Via Email

When your report is ready, you’ll receive an email with a magic-link button to view the PDF. The link is valid for about 30 days.

Via Surmado App

Navigate to Reports → select your report → the token and download links are visible in the report detail view.

Intelligence Token Schemas

The schemas for AI Visibility and Site Audit public_intelligence payloads are documented above. Strategy output is delivered as PDF; a structured public_intelligence payload is not currently exposed via the REST API for Strategy reports.

Integration Examples

In all examples below, public_intelligence is fetched from the REST API using GET /v1/reports/{report_id} (see the API Integration Guide).

Notion Dashboard

// Fetch a completed AI Visibility report and create a Notion database entry
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const signalData = report.public_intelligence;

await notion.pages.create({
  parent: { database_id: 'YOUR_DATABASE_ID' },
  properties: {
    'Business Name': { title: [{ text: { content: signalData.summary.business_name } }] },
    'Presence Score': { number: signalData.summary.presence_score },
    'Competitive Rank': { number: signalData.summary.competitive_rank },
    'Report Date': { date: { start: report.completed_at } },
    'Token': { rich_text: [{ text: { content: report.token } }] }
  }
});

Zapier Webhook

// Trigger Zapier workflow when presence score drops
const currentScore = signalData.summary.presence_score;
const previousScore = signalData.data?.baseline_metrics?.previous_presence_score;

if (previousScore && currentScore < previousScore - 10) {
  await fetch('https://hooks.zapier.com/hooks/catch/YOUR_WEBHOOK/', {
    method: 'POST',
    body: JSON.stringify({
      alert: 'Presence score dropped significantly',
      business: signalData.summary.business_name,
      current_score: currentScore,
      previous_score: previousScore,
      drop: previousScore - currentScore
    })
  });
}

Linear Issue Creation (Site Audit)

// Fetch a completed Site Audit report and auto-create Linear issues from quick wins
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const scanData = report.public_intelligence;

for (const [area, recommendation] of Object.entries(scanData.summary.quick_wins ?? {})) {
  await linearClient.createIssue({
    teamId: 'YOUR_TEAM_ID',
    title: `[SEO] ${area}: ${recommendation.slice(0, 60)}`,
    description: recommendation,
    priority: 1,
    labels: ['seo', 'technical-debt']
  });
}

Google Sheets Time-Series Tracking

// Append AI Visibility scores to Google Sheets for time-series tracking
const { GoogleSpreadsheet } = require('google-spreadsheet');
const doc = new GoogleSpreadsheet('YOUR_SHEET_ID');

await doc.useServiceAccountAuth(credentials);
await doc.loadInfo();

const sheet = doc.sheetsByIndex[0];
await sheet.addRow({
  'Date': report.completed_at,
  'Business': signalData.summary.business_name,
  'Presence Score': signalData.summary.presence_score,
  'Authority Score': signalData.summary.authority_score,
  'Rank': signalData.summary.competitive_rank,
  'ChatGPT Score': signalData.data?.platform_variance?.chatgpt?.presence_score,
  'Claude Score': signalData.data?.platform_variance?.claude?.presence_score
});

Quick Answers

What is an Intelligence Token?

Intelligence Token = Your unique identifier for a completed report (format: SIG-2025-11-XXXXX, SCN-2025-11-XXXXX, or SOL-2025-11-XXXXX). The token is returned on the API status response and is the key you pass when chaining reports (e.g. building a Strategy report from an existing AI Visibility report).

Why it’s valuable:

Programmatic access: Parse public_intelligence into your tools (Notion, Linear, Google Sheets)
Automation: Build workflows that trigger on new reports
Time-series tracking: Store historical data for trend analysis
Report chaining: Pass as signal_token or scan_token when creating a Strategy report

Where you get it: Returned by GET /v1/reports/{report_id} on completion, included in completion webhooks, and shown on the report detail page in the Surmado app.

How do I access my Intelligence Token?

3 ways to get your token:

REST API: Call GET /v1/reports/{report_id} once the report is completed — the token field holds the value.
Webhook: If you include a webhook_url on report creation, the completion payload contains the token at report.token.
PDF report: Token printed on the first page (format: Token: SIG-2025-11-A7K3Q).

Intelligence Tokens are stable identifiers for the completed report; they don’t expire. The magic-link URL for the PDF shown in completion emails is valid for about 30 days — re-fetch a fresh signed download URL from the status endpoint at any time after that.

Can I use Intelligence Tokens with Zapier?

Yes! Example Zapier workflow using the Surmado completion webhook:

Trigger: Surmado webhook (report.completed event) — configure webhook_url on report creation Action 1: Call GET /v1/reports/{report.id} with your API key to fetch public_intelligence Action 2: Parse public_intelligence.summary.presence_score Action 3: Create Notion database entry with scores Action 4: Send Slack notification if presence_score < 10

Common integrations:

Notion: Auto-populate marketing dashboard
Linear: Create tasks for low-scoring issues
Google Sheets: Time-series tracking
Slack: Alert team on visibility changes

See the Zapier Integration Guide for step-by-step setup, or the Google Sheets time-series example below.

Do Intelligence Tokens expire?

No. Tokens are stable identifiers for a completed report and remain valid for historical reference.

What does change over time:

The magic-link PDF URL delivered via email is valid for ~30 days. After that, re-fetch a signed download URL from GET /v1/reports/{report_id}.
Signed download URLs returned by the status endpoint expire after about 15 minutes. Download the file and store it on your side if you need it long-term.
Scores drift as AI platforms and competitor positioning change. Re-run reports periodically (quarterly is a common cadence) for fresh data.

What’s the difference between SIG, SCN, and SOL tokens?

Different schemas for different products:

SIG-* (AI Visibility tokens):

Schema: visibility metrics (presence_score, ghost_influence, platform_variance)
Use case: Track AI discoverability over time
Example: SIG-2025-11-A7K3Q

SCN-* (Site Audit tokens):

Schema: Technical SEO metrics (lighthouse, schema_validation, accessibility)
Use case: Monitor site health, track Core Web Vitals
Example: SCN-2025-11-A7K9P

SOL-* (Strategy tokens):

Schema: Strategic recommendations (todo_list, priority, rationale) — delivered as PDF; not exposed as public_intelligence
Use case: Strategic decision documentation, chaining into project management tools
Example: SOL-2025-11-A7K3Q

All tokens: stable identifiers returned on report completion.

See schema documentation →

Does Surmado have a REST API?

Yes. The Surmado REST API lets you:

Create AI Visibility, Site Audit, and Strategy reports programmatically
Manage brands with idempotent POST /v1/brands/ensure
Check report status and download PDFs/PPTX
Receive webhook notifications when reports complete

Authenticate with your API key (sur_live_...) via Bearer token or X-API-Key header. Each report costs 1 credit.

See the full API Integration Guide →

Can I automate AI Visibility reports?

Yes. Use the REST API to create AI Visibility reports programmatically:

POST /v1/reports/signal

Combine with webhooks for fully automated workflows — create a report, receive a webhook when it completes, then parse the results. See the API Integration Guide for required fields and examples.

You can also use no-code tools like Zapier, Make, or n8n to trigger report creation via the API. See the Zapier Integration Guide for step-by-step instructions.

Need Help?

Questions about schema fields? Check our FAQ or email support@surmado.com.

Building an integration? We’d love to hear about it! Share your use case at hi@surmado.com.

Get started: Try Surmado | Work with Scout

Table of Contents