Données structurées et Intelligence Tokens

Lecture 15 min

TLDR

Chaque rapport Surmado inclut du JSON structuré pour un accès programmatique. Les tokens AI Visibility contiennent des métriques de visibilité et des données sur les concurrents. Les tokens Site Audit incluent des scores de performance et des problèmes techniques. Les tokens Strategy contiennent des recommandations stratégiques et de la modélisation financière. Intégrez-les à Notion, Airtable, Google Sheets, Zapier ou à des outils sur mesure. Suivez les métriques dans le temps, automatisez les rapports, créez des tableaux de bord ou déclenchez des alertes quand la visibilité baisse.

Vous cherchez l’API REST ? Consultez le guide d’intégration de l’API pour créer des rapports, gérer des marques et recevoir des webhooks par programmation.

Chaque rapport Surmado inclut du JSON structuré pour un accès programmatique.

Que sont les Intelligence Tokens ?

Les Intelligence Tokens sont des identifiants uniques pour chaque rapport terminé (p. ex. SIG-2025-11-A7K3Q). Le token est renvoyé dans la réponse de l’API REST lorsqu’un rapport se termine. Pour les rapports AI Visibility et Site Audit, il donne accès à une charge utile JSON structurée public_intelligence que vous pouvez intégrer à :

Des tableaux de bord (Notion, Airtable, Retool, applications React sur mesure)
Des flux d’automatisation (Zapier, Make, n8n)
Des outils internes (CRM, gestion de projet, plateformes de BI)
Des agents sur mesure (assistants IA, bots de surveillance, intégrations Slack)

Où les trouver : appelez GET /v1/reports/{report_id} une fois votre rapport completed. Les réponses AI Visibility et Site Audit incluent un objet public_intelligence avec des champs sélectionnés et lisibles par machine. Les rapports Strategy renvoient le token à la fin, mais n’exposent pas public_intelligence pour le moment : utilisez le PDF généré pour le résultat de Strategy. Consultez le guide d’intégration de l’API pour l’authentification et le détail des endpoints.

Format : JSON standard. Des champs peuvent être ajoutés avec le temps ; nous cherchons à garder les champs existants stables.

Intelligence Token AI Visibility

Préfixe du token : SIG-* (identifiant du produit dans les chemins de l’API : signal) Objet : métriques de visibilité dans l’IA, positionnement concurrentiel et mesure du Ghost Influence.

Structure du schéma (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"
      ]
    }
  }
}

L’objet summary sélectionné, en haut, est rempli par l’API pour un accès rapide. Les métriques plus détaillées se trouvent sous data.*. Les champs internes comme persona_details et test_queries sont exclus et n’apparaissent jamais dans public_intelligence.

Principaux champs expliqués (AI Visibility)

summary.presence_score (et data.visibility_metrics.presence_score) : score de 0 à 100 qui mesure la fréquence à laquelle votre entreprise apparaît dans les réponses de l’IA aux requêtes pertinentes. Plus il est élevé, plus vous êtes visible.

data.visibility_metrics.ghost_influence_percentage : pourcentage des mentions pertinentes où l’IA décrit votre proposition de valeur ou vos fonctionnalités sans vous nommer. Un Ghost Influence élevé signifie que vous éduquez le marché, mais que ce sont vos concurrents qui récoltent l’attribution.

summary.competitive_rank (et data.competitive_position.rank) : votre position par rapport aux concurrents de la même catégorie. Le rang 1 correspond au plus mentionné.

data.platform_variance : détail par plateforme d’IA (ChatGPT, Claude, Gemini, etc.) qui montre où vous êtes le plus fort et le plus faible.

data.strategic_signals.visibility_opportunities : recommandations concrètes classées par impact estimé.

Cas d’usage courants (AI Visibility)

Intégration à un tableau de bord : récupérez summary.presence_score, data.visibility_metrics.ghost_influence_percentage et summary.competitive_rank pour suivre la visibilité dans l’IA au fil du temps.

Alertes : surveillez data.baseline_metrics.trend et déclenchez des alertes si le score de présence baisse de plus de 10 points.

Veille concurrentielle : comparez votre data.platform_variance aux rapports AI Visibility de vos concurrents pour repérer les écarts propres à chaque plateforme.

Stratégie de contenu : utilisez data.perception_analysis.weakness_signals pour orienter la création de contenu et l’optimisation des FAQ.

Intelligence Token Site Audit

Préfixe du token : SCN-* (identifiant du produit dans les chemins de l’API : scan) Objet : données d’audit SEO technique, métriques de performance, scores d’accessibilité et actions prioritaires.

Structure du schéma (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 est la synthèse sélectionnée que les clients utilisent pour l’automatisation. Les données plus détaillées se trouvent sous data.audit_data.*. Le tableau complet audit_data.pages[] est présent dans la réponse public_intelligence, mais il est long ; récupérez summary.quick_wins pour les recommandations les plus prioritaires.

Principaux champs expliqués (Site Audit)

summary.seo_score (et data.audit_data.site_metrics.seo_score) : score SEO de 0 à 100 qui regroupe les facteurs techniques et ceux de la page.

summary.performance_score (et data.audit_data.lighthouse.performance_score) : score de performance Lighthouse de 0 à 100. Moyenne du secteur : 65 à 75 pour les sites de e-commerce.

data.audit_data.site_metrics.images_without_alt : nombre d’images sans texte alternatif (problème de SEO et d’accessibilité).

data.audit_data.enrichment.schema_strategist : validation Schema.org et recommandations pour les données structurées.

data.audit_data.enrichment.content_gap_analysis : sujets sur lesquels vos concurrents sont classés et que vous ne couvrez pas. Ce sont des pistes d’opportunité SEO.

data.audit_data.pages[].issues : problèmes détaillés par page, avec leur gravité et des recommandations concrètes.

summary.quick_wins : recommandations priorisées, en langage clair, classées par domaine (link_analysis, schema_strategy, content_gaps).

Cas d’usage courants (Site Audit)

Intégration CI/CD : lancez un Site Audit dans votre pipeline de déploiement et faites échouer les builds si summary.performance_score < 80.

Monitoring : suivez summary.seo_score, summary.performance_score et summary.accessibility_score dans le temps, dans une base de données de séries chronologiques.

Suivi des problèmes : analysez data.audit_data.pages[].issues et créez automatiquement des tickets Jira ou Linear pour l’équipe de développement.

Reporting : récupérez l’objet summary pour des tableaux de bord de direction qui montrent la santé SEO.

Intelligence Token Strategy

Préfixe du token : SOL-* (identifiant du produit dans les chemins de l’API : solutions) Objet : résultats de planification stratégique, actions prioritaires, synthèse du débat contradictoire et cadres de décision.

Les rapports Strategy n’exposent pas d’objet public_intelligence via l’API REST pour le moment. La structure ci-dessous décrit ce qui apparaît dans le PDF généré et sert de référence : les consommateurs programmatiques doivent utiliser l’URL de téléchargement du PDF renvoyée par l’endpoint de statut.

Structure du schéma (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"
    }
  ]
}

Principaux champs expliqués (Strategy)

todo_list[].priority : 1 = priorité la plus haute. L’ordre représente la séquence logique et les dépendances.

todo_list[].dependencies : tableau des numéros de priorité dont cette action dépend. Sert à ordonnancer la gestion de projet.

adversarial_debate_summary : vue condensée des préoccupations soulevées par chaque perspective d’IA (CFO, COO, Market Realist, Game Theorist) et synthèse finale.

monte_carlo_scenarios : résultats de tests de résistance probabilistes qui montrent la probabilité de réussite ou d’échec selon des hypothèses variables.

evidence_citations : sources qui appuient les affirmations et recommandations clés. Transparence sur le raisonnement.

Cas d’usage courants (Strategy)

Le public_intelligence de Strategy n’est pas exposé via l’API REST aujourd’hui. Les champs ci-dessous décrivent le résultat du PDF : les consommateurs programmatiques doivent extraire les données du PDF, ou relancer le rapport AI Visibility ou Site Audit source et travailler à partir de son public_intelligence.

Gestion de projet : importez todo_list dans Linear, Asana ou Notion, avec les priorités et les dépendances déjà reliées.

Suivi des décisions : conservez les tokens Strategy dans votre dépôt de stratégie pour documenter pourquoi les décisions ont été prises.

Rapports au conseil : récupérez summary et monte_carlo_scenarios pour montrer à l’équipe de direction comment la stratégie a été mise à l’épreuve.

Gestion des connaissances : indexez evidence_citations pour bâtir la mémoire de l’entreprise sur la recherche stratégique.

Accéder aux Intelligence Tokens

Via l’API REST

C’est la voie principale. Appelez GET /v1/reports/{report_id} dès qu’un rapport atteint le statut completed. La réponse inclut le champ token et, pour les rapports AI Visibility et Site Audit, un objet public_intelligence avec des métriques structurées. Consultez le guide d’intégration de l’API pour l’authentification, les webhooks et le détail complet des endpoints.

Par e-mail

Quand votre rapport est prêt, vous recevez un e-mail avec un bouton de lien magique pour consulter le PDF. Le lien est valable environ 30 jours.

Via l’application Surmado

Allez dans Reports → sélectionnez votre rapport → le token et les liens de téléchargement sont visibles dans la vue détaillée du rapport.

Schémas des Intelligence Tokens

Les schémas des charges utiles public_intelligence d’AI Visibility et de Site Audit sont documentés plus haut. Le résultat de Strategy est livré en PDF ; une charge utile structurée public_intelligence n’est pas exposée via l’API REST pour les rapports Strategy pour le moment.

Exemples d’intégration

Dans tous les exemples ci-dessous, public_intelligence est récupéré depuis l’API REST avec GET /v1/reports/{report_id} (voir le guide d’intégration de l’API).

Tableau de bord Notion

// 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 } }] }
  }
});

Webhook Zapier

// 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
    })
  });
}

Création de tickets Linear (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']
  });
}

Suivi de séries chronologiques avec Google Sheets

// 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
});

Réponses rapides

Qu’est-ce qu’un Intelligence Token ?

Intelligence Token = votre identifiant unique pour un rapport terminé (format : SIG-2025-11-XXXXX, SCN-2025-11-XXXXX ou SOL-2025-11-XXXXX). Le token est renvoyé dans la réponse de statut de l’API. C’est la clé à transmettre pour enchaîner des rapports (p. ex. créer un rapport Strategy à partir d’un rapport AI Visibility existant).

Pourquoi c’est utile :

Accès programmatique : analysez public_intelligence dans vos outils (Notion, Linear, Google Sheets)
Automatisation : créez des flux qui se déclenchent à chaque nouveau rapport
Suivi chronologique : conservez l’historique des données pour analyser les tendances
Enchaînement de rapports : transmettez-le comme signal_token ou scan_token lors de la création d’un rapport Strategy

Où l’obtenir : renvoyé par GET /v1/reports/{report_id} à la fin du rapport, inclus dans les webhooks de fin, et affiché sur la page de détail du rapport dans l’application Surmado.

Comment accéder à mon Intelligence Token ?

3 façons d’obtenir votre token :

API REST : appelez GET /v1/reports/{report_id} une fois le rapport completed : le champ token contient la valeur.
Webhook : si vous indiquez un webhook_url à la création du rapport, la charge utile de fin contient le token à report.token.
Rapport PDF : le token est imprimé sur la première page (format : Token: SIG-2025-11-A7K3Q).

Les Intelligence Tokens sont des identifiants stables pour le rapport terminé ; ils n’expirent pas. L’URL de lien magique du PDF, indiquée dans les e-mails de fin, est valable environ 30 jours : après cela, récupérez à tout moment une nouvelle URL de téléchargement signée depuis l’endpoint de statut.

Puis-je utiliser les Intelligence Tokens avec Zapier ?

Oui ! Exemple de flux Zapier utilisant le webhook de fin de Surmado :

Déclencheur : webhook Surmado (événement report.completed) : configurez webhook_url à la création du rapport Action 1 : appelez GET /v1/reports/{report.id} avec votre clé API pour récupérer public_intelligence Action 2 : analysez public_intelligence.summary.presence_score Action 3 : créez une entrée de base de données Notion avec les scores Action 4 : envoyez une notification Slack si presence_score < 10

Intégrations courantes :

Notion : remplir automatiquement le tableau de bord marketing
Linear : créer des tâches pour les problèmes à faible score
Google Sheets : suivi chronologique
Slack : alerter l’équipe en cas de changement de visibilité

Consultez le guide d’intégration Zapier pour la configuration pas à pas, ou l’exemple de série chronologique Google Sheets ci-dessous.

Les Intelligence Tokens expirent-ils ?

Non. Les tokens sont des identifiants stables pour un rapport terminé et restent valables comme référence historique.

Ce qui change avec le temps :

L’URL de lien magique du PDF envoyée par e-mail est valable ~30 jours. Passé ce délai, récupérez de nouveau une URL de téléchargement signée depuis GET /v1/reports/{report_id}.
Les URL de téléchargement signées renvoyées par l’endpoint de statut expirent après environ 15 minutes. Téléchargez le fichier et conservez-le de votre côté si vous en avez besoin à long terme.
Les scores évoluent à mesure que les plateformes d’IA et le positionnement des concurrents changent. Relancez les rapports régulièrement (un rythme trimestriel est courant) pour obtenir des données à jour.

Quelle est la différence entre les tokens SIG, SCN et SOL ?

Des schémas différents pour des produits différents :

SIG-* (tokens AI Visibility) :

Schéma : métriques de visibilité (presence_score, ghost_influence, platform_variance)
Cas d’usage : suivre la découvrabilité dans l’IA dans le temps
Exemple : SIG-2025-11-A7K3Q

SCN-* (tokens Site Audit) :

Schéma : métriques SEO techniques (lighthouse, schema_validation, accessibility)
Cas d’usage : surveiller la santé du site, suivre les Core Web Vitals
Exemple : SCN-2025-11-A7K9P

SOL-* (tokens Strategy) :

Schéma : recommandations stratégiques (todo_list, priority, rationale), livrées en PDF ; non exposées comme public_intelligence
Cas d’usage : documentation des décisions stratégiques, enchaînement vers des outils de gestion de projet
Exemple : SOL-2025-11-A7K3Q

Tous les tokens : identifiants stables renvoyés à la fin du rapport.

Voir la documentation des schémas →

Surmado propose-t-il une API REST ?

Oui. L’API REST de Surmado vous permet de :

Créer des rapports AI Visibility, Site Audit et Strategy par programmation
Gérer des marques avec POST /v1/brands/ensure, idempotent
Vérifier le statut des rapports et télécharger les PDF et PPTX
Recevoir des notifications webhook lorsque les rapports se terminent

Authentifiez-vous avec votre clé API (sur_live_...) via un Bearer token ou l’en-tête X-API-Key. Chaque rapport coûte 1 Job.

Voir le guide d’intégration complet de l’API →

Puis-je automatiser les rapports AI Visibility ?

Oui. Utilisez l’API REST pour créer des rapports AI Visibility par programmation :

POST /v1/reports/signal

Combinez-la avec des webhooks pour des flux entièrement automatisés. Créez un rapport, recevez un webhook à sa fin, puis analysez les résultats. Consultez le guide d’intégration de l’API pour les champs obligatoires et des exemples.

Vous pouvez aussi utiliser des outils sans code comme Zapier, Make ou n8n pour déclencher la création de rapports via l’API. Consultez le guide d’intégration Zapier pour les instructions pas à pas.

Besoin d’aide ?

Des questions sur les champs du schéma ? Consultez notre FAQ ou écrivez à support@surmado.com.

Vous créez une intégration ? Nous aimerions en entendre parler ! Partagez votre cas d’usage à hi@surmado.com.

Pour commencer : Essayer Surmado | Travailler avec Scout