Launchbit API - Release v1.0 Documentation

Table of Contents

General Details



Available Endpoints

/version/

Endpoint Description

This endpoint returns the release version of the API.

Optional Caching: This endpoint returns an HTTP eTag unique to the resource, as well as an HTTP Expires header one week in the future. If desired, these may be used by third party developers to serve locally-cached content for faster responses.

Endpoint URI

HTTP GET Request: http://www.launchbit.com/api/v1.0/{api-key}/version/
Parameter Description
api-key Required Your API Key.

Endpoint Return Properties

Name Code Description
api_version String API version
status Array Returns a status code containing details about the success or failure of the endpoint. Status codes can be found here.

Example Return JSON

{
  "api_version":"1.0",
  "status":{
    "text":"GenericSuccess",
    "code":1000
  }
}



/tags/

Endpoint Description

This endpoint returns a list of available demographic tags. The tag ID numbers returned by this function are required for the Adunit endpoint. While tag ID numbers rarely change, we recommend querying this endpoint before performing additional requests to prevent mixups due to changes.

Optional Caching: This endpoint returns an HTTP eTag unique to the resource, as well as an HTTP Expires header one week in the future. If desired, these may be used by third party developers to serve locally-cached content for faster responses.

Endpoint URI

HTTP GET Request: http://www.launchbit.com/api/v1.0/{api-key}/tags/
Parameter Description
api-key Required Your API Key.

Endpoint Return Properties

Name Code Description
tags Array An array of Tag objects.
tags[ ].tag_id Integer ID number of the tag.
tags[ ].tag_name String Name of the tag. Listed for your reference only. Tag names are not used when querying additional endpoints. Use the tag_id property instead
status Array[] Returns a status code containing details about the success or failure of the endpoint. Status codes can be found here.

Full list of tags:

{
    "tags": [
        {
            "tag_name": "Automotive",
            "tag_id": 7
        },
        {
            "tag_name": "Fashion",
            "tag_id": 8
        },
        {
            "tag_name": "Programming",
            "tag_id": 9
        },
        {
            "tag_name": "Entrepreneurs",
            "tag_id": 10
        },
        {
            "tag_name": "Marketing",
            "tag_id": 12
        },
        {
            "tag_name": "Mobile",
            "tag_id": 16
        },
        {
            "tag_name": "Productivity",
            "tag_id": 17
        },
        {
            "tag_name": "Consumer Tech",
            "tag_id": 18
        },
        {
            "tag_name": "Sports",
            "tag_id": 19
        },
        {
            "tag_name": "Art",
            "tag_id": 20
        },
        {
            "tag_name": "Bargains / Discounts",
            "tag_id": 21
        },
        {
            "tag_name": "Beauty",
            "tag_id": 22
        },
        {
            "tag_name": "Books / Media",
            "tag_id": 23
        },
        {
            "tag_name": "Careers / Recruiting",
            "tag_id": 27
        },
        {
            "tag_name": "Education",
            "tag_id": 28
        },
        {
            "tag_name": "Gardening",
            "tag_id": 29
        },
        {
            "tag_name": "Food & Beverage",
            "tag_id": 30
        },
        {
            "tag_name": "Health / Wellness",
            "tag_id": 33
        },
        {
            "tag_name": "Fitness",
            "tag_id": 35
        },
        {
            "tag_name": "Agriculture",
            "tag_id": 37
        },
        {
            "tag_name": "Hobbies",
            "tag_id": 38
        },
        {
            "tag_name": "How To",
            "tag_id": 39
        },
        {
            "tag_name": "Motivational",
            "tag_id": 40
        },
        {
            "tag_name": "Music",
            "tag_id": 41
        },
        {
            "tag_name": "News",
            "tag_id": 42
        },
        {
            "tag_name": "Parenting",
            "tag_id": 43
        },
        {
            "tag_name": "Politics",
            "tag_id": 44
        },
        {
            "tag_name": "Spirituality",
            "tag_id": 45
        },
        {
            "tag_name": "Retirement",
            "tag_id": 46
        },
        {
            "tag_name": "Shopping",
            "tag_id": 47
        },
        {
            "tag_name": "Sustainability",
            "tag_id": 48
        },
        {
            "tag_name": "Travel",
            "tag_id": 49
        },
        {
            "tag_name": "World",
            "tag_id": 50
        },
        {
            "tag_name": "Finance / Investment",
            "tag_id": 51
        },
        {
            "tag_name": "Sales",
            "tag_id": 54
        },
        {
            "tag_name": "Entertainment",
            "tag_id": 55
        },
        {
            "tag_name": "Local Events",
            "tag_id": 56
        },
        {
            "tag_name": "Event Planning",
            "tag_id": 57
        },
        {
            "tag_name": "Networking",
            "tag_id": 58
        },
        {
            "tag_name": "Photography",
            "tag_id": 59
        },
        {
            "tag_name": "Advertising",
            "tag_id": 60
        },
        {
            "tag_name": "Design",
            "tag_id": 61
        },
        {
            "tag_name": "Pets",
            "tag_id": 64
        },
        {
            "tag_name": "Small Business",
            "tag_id": 65
        },
        {
            "tag_name": "Military",
            "tag_id": 66
        },
        {
            "tag_name": "Interior Design",
            "tag_id": 67
        },
        {
            "tag_name": "Non-Profit",
            "tag_id": 68
        },
        {
            "tag_name": "Women",
            "tag_id": 73
        },
        {
            "tag_name": "Real Estate",
            "tag_id": 83
        }
    ],
    "status": {
        "text": "GenericSuccess",
        "code": 1000
    }
}



/adzones/

Endpoint Description

This endpoint returns a list of adzones associated with your API key. The ID's from this endpoint may be used as an optional argument to the Adunit endpoint. Adzones represent unique "locations" where you place adunits.

E.g. if you manage two separate newsletters, each newsletter would have it's own adzone. This allows finer grained analytics for both our publishers and advertisers

Caching: This endpoint should never be cached. HTTP Modified headers are always set to current time, and HTTP Expires headers are always set in the past.

Endpoint URI

HTTP GET Request: http://www.launchbit.com/api/v1.0/{api-key}/adzones/
Parameter Description
api-key Required Your API Key.

Endpoint Return Properties

Name Code Description
adzones Array of Integers ID numbers corresponding to the adzones associated with your API key. These ID numbers can be used as an optional argument in the Adzone endpoint.
status Array[] Returns a status code containing details about the success or failure of the endpoint. Status codes can be found here.

Example Return JSON

{
  "adzones":[
    77,
    72,
    380
  ],
  "status":{
    "text":"GenericSuccess",
    "code":1000
  }
}



/adunit/

Endpoint Description

This endpoint returns a single adunit, which may be embedded into an email to your subscriber. This endpoint should be called each time you require an ad to be placed.

Note: Do not call this endpoint once and reuse the content in all your emails. Ad impressions and clicks are tracked via unique identifiers - utilizing only one adunit will result in a maxmium of one click recorded.

Caching: This endpoint should never be cached. HTTP Modified headers are always set to current time, and HTTP Expires headers are always set in the past.

Endpoint URI

HTTP GET Request: http://www.launchbit.com/api/v1.0/{api-key}/adunit/{uuid}/{tags}/{directory-id}/
Parameter Description
api-key Required Your API Key.
uuid Required Unique User ID (UUID). The UUID should be a unique identifier for each of the subscribers on your list. The UUID may be up to 15 alphanumeric characters long.
tags Required Comma-delimited list of tag ID numbers. Tags allow you to target ads to specific demographics of users, which increases both subscriber satisfaction and publisher earnings due to better ad relevance. Tag ID numbers are retrieved from the Tags endpoint
directory-id Optional ID number corresponding to the adzone that you wish this adunit placed in. If this parameter is left blank, the first adzone corresponding to your API key will be used by default. Adzone ID numbers are retrieved from the Adzones endpoint

Endpoint Return Properties

Property Type Description
ad_title String The title text for this adunit. Maximum length of this field will be 25 characters.
ad_body String The body text for this adunit. Maximum length of this field will be 165 characters.
ad_url String

The URL that is associated with this adunit. Clicks through this address are used to determine clicks in your adzone (and, correspondingly, your payout). We recommend that the text in ad_title be linked with this address. Maximum length of this field is 36 characters.

Note: The forward slashes in this field are escaped with backslashes to make it valid JSON. Backslashes should be removed via your favorite method before inserting into emails.

Note: This is a unique, generated address and should not be reused multiple times.

image_source String

The URL address to the square image that accompanies this adunit.

Note: The forward slashes in this field are escaped with backslashes to make it valid JSON. Backslashes should be removed via your favorite method before inserting into emails.

pixel String

The URL address to an invisible tracking pixel. We use this pixel to calculate impressions and is required to be present in all adunits. Maximum length of this field is 36 characters.

Note: The forward slashes in this field are escaped with backslashes to make it valid JSON. Backslashes should be removed via your favorite method before inserting into emails.

Note: This is a unique, generated address and should not be reused multiple times.

status Array[] Returns a status code containing details about the success or failure of the endpoint. Status codes can be found here.

Example Return JSON

{
  "ad_title":"Sample title text",
  "ad_body":"Sample ad body text.",
  "ad_url":"http:\/\/launchbit.com\/aa\/EwAAAA\/",
  "image_source":"http:\/\/launchbit.com\/taz-i\/2045b33a8ed-text.jpg",
  "pixel":"http:\/\/launchbit.com\/ap\/EwAAAA\/",
  "status":{
    "text":"GenericSuccess",
    "code":1000
  }
}

Sample HTML

<strong>From our sponsors:</strong>
<table>
    <tbody>
    <tr>
        <td width="130"><a href="{ad_url}"><img src="{image_source}" /></a></td>
        <td><a href="{ad_url}">{ad_title}</a> {ad_body} <img src="{ad_pixel}" /></td>
    </tr>
    </tbody>
</table>



/adunit/ (With Demographic Data)

Endpoint Description

This endpoint returns a single adunit, but includes optional demographic data to better target your subscribers. This endpoint should be called each time you require an ad to be placed.

This endpoint differs from the previous adunit endpoint in that it is an HTTP POST method (instead of GET) and includes a JSON-encoded request body. Some of our advertisers wish to show advertisements to certain demographics (e.g. females only). These adunits are excluded from normal API requests, but may be accessed if you have per-subscriber demographic data.

Note: Do not call this endpoint once and reuse the content in all your emails. Ad impressions and clicks are tracked via unique identifiers - utilizing only one adunit will result in a maxmium of one click recorded.

Caching: This endpoint should never be cached. HTTP Modified headers are always set to current time, and HTTP Expires headers are always set in the past.

Endpoint URI

HTTP POST Request: http://www.launchbit.com/api/v1.0/{api-key}/adunit/{uuid}/{tags}/{directory-id}/
Parameter Description
api-key Required Your API Key.
uuid Required Unique User ID (UUID). The UUID should be a unique identifier for each of the subscribers on your list. The UUID may be up to 15 alphanumeric characters long.
tags Required Comma-delimited list of tag ID numbers. Tags allow you to target ads to specific demographics of users, which increases both subscriber satisfaction and publisher earnings due to better ad relevance. Tag ID numbers are retrieved from the Tags endpoint
directory-id Optional ID number corresponding to the adzone that you wish this adunit placed in. If this parameter is left blank, the first adzone corresponding to your API key will be used by default. Adzone ID numbers are retrieved from the Adzones endpoint

Request Body

The request body contains a JSON object that specifies one or more demographics that relate to the subscriber you are requesting an adunit for. For example, if you are requesting an adunit for a 25 year old female, you may include the "age" and "gender" demographics in your request body.

Available demographics to include

Demographic Description
Age Integer The age of the subscriber
Gender String The gender of the subscriber. Legal values include: "male" and "female"

Example Request Body

{
  "age" : 25,
  "gender" : "female"
}

Endpoint Return Properties

Property Type Description
ad_title String The title text for this adunit. Maximum length of this field will be 25 characters.
ad_body String The body text for this adunit. Maximum length of this field will be 165 characters.
ad_url String

The URL that is associated with this adunit. Clicks through this address are used to determine clicks in your adzone (and, correspondingly, your payout). We recommend that the text in ad_title be linked with this address. Maximum length of this field is 36 characters.

Note: The forward slashes in this field are escaped with backslashes to make it valid JSON. Backslashes should be removed via your favorite method before inserting into emails.

Note: This is a unique, generated address and should not be reused multiple times.

image_source String

The URL address to the square image that accompanies this adunit.

Note: The forward slashes in this field are escaped with backslashes to make it valid JSON. Backslashes should be removed via your favorite method before inserting into emails.

pixel String

The URL address to an invisible tracking pixel. We use this pixel to calculate impressions and is required to be present in all adunits. Maximum length of this field is 36 characters.

Note: The forward slashes in this field are escaped with backslashes to make it valid JSON. Backslashes should be removed via your favorite method before inserting into emails.

Note: This is a unique, generated address and should not be reused multiple times.

status Array[] Returns a status code containing details about the success or failure of the endpoint. Status codes can be found here.

Example Return JSON

{
  "ad_title":"Sample title text",
  "ad_body":"Sample ad body text.",
  "ad_url":"http:\/\/launchbit.com\/aa\/EwAAAA\/",
  "image_source":"http:\/\/launchbit.com\/taz-i\/2045b33a8ed-text.jpg",
  "pixel":"http:\/\/launchbit.com\/ap\/EwAAAA\/",
  "status":{
    "text":"GenericSuccess",
    "code":1000
  }
}

Full cURL example

$ curl -XPOST http://www.launchbit.com/api/v1.0/my_api_key/adunit/uuid12345/9,10,11/ -d '
 {
   "age" : 25,
   "gender" : "female"
 }
'

  {
    "ad_title":"Sample title text",
    "ad_body":"Sample ad body text.",
    "ad_url":"http:\/\/launchbit.com\/aa\/EwAAAA\/",
    "image_source":"http:\/\/launchbit.com\/taz-i\/2045b33a8ed-text.jpg",
    "pixel":"http:\/\/launchbit.com\/ap\/EwAAAA\/",
    "status":{
      "text":"GenericSuccess",
	  "code":1000
    }
  }



/bulkadunit/

Endpoint Description

This endpoint is used to make bulk requests to the API. It can be used to request up to 1000 adunits at a time, by providing a JSON array of UUIDs and relevant tags/demographics. Adunits are returned in a JSON object, one adunit per UUID.

Caching: This endpoint should never be cached. HTTP Modified headers are always set to current time, and HTTP Expires headers are always set in the past.

Endpoint URI

HTTP POST Request: http://www.launchbit.com/api/v1.0/{api-key}/bulkadunit/{directory-id}/
Parameter Description
api-key Required Your API Key.
directory-id Optional ID number corresponding to the adzone that you wish this adunit placed in. If this parameter is left blank, the first adzone corresponding to your API key will be used by default. Adzone ID numbers are retrieved from the Adzones endpoint

Request Body

The request body contains a JSON array of adunit requests. Each object in the array may must specify a UUID and one or more tags. Demographics that relate to the subscriber may optionally be provided. For example, if you are requesting an adunit for a 25 year old female, you may include the "age" and "gender" demographics in your request body.

Request Body JSON Parameters

Parameter Description
uuid Required Unique User ID (UUID). The UUID should be a unique identifier for each of the subscribers on your list. The UUID may be up to 15 alphanumeric characters long.
tags Required Comma-delimited list of tag ID numbers. Tags allow you to target ads to specific demographics of users, which increases both subscriber satisfaction and publisher earnings due to better ad relevance. Tag ID numbers are retrieved from the Tags endpoint
demographics Optional Valid demographics: Age (integer) or Gender ("male" or "female")

Example Request Body

[
   {
      "uuid":"uuid-123-456",
      "tags":"7,8,9"
   },
   {
      "uuid":"abc-123",
      "tags":"15",
      "demographics":{
         "age":25,
         "gender":"male"
      }
   }
]

Endpoint Return Properties

Property Type Description
Adunit JSON Object A complete Adunit Object is returned. See the return values of the Adunit API endpoint for description of the parameters
status Array[] Returns a status code containing details about the success or failure of the endpoint. Status codes can be found here.

Example Return JSON

{
   "adunits":{
      "uuid-123-456":{
         "ad_title":"Retargeting on Facebook?",
         "ad_body":"Get more sales and conversions with Facebook retargeting. Try it free for 
		 14 days. Set up takes just minutes!",
         "image_source":"http://www.launchbit.com/taz-i/3463-bec100c9a6a60bac72c858bceadcfc4b17adade3-text.png",
         "ad_url":"http://www.launchbit.com/aa/1020294475/",
         "pixel":"http://www.launchbit.com/ap/1020294475/",
         "status":{
            "text":"GenericSuccess",
            "code":1000
         }
      },
      "abc-123":{
         "status":{
            "text":"NoAvailableAdunits",
            "code":2005,
            "message":"Due to the nature of dynamic budgets, there may be times when no 
			adunits are available for display.  We apologize for this inconvenience and are 
			working hard to make sure there are always adunits to serve."
         }
      }
   },
   "status":{
      "text":"GenericSuccess",
      "code":1000
   }
}

Full cURL example

$ curl -XPOST http://www.launchbit.com/api/v1.0/my_api_key/bulkadunit/ -d '
[
   {
      "uuid":"uuid-123-456",
      "tags":"7,8,9"
   },
   {
      "uuid":"abc-123",
      "tags":"15",
      "demographics":{
         "age":25,
         "gender":"male"
      }
   }
]
'

  {
     "adunits":{
        "uuid-123-456":{
           "ad_title":"Retargeting on Facebook?",
           "ad_body":"Get more sales and conversions with Facebook retargeting. Try it free 
		   for 14 days. Set up takes just minutes!",
           "image_source":"http://www.launchbit.com/taz-i/3463-bec100c9a6a60bac72c858bceadcfc4b17adade3-text.png",
           "ad_url":"http://www.launchbit.com/aa/1020294475/",
           "pixel":"http://www.launchbit.com/ap/1020294475/",
           "status":{
              "text":"GenericSuccess",
              "code":1000
           }
        },
        "abc-123":{
           "status":{
              "text":"NoAvailableAdunits",
              "code":2005,
              "message":"Due to the nature of dynamic budgets, there may be times when no 
			  adunits are available for display.  We apologize for this inconvenience and are 
			  working hard to make sure there are always adunits to serve."
           }
        }
     },
     "status":{
        "text":"GenericSuccess",
        "code":1000
     }
  }






Status Codes

Every API request returns a status code signifying the success or failure of that request. Each status response constains either two parts: a textual representation of the code, and an integer value. Optionally, some error codes contain a third field which provides extended information

Success codes are always in the range of 1000-1999 inclusive. Error codes are always in the range of 2000-2999 inclusive.

Success Codes

Name Code Description
GenericSuccess 1000 Generic response code that signifies a successful API request.

Error Codes

Name Code Description
PermissionDenied 2000 Returned if an incorrect or invalid API key is provided.
AdunitMissingUUID 2002 A unique user ID (UUID) must be supplied with each adunit request. The UUID is unique to each subscriber in your list.
AdunitMissingTags 2003 A comma-delimited list of tags must be supplied with each adunit request. Tag id numbers may be found using the /tags/ endpoint
AdunitInvalidAdzone 2004 The adzone ID that was provided is invalid. A list of your adzones may be found using the /adzones/ endpoint.
NoAvailableAdunits 2005 Due to the nature of dynamic budgets, there may be times when no adunits are available for display. We apologize for this inconvenience and are working hard to make sure there are always adunits to serve.
NoAvailableAdzones 2006 Your API key has no adzones associated with it. Please contact hello@launchbit.com to remedy this situation.
AdunitInvalidTags 2007 One or more of the tags provided was invalid. Please make sure all tags are numeric and separated by commas.

Example Return JSON

"status":{
  "text":"GenericSuccess",
  "code":1000
}

"status":{
  "text":"AdunitMissingTags",
  "code":2003,
  "message":"A comma-delimited list of tags must be supplied with 
             each adunit request.  Tag id numbers may be found 
             using the /tags/ endpoint"
}





Code Samples

PHP

This is a very basic example of how to utilize our API. It was created as a quick example that utilizes all the function calls.


<?php

//Replace this with your API key
define("API_KEY""12345");    
define("API_VERSION""1.0");    
define("API_BASE""http://www.launchbit.com/api/v" API_VERSION "/" API_KEY  "/");

//Simple function to retrieve the contents of an endpoint
function getEndpoint($endpoint$parameters = array()) {

    
//concatenate the parameters together...assumes correct order in the array
    
$strParameters implode("/"$parameters);
    
$api_url API_BASE $endpoint ."/"$strParameters;
    
$api_url .= (substr($api_url, -1) != "/") ? "/" "" ;

    
// Initializing curl
    
$ch curl_init$api_url );
    
    
// Configuring curl options
    
$options = array(
        
CURLOPT_RETURNTRANSFER => true,
        
CURLOPT_HTTPHEADER => array('Content-type: application/json')
    );
    
    
// Setting curl options
    
curl_setopt_array$ch$options );
     
    
// get the JSON result
    
$retJSON =  curl_exec($ch);
    
    
//decode the JSON into a PHP object
    
return json_decode($retJSON);
}


//get a list of all the tags
$result getEndpoint("tags");

//Example of checking the response code for an error
if ($result->status->code >= 2000) die("Error: " $result->status->text);

//We are selecting the first tag as an example
$tag_id $result->tags[0]->tag_id;
$tag_name $result->tags[0]->tag_name;



//get a list of our adzones
$result getEndpoint("adzones");

if (
$result->status->code >= 2000) die("Error: " $result->status->text);

//get the first adzone in the list
$adzone_id $result->adzones[0];


//set our parameters for the adunit call (uuid, tags, adzone_id)
$parameters = array("1234"$tag_id$adzone_id);
$result getEndpoint("adunit"$parameters);

if (
$result->status->code >= 2000) die("Error: " $result->status->text);

//retrieve the adunit information
$ad_title $result->ad_title;
$ad_body $result->ad_body;
$ad_url $result->ad_url;
$image_source $result->image_source;
$pixel $result->pixel;

?>


Documentation Changelog