IncentiveSwift User Guide

A comprehensive guide to IncentiveSwift — the complete platform for running engaging campaigns, qualifying leads with intelligent surveys, and integrating with your marketing stack. From viral giveaways to qualified lead generation, everything in one place.

🚀 Getting Started

IncentiveSwift is built around two core concepts: Campaigns (interactive giveaways and contests) and IQS (Intelligent Qualifying Surveys). You can use them independently or together — attach a survey as a gate before a campaign entry.

Quick Start

1. Log In

   Click Sign In at https://incentiveswift.com — or go straight to https://app.incentiveswift.com/login. Either way you land in your app dashboard. If you don't have an account, sign up first.

2. Create a Campaign

   From your dashboard click Admin Console (app.incentiveswift.com/admin — also served as admin.incentiveswift.com), then in the sidebar click Campaigns → + New Campaign. Choose a type (start with Spin the Wheel), give it a name, and set your entry rules.

3. Add Prizes

   Define what users can win — cash amounts, discounts, free shipping, or custom rewards. Configure the odds for each prize.

4. Launch

   Toggle the campaign to Active. Your campaign is now live with a shareable link and embed code.

5. Track Results

   Monitor entries, wins, and conversions in the Campaign detail view and Analytics section.

📊 Dashboard

The dashboard shows your key numbers at a glance: total campaigns, total entries, participants, points issued and rewards given — each figure read from your own account when the page opens. Under them, Recent activity lists the newest entries to your campaigns, naming the campaign, who took part and when. Until people start taking part it says so in words rather than showing zeros.

Your account sits under those numbers: your name, company and username, the plan you are on, your password, your sign-in email, the devices signed in to your account and your picture. The same card carries Close this account for when you want to leave: closing it stops you signing in and signs out every device, while your workspace, your campaigns and your loyalty records stay where they are, so your history and your invoices are kept. Ask support if you want the account reopened.

Example figures — your dashboard shows your own numbers.

💬 Telling us what you think

A Feedback button sits at the bottom-left of every screen in your dashboard. Press it, choose Idea, Problem or Complaint, write your note and press Send. The note reaches our team together with the screen you were on, so they know where to look, and their answer reaches you by email. Nothing is posted publicly, and nothing else in your dashboard changes.

🗂️ Workspaces and 📬 Inbox

A workspace is a separate drawer inside your business account - a client, a location, or a brand you run from the same login. Your plan says how many you may have, and exactly one of them is the default: the one a new sign-in opens.

In the Workspaces card on your dashboard you can:

• create a workspace (give it the name your team will recognise),
• rename one,
• press Make default so it opens on your next sign-in,
• delete one - your account always keeps at least one, and the server says so in plain English if you try to remove the last.

A name you already use is refused, and a plan ceiling is refused with the number your plan actually carries - you will never be left guessing.

The Inbox card on the same page gives your business real mailboxes on your own domain. The steps:

1. Add the domain you already own, together with the mail provider key for that domain. The key is stored encrypted; it is never shown back.
2. Press Show records and paste exactly what it prints at your DNS provider (Cloudflare, your registrar, anywhere - your domain stays yours).
3. Press Check again. Until the records are live the addresses cannot receive mail, and the server refuses to create one (with the sentence telling you to check again) rather than handing you an address that silently rejects mail.
4. Create the addresses you want - info, support, your own name - and each one appears in the list.

Read and answer the mail in the mail client: press Open the mail client or go to inbox.incentiveswift.com. It is the same account and the same mail - there is nothing to sign in to twice.

A branded address of your own (inbox.yourbusiness.com) is not offered yet; for now your mail is read and answered at inbox.incentiveswift.com. How much you can add is read from the plan you are on, and an operator can raise it for you on request.

💳 Plans & Billing

Your dashboard's Plan & billing card shows the plan this workspace is on, what each plan includes, and the way up. Nothing is charged from this screen: pressing Upgrade to … (or Downgrade to …) files a request for our team, and the card underneath — Your plan requests — lists every request this workspace has filed with its live state: open until the team picks it up, then the state they set, and this workspace is on it now once they have moved you onto the plan you asked for. Picking a paid plan on the pricing page at signup files the same request, so a fresh workspace's first ask is never lost.

If you filed a request by mistake, or you no longer want the change, press Withdraw on that row. The request leaves our queue, nothing was charged, and you can ask again at any time. Withdraw is offered only while the request is still open: once the team has moved the workspace onto the plan, that row is the record of the switch and it stays. A message you sent us through support is not a plan request and cannot be withdrawn — reply on it instead, and the team picks it up.

🎮 Campaign Types

Your console's campaign builder offers fifteen mechanics. You pick one on the Campaigns → New campaign form, and it decides what a participant does when they open the campaign. Every campaign has one public address — https://app.incentiveswift.com/play/<slug> — and the builder starts each mechanic with the settings listed below. Those settings live in the campaign's Edit form (the config box), so you can change them at any time without leaving the console.

🔄 Spin Wheel

The instant-win mechanic, and the one most campaigns use. The participant taps once and the wheel lands on a segment. Prizes are a list, so you can add as many as you like and give each its own label, colour and odds. Settings start as {"prize_pool":{"prizes":[]}} — the wheel has no segments until you add them.

🪙 Scratch Card

The participant scratches the card to reveal what is underneath. It carries the same prize list as the wheel plus win_probability (the builder starts it at 0.5), so you control how often a card is a winner.

🎟️ Raffle & Giveaway

Entries are collected over time and winners are drawn later, which suits a promotion that runs for a week rather than a single visit. The mechanic starts with no settings of its own: the schedule and the prize are yours to state on the campaign, and the entries are the list you draw from.

📝 Quiz

Multiple-choice questions with a pass mark. The builder starts the pass mark at 70 (passing_score), and questions are added to the campaign itself, so a quiz is a qualification gate as much as a game.

🧠 Personality Quiz

There is no right answer: the participant's choices sort them into one of the outcomes you define (outcomes). Use it for "which product suits me" style segmentation, where the outcome is the lead's tag.

🎯 Score Reveal

The participant answers, then sees a score placed in a band. Bands are tiers — each with a minimum, a maximum, a label and a message — so the same questions can read as a rating, a readiness check or a grade.

🧮 Calculator

The participant enters numbers and the campaign works out a figure from formula. Good for a savings, ROI or "how much is this costing you" pitch, where the number itself is the hook.

🎁 Mystery Reveal

A hidden reward the participant opens on the page. The reward's label is reward.label; the mechanic is the suspense of the reveal rather than a chance-based win.

⏳ Countdown Timer

A campaign built around a deadline: target_at holds the moment the timer counts to, and it starts at the end of the year. Use it for a launch, a drop or a closing offer.

📊 Poll

One question with a set of answers, starting as question "Your question here?" with options of Yes and No. Change both to your own wording — a poll is the lightest thing a visitor can take part in, which makes it a good first-touch campaign.

💬 Chat Funnel

A guided conversation instead of a form: chat_flow is the list of lines the participant is walked through, and system_prompt tells the assistant how to behave. Use it when the questions depend on what the person says.

🏆 Leaderboard

The same entries, ranked. A leaderboard campaign starts with no settings of its own because the ranking is the entries' own scores — publish it where a competitive audience can watch it move.

📋 Long-Form Qualifier

A multi-section qualifying form: sections hold the questions, rules decide what counts as qualified, and outcomes say what happens to each result. This is the mechanic to use when you need a real application rather than a game.

🏪 Loyalty and 🤝 B2B Loyalty

These two hand the campaign to your loyalty programme: a participant who takes part earns points, and the campaign can enrol them at the same time. Read the loyalty section below before you pick one — the points rate and the offers live there, not on the campaign.

Two mechanics you may have read about elsewhere — a three-reel Slots machine and a multi-tier Wheel of Fortune — are not offered in the builder. If a campaign of that kind is what you need, use Spin Wheel with more segments; it is the same wheel with the odds you set.

🏪 Loyalty Program

IncentiveSwift powers comprehensive loyalty programs with purchase verification, credit earning and redeeming, custom offers, and a referral system. The loyalty module transforms one-time campaign participants into repeat, engaged customers.

You start a programme from that same dashboard: under Loyalty programme give it a name (and, if you like, the points each check-in earns) and press Create programme. It appears in the card at once with its own check-in link — the address a printed counter QR encodes — and a Copy check-in link button beside it. Once you have one, a New programme button in the same card adds another; every rule can be changed afterwards under Edit programme settings.

Inside Edit programme settings you also build the status ladder: the rungs a member climbs by balance, each with its own name, the points it starts at, a colour and a multiplier that tops up every award while the member holds it (up to eight rungs). Press Save ladder and the rungs are saved at once; tick Status tiers on and press Save programme to put members on the ladder — with the switch off the rungs are stored but nobody is tiered. Members already on the ladder keep the rung their balance earns, and the check-in page your customers open prints the ladder so they can see what is next.

Your dashboard carries the roster that goes with it: open Members under a programme and you see everyone who has checked in on that programme's link, with their points balance, lifetime points, tier and last check-in, read from your own workspace only. Each row has a Show QR button that draws that member's scannable card, so the counter can pull up a customer's card instead of asking them to find it.

When a member crosses a reward tier's points threshold, the programme emails them about the reward they earned: the message carries your logo and business name like every other customer message, and a reward you approve by hand is emailed the moment you approve it. The wording is yours to change under Email Templates → Loyalty - Reward Earned; leave it as it is and the default text is used.

Configuring Credit Rate

The credit rate determines how many credits a customer earns per $1 spent. The minimum value is 1 (1 credit per dollar) and the maximum is 1000 (1000 credits per dollar). The default rate is 10. Set the credit rate per tenant in Settings → Loyalty.

Credit Formula

credits_earned = floor(purchase_amount * credit_rate)

For example, with a credit rate of 10, a $25.50 purchase earns floor(25.50 * 10) = 255 credits. The minimum credit award is always 1 credit, so any purchase of $0.10 or more earns at least 1 credit.

Purchase PIN

Every tenant is assigned a Purchase PIN automatically on signup. The PIN is a sequential identifier in the format Z100, Z101, Z102, and so on. This PIN is required for purchase verification — merchants enter it when verifying a customer's purchase.

The Purchase PIN is found in Settings → Loyalty. It is read-only in the UI. If a PIN is compromised, contact an admin to request a reset. PIN resets are a manual database operation with a full audit trail.

Creating Offers

Offers are discount incentives that customers can redeem using their earned credits. Create and manage offers from Loyalty → Offers.

Offer Fields

Field	Description	Constraints
Name	Display name for the offer	Required, max 255 characters
Discount Percent	Percentage discount off the purchase	1–100
Cap Dollars	Maximum dollar value of the discount	Must be greater than 0
Active	Toggle offer active/inactive	Only active offers appear during verification

How Caps Work

The discount amount is calculated as min(purchase_amount × discount_percent / 100, cap_dollars). For example, a 20% offer with a $10 cap on a $100 purchase gives a $10 discount (capped). The same offer on a $30 purchase gives a $6 discount (below cap).

Credits are redeemed based on the cap: credits_redeemed = cap_dollars × 100. This means 1 credit = $0.01 of discount value. The redeemed credits are deducted from the customer's balance.

Purchase Verification Flow

The purchase verification process works step by step at the point of sale:

1. Customer shows QR code

   The customer presents their unique loyalty QR code from their account portal. This identifies them to the merchant.

2. Merchant scans QR

   The merchant scans the QR code using the IncentiveSwift verification interface (mobile or web). The system identifies the customer account.

3. Enter purchase amount + PIN

   The merchant enters the purchase total and their tenant's Purchase PIN. The PIN authenticates the merchant and links the transaction to the correct tenant.

4. Optional offer selection

   The merchant may select an active offer to apply. If no offer is selected, the customer simply earns credits on the purchase.

5. Verify

   Click Verify to process the transaction. The system calculates: credits_earned = floor(amount × credit_rate). If an offer was selected, the discount is applied, credits redeemed are deducted from the customer's balance, and the offer name is logged in the transaction record.

Referral System

The referral system encourages customers to bring in new business. Every participant gets a referral code (e.g., REF-JOHN-ABC123) they can share with friends.

When a referred friend signs up and completes their first purchase verification, the referrer earns bonus credits. The bonus amount is configurable per tenant. Referral history is visible in the customer portal under Loyalty → Referrals.

How It Works

1. Get your code

   Share your referral code from the Loyalty → Referrals section of your account.

2. Friend signs up

   The referred friend enters (or is tagged with) your referral code during account creation.

3. First purchase

   When the friend completes their first purchase verification, the system credits your account with the bonus amount.

4. Track earnings

   View your referral history, bonus credits earned, and pending referrals in the Referrals dashboard.

API Endpoints

The following API endpoints support the loyalty program. They are available for custom integrations:

Method	Endpoint	Description
GET	/api/v1/credits/balance	Get the customer's current credit balance
GET	/api/v1/credits/history	Get the customer's credit transaction history
GET	/api/v1/loyalty/referrals	Get the customer's referral history
POST	/api/v1/loyalty/referrals/create	Create a new referral code
GET	/api/v1/loyalty/rewards	List available rewards

💵 How the programme stays funded — the float rule

The loyalty programme pays real money out of a float that the businesses fund. Three independent conditions protect that float, and if any one of them is short the programme holds the payment to you (the business) for that redemption. The customer still gets their reward at the counter; you are reimbursed as soon as the float is back above all three conditions. Nothing is confiscated and no reward is taken back.

What is expected of you (the business)

• Fund before you launch. Rewards are paid out of money you have put in — by default the programme does not extend credit.
• Top up before you grow. A promotion raises redemptions immediately, so the float has to be ahead of the campaign, not behind it.
• A pause is not a loss. When a condition is short, the payment to you for each new redemption is held until you top up. The customer still gets their reward; you are reimbursed once the float is back above all three conditions. Nothing is taken away.
• You will always be told why. The console names the exact condition that is short and the amount needed to clear it — never just “breach”.

Your programme’s live rules are generated from the settings the platform is actually enforcing, so the rules you read can never describe a rule the system is not applying. The three thresholds (coverage %, burn months, safety balance) are set per programme in the admin console.

➕ Creating Campaigns

Basic Setup

1. Name & Type

   Give your campaign a name and select the campaign type. You can also add a description and custom slug for the public URL.

2. Prizes

   Define prize tiers. Each prize has a label, type (cash, discount, free_shipping, custom), value, and probability weight. Higher weight = more likely to win.

3. Entry Rules

   Set how many times a user can enter (once per day, once total, unlimited). Optionally require email verification or phone number.

4. Schedule

   Set a start and end date. Campaigns are only active within this window. You can manually toggle active/inactive anytime.

5. Theme

   Customize the colors and appearance to match your brand. The campaign player will automatically use your theme colors.

6. Save & Launch

   Click Create Campaign, then toggle Active to publish. Your campaign now has a public play URL.

Attaching an IQS Survey (Optional)

You can gate any campaign with an IQS survey. When enabled, users must complete the survey before they can enter the campaign. To attach a survey:

7. Open the survey

   Go to IQS in the sidebar and open the funnel you want to use as the gate.

8. Choose the campaign

   In the funnel editor's Campaign box pick the campaign this survey should gate, then click Save Funnel. That list marks the campaign it currently gates with a “✓ gated”.

9. Detach it

   To remove a gate, set the same box back to — none — and save. The campaign then runs without the survey.

Promo Codes and Their Expiry Date

A promo code is a campaign secret code: the customer types it on the campaign and is credited its points. Manage them on the admin console's Promo Codes screen: pick the campaign at the top, then fill New promo code — the code itself, its points, a maximum number of uses (leave it blank for unlimited) and an expiry date (leave it blank for a code that never expires) — and press Create code. Every code on that campaign is listed with its points, how many times it has been used, its expiry and whether it is Live or Paused: Pause stops a code earning anything without losing it, Resume switches it back on, and Delete removes it for good. The list's Expires column shows never for a code with no expiry date.

Changing a code's expiry date after the code exists — or taking the date off again — is done through the API panel's 16 · Campaign secret codes → Update code, whose body is {"code":"SPRING25","points":100,"max_uses":50,"expires_at":"2030-01-01T00:00:00Z"}.

🎁 Prize Delivery

Each prize type supports a different delivery mechanism. Configure per-prize delivery in the campaign editor.

Delivery lives on the campaign row itself: open Campaigns and click the Delivery button beside Edit and Embed. The panel keeps the win leg and the lose leg separate, so a winning player and an unsuccessful one can be sent to different places. For each leg it sets the redirect URL and the message the player lands on, the email subject and body sent to the player, which integration targets receive the webhook (chosen from the targets you configured in Integration Hub), and whether the autoresponder fires. Saving writes the delivery block only — the rest of the campaign's configuration is passed through untouched.

Two different buttons beside each campaign connect it to your other tools, and they do different things. Delivery decides what the player sees and writes the win/lose legs described above. Connections binds a webhook target from your Integration Hub to the campaign: pick the target, press Connect, and every win on that campaign posts the player, the prize and the campaign to that target until you press Disconnect. The pane lists each connected target with the event it fires on, and Disconnect only unlinks it — the target itself stays in the Integration Hub for other campaigns.

Prize Type	Delivery Method	Notes
Cash	Manual payout or API trigger	Amount recorded; payout handled externally
Discount Code	Auto-generated code (Redeem-XXXX)	Unique code shown instantly on win; also stored in campaign_wins
Free Shipping	Auto-generated code	Same as discount, common for e-commerce lead gen
Custom	Manual or webhook	Your own reward — use Integration Hub for webhook delivery

Wins are recorded with a unique redemption code in the format REDEEM-XXXXXXXX. Users see their code on the post-win screen and can copy or save it. For manual delivery prizes, the system records the win and you handle fulfillment from the campaign detail view.

Where every prize is written down. The dashboard’s Your data card has a Prizes won (CSV) button. It downloads one line for every prize this workspace has awarded: the campaign, the winner’s email, the prize and its type, the redemption code, whether that code has been redeemed and when, and when the prize was won. It is the same set of wins the Rewards given number on your dashboard counts, so the file and the tile can never disagree, and it contains your own workspace’s prizes only.

🔌 Embedding Campaigns

Campaigns can be played directly on IncentiveSwift or embedded on your own website. From the campaign detail view — Campaigns in your admin console — click the Embed button to get options:

• Direct Link — Share the campaign URL directly. e.g. https://app.incentiveswift.com/play/YOUR-SLUG
• Iframe Embed — Copy an iframe snippet to embed the campaign within your site's content
• Widget Script — A JavaScript widget that overlays on your page, great for popup campaigns

In the campaign editor's Theme section, pick the colours, font, corner radius and dark mode for the campaign. The play page and every embed use the saved theme automatically, so the widget keeps your branding rather than the defaults.

📋 IQS — Intelligent Qualifying Surveys

IQS (Intelligent Qualifying Survey) is IncentiveSwift's advanced survey engine. Use it to qualify and score leads, collect structured data, and push results into your CRM — all before they enter a campaign or independently as a stand-alone survey.

Creating a Survey Funnel

1. Navigate to IQS

   Click IQS in the main sidebar (not the admin menu). Click + New Funnel to create a survey.

2. Funnel Settings

   Give your funnel a name and description. Optionally enable Auto-Classification to automatically sort respondents into Hot/Warm/Cold based on score thresholds.

3. Add Questions

   Click + Add Question. Choose a question type, write the question text, and configure options (for choice types). Each option has a Score and Tag that applies when selected.

4. Set Outcomes

   Define outcome ranges for Qualified and Disqualified based on total score percentage. Configure redirect URLs and thank-you messages for each outcome.

5. Save & Publish

   Save the funnel and toggle it Active. Your survey is now available for standalone play, widget display, or campaign attachment.

Survey Play Modes

IQS surveys support two play modes that users can choose from:

• Step by Step — One question at a time with smooth transitions. Best for longer surveys where you want to maintain focus.
• All at Once — All questions displayed on a single page. Best for short surveys where speed is important.

❓ Question Types

IQS supports 13 question types, each designed for specific data collection needs:

Type	Icon	Best For	Config Options
Single Choice	☑️	Yes/No, pick one from list	Options with scores & tags
Multiple Choice	✅	Select all that apply	Options with scores & tags
Open Text	📝	Free-form written answers	Placeholder text
Numeric	🔢	Age, budget, quantity	Min, max, step, unit label
Email	📧	Email collection	Auto-validates format
Phone	📞	Phone number with country code	Country code selector
Rating	⭐	Star rating (1-5, 1-10)	Max rating value
Date	📅	Appointment or birth date	Include time toggle
File Upload	📁	Resume, photo, document	Allowed extensions, max size
Consent	📋	GDPR/terms agreement	Custom consent label
Slider	🎚️	0-100 scale (satisfaction, likelihood)	Min, max, step size
Dropdown	📋	Long option lists in compact format	Options with scores & tags
Image Choice	🖼️	Visual selection (product, style, photo)	Image URLs + options
Matrix/Grid	📊	Rate multiple items on same scale	Rows & columns config

Question Options: Scores & Tags

Every choice-type question option has two extra fields:

• Score — A numeric value assigned when this option is selected. The total score across all questions determines the respondent's qualification outcome.
• Tag — A text label that gets applied to the respondent's profile in CoreSwift CRM. Tags make it easy to segment and filter leads later.

Example: On a question "What's your budget?" — Option "Under $500" has score 5, tag "budget_low". Option "$500-$2000" has score 15, tag "budget_mid". Option "Over $2000" has score 25, tag "budget_high".

🔥 Auto-Classification (Hot/Warm/Cold)

Auto-Classification automatically sorts respondents into lead tiers based on their survey score percentage. Enable it in your funnel settings.

How It Works

When enabled, the system calculates the respondent's final score as a percentage of the maximum possible score. It then matches the percentage against your configured ranges:

Classification	Score Range	Badge	Action
🔥 Hot	80% – 100%	Hot	High priority — push to CRM immediately, auto-assign to hot pipeline stage
🟡 Warm	50% – 79%	Warm	Nurturing — enters standard pipeline, scheduled follow-up
🔵 Cold	0% – 49%	Cold	Long-term — saved for future campaigns or drip nurture

Configuration

In the funnel editor, enable Auto-Classification. Three default ranges (Hot/Warm/Cold) are pre-configured but fully customizable. For each range you can set:

• Label — The name of the classification (e.g. "Hot", "VIP", "Tier 1")
• Minimum Score % — The lower bound of this range (0-100)
• Tag — A tag automatically applied to the respondent's profile (e.g. "hot_lead", "vip_prospect")

🔀 Conditional Branching

Conditional Branching lets you create smart surveys that adapt to each respondent's answers. Questions appear or hide based on what was answered previously.

How It Works

Each question can have a condition (show_if) that controls whether it's displayed:

Operator	Description	Example
equals	Show if previous answer exactly matches value	Show "What's your budget?" only if "Are you interested?" = "Yes"
not_equals	Show if previous answer does NOT match	Show "Why not?" only if "Interested?" ≠ "Yes"
contains	Show if previous answer contains the value (for multi-select)	Show follow-up if answer contains "Premium"

Setting Up Conditions

1. Open Question Editor

   When creating or editing a question, scroll to the Advanced section.

2. Enable Condition

   Toggle "Show this question only if..." — this reveals the condition fields.

3. Select Dependency

   Choose which previous question this depends on from the dropdown. All questions with a lower sort order are available.

4. Set Operator & Value

   Choose equals/not_equals/contains and enter the value to match against.

5. Save

   The condition is stored. When the survey is played, this question only appears if the condition is met.

🎯 Survey + Campaigns

You can attach an IQS survey as a qualification gate before any campaign type. This creates a two-step flow: survey first, then campaign for qualified respondents.

A survey gates one campaign at a time: attaching it to a campaign that already runs another survey is refused, and detaching it is what frees it for the next one (see Attaching an IQS Survey above).

How the Flow Works

1. User visits campaign link

   The system detects an attached IQS funnel and redirects to the survey play page instead of the campaign directly.

2. User completes survey

   All question types, scoring, classification, and branching apply normally. The system calculates total score and compares against outcome thresholds.

3. If Qualified

   The user is redirected to the campaign play page where they can enter normally (spin the wheel, scratch the card, etc.). Their survey score and tags flow with them.

4. If Disqualified

   The user sees a thank-you/disqualified message with an optional redirect URL (e.g., "Thanks for your interest — here's a consolation offer").

Use Cases

• VIP Giveaways — Only qualified leads can enter the prize drawing
• Product Launches — Survey to gauge interest, then offer a discount spin to high-scorers
• Lead Gen Campaigns — Collect qualification data before allowing entry, pushing scores + tags to CoreSwift
• Event Registration — Qualify attendees before they enter a raffle for a free ticket

🪟 Popup Widget

The IQS Popup Widget lets you display a survey as a floating overlay on any website. Perfect for capturing leads with minimal friction — visitors see a subtle trigger button (or auto-display), click it, and complete the survey without leaving your page.

Setting Up the Widget

1. Open an IQS Funnel

   From the IQS section, open the funnel you want to use as a widget.

2. Click Widget Button

   Click the Widget button (🔌) in the funnel detail view. The popup is served per campaign, so the funnel has to be attached to a campaign first (Campaign Gate in the builder) — if it is not, the button says so instead of handing you a snippet that 404s.

3. Copy Embed Code

   Copy the generated code snippet and paste it just before </body> on your website.

4. Visitor trigger

   Visitors get a small floating button carrying your campaign's call-to-action; clicking it opens the survey in an overlay on your page. The trigger is always visitor-initiated — there is no auto-display mode — and the overlay is dismissed with its ✕ or a click outside it.

Widget Features

• Responsive — works on desktop and mobile
• Themed — auto-matches your funnel's colors
• Non-intrusive — trigger button stays small, modal is dismissible
• Auto-captures source tracking (referrer, UTM params)

✅ Post-Submit Flow

After a survey is completed, you control exactly what happens next. Configure different outcomes and responses per qualification level.

Outcome Configuration

In the funnel editor, under Outcomes, set:

• Qualified Range — The minimum score % threshold (default 60%)
• Qualified Message — A themed thank-you message shown to qualified respondents (e.g. "Great news! You qualify for our special offer.")
• Disqualified Message — Message for those who don't meet the threshold (e.g. "Thanks for your interest — we'll be in touch.")
• Redirect URLs — Optional URLs for each outcome. After 3 seconds, the user is automatically redirected. Leave blank for no redirect.

🧩 Grouped Form Sections

The long-form qualifier form can be broken into titled sections — for example About you, then Your business, then Your goals. Sections are a presentation overlay: they control the grouping and the order of the questions on the public form, and nothing else.

Configuring Sections

1. Open the Campaign

   In the campaign editor, set Mechanic Type to Long-Form Qualifier. A 🧩 Sections block appears under the Config (JSON) field.

2. Add a Section

   Click + Add section, give it a title, and tick the question keys that belong in it. The tick list is built from the question keys already present in your rules — a question has to exist in rules before you can group it.

3. Order It

   Sections render in the order you list them, and the questions inside a section render in the order you tick them. ✕ removes a section.

4. Save

   Saving merges sections into the campaign config alongside rules and outcomes — it does not replace them.

Ungrouped and Unknown Keys

Case	What Happens
A question is in rules but in no section	It still appears on the form, in a trailing untitled group. A question can never be silently dropped by grouping.
A section names a key that is not in rules (a misspelling)	The key is ignored. No error, no warning, no broken form.
The same question is named in two sections	It renders once, in the first section that names it.
The campaign has no sections at all	The form renders as a plain flat list of questions, exactly as it did before sections existed.

On the Public Form

The form page at https://incentiveswift.com/long-form-qualifier.html?slug=<your-campaign> renders one heading per non-empty section, with that section's questions underneath. The server-resolved ordering comes back as form_sections in GET /api/v1/play/<slug>, and is present only when the campaign defines sections; without it the page falls back to the flat rules order.

🔗 Integration Hub

The Integration Hub connects your campaigns and surveys to external services. Every time a user wins a prize or enters a campaign, configured integrations fire automatically.

Managing Integrations

Navigate to Integrations in the sidebar. Here you can:

• Add Integration Targets — External endpoints or services that receive data
• Configure Provider Keys — API keys for connected services (Marketing Boost, Telnyx, DeepSeek/OpenAI for Chat Funnel AI replies, etc.)
• Link Integrations to Campaigns — Toggle which integrations fire for each campaign
• Monitor Webhook Security — View domain allowlists and daily usage

Chat Funnel AI replies

A Chat Funnel campaign serves the questions you write in its config (chat_flow) and, when a visitor types a message, can answer with an LLM. The LLM is your own credential: connect a DeepSeek key (preferred) or an OpenAI key under Integrations → Provider Keys. The key is stored encrypted, is used only for your account's chat campaigns, and both providers use their public vendor endpoint by default.

With no LLM key connected the funnel still works — it replies with your scripted chat_flow text. So the AI reply is an enhancement you switch on, never a requirement. A connected endpoint must be a public destination: a base URL that resolves to a private, loopback or link-local address is refused when it is saved and is never contacted. The platform's own CoreSwift bridge is the one exception — it is the preset endpoint those accounts already use.

Integration Types

Type	When It Fires	Data Sent
Webhook	Entry or Win	JSON payload with user info, campaign, prize, score
Marketing Boost	Win/Entry	Offer ID + user contact info for email/SMS dispatch
Custom API	Entry or Win	Configurable payload to any HTTPS endpoint

📈 Marketing Boost

Marketing Boost is an integrated email/SMS marketing dispatch service. When a user wins a prize or enters a campaign, Marketing Boost can automatically send them a targeted email or SMS offer.

Setting Up Marketing Boost

1. Go to Provider Keys

   Navigate to Integrations → Provider Keys and add your Marketing Boost API key (provider marketing_boost).

2. Open the campaign

   On Campaigns, press Marketing Boost on the campaign you want to send for. The panel reads that campaign's current settings first, so it never shows you another campaign's configuration.

3. Choose the incentive

   Tick Send a Marketing Boost incentive for this campaign and pick one: Dining voucher ($25 / $50 / $100 / $200), Hotel savings card ($100 / $200 / $300 / $500), or Vacation incentive — which needs a Destination (Offer ID): press Load list to read the destinations your own Marketing Boost account offers, or type the id. Sender and Business are optional and fall back to your Provider Keys row.

4. Choose when it sends

   Tick the player wins and/or the player redeems a reward, then press Save Marketing Boost.

5. Done

   Every time that campaign resolves on a ticked event, Marketing Boost is dispatched for that player's contact details. An entry with no email address is skipped and written to the platform log, never sent to the vendor.

Key Resolution Chain

When dispatching to Marketing Boost, the system resolves the API key in this order:

1. Integration Target's own key — if set directly on the target
2. Portfolio company settings — if the target is shared by a portfolio company
3. Provider Keys table — the user's global Marketing Boost key

📡 Webhooks & Security

Webhook integrations let you send data to any external service when events happen in IncentiveSwift.

Webhook Security

Every outbound webhook passes a security check before it is sent:

• Internal-network refusal — the destination host is resolved first, and a webhook pointing at a private, loopback or link-local address (127.0.0.1, 10.x.x.x, 192.168.x.x, 172.16–31.x.x, 169.254.x.x) is refused and never sent. Redirects are not followed, so an approved host cannot bounce a delivery to one of those addresses.
• Domain Allowlist — configure approved domains per integration target and only those domains (and their subdomains) are sent to. Leave the list empty and any public domain is allowed; internal addresses stay refused either way.
• Daily Limit — set a maximum number of dispatches per day per integration target. The count runs on the UTC day and resets at midnight UTC; once it is reached, further dispatches to that target are refused.
• Delivery Log — each dispatch to an integration target is recorded with its status (sent or failed) and response code. A dispatch refused by a security check is never sent, and the reason is written to the platform log and returned by the Test Webhook panel.

📈 Analytics

The Analytics section provides deep insights into your campaigns and surveys. Access it from the sidebar.

Analytics Dashboard

• Overview KPIs — Total entries, unique participants, conversion rates, win rates, average score
• Campaign Analytics — Per-campaign breakdown with entries over time, source attribution, prize distribution
• Source Tracking — See where your entries come from (direct, referral, UTM sources, UTM medium, UTM campaign)
• Hourly Heatmap — When are users most active? Heatmap shows engagement by hour of day
• Loyalty Metrics — Track returning participants, multi-entry users, repeat engagement
• CSV Export — Export any analytics view to CSV for offline analysis

Source Tracking Fields

IncentiveSwift automatically captures these fields for every entry:

Field	Source
utm_source	URL parameter on the play page or embed
utm_medium	URL parameter on the play page or embed
utm_campaign	URL parameter on the play page or embed
referrer_url	document.referrer from the user's browser
page_url	Where the campaign was embedded or played
user_agent	Browser user-agent string
ip_address	Request IP (anonymized in reports)

⚙️ Settings

Configure your account and workspace settings from the sidebar's gear icon.

Profile Settings

• Name & Email — Update your profile information
• Profile Picture — Set the picture that appears beside your name on your dashboard and in the console. The Profile picture card on your dashboard does it directly (PNG, JPEG, GIF or WebP, up to 2 MB, with a Remove picture button beside it); the same picture can be set on the Profile screen in the console. Leave it unset and your initial is shown instead.
• Password — Change your login password
• Signed-in devices — If a phone, tablet or old computer is still signed in to your account, the Signed-in devices card on your dashboard ends it: press Sign out of every other device, confirm, and every other session has to sign in again. The browser you press it from stays signed in — nothing about your password changes, so this is the way to close an old session when you still remember your password.
• SEO Settings — Configure page title, description, and keywords for your campaign pages

Integration Provider Keys

Manage API keys for third-party services used by the Integration Hub. Keys are encrypted at rest and never exposed in logs. Provider endpoints must be public destinations: a base URL that resolves to a private, loopback or link-local address is refused when it is saved and never contacted by a dispatch. The platform's own CoreSwift bridge is the one exception — it is the preset endpoint those accounts already use.

Email — Your Mail Server

Your campaign and loyalty email can go out through your own mail server instead of the platform's. Open Settings in the sidebar, fill in Email — your mail server (server host, port — 587 by default — username, password and the from address your recipients see), then press Save. Press Send test email to send one real message to your own account address through the server you just saved: the platform reports exactly what your server answered, and it never quietly falls back to the platform mailer for that test.

The password is stored encrypted and is never shown again — the box shows dots when a password is saved, so leave it untouched to keep it, or type a new one to replace it. Leave the mail server unconfigured, or press Remove mail server, to keep using the platform mail service — removing deletes this account's saved mail server, so every mail from then on goes out through the platform mailer again, and it is the only way to unset a mail server (a blank host is refused rather than saved). For safety the platform refuses a mail server whose host is a private or loopback address, and the test is always sent to your own account address.

❓ Frequently Asked Questions

🆓 Tag to free account

When a lead is tagged in FunnelSwift with one of this app's tags — for example IncentiveSwift — Free — IncentiveSwift is told to create a free account for that lead, using the same name and email the lead was captured with. IncentiveSwift emails the new user their login details automatically, so they can sign in and upgrade here whenever they are ready.

What happens when it is ON

• A tagged lead gets a real account here on the free plan — not just a contact record
• The new user is emailed their login details by IncentiveSwift
• Tagging the same lead twice does not create a duplicate account — the second attempt is recognised by email and ignored

What happens when it is OFF

The tagged lead is still recorded here as a contact, so nothing is lost, but no account is created and no login email is sent. Use this if you want to review leads before accounts exist for them.

Where the switch is

Operators turn this on or off in the admin console, under Provisioning (the Auto-provision free accounts from tags switch and the entry plan beside it).