Quiz Setup with API Steps

Overview

SuperFunnel now supports advanced quiz logic beyond conditional branching. You can make API calls within quiz steps, route visitors based on API responses, manage secrets securely, and visualize all of this in the Logic view.

This guide covers the new capabilities:

• API Call Steps — make HTTP requests to external services
• Router Steps — branch logic based on conditions or API responses
• Secrets management — securely store and use API keys, tokens, and credentials
• Logic visualization — see your entire quiz's logic flow, including API calls and routing

API Call Steps

An API Call Step lets you make an HTTP request to an external service during the quiz flow. Common use cases:

• Validate data in real-time — check if an email exists, verify a phone number, look up company info
• Enrich data — call an API to fetch additional information (geolocation, firmographics, etc.)
• Integrate with backend systems — trigger workflows, create records, or fetch dynamic content
• Route based on API response — use the API's response to decide which step comes next

How to Add an API Call Step

Ask your agent to add an API step:

Add an API call step that [describes what you want to do].
Use [HTTP method] to [endpoint].
[Describe any parameters or headers needed].
Route based on the response: if [condition], go to [step], else go to [step].

Example:

Add an API call step that validates the email address using the Zerobounce API.
Use GET to https://api.zerobounce.net/v1/validate.
Include the email from the previous step and the API key.
If the email is valid, go to "Qualified Questions", otherwise go to "Invalid Email".

The agent will set up:

1. The API request (method, URL, headers, parameters)
2. How to pass form data into the request
3. Which fields from the API response to capture
4. Routing logic based on the response

API Call Step in Logic View

When you view your quiz's Logic, API Call Steps appear as standalone nodes in the flow, making it easy to see where API calls happen and how they connect to other steps.

Router Steps

A Router Step (or branch/decision node) routes visitors to different steps based on conditions. Routers are useful when:

• You need complex conditional logic that spans multiple paths
• You're branching based on API responses from an earlier step
• You want to group multiple conditions together visually

How to Add a Router Step

Ask your agent to add routing logic:

After step [name], add a router that branches based on [condition].
If [condition 1], go to [step A].
If [condition 2], go to [step B].
Otherwise, go to [step C].

Example:

After the "Company Size" question, add a router.
If company_size >= 100, go to "Enterprise Questions".
If company_size >= 10, go to "Mid-Market Questions".
Otherwise, go to "SMB Questions".

Routers appear in the Logic view as decision nodes, making your quiz's flow easy to understand at a glance.

Secrets Management

When your API calls need credentials (API keys, tokens, OAuth credentials), SuperFunnel keeps them secure on a SuperFunnel server. You don't have to manage them yourself or expose them in your quiz.

How Secrets Work

1. You provide the secret — When you add an API step, the agent may prompt you to provide an API key or token. You enter it once.
2. SuperFunnel stores it securely — The secret is stored on SuperFunnel's secure servers, never in your quiz code or browser.
3. The agent references it — The agent uses [secret.key_name] syntax in API calls to reference the secret. The actual value is never exposed.
4. You cannot retrieve it — For security, you cannot copy a secret retroactively after it's stored. Keep a record of your secrets somewhere safe.

Managing Secrets

To see all secrets in your workspace and manage them:

1. Open any quiz
2. Click the three dots (...) on a step, select Edit
3. In the Execution section, click Manage
4. You'll see a list of all secrets used in your workspace
5. You can review which steps use which secrets, but you cannot view the secret values themselves

Best Practices for Secrets

• Keep a record — Store your API keys and tokens in a password manager or secure vault. You won't be able to retrieve them from SuperFunnel.
• Rotate regularly — Periodically update your API keys in your source system (e.g., regenerate in the API provider), then update them in SuperFunnel.
• Limit scope — Use API keys with minimal permissions needed for the specific task.
• Use per-environment keys — Keep separate keys for development/testing and production, if possible.

When the Agent Asks for a Secret

If you ask the agent to add an API call that needs a credential, the agent will recognize this and prompt you:

You: "Add an API step that calls the Stripe API to create a customer."
Agent: "I can do that. You'll need a Stripe API key. Please provide your Stripe secret key (it will be stored securely and you won't be able to retrieve it later)."

Provide the secret, and the agent will store it and reference it in the API call.

Execution Settings

When you add an API Call Step, you can configure how and when the call executes using the Execution section.

Browser vs. Server Execution

When editing an API step, you'll see an Execution dropdown with two options:

Browser (default)

• The API call runs in the visitor's browser
• Use this when your API needs local information (geolocation, device type, screen size, timezone)
• The API receives the actual user's location/device data
• Example: calling a geolocation API to determine the user's city

Server (proxy + secrets)

• The API call runs on SuperFunnel's server
• Use this for validation, enrichment, and integration API calls
• Secrets are stored securely on the server and never exposed to the browser
• The server's location is used if the API depends on where the request originates from
• Example: calling Zerobounce to validate an email, or Clearbit to enrich company data

Rule of thumb: If your API needs the visitor's location or device info, use Browser. For everything else (validation, data enrichment, integrations), use Server.

On Failure: Route to a Step

If an API call fails (timeout, invalid response, error), you can route visitors to a specific step instead of breaking the quiz:

1. In the API step settings, find On failure, go to
2. Select a step to route to (e.g., "Try Again", "Skip This Question", or "End Quiz")
3. This ensures visitors always have a next step even if the API fails

Timeout and Retries

By default, API calls wait 5 seconds and retry 0 times. If your API is slow or unreliable, you can customize these:

Timeout (milliseconds)

• How long to wait for the API to respond
• Default: 5000 ms (5 seconds)
• Increase if your API is known to be slow
• Example: set to 10000 ms if the API sometimes takes 7-8 seconds

Retries

• How many times to retry if the API fails
• Default: 0 (no retries)
• Set to 1–3 if your API occasionally fails
• Example: set to 2 if the API fails ~10% of the time

If the API still fails after retries, it will route to your "On failure" step (if configured).

Logic View

The Logic view shows your entire quiz's flow, including:

• All steps and questions
• API Call Steps as standalone nodes
• Router Steps as decision points
• Connections between steps
• Conditional branches and routing logic

This makes it easy to:

• Understand the overall quiz flow at a glance
• See where API calls happen and how they affect routing
• Identify complex logic that might confuse visitors
• Debug issues with branching or conditional logic

To view Logic:

1. Open your quiz
2. Look for a Logic tab or button (exact location depends on your UI)
3. The flow diagram shows all steps and connections

API Call vs. Custom Code

SuperFunnel now supports both approaches for integrating with external systems:

API Call Steps (recommended):

• ✅ UI-based, easy to configure through the agent
• ✅ Secrets managed securely by SuperFunnel
• ✅ Visible in Logic view for easy understanding
• ✅ No custom code to maintain

Custom Code (for advanced users):

• Still available if you need maximum flexibility
• You manage secrets in your code
• Harder to visualize in Logic
• Requires technical knowledge

For most cases, API Call Steps are the recommended approach because they're simpler, more secure, and easier to understand.

Example: A Complete Quiz with API Validation

Here's what a quiz with API steps might look like:

1. Step 1: Email — visitor enters email
2. API Step: Validate Email — calls Zerobounce API to validate, stores result
3. Router Step: Valid Email? — branches based on validation result
   • If valid → go to Step 2
   • If invalid → go to "Invalid Email" (exit step)
4. Step 2: Company — visitor enters company name
5. API Step: Lookup Company — calls Clearbit API to enrich company data
6. Step 3: Qualification Questions — ask follow-up questions
7. Router Step: Qualified? — routes based on answers
   • Enterprise → Results page 1
   • Mid-market → Results page 2
   • SMB → Results page 3

You can ask the agent to build this entire flow:

Build a quiz with these steps:
1. Email field
2. Validate the email using Zerobounce API
3. If invalid, end the quiz with an "Invalid Email" message
4. If valid, ask for company name
5. Look up the company using Clearbit API
6. Ask qualification questions (budget, team size)
7. Route to different results pages based on company size and budget

Use my Zerobounce API key (I'll provide it) and my Clearbit API key.

Troubleshooting

API call is failing:

• Check that your secret (API key) is correct and still valid in the source system
• Verify the endpoint URL and HTTP method are correct
• Make sure required parameters are being passed from form fields
• Use test mode to try the API call before going live

Router not working:

• Check that your conditions are written correctly
• Ensure the field names match exactly (case-sensitive)
• Test with actual data to see which path the router takes

Secret not recognized:

• Ensure the secret is managed in the Execution > Manage section
• Verify the secret name matches what you're referencing in the API call

What's Next