Image depicts some of the capabilities of the Kochava API: automatic campaign creation, lookback window creation, session threshold triggers, custom Fraud Blacklist, and reporting.

Imagine you’re building a house. Your architect has finished the blueprints, a contractor has been selected, and you have your day to “break ground” already set. Your plumber, electrician, roofer, and finishing teams all request a copy of the blueprints and schematics from your architect. The architect gives you a funny look and responds that these blueprints only include carpenter instructions, and he’ll need to go back to the drawing board and start new blueprints for each service provider individually. That would be ridiculous, right? A standard building blueprint accounts for the required steps to make your house a reality. The existence of standard “blueprint” holds true for an API so that any developer, regardless of the service they provide, can tap into it for their company’s marketing needs.

The value of a blueprint is a set of standards that each team can use as a foundation, a common understanding. Building a system on APIs allows us to exchange these blueprints with our internal teams, customers, network partners, and agencies. It’s what allows them to create new and unique systems on top of our core platform.

The reporting API we introduced in 2016 allows for an incredible level of customization. It was built on an entirely new API and is even more flexible than its predecessor. We’ve had great feedback on this API and in addition to using this system to power our reporting user interface (UI) we have built a number of other systems on top of it. In our 2016 release, we introduced token-based querying. This created a clean and common interface between our scheduled, summary, ad-hoc, and recurring reports. Here’s what it looks like to retrieve a report token, either ad-hoc or scheduled, from the API:

{

“status”: “completed”,
“report_token”: “-4231405407304221306”,
“status_date”: “2016-03-04 18:42:24”,
“progress”: “100”,
“report”: “http://kochava-reporting.s3.amazonaws.com/…”,
“report_type”: “summary”

}

 

API Configurations

We also introduced custom report times, column mapping, “traffic include” options, custom parameters, custom group types, and more. The API allows for all of this configuration, enabling customers to plug our reporting infrastructure directly into a dashboard, service, or another internal system on their end. Take a look at what’s exchanged when a new scheduled report is submitted:

{

“api_key”: “***”,
“api_key”: “***”,
“app_guid”: “***”,
“traffic”: [
“click”,
“install”,
“event”
],
“traffic_grouping”: [
“country”
],
“time_series”: “24”,
“traffic_filtering”: {
“country”: [
“us”,
“ca”,
“mx”
]
},
“delivery_format”: “csv”,
“delivery_method”: [
“S3link”
],
“notify”: [
“emann@kochava.com”
],
“frequency”: “weekly”,
“run_on”: “3”,
“delay”: “2”,
“previous_time”: “2”

}

 

Kochava API = real-time interaction

Our APIs don’t end with reporting. The power of integrating directly with Kochava via one of APIs allows you to engage and react in real time to your marketing efforts and really is unparalleled. You won’t find this level of customization and remote control available on other measurement platforms. Our customers connect their internal systems to everything from automatic campaign creation, lookback window adjustment, session threshold triggers, custom fraud blacklisting, reporting, device ID exports, and probably dozens we’re not even aware of (which is great)!

This has advantages beyond only servicing external customers. When we onboard new developers, we have them build new services on top of our public APIs. This not only creates a safe onboarding environment but gives them access to the powerful Kochava platform on day one. It puts the power of our microservices into a sandbox environment for quick implementation and innovation.

When we design, architect, and build a new system, we imagine this service being utilized by a customer who wants to take advantage of the engine, but would rather fit their own interior. If you’ll forgive the metaphor change, putting a Porsche engine into a VW camper—you get the power and reliability of a great engine, with your own unique style. Giving programmatic access to services allows for rapid innovation and hands a new level of creativity to marketing teams with even a little technical know-how. Let’s unpack two scenarios made possible only by allowing API access to our services:

Scenario 1: Based on Kochava Alert of fraudulent activity, automatically decrease lookback window for a single tracker.

Our alerting system can either trigger an external action or be used to retrieve alert status directly. An alert object from the API could look something like this:

{

“id”: 11,
“active”: 1,
“name”: “Bingo”,
“type”: “click_volume”,
“duration”: 60,
“filters”: {
“in”: {
“tracker_id”: [
“my_sample_tracker_id”
]
},
“not_in”: {
“campaign_name”: [
“Demo Campaign”
]
}
},
“condition”: “>”,
“threshold”: 90000,
“action_id”: 1,
“severity”: “high”,
“last_checked”: “2016-10-26 17:10:56”
“triggered”: 1,

}

 

A system polling this API could understand that the tracker received over 90,000 clicks within 90 minutes, which was designated as fraudulent by the customer during configuration. Utilizing tracker overrides, we can decrease the lookback window (for this tracker only) with a goal to cut the attribution feedback loop for this impacted publisher. In this scenario, we’ll decrease the lookback window for IP, partial IP, and fingerprint matching and leave device ID matching unchanged. I’ll also go ahead and turn on Traffic Verifier for this tracker to specify an acceptable traffic volume as an additional precaution.

{

“tracker_overrides”: [

{
“name”: “Enable Verification”,
“key”: “enable_verification”,
“group”: “general”,
“value”: 1,
},
{
“name”: “Fingerprint”,
“key”: “fingerprint_lookback_window”,
“group”: “click”,
“value”: 30,
},
{
“name”: “IP”,
“key”: “ip_lookback_window”,
“group”: “click”,
“value”: 15,
},
{
“name”: “Partial IP”,
“key”: “partial_ip_lookback_window”,
“group”: “click”,
“value”: 5,
}
]
}

 

While this scenario may not be a common request, it highlights the flexibility of connecting any two systems via some custom business logic. I’m not sure you’d ever want to adjust your lookback windows based on the lunar position, but it’s possible.

Scenario 2: Based on internal metrics for user fraud, automatically add a device ID to your account Blacklist.

Our Global Fraud Blacklist is our curated list of known fraudsters. This list is a subset of all the metrics you can browse in our Fraud Console. When we created the Fraud Console, we realized the power of being able to, with one click, add something to a Fraud Blacklist that only applies to a single account. As soon as we introduced this, we quickly saw the powerful ways in which customers could utilize their own fraud logic or models to add items to their Blacklist. Here’s what a device ID being added looks like:

{

“deviceIdValue”: “-1173750892943404010”,
“deviceIdType”: “adid”,
“reason”: “Device High Click Volume”,
“createDate”: “2017-03-03 13:56:09”,
“updateDate”: “2017-03-03 13:56:09″<
}

Let us handle the real-time verification; just send the Kochava API the site IDs, device IDs, or IP addresses your system has flagged as fraudulent. Customers have added tens of thousands of entities to their account-only Blacklists—all automatically through the API.

API interfaces provide a universal translation to any developer, regardless of programming language or tech stack and allow for automated services to tap into our infrastructure and data centers to power new tools and capabilities. Head over to our support site to browse for our publicly available APIs, and keep us in the loop on new and creative uses. We love to hear how customers are plugging into Kochava!

See why we're the best

About the Author

Eric Mann is the Director of Product Engineering at Kochava where he spends his days both hands-on with the codebase, as well as alongside fellow developers to architect, build, and sustain Kochava products and services. In addition to his role inside of Product/Development, Eric enjoys working directly with clients on implementations of the Kochava platform.