/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
  }
}

/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
     }
  }

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.

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

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 jennifer@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.

"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"
}

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

09-17-2012
- Better description of which HTTP headers are returned by API requests
- Fixed typo in /adunit/ description. "pixel_source" should be "pixel".
- An error status code (2007 "AdunitInvalidTags") was undocumented. Added to status code section

Launchbit API - Release v1.0 Documentation

Table of Contents

General Details

Available Endpoints

/version/

Endpoint Description

Endpoint URI

Endpoint Return Properties

Example Return JSON

/tags/

Endpoint Description

Endpoint URI

Endpoint Return Properties

Full list of tags:

/adzones/

Endpoint Description

Endpoint URI

Endpoint Return Properties

Example Return JSON

/adunit/

Endpoint Description

Endpoint URI

Endpoint Return Properties

Example Return JSON

/adunit/ (With Demographic Data)

Endpoint Description

Endpoint URI

Request Body

Available demographics to include

Example Request Body

Endpoint Return Properties

Example Return JSON

Full cURL example

/bulkadunit/

Endpoint Description

Endpoint URI

Request Body

Request Body JSON Parameters

Example Request Body

Endpoint Return Properties

Example Return JSON

Full cURL example

Status Codes

Success Codes

Error Codes

Example Return JSON

Code Samples

PHP

Documentation Changelog