Developing With KickoffLabs

KickoffLabs is a great platform for collecting leads and running viral contests. We make it easy to setup refer a friend style contests, giveaways, sweepstakes, and product launches.

You can build out amazing marketing experiences with our script platform and developer APIs. We have some best practices outlines here that teach you how based on your goals.

In most cases, we recommend using the AnyForm widget for custom pages instead of adding leads directly via the API

Using custom HTML and CSS on KickoffLabs Pages

In this case you just want to add a little bit of flair beyond what what you can control in our designer.

Read our complete guide to this here. You may not need to develop your own page or use our API directly.

Ex: Using the custom HTML block.

Building a landing page from scratch with AnyForm

We get it. No landing page template does your brand justice. You are a designer or developer that likes to write their own HTML and connect that page and form to a contest platform like ours. You may already have a site built or have purchased a template you want to use instead.

That’s where AnyForm comes in. KickoffLabs AnyForm is a script turns any custom HTML form into a KickoffLabs form. The process looks like this:

You build the HTML with a form on it.
You generate the AnyForm Script for your campaign within KickoffLabs.
You paste that script onto your custom page.
When someone submits that form you redirect them to a page that encourages sharing.

In most cases people choose to use a KickoffLabs hosted page like https://thanks.YourWebSiteDomainHere.com.

Click here to learn how to generate the AnyForm Script for your campaign.

90% of the time this is what you probably want to do if you are here. If you need something more custom then keep reading below about our API.

The AnyForm Script ready to install.

Recieving WebHook Lead Notifications

When a lead signs up we can make an HTTP Post to the URLs you specify for your campaign. The body of the post will have all of the parameters specified in our API documentation here.

Learn how to setup WebHook targets for your campaign. You may not need to develop your own page or use our API directly.

Sample response to the webhook...

Using the KickoffLabs API Directly

It's also possible to use the KickoffLabs API directly. You can add leads to your campaign, check a leads status to build your own reward pages, and tag leads as well to assign custom points for your contest.

Enabling API Access

To use the API you'll need to make sure it's enabled for your campaign, you know the campaign ID, and you are using an API key. To get this:

Open a campaign in KickoffLabs.
Click campaign settings in the left nav.
Scroll down to "Other Settings" and choose "API Access".
Turn on the API and copy the ID and API key you see.

Read below for API endpoints.

You need the campaign ID and API key.

API Direct Endpoints

/subscribe - Adding a new lead

To add an email to your customer list, you need to make an HttpPost to the following end point:

https://api.kickofflabs.com/v1/{YOUR CAMPAIGN ID}/subscribe

Parameters

Required

email: The email address of the lead
api_key: The campaign api_key. You can find this under your campaign settings

Recommended

Supplying these values will help us better categorize your leads and prevent fraudelent/spam leads from adversely affecting your campaign.

ip: By default, we use the IP address of the request. This is great if your are using ajax to make the request. However, if you are making the request on the server, you may want to include user's ip address
__url: The URL which the lead signed up on.
__ref: The referrer url the lead came from.
__user_agent: The user agent of the lead.

Optional

social_id: This is the social id of the parent record for this user
points: Points to add to the lead. If this value is not null, it will overrite previous values.
your_custom_parameters: This allows you to store additional data with each user. Please do not start any parameter name with a '_'.

/INFO - Retrieving Lead Information

This is useful to simply pull information about an existing subscriber.

To retrieve subscriber information from your customer list, you need to make Get request to the following end point:

https://api.kickofflabs.com/v1/{YOUR CAMPAIGN ID}/info

Required Parameters

You must include only 1 of the following parameters

email: The email address used when signing up.
social_id: The social id returned when the user signed up. This is the value used to track social sharing.

You can also optionally include an api_key parameter (found in your KickoffLabs dashboard). When this is present, the response will include a users custom fields.

NOTE: While recommend using an HttpPost, since we also support JSONP, you can also add subscriptions via HttpGet

Response - The same for both endpoints!

The response body is JSON and will contain parameters:

avatar - an image of the current lead
contest_score - the number of points generated by this lead
contest_score_rank - this leads position based on content score
counter - the number of times this lead has been added to your campaign
custom_fields - any additional fields you submitted with the request
email - this is the email address you just submitted
family_name - Last name of the current lead. This may be sourced by custom fields or via our Magic Data
given_name - First name of the the lead. This may be sourced by custom fields or via our Magic Data
lead_count - the number of leads on this campaign
parent_id - the social id who referred this user. This value maybe null.
rank - this is based on sign up order
redirect_url - the default thank you page url for this lead
referrals - the number of referrals generated by this lead. If verification is enabled, this will only include other verified leads.
social_id - this is the social id for this email address. This value is scoped to your list
social_url - this the url for the KickoffLabs landing page with the social_id appended to it.
url - this is the url of the landing page.

You can also include a query string parameter jsonp. When this is present (HttpGet only) we will wrap the JSON response with the name of the callback. This is generally used to integrate our API directly into a web page wit JavaScript.

API Code Samples

Keep on reading to find examples from Ruby to VB.NET. :) We also have a complete demo you can download.

curl

HTML (Form)

Please keep in mind that if you are building a custom form you should probably be using AnyForm. This is for example purposes only.