Surmado API - No-Code Guide

Build AI visibility and competitive intelligence into your workflow without writing code.

This guide is for marketers, agencies, and consultants using automation tools like Zapier, Make, and n8n.

Developer? See DEVELOPER_GUIDE.md for code examples and API reference.

---

What You Can Do

Connect Surmado to 5,000+ apps to automate:

• ✅ Generate reports from Google Sheets or Airtable
• ✅ Create reports when deals close in HubSpot/Salesforce
• ✅ Schedule monthly competitive analysis
• ✅ Build public forms where users request their own reports
• ✅ Bulk generate reports for 100+ clients

No coding required! Just connect blocks in your automation tool.

---

Table of Contents

• 5-Minute Quick Start
• Core Concepts
• Zapier Integration
• Make Integration
• n8n Integration
• Common Patterns
• Troubleshooting

---

5-Minute Quick Start

Step 1: Get Your API Key

1. Visit app.surmado.com
2. Click Settings → API Keys
3. Click Create New API Key
4. Copy the key (you’ll only see it once!)

Your key looks like: sur_live_H2gPVFuEPytcw2EKQ79Z...

💾 Save this somewhere safe! You’ll use it in all your automations.

---

Step 2: Choose Your Approach

🎯 Simple Approach (Recommended): Send company name directly - we handle everything!

Just include "brand_name" in your report request
→ We auto-create the brand
→ Response includes brand_slug
→ ONE step instead of two!

🔧 Advanced Approach: Create brand first, then use brand_slug

Step 1: POST /v1/brands/ensure → Get brand_slug
Step 2: POST /v1/reports/[product] → Use brand_slug

For this guide, we’ll use the Simple Approach - it’s easier and requires less setup!

---

Step 3: Your First Automation (Zapier Example)

Goal: Google Sheet → Signal Report

Step 1: Create a Zap

• Trigger: New row in Google Sheets
• Columns: Company Name, Email

Step 2: Create Signal Report (Webhooks by Zapier)

• Action: POST Request
• URL: https://api.surmado.com/v1/reports/signal
• Headers:

  Authorization: Bearer YOUR_API_KEY_HERE
  Content-Type: application/json

• Body:

  {
    "brand_name": "{{Company Name}}",
    "tier": "basic",
    "email": "{{Email}}",
    "industry": "Technology",
    "business_scale": "medium",
    "location": "United States",
    "product": "Software",
    "persona": "Tech companies",
    "pain_points": "Need better visibility",
    "brand_details": "Innovative tech company",
    "direct_competitors": "Competitor A, Competitor B",
    "keywords": "tech, software"
  }

• Test it → You’ll get back report_id, brand_slug, and brand_created

Step 3: Update Google Sheets (Optional)

• Action: Update Row
• Column D: {{Step 2 report_id}}
• Column E: {{Step 2 brand_slug}}

Done! ✅ Every new row → New Signal report (ONE step instead of two!)

---

Core Concepts

What’s a Brand?

A brand is like a folder for a company. Create it once, use it forever.

You → Create brand "Acme Corp"
    → Get back: brand_slug = "acme_corp"
    → Use "acme_corp" for all Acme reports

Why brands?

• No typing company names over and over
• Easy filtering (“show all Acme reports”)
• Future: Brand history and context

Two Patterns (Choose One!)

Pattern 1: Simple (Recommended)

POST /v1/reports/[product]
    {"brand_name": "Company Name", ...}
    → Returns: report_id, brand_slug, brand_created

Just send the company name - we create the brand automatically!

Pattern 2: Advanced (More Control)

Step 1: POST /v1/brands/ensure
        {"brand_name": "Company Name"}
        → Returns: brand_slug

Step 2: POST /v1/reports/[product]
        {"brand_slug": "company_name", ...}
        → Returns: report_id

Use this if you need to manage brands separately or reuse brand_slug across multiple reports.

Three Products

Product	What It Does	Time	Cost
Signal	How AIs talk about your brand	~5 min	2 credits
Pulse	Website competitive analysis	~3 min	1-2 credits
Solutions	Strategic advisory board session	~10 min	2 credits

---

Zapier Integration

Best for: Beginners, simple workflows, connecting popular apps

Pattern 1: Google Sheets → Signal Report

Use Case: Bulk generate reports from a spreadsheet

Trigger: New row in Google Sheets

• Column A: Company Name
• Column B: Website
• Column C: Email

Action 1: Webhooks by Zapier (POST)

URL: https://api.surmado.com/v1/reports/signal
Method: POST
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json
Body:
{
  "brand_name": "{{Column A: Company Name}}",
  "tier": "basic",
  "email": "{{Column C: Email}}",
  "industry": "Technology",
  "business_scale": "medium",
  "location": "United States",
  "product": "{{Column B: Website}}",
  "persona": "Business decision makers",
  "pain_points": "Need better AI visibility",
  "brand_details": "Innovative company seeking AI presence",
  "direct_competitors": "Industry leaders",
  "keywords": "AI, visibility, search"
}

Action 2: Update Google Sheets

• Action: Update Row
• Column D: {{Step 1 report_id}}
• Column E: {{Step 1 brand_slug}}
• Column F: “Queued”

Result: Add 100 companies to sheet → 100 reports generated automatically! (ONE step per report instead of two!)

---

Pattern 2: Typeform Submission → Solutions Report

Use Case: Public form where users request strategic advice

Trigger: New Typeform submission

Action 1: Ensure Brand

URL: https://api.surmado.com/v1/brands/ensure
Body:
{
  "brand_name": "{{Company Name from form}}"
}

Action 2: Create Solutions Report

URL: https://api.surmado.com/v1/reports/solutions
Body:
{
  "brand_slug": "{{brand_slug}}",
  "email": "{{Email from form}}",
  "name": "{{Name from form}}",
  "business_story": "{{Tell us about your business}}",
  "decision": "{{What decision are you making?}}",
  "success": "{{What does success look like?}}",
  "timeline": "{{When do you need this?}}",
  "scale_indicator": "{{Business size}}"
}

Action 3: Send Email

• To: {{Email from form}}
• Subject: “Your Strategic Advisory Report is Processing”
• Body: “We’ll email you at this address when your report is ready (usually 10 minutes).”

---

Pattern 3: Scheduled Monthly Reports

Use Case: Monthly competitive analysis for all clients

Trigger: Schedule (First day of month)

Action 1: Google Sheets - Get Rows

• Get all rows from “Clients” sheet

Action 2: Loop** (For each client)

Inside Loop:

1. Ensure Brand
2. Create Pulse Report

   {
     "brand_slug": "{{brand_slug}}",
     "tier": "premium",
     "url": "{{Client Website}}",
     "email": "{{Client Email}}",
     "report_style": "executive"
   }

3. Send Email to client

---

Make Integration

Best for: Complex workflows, visual automation, advanced logic

Scenario: HubSpot Deal → Signal Report

1. Watch Deals (HubSpot)

• Trigger: Deal reaches “Won” stage

2. HTTP Request (Ensure Brand)

Method: POST
URL: https://api.surmado.com/v1/brands/ensure
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json
Body:
{
  "brand_name": "{{1.company_name}}"
}

Parse response: Yes Output: brand_slug

3. HTTP Request (Create Signal Report)

Method: POST
URL: https://api.surmado.com/v1/reports/signal
Body:
{
  "brand_slug": "{{2.brand_slug}}",
  "tier": "pro",
  "email": "{{1.contact_email}}",
  "industry": "{{1.industry}}",
  "business_scale": "{{1.company_size}}",
  "location": "{{1.company_location}}",
  "product": "{{1.product_description}}",
  "persona": "{{1.target_customer}}",
  "pain_points": "{{1.pain_points}}",
  "brand_details": "{{1.notes}}",
  "direct_competitors": "{{1.competitors}}",
  "keywords": "{{1.keywords}}"
}

4. Update Deal (HubSpot)

• Field: “Signal Report ID” = {{3.id}}
• Field: “Report Status” = “Queued”

5. Slack - Send Message

• Channel: #sales
• Message: ”🎉 Signal report queued for {{1.company_name}}! Report ID: {{3.id}}“

---

Advanced: Conditional Logic

Scenario: Different report types based on deal size

1. HubSpot Deal Won
   ↓
2. Router (by deal value)
   ├─ If value > $50K → Signal Pro
   ├─ If value > $10K → Signal Basic
   └─ If value < $10K → Skip

3a. Branch 1: Create Signal Pro
3b. Branch 2: Create Signal Basic

4. Merge → Update HubSpot

---

n8n Integration

Best for: Self-hosted, open-source, maximum control

Workflow: Airtable → Pulse Reports

1. Airtable Trigger (New Record)

• Base: Clients
• Table: Active Clients
• Fields: Company Name, Website, Email

2. HTTP Request (Ensure Brand)

Method: POST
URL: https://api.surmado.com/v1/brands/ensure
Authentication: Header Auth
  Name: Authorization
  Value: Bearer YOUR_API_KEY
Body (JSON):
{
  "brand_name": "={{ $json.Company_Name }}"
}

Output: Parses automatically to {{ $node["HTTP Request"].json.brand_slug }}

3. HTTP Request (Create Pulse Report)

Method: POST
URL: https://api.surmado.com/v1/reports/pulse
Body:
{
  "brand_slug": "={{ $node["HTTP Request"].json.brand_slug }}",
  "tier": "basic",
  "url": "={{ $json.Website }}",
  "email": "={{ $json.Email }}"
}

4. Airtable (Update Record)

• Record ID: ={{ $json.id }}
• Fields:
  • Report ID: ={{ $node["HTTP Request 1"].json.id }}
  • Status: “Queued”
  • Queued At: ={{ $now }}

5. Discord Webhook (Optional)

• Message: ”✅ Report queued for {{ $json.Company_Name }}“

---

Pro Tip: Error Handling in n8n

Add an “Error Trigger” node to catch failures:

Main Workflow
   ├─ Success → Update Airtable
   └─ Error → Error Trigger
              └─ Send Slack Alert
              └─ Log to Error Table

---

Common Patterns

Pattern 1: Bulk Report Generation

Use Case: Generate reports for 100 clients from spreadsheet

Tool: Any (Zapier, Make, n8n)

Flow:

Spreadsheet → For Each Row →
  Ensure Brand → Create Report → Update Spreadsheet

Pro Tip: Add a delay (5-10 seconds) between reports to avoid rate limits.

---

Pattern 2: CRM Integration

Use Case: Auto-generate Signal when prospect added

Tool: Make or n8n (better for CRM integrations)

Flow:

CRM New Contact →
  Ensure Brand → Create Signal → Add Report Link to CRM

Bonus: Set up a webhook to update CRM when report completes.

---

Pattern 3: Scheduled Monitoring

Use Case: Monthly competitive analysis for all clients

Tool: Zapier (simplest for schedules)

Flow:

Schedule (1st of month) →
  Fetch Client List →
  For Each Client →
    Ensure Brand → Create Pulse →
    Email Report to Client

---

Pattern 4: Public Form

Use Case: Anyone can request a report from your website

Tool: Zapier + Typeform/Google Forms

Flow:

Form Submission →
  Ensure Brand → Create Report →
  Send Confirmation Email

Safety: Add a filter to only process verified email domains or require approval.

---

Field Reference

Required Fields (All Reports)

These fields are always required:

Field	Type	Description	Example
brand_name OR brand_slug	string	Company name OR slug	"Acme Corp" OR "acme_corp"
email	email	Contact email	"hi@acme.com"
tier	string	"basic" or "pro"	"basic"

Pro tip: Just send brand_name - we’ll create brand_slug automatically!

Signal-Specific Fields

Field	Required	Description	Example
industry	Yes	Industry category	"Technology"
business_scale	Yes	small/medium/large	"regional"
location	Yes	Primary location	"United States"
product	Yes	What you offer	"CRM software"
persona	Yes	Target customer	"Small business owners"
pain_points	Yes	Customer problems	"Losing track of customers"
brand_details	Yes	Brand description	"Simple CRM with email integration"
direct_competitors	Yes	Comma-separated	"HubSpot, Pipedrive"
keywords	No	SEO keywords	"CRM, sales"

Pulse-Specific Fields

Field	Required	Description	Example
url	Yes	Website to analyze	"https://acme.com"
report_style	No	executive/technical/comprehensive	"executive"
competitor_urls	No	Array of competitor URLs	["https://rival.com"]

Solutions-Specific Fields

Field	Required	Description	Example
name	Yes	Contact name	"John Smith"
business_story	Yes	Tell us about your business	"B2B SaaS, 50 employees, $3M ARR"
decision	Yes	What are you deciding?	"Should we build mobile app?"
success	Yes	What does success look like?	"40% engagement increase"
timeline	Yes	When do you need this?	"Next 30 days"
scale_indicator	Yes	Business scale	"regional"
signal_token	No	Signal report token	"SIG-2025-11-ABC12"

---

Troubleshooting

”401 Unauthorized”

Problem: Your API key is invalid or missing.

Fix:

1. Check you copied the full key (starts with sur_live_)
2. Verify the Authorization header format:

   Authorization: Bearer sur_live_YOUR_KEY

3. Make sure there’s a space after “Bearer"

---

"402 Insufficient Credits”

Problem: Your organization doesn’t have enough credits.

Fix:

1. Log into app.surmado.com
2. Go to Billing
3. Purchase more credits

Pro Tip: Set up low-credit alerts in your automation:

Before creating report →
  Check credits →
  If < 10 → Send alert

---

“404 Brand Not Found”

Problem: You’re passing brand_slug but the brand doesn’t exist.

Fix: Always use the two-step pattern:

Step 1: POST /v1/brands/ensure → Get brand_slug
Step 2: POST /v1/reports/[product] → Use that brand_slug

Don’t hardcode brand slugs or skip Step 1!

---

”Validation Error: Missing Field”

Problem: You didn’t include a required field.

Fix: Check the Field Reference above and make sure all “Yes” fields are included.

Common mistake: Forgetting brand_slug in Step 2.

---

Report ID is Coming Back as “null”

Problem: The API returned an error, but your automation isn’t showing it.

Fix in Zapier:

1. Click on the failed step
2. Look at the “Response” section
3. Find the error message in detail

Fix in Make/n8n:

• Enable “Parse response” on HTTP modules
• Check the full response body

---

Automation Keeps Failing at Random

Problem: Hitting rate limits (20 requests/minute).

Fix: Add delays between bulk operations:

Zapier: Add “Delay” action (3-5 seconds between requests)

Make: Add “Sleep” module (3-5 seconds)

n8n: Use “Wait” node (3-5 seconds)

Need higher limits? Contact support@surmado.com with your use case. We can configure custom limits for high-volume integrations.

---

How Do I Know When Report is Done?

Option 1: Use Webhooks (Recommended)

Add webhook_url to your report request:

{
  "brand_slug": "acme_corp",
  "webhook_url": "https://your-automation-tool.com/webhook",
  ...
}

When report completes, we POST to that URL with download link.

Option 2: Poll (Not Recommended)

Create a second automation:

Schedule (every 5 minutes) →
  Check report status →
  If complete → Do something

---

Using Webhooks (Step-by-Step)

Webhooks let your automation automatically continue when a report finishes - no waiting or checking!

What You’ll Receive

When your report completes, we’ll POST to your webhook URL:

{
  "report_id": "rep_abc123",
  "status": "completed",
  "brand_slug": "acme_corp",
  "brand_name": "Acme Corp",
  "result_url": "https://storage.googleapis.com/.../report.pdf",
  "pptx_url": "https://storage.googleapis.com/.../report.pptx",
  "completed_at": "2025-11-17T06:00:00Z",
  "report_type": "signal",
  "tier": "pro"
}

Make.com Setup

Step 1: Add “Custom Webhook” module at the START of your scenario

Step 2: Click “Add” → Copy the webhook URL

Step 3: Run your “Create Report” module with this webhook URL:

{
  "brand_name": "{{1.CompanyName}}",
  "tier": "pro",
  "webhook_url": "https://hook.us1.make.com/abc123...",
  ...
}

Step 4: Add modules AFTER the webhook to handle completion:

• Download PDF from result_url
• Save to Google Drive
• Send email notification
• Update CRM

That’s it! Your scenario will pause after creating the report, then automatically resume when we send the webhook.

Zapier Setup

Step 1: Create a new Zap

Step 2: Choose “Webhooks by Zapier” as trigger → Select “Catch Hook”

Step 3: Copy the webhook URL

Step 4: In your “Create Report” action, include the webhook URL:

{
  "brand_name": "Acme Corp",
  "webhook_url": "https://hooks.zapier.com/hooks/catch/YOUR_ID/",
  ...
}

Step 5: Test trigger to see webhook data structure

Step 6: Add actions:

• Send email with result_url
• Save to Airtable
• Post to Slack
• Whatever you need!

n8n Setup

Step 1: Add “Webhook” node at the START of your workflow

Step 2: Set “HTTP Method” to POST

Step 3: Copy the “Production URL”

Step 4: In your “Create Report” HTTP Request node:

{
  "brand_name": "{{$node["Get_Company"].json["name"]}}",
  "webhook_url": "https://your-n8n.com/webhook/YOUR_PATH",
  ...
}

Step 5: Add nodes after webhook to process the data

Step 6: Activate workflow (must be active to receive webhooks!)

Testing Your Webhook

Easiest way: webhook.site

1. Go to https://webhook.site
2. Copy your unique URL
3. Create a test report with that URL as webhook_url
4. Wait 2-5 minutes
5. See the webhook arrive in real-time!

What you should see:

• Request Method: POST
• Header: X-Surmado-Signature (security signature)
• Body: JSON with report_id, result_url, etc.

Common Questions

Q: How long until webhook fires? A: 2-10 minutes depending on report type and tier

Q: What if my webhook URL is wrong? A: No problem! The report still generates. You can get the PDF from the dashboard.

Q: Can I use the same webhook for multiple reports? A: Yes! Use the report_id and brand_slug fields to identify which report completed.

Q: What if my webhook endpoint is down? A: We retry 3 times (30s, 2min, 5min delays). After that, you can still get the PDF from app.surmado.com

---

Quick Reference

Key Endpoints

Action	URL	Method
Get/create brand	/v1/brands/ensure	POST
Create Signal	/v1/reports/signal	POST
Create Pulse	/v1/reports/pulse	POST
Create Solutions	/v1/reports/solutions	POST
Check status	/v1/reports/{id}	GET

Authentication Header

Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

Minimum Request Body

For any report:

{
  "brand_slug": "from_step_1",
  "tier": "basic",
  "email": "contact@company.com",
  // ... product-specific required fields
}

---

Next Steps

Ready to automate?

1. ✅ Get your API key from app.surmado.com
2. ✅ Pick your tool (Zapier, Make, or n8n)
3. ✅ Follow the pattern for your use case above
4. ✅ Test with a single report first
5. ✅ Scale up to bulk operations

Need code examples? → DEVELOPER_GUIDE.md

Questions? → hi@surmado.com

---

🎉 You’re all set! Start building amazing automated workflows with Surmado.