Change log

Date	API version	Change
4 September 2015	v1.33	Added authentication reference
24 September 2015	v1.35	Add "last-modified" support
10 October 2015	v1.36	Added object "forecast" for advertiser
5 November 2015	v1.37	Campaigns, campaign_groups, creatives, sites added to common objects

Introduction

This document describes the RTBSuite API. The API consists of two major parts:

Campaign management API. This API allows to create and edit advertising campaigns along with related entities (creatives, segments and etc)
Reporting API. This part of API allows to get statistical information about campaign that are already running

General approach: object and methods

API is build as JSON RESTful service. Each object has it’s JSON representation and could be retrieved using get method. Also list, update and new are available.
Each type of JSON object has name and id. The structure is as follows:\

{
	id: 1,
	name: "<name>",
 	...
}

Also some object may belong to specific advertiser, in this case advertiser_id field would be required

{
	id: 1,
	name: "<name>",
	advertiser_id: 6
 	...
}

The general URL API pattern is:

http://ui.getintent.com/api/v1/<object_type>/<action>(/<id>)?token=<token>

Where token is authentication token (it could be obtained through user settings in UI)

Advertiser Object

Below you will find API examples advertiser's objects to work with.

Important: All variables are required!

Variables

Variable	Description
<advertiser_id>	Advertiser's ID. Important: Advertiser's settings have to be managed at Common and System level
<entity>	Object type (Campaigns, sites etc..)
<entity_id>	Object's ID
<token>	Token to access to API. It can be found at user's settings. Important: user has to have access to advertiser with id = <advertiser_id>

Available Entities

Character ID	Description
campaigns	Ad Campaigns
campaign_groups	Ad Campaigns Groups
creatives	Creatives
sites	Sites
domains_lists	Domain lists
snippets	Snippets
segment_definitions	Segments
forecast	Campaigns status and forecast (only list method is available)

Methods

Entity's objects list

GET https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/list?token=<token>

Returns objects <entity> type list for Advertiser <advertiser_id>.

"Id" and "name" fields are being returned for each object by default. Example for such list is as below:

{
	"137": {
		"id": 137,
		"name": "Test campaign!"
	},
 
	...
	"4452": {
		"id": 4452,
		"name": "test"
	}
}

To get any additional fields at list you need to add them separated by comma in GET request in "custom_fields" parameter.

To get objects list with all existing fields another method should be used:

GET https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/all?token=<token>

Additional parameters

Parameter	Description	Available at, method	Values	By default	Example
mode	Affects on list's view. Old version: all collection will be returned at root (deprecated) New version: all collection will be placed to data node Value recommend to use always: 1	all, list	0 - old version (deprecated). 1 - new version.	0	../list?token=<token>&mode=1
custom_fields	Includes all listed object's fields in output for "list" method	list	Listed by comma additional fields.	null	../list?token=<token>&custom_fields=starts,ends
page_limit	Limits count of items per request. Realizes pagination. If "page_limit" parameter is used, then "mode" property's value becomes mode=1 automatically.	all, list	Count of items per one page.	null	../list?token=<token>&page_limit=10
page	Current page. Works with "page_limit" method together only.	all, list	Current page in output.	null	../list?token=<token>&page_limit=10&page=2
pretty	Controls JSON output format	all,list	0 - minimized JSON , 1 - formatted JSON	0	../list?token=<token>&page_limit=10&pretty=1

Additional headers

Parameter	Description	Available at, method	Values	By default	Example
if-modified-since	Return header HTTP 304 Not Modified without content, if data has not updated since this date	list	Date in specify format D, d M Y H:i:s GMT	null	if-modified-since: Fri, 18 Sep 2015 10:34:37 GMT

{
    "data": {
        "921": {
            "id": "921",
            "name": "test_campaign"
        },
        "1400": {
            "id": "1400",
            "name": "1"
        }
    },

    "pages": {
        "total_elements": "6",
        "total_pages": 3,
        "current_page": 1,
        "previous_page": false,
        "next_page": 2,
        "page_size": 2,
        "offset": 0
    }
}

Create an Entity

PUT https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/new?token=<token>

Use PUT request type. At JSON with object's structure have to be at request's body.

Example:

curl --data '{"name": "title"}' -X PUT https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/new?token=<token>

Get an Entity

GET https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/get/<entity_id>?token=<token>

Example.

curl -X GET https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/get/<entity_id>?token=<token>

Additional headers

Parameter	Description	Available at, method	Values	By default	Example
if-modified-since	Return header HTTP 304 Not Modified without content, if data has not updated since this date	get	Date in specify format D, d M Y H:i:s GMT	null	if-modified-since: Fri, 18 Sep 2015 10:34:37 GMT

Update an Entity

PUT https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/edit/<entity_id>?token=<token>

Use PUT request type. At JSON with object's structure have to be at request's body.

Example:

curl --data '{"name": "new title"}' -X PUT https://ui.getintent.com/api/v1/advertisers/<advertiser_id>/<entity>/edit/<entity_id>?token=<token>

Delete an Entity

DELETE https://ui.gcom/api/v1/advertisers/<advertiser_id>/<entity>/delete/<entity_id>?token=<token>

Example:

curl -X DELETE https://ui.g getintent com/api/v1/advertisers/<advertiser_id>/<entity>/delete/<entity_id>?token=<token>

Common and System Objects

Here you'll find API examples for work with Common and System objects.

Also those methods should be used for Advertiser's settings management.

Important! All variables are required.

Variables

Variable	Description
<entity>	Object type (reference_tables, segment_definitions и тд)
<entity_id>	Object's ID
<token>	Token for API access. Its value can be found at "my settings" user's menu. Important: token has to belong to Admin user.

Available Entities

ID	Description
advertisers	Advertiser and its settings. Important: Advertiser's objects have to be managed at Advertiser's level
segment_definitions	Common segments
reference_tables	Contains additional information and variety settings
domains_lists	Common domain lists
snippets	Common snippets

Methods

Entity's objects list

GET https://ui.getintent.com/api/v1/<entity>/list?token=<token>

Returns System and Common <entity> type Objects list.

"id" and "name" fields will be returned for each object by default.

Here is example of such "list" method:

{
	"137": {
		"id": 137,
		"name": "Test campaign!"
	},
 
	...
	"4452": {
		"id": 4452,
		"name": "test"
	}
}

If any additional fields are needed at the list just put all of them separated by comma at GET custom_fields parameter.

In case you need to get list of objects with absolutely all existing fields, just use "all" method as below:

GET https://ui.getintent.com/api/v1/<entity>/all?token=<token>

Additional parameters

Parameter	Description	Available at, method	Values	By default	Example
mode	Affects on list's view. Old version: all collection will be returned at root (deprecated) New version: all collection will be placed to data node Value recommend to use always: 1	all, list	0 - old version (deprecated). 1 - new version.	0	../list?token=<token>&mode=1
custom_fields	Includes all listed object's fields in output for "list" method	list	Listed by comma additional fields.	null	../list?token=<token>&custom_fields=starts,ends
page_limit	Limits count of items per request. Realizes pagination. If "page_limit" parameter is used, then "mode" property's value becomes mode=1 automatically.	all, list	Count of items per one page.	null	../list?token=<token>&page_limit=10
page	Current page. Works with "page_limit" method together only.	all, list	Current page in output.	null	../list?token=<token>&page_limit=10&page=2

Additional headers

Parameter	Description	Available at, method	Values	By default	Example
if-modified-since	Return header HTTP 304 Not Modified without content, if data has not updated since this date	list	Date in specify format D, d M Y H:i:s GMT	null	if-modified-since: Fri, 18 Sep 2015 10:34:37 GMT

Create an Entity

PUT https://ui.getintent.com/api/v1/<entity>/new?token=<token>

Use PUT request type. At JSON with object's structure have to be at request's body.

Example:

curl --data '{"name": "title"}' -X PUT https://ui.getintent.com/api/v1/<entity>/new?token=<token>

Get an Entity

GET https://ui.getintent.com/api/v1/<entity>/get/<entity_id>?token=<token>

Example:

curl -X GET https://ui.getintent.com/api/v1/<entity>/get/<entity_id>?token=<token>

Additional headers

Parameter	Description	Available at, method	Values	By default	Example
if-modified-since	Return header HTTP 304 Not Modified without content, if data has not updated since this date	get	Date in specify format D, d M Y H:i:s GMT	null	if-modified-since: Fri, 18 Sep 2015 10:34:37 GMT

Update an Entity

PUT https://ui.getintent.com/api/v1/<entity>/edit/<entity_id>?token=<token>

Use PUT request type. At JSON with object's structure have to be at request's body.

Example:

curl --data '{"name": "new title"}' -X PUT https://ui.getintent.com/api/v1/<entity>/edit/<entity_id>?token=<token>

Delete an Entity

DELETE https://ui.getintent.com/api/v1/<entity>/delete/<entity_id>?token=<token>

Example:

curl -X DELETE https://ui.getintent.com/api/v1/<entity>/delete/<entity_id>?token=<token>

Objects examples

Advertiser (advertisers)

{
	"name": "Test (for Monitoring)",
	"currency": "RUB",
	"url": "https://ui.getintent.com",
	"max_budget": 0,
	"manage_campaigns_commissions": "true",
	"hide_billing": "false"
}

Ad Campaign (campaigns)

{
	"name": "Test campaign!",
	"advertiser_id": 27,
	"test-field": "test",
	"starts": "2013-11-12 00:00:00",
	"ends": "2014-03-09 22:59:59",
	"currency": "RUB",
	"creatives_type": "plain",
	"landing_page": "http://getintent.com",
	"disabled": true,
	"budget": 1000,
	"financing": {
		"type": "max_cpm",
		"price": 0.00003
	},
	"commissions": {
		"agency": "0",
		"dsp": "10"
	},
	"group_id": 0,
	"was_enabled": 1421915484,
	"targeting": {
		"geo": {
			"countries": [
				"US"
			],
			"regions": [
				"US/FL",
				"US/PA",
				"US/NJ"
			],
			"cities": [
				"Jersey City",
				"Houston"
			],
			"dma_code": [
				"500",
				"502"
			],
			"zip_code": [
				"10010"
			]
		},
		"segments": [
			1009,
			1048,
			1050,
			1071
		],
		"categories": [
			"iab2",
			"iab2-1",
			"iab2-2",
			"iab2-3",
			"iab2-12"
		], 
		"frequency_capping": {
			"hour": 4,
			"day": 10,
			"week": 30
		},
		"weekdays": [
			"1",
			"2",
			"3",
			"4",
			"5",
			"6",
			"7"
		],
		"time": [
			"1",
			"2",
			"3",
			"4",
			"5",
			"6",
			"7",
			"8",
			"9",
			"10",
			"11",
			"12",
			"13",
			"14",
			"15",
			"16",
			"17",
			"18",
			"19",
			"20",
			"21",
			"22",
			"23",
			"0"
		],
		"ssps": [
			"goog",
			"bsw.rubicon",
			"bsw.pubmatic"
		],
		"page_language": [
			"en"
		],
		"devices": [
			"DESKTOP",
			"SMARTPHONE",
			"TABLET"
		],
		"positions": [
			"above",
			"below",
			"unknown"
		],
		"operating_systems": [
			"IOS",
			"ANDROID",
			"WINDOWS",
			"LINUX",
			"MACOS",
			"OTHER",
			"WINDOWS_PHONE"
		],
		"browsers": [
			"FIREFOX",
			"IE",
			"EDGE",
			"OPERA",
			"YANDEX",
			"CHROME",
			"SAFARI",
			"ANDROID_BROWSER",
			"OTHER"
		]
	},
	"daily_budget": 12,
	"site_id": 42,
	"creatives": [
		210,
		3013,
		3014,
		3015,
		3016,
		3017,
		3018,
		3019,
		3020,
		3021,
		3022,
		3023,
		3024
	]
}

Ad Campaigns Group (campaign_groups)

{
	"name": "group name",
	"advertiser_id": 27,
	"budget_limit": 55000
}

Domains list (domains_lists)

{
	"name": "Test list",
	"advertiser_id": 27,
	"domains": [
		"yandex.ru",
		"google.com",
		"yahoo.com"
	]
}

Creative (creatives)

{
	"name": "1220849983_p9290052.jpg",
	"advertiser_id": 27,
	"creative_type": "plain",
	"url": "cdn.adhigh.net/media/1424168069-1220849983_p9290052.jpg",
	"size": "700x525",
	"alternative_creative_id": "false"
}

{
	"name": "240 for show",
	"advertiser_id": 27,
	"creative_type": "dynamic_creatives",
	"site_logo": "cdn.adhigh.net/media/1432213856-logo.png",
	"size": "240x400",
	"snippets": [
		169
	]
}

{
	"name": "Test_rtbmedia",
	"advertiser_id": 27,
	"creative_type": "3rd_party_creatives",
	"size": "300x250",
	"HTML": "<iframe src=\"http://localnetmarketer.com/ads/frame/300x250/722647/ad.html?t=142986782&click=[[CLICK_PREFIX_ENCODED]]\" style=\"border:0;width:300px;height:250px\"></iframe>\n\n",
	"ssl_compliant": "false",
	"click_tracking": "false"
}

{
	"name": "http://whoabella.com/whoabella-connected-s1e16-with-change-comes-challenge",
	"advertiser_id": 27,
	"creative_type": "native_creatives",
	"landing_page": "http://whoabella.com/monitordtr.php?i=pp.s1&url=http://whoabella.com/whoabella-connected-s1e16-with-change-comes-challenge/?utm_source=getintent&utm_medium=referral&utm_campaign=3bluemedia_camp1_cv1",
	"assets": [
		{
			"type": "img",
			"url": "nm.contextweb.com/media/1434570383-connected_cast.jpg",
			"image_type": 3,
			"size": "300x260"
		},
		{
			"type": "title",
			"text": "Check Out Latest Episode Of 'Connected'"
		},
		{
			"type": "data",
			"data_type": 1,
			"value": "Whoa Bella!"
		},
		{
			"type": "data",
			"data_type": 2,
			"value": "We've been rooting for Rosie's career to take off for a long time. Anyone can see that she's crazy talented, gorgeous and really freakin' deserves her big break and the sooner the better.\n\n"
		}
	]
}

Site (sites)

{
	"name": "http://test.com",
	"advertiser_id": 27,
	"click_control": "false",
	"feed_url": "http://names.ru/bitrix/catalog_export/rtb.xml"
}

Segment (segment_definitions)

{
	"name": "Test",
	"advertiser_id": 27,
	"available_to_all": false,
	"type": "standard",
	"terms": [
		{
			"type": "site_visitor",
			"values": [
				198
			],
			"times": 1,
			"days": 30,
			"negative": false
		}
	]
}

{
	"name": "AmberData/Продукты питания/Молочные продукты",
	"available_to_all": true,
	"type": "3rdparty",
	"3rd_party_id": "vi_316104",
	"price": 25,
	"currency": "RUB"
}

Snippet (snippets)

{
	"name": "standard_240x400",
	"js": "createGIADelement = function(element) {\n    var item = document.createElement(\"div\");\n    item.setAttribute(\"class\",\"__gi_item\");\n    var link = document.createElement(\"a\");\n    item.appendChild(link);\n    link.setAttribute(\"href\",element['url']);\n    link.setAttribute(\"target\",\"_blank\");\n    var image = document.createElement(\"img\");\n    link.appendChild(image);\n    image.setAttribute(\"src\",element['picture']);\n    var desc = document.createElement(\"div\");\n    link.appendChild(desc);\n    desc.setAttribute(\"class\",\"__gi_desc\");\n    desc.appendChild(document.createTextNode(element['name']));\n    var price = document.createElement(\"div\");\n    link.appendChild(price);\n    price.setAttribute(\"class\",\"__gi_price\");\n    price.appendChild(document.createTextNode(element['price'] + \" \" + element['currencySymbol']));\n\n    return item;\n}\n\ncreateGIADlogo = function(logoImg) {\n    var logo = document.createElement(\"div\");\n    if (logoImg && logoImg!==\"\"){\n      logo.setAttribute(\"class\",\"__gi_header\");\n      var link = document.createElement(\"a\");\n      logo.appendChild(link);\n      link.setAttribute(\"href\",\"[[LANDING_PAGE]]\");\n      link.setAttribute(\"target\",\"_blank\");\n      var sp = document.createElement(\"span\");\n      link.appendChild(sp);\n      var image = document.createElement(\"img\");\n      sp.appendChild(image);\n      image.setAttribute(\"src\", logoImg);\n    }\n    return logo;\n}\n\nvar domain = (typeof __GetI_domain) == \"undefined\" ? \"px.adhigh.net\" : __GetI_domain;\nvar src = ('https:' == document.location.protocol ? 'https://' : 'http://') + domain + '/ad240x400.css';\ndocument.write(\"<link rel='stylesheet' type='text/css' href='\"+src+\"'/>\");\n\nvar container = document.createElement(\"div\");\ncontainer.setAttribute(\"class\",\"_gi_ad_240x400\");\ndocument.getElementById(elementId).appendChild(container);\nvar siteLogo = \"[[SITE_LOGO]]\";\nif (siteLogo){\n    siteLogo = ('https:' == document.location.protocol ? 'https://' : 'http://') + siteLogo; \t  \n}\ncontainer.appendChild(createGIADlogo(siteLogo));\nfor(var i=0; i<products.length && i<4; i++) {\n  container.appendChild(createGIADelement(products[i]));\n}"
}

Reporting API

Build a Report

GET https://ui.getintent.com/api/v1/bigdata/reports?token=<token>

Parameters:

Parameter	Description	Values	By default	Example
token	It's required. Validates if method is available for particular user. Affects on data available for report building according to access settings.	It's string value. Can be found at "My Settings" menu at API tab	null	../reports?token=tokenstring
format	Manages report's format	json - json report format text - text report format divided by tab	text	../reports?token=<token>&format=json
dataset_name	Dataset name	browser_traffic - current campaigns available_inventory - available inventory bidding_performance - bids statistic pixel_traffic - traffic statistic	null	../reports?token=<token>&dataset_name=browser_traffic
start	Report's period start date. End date is required also.	Date at YYYY-mm-dd format	null	../reports?token=<token>&start=2015-05-01&end=2015-05-31
end	Report's period end date. Start date is required also.	Date at YYYY-mm-dd format	null	../reports?token=<token>&start=2015-05-01&end=2015-05-31
timezone	Timezone report's period	Timezone name	UTC	../reports?token=<token>&timezone=Europe/Moscow
keys	"Group by" report data fields. Fields can be found at Meta Data	Comma-separated field names	null	../reports?token=<token>&keys=country,os
filter[]	Array for report's output data filtering values.	Filter value's format is op:field:values Each separated value should be specified at new filter[] key op - comparison operation. Available options are eq (is equal) and is_not (is not equal). field - field name values - values for filtered field. If several values are needed, just list them with comma.	null	../reports?token=<token>&filter[]=eq:country:RU,UA&filter[]=is_not:advertiser_id:27
limit	Output rows number cap.	Max rows number expected	10000	../reports?token=<token>&limit=2000

Meta Data

GET https://ui.getintent.com/api/v1/bigdata/reports/meta_data?token=<token>

Returns Meta Data for report building.

Working Sample:

{
	"datasets": [
		{
			"name": "browser_traffic",
			"display_name": {
				"en": "Campaigns",
				"ru": "Кампании"
			},
			"bq_dataset_name": "browser_traffic",
			"key_fields": {
				"deal_id": "STRING",
				"geo_available": "STRING",
				"day": "TIMESTAMP",
				...
				"zip_code": "STRING"
			},
			"value_fields": {
				"imps": "INTEGER",
				"deliv_imps": "INTEGER",
				"unique_imps": "INTEGER",
				"clicks": "INTEGER",
				...
				"p_convs": "FLOAT"
			},
			"dates": [
				"2013_12_25",
				"2013_12_26",
				"2013_12_27",
				"2013_12_28",
				...
				"2015_07_11",
				"2015_07_12",
				"2015_07_13"
			],
			"sorting_key_default": {
				"day": "asc",
				"hour": "asc",
				"month": "asc"
			}
		},
 
		...
		
		{
			"name": "pixel_traffic",
			...
		}
	]
}