API Docs & Sample Code

The API consists of two end points. Using these two end points, you can create a subscription by email address, set their social share id, control if they get the autoresponder email, and return info about previous subscriptions.

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

The endpoints

1. Adding a new Subscription

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

Required, Recommended, and Optional Parameters

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

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.
  • social_id: This is the social id of the parent record for this user
  • your_custom_parameters: This allows you to store additional data with each user. Please do not start any parameter name with a '_'.

2. Retrieving Subscriber 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 LIST ID}/info

Required Parameters

You must include only 1 of the following parameters

  1. email: The email address used when signing up.
  2. 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:

  1. email - this is the email address you just submitted
  2. social_id - this is the social id for this email address. This value is scoped to your list
  3. url - this is the url of the landing page.
  4. social_url - this the url for the KickoffLabs landing page with the social_id appended to it.
  5. parent_id - the social id who referred this user. This value maybe null.
  6. influence - contains two values:
    1. direct - the number of users directly referred by this user
    2. indirect - the number of users referred by this user those users referrals
  7. 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.

Do you have any example code? YES!

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

KickoffLabs API Sample Code


HTML (Form)



C# (.NET)