Campaign Management API

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 API of GetIntent RTBSuite platform. The API consists of three major parts:

Common API: allows to create and edit common RTB entities
Advertiser API: allows to manage advertiser related entities (creatives, segments and etc)
Reporting API: allows to get available reporting information campaign performance, available inventory, etc.

General approach

API is built as JSON RESTful service and support standard GET/PUT/DELETE methods over HTTP 1.1 protocol.

GET	read/retrieve
PUT	create/add/update/modify
DELETE	delete

API endpoint

API endpoint is RTBSuite UI hostname, general API URL pattern is:

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

<ui.getintent.com> should be replaced by proper RTBSuite UI domain. <token> is authentication token (can be obtained through user settings in RTBSuite UI).

JSON data model

RTB data model contains several entities, each entity has it’s own JSON representation with name and id:

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

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

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

API output

API output can be controlled by the following additional parameters and headers

Additional parameters controlling pagination/formatting

Parameter	Description	Method	Values	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	Page limit option, activates pagination mode. 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	Retrieves desired output page, works only in case "page_limit" parameter is set.	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

Returns "HTTP 304 Not Modified" header without content,

if data has not been updated since requested 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

Example of API JSON output in case pagination mode

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

Дерево страниц