For API Access
To receive API access, please reach out to Getintent sales team – us-sales@getintent.com.
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 |
| 23 March 2017 | v2.00 | API v2 documentation release |
Introduction
This document describes the API of Getintent platform. The API consists of three major services:
- Common API service: allows to create and edit common RTB entities
- Advertiser API service: allows to manage advertiser related entities (creatives, segments and etc)
- Reporting API service: 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 endpoints
API URLs have the following pattern:
| Блок кода | ||
|---|---|---|
| ||
http://ui.getintent.com/api/v2/<object_type>/<action>(/<id>)?token=<token> |
API response codes
API always returns valid JSON as output, the following HTTP response codes are supported:
| Response code | Description |
|---|---|
| 200 | Success |
| 400 | Validation error |
| 403 | API not found |
| 404 | Object not found |
| 500 | Server error |
API error example:
| Блок кода | ||
|---|---|---|
| ||
{
"error": 1,
"code": 403,
"msg": "Unavailable AdData object 'aadvertisers'"
} |
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 additional fields in "list" method output (by default "list" method returns only "id" and "name" fields) | list | CSV fields | null | ../list?token=<token>&custom_fields=<field1>,<field2>,... |
page_limit | Items per one page. If "page_limit" parameter is used, then "mode" property's value becomes mode=1 automatically. | all, list | integer | null | ../all?token=<token>&page_limit=10 |
page | Retrieves page [N] output, works only in case "page_limit" parameter is set. | all, list | integer | null | ../all?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 formatD, 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
}
} |