Introduction

Welcome to the DropIn API! You can use our API to access DropIn API endpoints, which can create, edit, and provide analytics on mobile advertising campaigns.

We have language bindings in Shell, Ruby, and Java! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code

                            require 'rest-client'

                            dropin = RestClient::Resource.new('http://api.dropin.io/api/', :headers=>{ :Authorization => 'meowmeowmeow' })
                        
                
                            # With shell, you can just pass the correct header with each request
                            curl "api_endpoint_here" -H "Authorization: meowmeowmeow"
                        
                

Make sure to replace meowmeowmeow with your API key.

DropIn uses API keys to allow access to the API. Please contact DropIn Ad Operations for your developer key (ops@dropin.io).

DropIn expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: meowmeowmeow

Advertisers

An Advertiser is an identifier for the organization for which Media Plans, Media Buys, and Campaigns are run across the DropIn Platform.

Create an Advertiser

The above command returns JSON structured like this:

                                {
                                  "id": 436,
                                  "name": "Test Advertiser",
                                  "advertiserCategories": [],
                                  "apiKey": "meowmeowmeow",
                                  "fbId": "",
                                  "xid": "advertiser/436"
                                }
                            
                

HTTP Request

POST http://api.dropin.io/api/advertiser/create

Get all Advertisers

The above command returns JSON structured like this:

                                [
                                  {
                                    "id": 436,
                                    "name": "Test Advertiser",
                                    "advertiserCategories": [],
                                    "apiKey": "meowmeowmeow",
                                    "fbId": "",
                                    "xid": "advertiser/436"
                                  },
                                  {
                                    "id": 501,
                                    "name": "Another.co",
                                    ...
                                    "xid": "advertiser/501"
                                  }
                                ]
                            
                

HTTP Request

GET http://api.dropin.io/api/advertiser

Get an Advertiser

The above command returns JSON structured like this:

                                {
                                  "id": 436,
                                  "name": "New Advertiser",
                                  "advertiserCategories": [],
                                  "apiKey": "meowmeowmeow",
                                  "fbId": "",
                                  "xid": "advertiser/436"
                                }
                            
                

HTTP Request

GET http://api.dropin.io/api/advertiser/{id}

Media Plans

A Media Plan is a container object holding the template parameters for bulk creation of advertising campaigns.

Media Plans specify the base creative elements, campaign budget, and start and end dates for all Media Buys created in the Media Plan

Media Plans can optionally specify that certain elements are to be customizable on a per-Media Buy basis.

Create a Media Plan

                                response = dropin['plan/create'].post 'advertiserId'=>'436', 'img'=>'http://dropin-user.s3.amazonaws.com/cpFcWWAQkWYflj6EK6g4_dropin_grid_75.png',
                                    'url'=> 'http://www.dropin.io/get-started-now',
                                    'dailyBudget'=>'10',
                                    'totalBudget'=>'10',
                                    'title'=> 'Test',
                                    'copyText'=>'This is the copy',
                                    'start'=>'15 Feb 2014 12:00:00 GMT',
                                    'end'=>'16 Feb 2014 12:00:00 GMT'
                                plan = JSON.parse(response)
                            
                

The above command returns JSON structured like this:

                                {
                                    "id": 19,
                                    "name": "Test",
                                    "advertiser": {
                                      "id": 436,
                                      ...
                                      "xid": "advertiser/436"
                                    },
                                    "copyText": "This is the copy",
                                    "customizedCopy": false,
                                    "customizedDailyBudget": false,
                                    "customizedDestitation": false,
                                    "customizedEndDate": false,
                                    "customizedImage": false,
                                    "customizedStartDate": false,
                                    "customizedTitle": false,
                                    "customizedTotalBudget": false,
                                    "dailyBudget": 10,
                                    "destinationUrl": "http://www.dropin.io/get-started-now",
                                    "endDate": 1392552000000,
                                    "imageUrl": "http://dropin-user.s3.amazonaws.com/cpFcWWAQkWYflj6EK6g4_dropin_grid_75.png",
                                    "mediaBuys": [],
                                    "startDate": 1392465600000,
                                    "status": "REQUESTED",
                                    "totalBudget": 10,
                                    "xid": "plan/19"
                                  }
                            
                

HTTP Request

POST http://api.dropin.io/api/plan/create

Query Parameters

Parameter Default Optional Description
advertiserId false Advertiser ID associated with authorization token and media plan.
name false Name of campaign.
title false Default title for ad creative.
copyText false Default text for ad creative body.
img false URL of image asset for creative generation.
url false URL of landing page for ad-unit click-throughs.
dailyBudget false Amount in dollars per day to spend for each Media Buy.
totalBudget false Total amount in dollars to spend across campaign length for each Media Buy.
start false Default start date for media buys.
end false Default end date for media buys.
customizedTitle true Allow media buys to override title.
customizedCopy true Allow media buys to override copyText.
customizedImage true Allow media buys to override img.
customizedCopy true Allow media buys to override copyText.
customizedDestination true Allow media buys to override url.
customizedStartDate true Allow media buys to override start date.
customizedEndDate true Allow media buys to override end date.
customizedDailyBudget true Allow media buys to override daily budget.
customizedTotalBudget true Allow media buys to override total budget.

Get all Media Plans

                                response = dropin['plan'].get
                                plans = JSON.parse(response)
                            
                
                                curl http://api.dropin.io/api/plan -H "Authorization: meowmeowmeow"
                            
                

The above command returns JSON structured like this:

                                [
                                    {
                                      "id": 12,
                                      "name": "Unnamed Plan",
                                      "advertiser": {
                                        "id": 436,
                                        "name": "New Advertiser",
                                        "advertiserCategories": [],
                                        "apiKey": "meowmeowmeow",
                                        "fbId": "",
                                        "xid": "advertiser/436"
                                      },
                                      ...
                                      "xid": "plan/12"
                                    },
                                    {
                                      "id": 13,
                                      "name": "Test Campaign",
                                      ...
                                      "xid": "plan/13"
                                    }
                                  ]
                            
                

Media Buys

Create a Media Buy

                                dropin["plan//buy"].post  'url'=> 'http://www.dropin.io/get-started-now',
                                    'dailyBudget'=>'10',
                                    'totalBudget'=>'10',
                                    'zips' => ['02127','02129'],
                                    'title'=> 'Test Custom title',
                                    'copyText'=>'This is the custom copy',
                                    'start'=>'20 Feb 2014 12:00:00 GMT',
                                    'end'=>'21 Feb 2014 12:00:00 GMT' 
                            
                

HTTP Request

POST http://api.dropin.io/api/plan/{id}/buy

Reporting

DropIn provides several ways to view performance data on Media Plans and Media Buys.

Impressions

                                dropin["plan//impressions"].get 
                            
                

The above command returns JSON structured like this:

                                {
                                  "plan": 54,
                                  "impressions": 3504
                                }
                            
                

Provides a real-time update on the total number of impressions served to date in the Media Plan.

HTTP Request

GET http://api.dropin.io/api/plan/[id]/impressions

Clicks

                                dropin["plan//impressions"].get 
                            
                

The above command returns JSON structured like this:

                                {
                                  "plan": 54,
                                  "clicks": 19
                                }
                            
                

Provides a real-time update on the total number of clicks recorded to date in the Media Plan.

HTTP Request

GET http://api.dropin.io/api/plan/[id]/clicks

Plan Report

                                dropin["plan//report"].get 
                            
                

The above command returns JSON structured like this:

{
  "id": 63,
  "impressions": 7097,
  "clicks": 9,
  "ctr": 0.0012681414682260109,
  "cost": 6.9599999999995665,
  "cpm": 0.0009806960687613875,
  "items": [
    {
      "id": 1786,
      "impressions": 2376,
      "clicks": 5,
      "ctr": 0.0021043771043771043,
      "cost": 2.3199999999998555,
      "cpm": 0.0009764309764309156,
      "properties": [
        {
          "property": "Accuweather-Android-US|http://www.accuweather.com/",
          "min": 1395860420000,
          "max": 1395860420000,
          "count": 12,
          "rate": 0
        },
        {
          "property": "Accuweather-iPhone-US|http://www.accuweather.com/",
          "min": 1395860420000,
          "max": 1395860420000,
          "count": 1,
          "rate": 0
        },
        {
          "property": "Accuweather-MobileWeb-300x250-US|http://www.accuweather.com/",
          "min": 1395860420000,
          "max": 1395860420000,
          "count": 5,
          "rate": 0
        },
        {
          "property": "Accuweather-MobileWeb-US|http://www.accuweather.com/",
          "min": 1395860420000,
          "max": 1395860420000,
          "count": 6,
          "rate": 0
        },
        {
          "property": "AccuWeather|http://www.accuweather.com",
          "min": 1395860420000,
          "max": 1395860420000,
          "count": 1,
          "rate": 0
        },
        ...
        {
          "property": "|http://www.coxdigitalsolutions.com",
          "min": 1395860420000,
          "max": 1395860420000,
          "count": 1,
          "rate": 0
        }
      ]
    }
  ],
  "generated": 1395860420000
}
                            
                

Plan Reports are aggregated detailed reports that contain all information from a Media Plan and associated individual Media Buys, including # of impressions, # of clicks, CTR, and cost

Plan Reports are updated hourly throughout the execution of campaigns.

HTTP Request

GET http://api.dropin.io/api/plan/[id]/report

Heatmap Report

The above command returns JSON structured like this:

                                {
                                    "max": 3.2580965380215,
                                    "data": [
                                      {
                                        "lat": 40.039088,
                                        "lng": -76.305891,
                                        "count": 0.69314718055995
                                      },
                                      {
                                        "lat": 39.963902,
                                        "lng": -75.203552,
                                        "count": 0.69314718055995
                                      },
                                      ...
                                      {
                                        "lat": 39.99474,
                                        "lng": -75.116562,
                                        "count": 1.0986122886681
                                      }
                                    ]
                                  }
                            
                

This call returns a data object compatible with heatmap.js showing the relative density of clicks recorded in various target locations throughout the course of a campaign.

Please see the site for heatmap.js for a complete example of how to render such a heatmap on a Google Maps overlay.

HTTP Request

GET http://api.dropin.io/api//plan/{id}/heatmap

Errors

The DropIn API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! Slown down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.