Quick-Start Guide — Your First API Call in 5 Minutes

This guide gets you from zero to pulling demo analytics data in under 5 minutes. No coding experience required — just a terminal or any HTTP tool (Postman, Insomnia, etc.).

What You Need

• Your API key (provided by your Walnut account team, starts with wlt_)
• A terminal (Mac/Linux) or Postman (Windows/Mac/Linux)

<aside> 🔑

Keep your API key safe. Treat it like a password. Don't share it in Slack, email, or commit it to code repositories. If you lose it, contact your Walnut account team for a replacement.

</aside>

Step 1: Verify the Connection

Run this command — no API key needed. If you get {"status": "ok"}, you're good to go.

curl <https://customer-api.teamwalnut.com/health>

Expected response:

{ "status": "ok" }

Step 2: Pull Your First 5 Sessions

Replace YOUR_API_KEY with the key your Walnut team provided.

curl -H "x-api-key: YOUR_API_KEY" \\
  "<https://customer-api.teamwalnut.com/demo-sessions?limit=5>"

What you'll see: A JSON response with your 5 most recent demo sessions, including viewer type, engagement metrics, geography, and more.

<aside> ✅

Got data back? You're authenticated and connected. Everything below builds on this.

</aside>

<aside> ❌

Got an error?

• 401 Unauthorized → Check that you included the x-api-key header (not Authorization)
• 403 Forbidden → Double-check your API key is correct and active
• Connection error → Make sure you can reach customer-api.teamwalnut.com from your network </aside>

Step 3: Filter to What Matters

You probably don't need all 29 fields. Here's how to get just the essentials for external prospects in the last 30 days:

curl -H "x-api-key: YOUR_API_KEY" \\
  "<https://customer-api.teamwalnut.com/demo-sessions?fields=demo_name,started_at,is_completed,interaction_count,geo_country_name&user_type=external&start_date=2026-02-01&limit=20>"

This returns only 5 fields instead of 29, filtered to external viewers, scoped to a date range.

Useful filters:

Step 4: Get a High-Level Summary

Don't need individual sessions? Get a full analytics snapshot in one call:

curl -H "x-api-key: YOUR_API_KEY" \\
  "<https://customer-api.teamwalnut.com/demo-sessions/summary>"

This gives you in a single response:

• Total sessions, completed, and bounced counts
• Average duration, interactions, and screen views
• Breakdown by user type (external vs. internal)
• Breakdown by viewer type (prospect, owner, colleague)
• Embedded vs. direct link split
• Top 10 demos by session volume
• Top 10 countries

You can scope the summary to a specific period:

curl -H "x-api-key: YOUR_API_KEY" \\
  "<https://customer-api.teamwalnut.com/demo-sessions/summary?start_date=2026-01-01&end_date=2026-01-31>"

Step 5: See Trends Over Time

Use group_by to aggregate sessions by date — perfect for charts and dashboards:

curl -H "x-api-key: YOUR_API_KEY" \\
  "<https://customer-api.teamwalnut.com/demo-sessions?group_by=date&start_date=2026-02-01&user_type=external>"

Response:

{
  "data": {
    "2026-02-01": 142,
    "2026-02-02": 98,
    "2026-02-03": 215
  },
  "total": 455,
  "group_by": ["date"]
}

You can also group by user_type, viewer_type, demo_id, or is_embed. Combine multiple dimensions with commas: group_by=date,user_type.

You're Up and Running

That's it — you're pulling live demo analytics data. Here's what to explore next:

Quick Reference

<aside> 💬

Need help? Reach out to your Walnut account team with the request URL, timestamp, and HTTP status code — we'll sort it out quickly.

</aside>