REST API Adskeeper for advertisers

* Please note that all API requests must be performed via HTTPS.

Table of contents

  1. The main provisions of REST API
  2. Identification
  3. Adskeeper REST API answer
  4. Working with clients
    1. Getting the current client's token
    2. Getting information about the current financial status of the client
  5. Working with client's advertising campaigns
    1. Getting a collection of client's advertising campaigns
    2. Getting advertising campaign statistics by site
    3. Advertising campaigns detailed daily statistics
    4. Advertising campaigns daily statistics
    5. Advertising campaigns daily statistics for video campaigns

    6. Creating a new ad campaign (with all settings)
    7. Creating a new ad campaign
    8. UTM markup settings for ad campaign
    9. Setting limits on advertising campaign
    10. Block / unblock advertising campaign
    11. Getting creation date of ad campaign
    12. Setting the coefficient of a selective auction of an advertising campaign
    13. Setting the coefficient of a selective auction to all sub-sources
    14. Retrieving conversion settings for an advertising campaign
    15. Editing conversion settings for an advertising campaign
    16. Removing campaign to trash
  6. Advertising campaigns targeting settings
    1. Setting up the geo targeting of advertising campaigns
    2. Getting a list of available countries for setting up geo targeting
    3. Getting a list of available regions (cities) for geo targeting settings
    4. Editing geo targeting settings for advertising campaign
    5. Editing advertising campaign browser targeting
    6. Editing advertising campaign IP targeting
    7. Editing advertising campaign operating system targeting
    8. Getting advertising campaign operating system targeting settings
    9. Editing the filter settings on the sites for advertising campaign by UID
    10. Editing browser language targeting
    11. Getting browser language targeting settings
    12. Getting browser targeting settings
    13. Editing phone price range targeting
    14. Getting phone price range targeting
  7. Working with client's teasers
    1. Constants and identifiers in use
    2. Getting a list of client teasers
    3. Teaser detailed daily statistics
    4. Creating a new teaser for ad campaign
    5. Editing ad campaign teaser settings
    6. Changing advertising campaign teaser's CPC
    7. Block / unblock a teaser for advertising campaign
    8. Removing teaser (move to bin)

 

The main provisions of REST API

REST API allows you to integrate external applications with Adskeeper online  
advertising system.
API provides the ability to retrieve, add, and modify the data. Practically each  object in Adskeeper (whether it's a client, an advertising company, a teaser, etc.) can  be controlled by API. Adskeeper REST API Request is an HTTP request, which, with  the help of the ways in URL the object to perform the action is specified, and  with the help of parameters the necessary data is passed. Adskeeper API is a "RESTful  Web API". The API uses the following REST commands:
● GET
● PUT
● PATCH
● POST
● DELETE

The query parameters are case sensitive.

These commands correspond to certain actions within the Adskeeper system. Get an item or a collection of items (for example, a list of advertising campaigns):    

Command Action Description
POST Create Creates a new element (eg, a teaser)
GET Get (read)    Retrieve an element or a collection of elements
PUT Update Recreate an existing element or a collection of elements
PATCH Change Change certain properties of an element
DELETE Delete Delete an item or collection of items (eg, move a teaser to recycle bin)
Important! POST and PUT are not interchangeable. Each of the commands fulfills its specific function.

Adskeeper API URL:
Adskeeper REST API for clients is available at:

https://api.adskeeper.co.uk/v1

In general, the query looks like this:
https://api.adskeeper.co.uk/v1/module/controller/action?parameter_1=value_of_parameter_1&parameter_2=value_of_parameter_2&parameter_3=value_of_parameter_3

 

Identification

For identification the Adskeeper REST API uses a unique token consisting of 32 characters which is passed in client’s request Authorization header. To obtain a valid token client should use a special API function.

Every request sent to the Adskeeper REST API must contain the API token

 

Adskeeper REST API answer

In response to a request to the REST API server always returns the HTTP response with a status code , depending on the result of the query. 

Answer code Description
200 OK The query has been successfully
processed

The format of the returned data


The returned data can be formatted as JSON, or XML.  The default format is JSON. The request header is used to specify the format in which the data is  
returned. The client sends an Accept header, which indicates desired response format:  
Accept: application / xml  
or  
Accept: application / json


Description of the response format is sent in the response header Content Type. The data returned is the answer is a JSON string, which generally looks as follows:  

{
    "element_1":"value_of_element_1",    
    "element_2":"value_of_element_2", 
    "element_3":{
         "property_1_of_element_3":"value_of_property_1_of_element_3",       
         "property_2_of_element_3":[
               "value_1_of_property_2_of_element_3",
               "value_2_of_property_2_of_element_3"
         ]       
     }    

  . . . .  
}

 

If an error has occurred during the execution of the query   the description corresponding to the error is returned, such as:

{ "errors": [ "[_error_description_]" ] }

The data in the responses is returned taking into account the time zone of the client.

 

Working with clients

 

Getting the current client's token

Method URL
POST api.adskeeper.co.uk/v1/auth/token

Transferred parameters (required parameters are marked with asterisk *):

Parameter Value
email* E-mail of the client, specified at registration in Adskeeper system
password* Password of the client, received during registration in Adskeeper system
force

Ignores the restriction to regenerate the token more than once a day

1 - allows to regenerate, 0 - does not allow (default)

Returns an answer:

{
"token":"_current_token_",
"refreshToken":"_token_for_refresh_"
"idAuth":"_client_api_id_"
}

_current_token_  is used to identify the client;  
_token_for_refresh_ will be used in future versions to update an overdue current token.

 

Getting information about the current financial status of the client

Method GET
URL api.adskeeper.co.uk/v1/clients/_identifier_of_client's_account_
Headers

Accept: application/json

Authorization: Bearer {token}


Returned answer:

{
"id":"_client_api_id_",
"timezone":"_client's_timezone_",
"wallet":{
"balance":_state_of_MG_wallet_,
"credit":_overdraft_amount_,
"income":_total_replenish_sum_,
"currency":"_client_currency_"
}
}

All refunds are made in cents (0.01$) balance can have both positive and negative value. Available funds are defined as: balance + credit. Funds spent on advertising: income  balance.

 

Working with client's advertising campaigns

Getting a collection of client's advertising campaigns

Method GET
URL api.adskeeper.co.uk/v1/goodhits/clients/_client's_accont_ID_ / campaigns[_ad_campaign_ID_]
Headers

Accept: application/json

Authorization: Bearer {token}

If _ad_campaign_ID_ was not passed, then the method returns a collection of client's advertising campaigns. If the ID has been passed correctly, it returns information only about specific ad campaign.

Transferred parameters (required parameters are marked with asterisk *):

Parameter Value
Fields
  • array of client's properties, information on which you
    need to get.( example: fields=['name','ipsFilter','domainsFilter']).  
    If the parameter is not passed, then all properties are returned. The list may include the following properties:
  • id - ad campaign id
  • language - ad campaign language id
  • name - ad campaign id  
  • status - ad campaign status
  • ipsFilter- IP filter settings  
  • domainsFilter - domain filter settings  
  • widgetsFilterUid - widget filter settings
  • limitsFilter — limit settings for budget and clicks
  • targets - ad campaign operating systems targeting
  • languageTargeting - language filter settings. Ad campaign language id
  • browserTargeting - browsers filter settings. Possible browser values
  • category - campaign category
limit turns on the pagination, limiting the number of campaigns displayed on the page.
start uses for navigation for pagination pages. The default is 0.

 

Languages list:

ID NAME LANGUAGE_CODE
1 English en
2 Spanish es
3 French fr
4 German de
5 Vietnamese vi
6 Dutch nl
7 Italian it
8 Portuguese pt
9 Indonesian id
10 Greek el
11 Thai th
12 Hindi hi
13 Khmer km
14 Swedish sv
15 Hungarian hu
16 Malay ms
17 Romanian ro
18 Norwegian nb
19 Croatian hr
20 Polish pl
21 Finnish fi
22 Danish da
23 Filipino fil
24 Czech cs
25 Korean ko
26 Bosnian bs
27 Slovak sk
28 Japanese ja
29 Bulgarian bg
30 Slovene sl
31 Macedonian mk
32 Turkish tr
33 Estonian et
34 Armenian hy
35 Serbian sr
36 Lithuanian lt
37 Azerbaijani az
38 Latvian lv
39 Russian ru
40 Urdu ur
41 Arabic ar
42 Hebrew he
43 Chinese zh
44 Georgian ka
45 Nepali ne
46 Albanian sq
47 Bengali bn
48 Sinhalese si
49 Uzbek uz
50 Ukrainian uk
51 Tamil ta
52 Telugu te
53 Persian fa
54 Somali so
55 Tajik tg
56 Kyrgyz ky
57 Lao lo
58 Gujarati gu
59 Marathi mr
60 Malayalam ml
61 Kannada kn
62 Burmese my
63 Kazakh kk
64 Turkmen tk
65 Afrikaans af
66 Punjabi pa
67 Belarusian be
68 Swahili sw
69 Mongolian mn
70 Amharic am
72 Catalan ca
96 Tagalog tl
104 Odia or

Answer returned:

{
"_advertising_campaign_id_":{
"id":_advertising_campaign_id_,
"language":_campaign_language_,
"name":"_advertising_campaign_name_",
"status":{
"id":_state_identifier_,
"name":"_ad_campaign_status_name_",
"reason":"_campaign_state"
},
"domainsFilter":{
"filterType":"_domain_filter_type_",
"domainsNames":[
"_domain_1_",
"_domain_2_",
. . . . . . .
]
},
"ipsFilter":{
"filterType":"_IP_filter_type_",
"ips":[
"IP_adress_1",
"IP_adress_2",
. . . . . .
]
},
"widgetsFilterUid":{
"filterType":"_widget_filter_type_",
"widgets":{
" _widget_id_1":"[_widget_subid_1]",
" _widget_id_2":"[_widget_subid_2]",
" _widget_id_3":"[ _widget_subid_3]",

}
},
"statistics":{
"clicks":_counted_clicks_amount_for_today_,
"wages":_funds_spent_for_today_
},
      "category":{
         "id":"_category_ID_", 
         "name":"_category_name_"
      },
},
...........
}

Possible errors in this section:

[ERROR_TOO_MANY_CAMPAIGNS_USE_PARAMS_LIMIT_AND_START] - if the user has more than 500 campaigns and the optional limit parameter is not specified
[ERROR_MAX_LIMIT_PER_PAGE_500] - if the additional parameter limit is specified and it is more than 500

Status property indicates current campaign state and status.

Description of status value returned:

id

Description

1

Campaign is blocked due to end date

2

Campaign has reached total budget limit

3

Campaign has reached total clicks limit

4

Campaign is blocked by manager of client

5

Campaign is blocked due to negative balance

6

Campaign is unlimited and active

7

Campaign hasn't reached its daily limit

8

Yesterday campaign has reached its daily clicks or budget limit and is active

9

Campaign has reached its daily budget limit

10

Campaign has reached its daily clicks limit

11

Campaign is paused due to time schedule settings

12

Campaign stopped because the client delayed
13 Campaign stopped by manager
14 Campaign deleted
15 Campaign stopped because the client rejected
19 Campaign stopped due to violation of the creativity rules

IpsFilter property displays the IP filter settings of an advertising campaign (teasers of this campaign should not be shown to visitors with this IP). _IP_filter_type_ can take the following values:
off - the filter is disabled
except - "except" filter  
ips - a list of IP address ranges for filtering as an array.  _spent_by_the_client_for_today_ in $

 

Getting advertising campaign statistics by site

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_ad_campaign_ID_/quality-analysis/_uid_
Headers

Accept: application/json

Authorization: Bearer {token}

Transfered parameters (required parameters marked with asterisk *):

Parameters Values
campaignId* _ad_campaign_ID_
dateInterval

Period for which you need to get statistics. If interval is not specified, returns statistics for 90 days. Valid values are:

  • interval - need to 2 specify additional parameters: startDate and endDate in format yyyy-mm-dd
  • all - all time
  • thisWeek - current week
  • lastWeek - last week
  • thisMonth - current month
  • lastMonth - last month
  • lastSeven - last 7 days
  • today - today
  • yesterday - yesterday
  • last30Days - last 30 days
uid _uid_. If specified, displays information only for this site.
browser Filters data by browser. 1 value to a parameter can be passed. Browsers values list
os Filters data by OS. 1 value to a parameter can be passed. OS codes list
country Filters data by country. 1 value to a parameter can be passed. Countries codes list

Request example:

api.adskeeper.co.uk/v1/goodhits/campaigns/campaign_id/quality-analysis/uid?dateInterval=lastMonth&browser=chrome&os=android10mobile&country=CA

Answer returned:

{  
 "_campaignId_":{
  "_dateInterval_":{  
     "_widgetUid_":{  
        "clicks":"_clicks_",
        "spent":"_spent_",
        "cpc":"_cpc_client_currency_",
"qualityFactor": "_quality_factor_",
        "buy":"_conversions_at_the_buying_stage_",
        "buyCost":"_price_of_conversions_at_the_buying_stage_",
        "decision":"_conversions_at_the_decision_stage_",
        "decisionCost":"_price_of_conversions_at_the_decision_stage_",
        "interest":"_conversions_at_the_interest_stage_",
        "interestCost":"_price_of_conversions_at_the_interest_stage_",
        "sources": {
            "17": {
                  "clicks":"_clicks_",
                   "spent":"_spent_",
                   "cpc":"_cpc_client_currency_",
"qualityFactor": "_quality_factor_",
                   "buy":"_conversions_at_the_buying_stage_",
                  "buyCost":"_price_of_conversions_at_the_buying_stage_",
                   "decision":"_conversions_at_the_decision_stage_",
                 "decisionCost":"_price_of_conversions_at_the_decision_stage_",
               "interest":"_conversions_at_the_interest_stage_",
                  "interestCost":"_price_of_conversions_at_the_interest_stage_",
            },
            "0": {
                  "clicks":"_clicks_",
                  "spent":"_spent_",
                  "cpc":"_cpc_client_currency_",
"qualityFactor": "_quality_factor_",
                  "buy":"_conversions_at_the_buying_stage_",
                  "buyCost":"_price_of_conversions_at_the_buying_stage_",
                  "decision":"_conversions_at_the_decision_stage_",
                  "decisionCost":"_price_of_conversions_at_the_decision_stage_",
                "interest":"_conversions_at_the_interest_stage_",
                  "interestCost":"_price_of_conversions_at_the_interest_stage_",
            }
        }
     }
  }
}

If there are some errors:

{"errors":["[_error_]"]}

[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST] - widgets with given uid do not exist, if there are valid uid in the list - they will be written to the database

[ERROR_INVALID_OS_TARGETING] - invalid os value has been specified
[ERROR_INVALID_BROWSER_TARGETING] - invalid browser value has been specified
[ERROR_INVALID_COUNTRY_TARGETING] - invalid country value has been specified

{
"id":_campaignId_,
"errors":"[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]",
"data":["1000000","111111"]
}

 

Advertising campaigns detailed daily statistics

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_adcampaign_id_/statistics
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters (required parameters are marked with asterisk *):

Parameters Value
type* Statistics type. Values:  byClicksDetailed
date* Format date: YYYY-MM-DD


Returned values:
If the request is correctly, it returns an array of data in the next format:

{
"id":_ad_campaign_ID_,
"statistics":{
"summary":{
"numberOfClicks":_total_number_of_clicks_,
"numberOfAcceptedClicks":_ enrollment_clicks _,
"fundsEarned":_spent_clicks _,
"numberOfRejectedClicks":_not_couted_clicks_,
"numberOfShows":_total_number_of_shows_
},
"acceptedClicks":[
{
"time":"_click_time_",
"ip":"_ip_address_",
"referer":"_referrer_",
"teaserId":"_id_teaser_",
"informerId":"_site_id__",
"country":"_two_letter_country_code",
"region":"_region_",
"price":"_click_price_" // _click_price_/1000 = USD
},
….
]
}
}

 

Advertising campaigns daily statistics

Method GET
URL api.adskeeper.co.uk/v1/goodhits/clients/{clientId}/campaigns-stat
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters:

Parameter Value
dateInterval

Period for which you need to get statistics. If interval is not specified, returns statistics for 90 days. Valid values are:

  • interval - need to 2 specify additional parameters: startDate and endDate in format yyyy-mm-dd
  • all - all time
  • thisWeek - current week
  • lastWeek - last week
  • thisMonth - current month
  • lastMonth - last month
  • lastSeven - last 7 days
  • today - today
  • yesterday - yesterday
  • last30Days - last 30 days

Answer:

"_campaign_id_":{
"campaign_id":_campaign_id_,
"imps":_imps_,
"clicks":_clicks_,
"spent":_spent_,
"avcpc":_average_cpc_
}

If the customer has conversion settings - additional data transferred:

  • buy - quantity of buying conversions
  • buyCost - cost of buying
  • decision - quantity of decision conversions
  • decisionCost - cost of decision
  • interest - quantity of interest conversions
  • interestCost - cost of interest
  • convertionCost - conversions profit
  • revenue - revenue
  • epc - earn per click
  • profit - revenue - spent

If there are some errors:

{"errors":["[_error_]"]}

[THERE_NO_DATA_IN_CHOSEN_PERIOD] - if there is no data in chosen period

[INVALID_VALUE_FOR_INTERVAL] - invalid value for interval

Advertising campaigns daily statistics for video campaigns

Method GET
URL api.adskeeper.co.uk/v1/goodhits/clients/{clientId}/campaigns-video-stat
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters:

Parameter Value
dateInterval

Period for which you need to get statistics. If interval is not specified, returns statistics for 90 days. Valid values are:

  • interval - need to 2 specify additional parameters: startDate and endDate in format yyyy-mm-dd
  • all - all time
  • thisWeek - current week
  • lastWeek - last week
  • thisMonth - current month
  • lastMonth - last month
  • lastSeven - last 7 days
  • today - today
  • yesterday - yesterday
  • last30Days - last 30 days

Answer:

 "_campaignId_":{
   "campaignId":_campaign_id_,
"impressions":_impressions_,
"viewability":_viewability_,
"first_quartile":_first_quartile_,
"midpoint":_midpoint_,
"third_quartile":_third_quartile_,
"complete":_complete_,
"completion_rate":_completion_rate_,
"clicks":_clicks_,
"ctr":_ctr_,
"spent":_spent_,
"cpm":_cpm_
}

 

If there are some errors:

{"errors":["[_error_]"]}

[THERE_NO_DATA_IN_CHOSEN_PERIOD] - if there is no data in chosen period

[INVALID_VALUE_FOR_INTERVAL] - invalid value for interval

 

Creating a new ad campaign (with all settings)

Method POST
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/campaigns
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters (* - required; ** - required, if parent parameter transferred):

Section 1

Parameters Value
name* Campaign name. Must be unique for the client. 128 symbols max.
enabledGeoTargetingFlag* Flag on/off GeoTargeting
keyword Keyword. Required parameter for search_feed campaigns type 
geoTargets**

List of countries and cities (regions) for targeting. Example:

{'method':'set','cities':['2'],'countries':['ua']}

If both cities and countries are filled, the priority will be given to the 'countries' parameter.

startDate Campaign start date YYYY-MM-DD
language ad campaign language_code
languageTargets Filter by language_code of an ad campaign in include mode. IDs of languages separated by a comma.
campaignType product/content/push/search_feed. If campaign_type didn't transfer campaign_type = product
advertiserName Advertiser name. Field length 1-25 characters
categoryId campaign category ID

Possible errors for this section:

[ADVERTISE_NAME_EXISTS]
[CAMPAIGN_NAME_TOO_LONG]
[ERROR_PARAMETER_ENABLED_GEO_TARGETING_FLAG_CAN_NOT_BE_EMPTY]
[ERROR_PARAMETER_GEO_TARGETS_CAN_NOT_BE_EMPTY]
[ERROR_INVALID_PARAMETER]
[ERROR_WRONG_DATE_FORMAT]
[ERROR_NOT_VALID_CAMPAIGN_TYPE]
[ERROR_PARAMETER_LANGUAGE_TARGETS_VALUE_INVALID]
[ERROR_PARAMETER_LANGUAGE_TARGETS_EMPTY]
[NOT_VALID_WHEN_AUTOSTART] - startDate < today's date

 

Section 2
If at least one of the utm_source, utm_campaign, utm_medium transferred, then all three are required
Parameters Value
utm_source** 0, 9, A Z, a z, _ + & = ][ (up to 200 symbols)
utm_campaign** 0, 9, A Z, a z, _ + & = ][ (up to 200 symbols)
utm_medium** 0, 9, A Z, a z, _ + & = ][ (up to 200 symbols)
utm_custom Macroses: {widget_id}/{teaser_id}/{campaign_id}/{category_id} etc

Possible errors for this section:

[UTM_TAGGING_FIELDS_MUST_NOT_BE_EMPTY]
[UTM_CUSTOM_TOO_LONG_STR]
[WRONG_UTM_CUSTOM_FORMAT]
[UTM_MEDIUM_TOO_LONG_STR]
[UTM_SOURCE_TOO_LONG_STR]
[UTM_CAMPAIGN_TOO_LONG_STR]

 

Section 3
If limitType parameter transferred, then limit type must be specified (day or total)
Parameters Value
limitType

clicks_limits - limit on clicks, budget_limits - limit on budget

dailyLimit**

Setting the limit per day.

For clicks_limits  must be an integer value. Min 500. If a value is empty - campaign has no limits.

For budget_limits  The value of 2 characters after the decimal point (up to hundredths).

overallLimit**

Setting the limit on the campaign in general.

For clicks_limits – must be an integer value and more than a dailyLimit, if specified. If value is empty - campaign has no limits.

For budget_limits value with 2 characters after the decimal point (up to hundredths). Must be more than a dailyLimit, if specified. If value is empty - campaign has no limits.

splitDailyLimitEvenly Option of evenly daily traffic distribution. 0 - on, 1 - off

Possible errors for this section:

[NOT_ENOUGH_PARAMETERS]
[ERROR_NOT_VALID_TYPE]
[ERROR_GREATER_THAN_LIMIT_PER_DAY]
[MINIMAL_DAILY_BUDGET_LIMIT_ERROR]
[WRONG_USE_FLOATING_LIMIT]
[ERROR_SPLIT_DAILY_LIMIT_EVENLY_IS_AVAILABLE_IF_ONLY_DAILY_LIMIT_SET]
[ERROR_MINIMAL_DAILY_CLICKS_LIMIT_IS_ %]
[ERROR_MINIMAL_DAILY_BUDGET_LIMIT_IS_ %]
[ERROR_OVERALL_CLICKS_LIMIT_LESS_THAN_DAILY_LIMIT]
[ERROR_OVERALL_BUDGET_LIMIT_LESS_THAN_DAILY_LIMIT]

 

Section 4

Parameters Value
browserTargets _browser1_, _browser2_, _browser3_
osTargets _os1_,_os2_,_os3_

Possible errors for this section:

"[ERROR_NO_ENOUGH_PARAMETERS]"

Answer returned:

{
     "id":_campaign_id_,
}

 

Creating a new ad campaign

Method POST
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/campaigns
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters (required parameters are marked with asterisk *):

Parameters Values
name* Campaign name. Must be unique for the client
enabledGeoTargetingFlag* Flag on/off GeoTargeting
keyword Keyword. Required parameter for search_feed campaigns type 
geoTargets
List of countries and cities (regions) for
(parameter is required if targeting:
enabledGeoTargetingFlag =1)

{'method':'set','cities':['2'],'countries':['ua']}

If both cities and countries are filled, the priority will be given to the 'countries' parameter.

language ad campaign language_code
languageTargets Filter by language_code of an ad campaign in include mode. IDs of languages separated by a comma.
startDate campaign start date YYYY-MM-DD
campaignType product/content/push/search_feed. If parameter didn't send campaign_type = product
advertiserName Advertiser name. Field length 1-25 characters
categoryId campaign category ID

Answer returned:

{
"id":_campaign_ID_,
}

If there already exists an ad campaign with the name specified in the request, then new campaign will not be created and system return error:

{
"errors":
[ "[ADVERTISE_NAME_EXISTS]" ]
}

 

UTM markup settings for ad campaign

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_campaign_ID_/utmtracking/
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters:

Parameters Value
utm_source Standard setting Google Analytics to track traffic source
utm_campaign Standard setting Google Analytics to track purchases traffic campaign
utm_medium Standard setting Google Analytics to track traffic channel
utm_custom Custom markup. Ability to specify custom settings, which
will be added to the links campaign teaser

Values for Google Analytics (utm_source, utm_campaign, utm_medium) must be given a single query. If you are using one of the this parameters, other are required. Error if one of values is empty: [UTM_TAGGING_FIELDS_MUST_NOT_BE_EMPTY]  
When you specify the default settings Google Analytics also automatically added utm_content and utm_term . In tag utm_content  automatically substituded ID ads.  utm_term=_site_ID_

Utm_custom , should not exceed 200 characters, or system return error:  [UTM_CUSTOM_TOO_LONG_STR]  

Valid characters are: 0 9, A Z, a z,   _ + & = ][ . And macros: {widget_id},  {teaser_id}, {campaign_id}, {category_id}.  

Or system return error:  [WRONG_UTM_CUSTOM_FORMAT]

You can't use system parameters adclid or  adclida - you'll get an error [ERROR_MGCLID_MGCLIDA_SYSTEM_PARAMETERS_CANNOT_USE_THEM]


If you pass an empty field markup is disabled. If the settings are saved successfully, system return campaign ID:

{
"id":_campaign_ID_
}

 

Setting limits on advertising campaign

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/campaigns/_campaign_ID_
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters send in the body of the request (required parameters marked with asterisk *):

Parameters Value
limitType*

clicks_limits - clicks limit

budget_limits - budget limit

dailyLimit

Setting the limit per day.

For clicks_limits  must be an integer value. Min 500. If a value is empty - campaign have no limits.

For budget_limits  The value of 2 characters after the decimal point (up to hundredths).

overallLimit

Setting the limit on the pampaign in general.

For clicks_limits – must be an integer value and more than a dailyLimit, if specified. If value is empty - campaign have no limits.

For budget_limits value with 2 characters after the decimal point (up to hundredths). Must be more than a dailyLimit, if specified. If value is empty - campaign have no limits.

splitDailyLimitEvenly

Option of evenly daily traffic distribution. 0 - on, 1 - off

  • The daily limit can not be less than $10
  • The total limit can not be less than the daily limit
  • Step limit - 1 cent

A system returns  _campaign_ID_ if  all done:

{
"id":_campaign_ID_
}

 

Block / unblock advertising campaign

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/campaigns/_campaign_ ID_
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters send in the body of the request:

Parameters Value
whetherToBlockByClient 0 – unlock ad campaign
1 — lock ad campaign

 

Getting creation date of ad campaign

Method GET
URL api.adskeeper.co.uk/v1/goodhits/clients/_client's_accont_ID_/campaigns/_ad_campaign_ID_?fields=['whenAdd']
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters:

Parameter Value
fields whenAdd

Answer returned:

{
"id":_ad_campaign_ID_,
"whenAdd":_campaigns_creation_date_
}

 

Setting the coefficient of a selective auction of an advertising campaign

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_clientID_/campaigns/_campaignID_
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters send in the body of the request (required parameters marked with asterisk *):

Parameters Values
qualityFactor* Contains a widgetUID and a new quality factor on the site. There can be several pairs in json format: {"_widgetUid1_":_qf1_,"_widgetUid2_s_sourceId2_":_qf2_,"_widgetUid3_":_qf3_}

Answer returned:

{  
"id":_ad_campaign_ID_"
}

Possible errors:

  • ERROR_CAMPAIGN_USES_AUTORETARGETING_CANT_CHANGE_QF- autoretargeting is on
  • ERROR_CAMPAIGN_USES_PRICE_OPTIMIZATION_CANT_CHANGE_QF- autooptimization is on
  • ERROR_CAMPAIGN_IS_DSP_CANT_CHANGE_QF- DSP campaign
  • ERROR_QUALITY_FACTOR_INVALID_FORMAT - wrong data format in parameter qualityFactor
  • ERROR_WIDGETUID_INVALID_FORMAT - wrong data format in parameter _widgetUid2_or _widgetUid2_s_sourceId2_

 

Setting the coefficient of a selective auction to all sub-sources

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_clientID_/campaigns/_campaignID_
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters send in the body of the request (required parameters marked with asterisk *):

Parameters Values
widgetQualityFactor* It contains a widgetUID and a new quality factor. Applies a source value to all its sub-sources. There can be several pairs in json format: {"_widgetUid1_":_qf1_,"_widgetUid2_":_qf2_,"_widgetUid3_":_qf3_}

Answer returned:

{  
"id":_ad_campaign_ID_"
}

Possible errors:

  • ERROR_CAMPAIGN_USES_AUTORETARGETING_CANT_CHANGE_QF- autoretargeting is on
  • ERROR_CAMPAIGN_USES_PRICE_OPTIMIZATION_CANT_CHANGE_QF- autooptimization is on
  • ERROR_CAMPAIGN_IS_DSP_CANT_CHANGE_QF- DSP campaign
  • ERROR_WIDGET_QUALITY_FACTOR_INVALID_FORMAT - wrong data format in parameter widgetQualityFactor
  • ERROR_WIDGETUID_INVALID_FORMAT - wrong data format in parameter _widgetUid2_

 

Retrieving conversion settings for an advertising campaign

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_campaign_ID_/conversions
Headers

Accept: application/json

Authorization: Bearer {token}

The response comes with an array of conversion settings for an advertising campaign.

The array can be:

  • empty (there are no settings)
  • with three elements (all conversion stages with settings)
  • from one to three elements (only a part of the stages is configured)

Each element will contain the following information:

  • stage - name of the conversion stage
  • target_id - The ID of an existing target that is associated with the specified stage.
  • type - type of conversion. The options are: 'url', 'event', 'visited', 'regexp' and 'postback'.
  • conditions - conversion trigger settings.
  • conditions.[i].type - type of trigger condition. The options are 'contain', 'starts', 'ends', 'visited', 'regexp' and 'postback'.
  • conditions.[i].value - value of trigger condition.
  • price - cost per conversion in the client's currency. Either the price will be a number, or 0 if no price is specified.

Response:

[
{
"stage": _stage_,
"target_id": _target_id_,
"type": _target_type_,
"conditions": [
{
"type": _confition_type1_,
"value": _condition_value1_
},
{
"type": _confition_type2_,
"value": _condition_value2_
}
],
"price": _price_of_conversion_
},
...
]

Response with buy stage:

[
{
"stage": "buy",
"target_id": 59041,
"type": "url",
"conditions": [
{
"type": "contain",
"value": "thankyou.php"
}
],
"price": 123.123457
}
]

 

Editing conversion settings for an advertising campaign

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_campaign_ID_/conversions
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters send in the GET parameters:

Параметр Значение
buy settings for stage buy
decision settings for stage decision
interest settings for stage interest

Value format: _target_id_,_price_

  • _target_id_ - ID of an existing target
  • _price_ - cost per conversion in the client's currency. Either a number or null.

Passing an empty array implies deleting the settings.

Response:

{
"id":_campaign_id_
}

Possible errors:

[ERROR_NOT_VALID_CAMPAIGN_ID] - invalid campaign ID (zero or invalid ID)
[ERROR_CAMPAIGN_DOES_NOT_EXIST] - the campaign with this ID does not exist or belongs to another client
[ERROR_CAMPAIGN_HAS_ANOTHER_CONVERSIONS_DATA_SOURCE] - the campaign has a different source of conversions (GA, YM, or GTM)
[TARGET_ID_EMPTY] - target ID not passed
[CONVERSION_TARGET_UNIQUE_ERROR] - the same goal is used in several stages
[TARGET_ID_INVALID] - non-existent goal or purpose of another client

 

Removing campaign to trash

Only stopped ad campaigns can be removed.

Method DELETE
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID/campaigns/_ad_campaign_ID_
Headers

Accept: application/json

Authorization: Bearer {token}

Answer returned:

{
"id":_campaign_id_
}

Possible errors:

[ERROR_CAMPAIGN_DOES_NOT_EXIST] - Invalid campaign id 
[ERROR_CAMPAIGN_DOES_NOT_EXIST] - Campaign does not belong to the client
[WRONG_CAMPAIGN_ID] - Campaign type video

 

Advertising campaigns targeting settings

 

Setting up the geo targeting of advertising campaigns

Getting geotargeting settings ad campaign of client:

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_campaign_ID_/targetings/geo
Headers

Accept: application/json

Authorization: Bearer {token}

Answer returned:

{
"targets":  {
"actual":{
"countries":{
"_country_code_":{
"code":"_ country_code _",
 "name":"_country_name_",
 "cities":[
"_city_ID_":{
"id":_ city_ID _,
 "name":"_name_of_city",
 "normalizedName":"_ Latin_letters_name _"   
},
.......
]
} ......
}
},
"requested":{
"countries":{
"_country_code_":{
"code":"_country_code_",
  "name":"_country_name_",
  "cities":[
"_city_ID_":{
"id":_ city_ID _,
  "name":"_ name_of_city_",
  "normalizedName":"_ Latin_letters_name_"
},
.......
]
}
}
}
}
}

Section "actual"  contains the current geotargeting.  Section "request"  updated geotargeting settings that will be applied (or in the near future, or from the following day). If geotargeting settings are not used, it returns an answer like:

{
"targets":{
"actual":{
"countries":[

]
},
"requested":{
"countries":[

]
}
}
}

 

Getting a list of available countries for setting up geo targeting

Method GET
URL api.adskeeper.co.uk/v1/dictionaries/geo
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters (required parameters marked with asterisk *)::

Parameter Value
type* countries

Returns an array of countries that can be used for setting geotargeting:

[
{
"code":"_ two_letter_country_code _",
"name":"_country_name_"
},
.....
]

 

Getting a list of available regions (cities) for geo targeting settings

Method GET
URL api.adskeeper.co.uk/v1/dictionaries/geo
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters (required parameters marked with asterisk *)::

Parameters Value Comments
type* cities  
countries* ['_ two_letter_country_code _', ....] An array of country codes for which you need to get a cities (regions) list.


Returns an array of regions (cities) that can be used for geo targeting:

[
{
"id":_city_ID_,
"name":"_city_name_",
"normalizedName":"_ name of city_Latin_Letters _",
"countryCode":"_ two_letter_country_code _"
},
......
]

 

Editing geo targeting settings for advertising campaign

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_campain_ID_/targetings/geo
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters (required parameters marked with asterisk *)::

Parameter Value
targets* The list of countries and cities (regions) for targeting:
{ 'method':'set', 'cities': [ _city_ID_, . . . . . ], 'countries': [ two_letter_country_code _,  . . . . . . ] }If filled cities and countries in the priority will be countries parameter.
enabledFlag* Flag on/off geo targeting(1/0)


If the request is correct, will be returned  ID edited ad campaign:

{
 "id":_campaign_ID_
}

If you do not specify any parameters or configured incorrectly, the changes  
settings will not be saved and will return an error message:

{
"errors":[
"[ERROR_NO_ENOUGH_PARAMETERS]"
]
}

 

Editing advertising campaign browser targeting

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_ad_campaign_ID_/targetings/browsers
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters (required parameters marked with asterisk *)::

Parameter Value
targets* _ editing_method_ , _ browser_,_ browser_.....
enabledFlag* 0 – target off, 1 — target on

Possible values for the  _editing_method_ :
include- inclusion of a browser in the list for targeting

Possible values for _browser_ :

Name Value
Other others
Google Chrome chrome
Safari safari
Opera Mini operamini
Opera Mobile operamobile
Opera opera
Firefox firefox
MSIE msie
Facebook facebook
WebView webview
Yandex Browser yandex
Microsoft Edge edge
UC Browser ucbrowser
Pinterest App pinterest
Mobile Samsung Brows mobilesamsungbrowser
Google Search App googlesearchapp
TopBuzz App topbuzzapp
ViVo Browser vivobrowser
Phoenix Browser phoenixbrowser
 

Upon successful saving settings system returns campaign ID:

{
"id":_campaign_ID_
}

 

Editing advertising campaign IP targeting   

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/campaigns/_ad_campain_ID_
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters send in the body of the request (required parameters marked with asterisk *):

Parameter Value
ipsFilter* _ editing_methods _ , _filter_type_, IP1,IP2....


Settings:

  • Editing methods:
    • include include an address in the list
    • exclude remove an address from the list
  • Filter type :
    • except  
    • only
    • off – filter off

IP can be specified as single or as subnets (192.168.0.1/24)

Upon successful saving settings system returns campaign ID:

{
"id":_campaign_ID_
}

 

Editing advertising campaign operating system targeting

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_ad_campaign_ID_/targetings/operatingsystems
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters:

Parameter Value
enabledFlag on/off OS targeting,  on=1, off=0
targets _editing_method_,_os_code1_,_os_code2_,_os_code3_

Operating systems:  

 
id name version code
8 Windows OS Other windowsos
9 Mac OS Other macos
10 Other Desktop OS otherdesctop  
11 Android 2.2 and lower android22mobile
12 Android 02.мар android23mobile
13 Android 3.хх android3mobile
14 Android 4.0 android40mobile
15 Android 04.янв android41mobile
16 Android 04.фев android42mobile
17 Android 04.мар android43mobile
18 Android 04.апр android44mobile
19 iOS 4.хх and lower ios4mobile
20 iOS 5.хх ios5mobile
21 iOS 6.хх ios6mobile
22 iOS 7.хх ios7mobile
23 iOS 8.хх ios8mobile
24 Other Mobile OS othermobile  
25 Android 2.2 and lower android22tablet
26 Android 02.мар android23tablet
27 Android 3.хх android3tablet
28 Android 4.0 android40tablet
29 Android 04.янв android41tablet
30 Android 04.фев android42tablet
31 Android 04.мар android43tablet
32 Android 04.апр android44tablet
33 iOS 4.хх and lower ios4tablet
34 iOS 5.хх ios5tablet
35 iOS 6.хх ios6tablet
36 iOS 7.хх ios7tablet
37 iOS 8.хх ios8tablet
38 Other Tablet OS othertablet  
39 Android 5.xx android50mobile
40 Android 5.xx android50tablet
41 iOS 9.хх ios9tablet
42 iOS 9.хх ios9mobile
43 Android 6.xx android60mobile
44 Android 6.xx android60tablet
45 iOS 10.хх ios10mobile
46 iOS 10.хх ios70tablet
47 Android 7.xx android70tablet
48 Android 7.xx android70mobile
50 iOS 11.xx ios11mobile
51 iOS 11.xx ios11tablet
53 Android 8.xx android80mobile
54 Android 8.xx android80tablet
55 Android 9.xx android90mobile
56 Android 9.xx android90tablet
57 iOS 12.xx ios12mobile
58 iOS 12.xx ios12tablet
59 Android 10.хх android10mobile
60 Android 10.хх android10tablet
61 iOS 13.хх ios13mobile
62 iOS 13.хх ios13tablet
63 Windows OS 10 windowsos10
64 Windows OS 08.янв windowsos81
65 Windows OS 8 windowsos8
66 Windows OS 7 windowsos7
67 Windows OS Vista windowsosvista
68 Windows OS XP windowsosxp
69 Mac OS 10.12 Sierra macos1012
70 Mac OS 10.13 High Sierra macos1013
71 Mac OS 10.14 Mojave macos1014
72 Mac OS 10.15 Catalina macos1015
73 Other Smart TV othersmarttv  
74 Android androidsmarttv  
75 Fire OS (Amazon) fireossmarttv  
76 tvOS (Apple TV) tvossmarttv  
77 Tizen tizenossmarttv  
78 webOS webossmarttv  
79 Android 11.xx android11mobile
80 Android 11.xx android11tablet
81 iOS 14.хх ios14mobile
82 iOS 14.хх ios14tablet
83 Mac OS 11 Big Sur macos110
84 RocuOS rocuossmarttv  
85 Android 12.хх android12mobile
86 Android 12.хх android12tablet
87 Mac OS 12 Monterey macos120
89 iOS 15.xx ios15mobile
90 Windows OS 11 windowsos11
92 iOS 16.xx ios16mobile
93 Android 13.хх android13mobile
94 Android 13.хх android13tablet
95 iPadOS 15.xx ipados15tablet
96 iPadOS 16.xx ipados16tablet
97 Mac OS 13 Ventura  macos130
98 iOS 17.xx ios17mobile
99 iOS 17.xx ipados17tablet
100 Android 14.xx android14mobile
101 Android 14.xx android14tablet
102 Mac OS 14 Sonoma  macos140

Editing methods :
include - add OS to the list
exclude - remove OS from the list
Upon successful saving settings system returns campaign ID:

{
"id":_campaign_ID_
}

Getting advertising campaign operating system targeting settings

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/id_campaign/targetings/operatingsystems
Headers

Accept: application/json

Authorization: Bearer {token}

On success - returns the list of operating systems included:

{
  "targets": [
    "windowsos", 
    "macos",
    "otherdesctop",
    "android22tablet"
  ]
}

Possible errors:

Advertising campaign id doesn't exist or the token of the wrong user used:

{
    "errors": [
        "[ERROR_CAMPAIGN_DOES_NOT_EXIST]"
    ]
}

Empty token:

{
    "errors": "Authentication token is missing"
}

 

Editing the filter settings on the sites for advertising campaign by UID

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/campaigns/_ad_campaign_ID_
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters send in the body of the request:

Parameter Value
widgetsFilterUid

editing_method, filter_type, uid1,uid2…

you can send sub-source parameters in brackets filter_type, uid1(subid subid sibid),uid2… or through "s" filter_type, UID1sSUBID1...

block-widget-priority

For the edit method include, when it receives a request to add sub_id, it checks whether the source is added to the filter, if added, then the record of the source is ignored. Thus, using this parameter, you can slightly change the query processing logic.

Request example:

api.adskeeper.co.uk/v1/goodhits/clients/{client id}/campaigns/{campaign id}?widgetsFilterUid=include, only, {uid id}s{subid id}&block-widget-priority

Editing methods:

  • include - include in list
  • exclude - exclude from the list

Filter types:

  • only
  • except
  • off


On success - returns the identifier of editable ad campaign

{"id":_ad_campaign_ID_}

Example response with errors in the data - sites not transferred:

{"errors":["[WIDGETS_IDS_CANNOT_BE_EMPTY]"]}

Example response with errors in the data - non-existing sites id transferred:

{"errors":["[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]"],"data":["1000000001000"]}

Example response with errors in the data - filter parameters not transferred(include|exclude,off|only|except) or transferred in wrong way:

{"errors":["[ERROR_NOT_VALID_FILTER_TYPE]"]}

If transfered valid & non-valid IDs ("widgetsFilter": "include, only, ttttts1, 5676301111, 5676672rrr, eeeeee") - valid IDs will be written in database, for non-valid will be the answer with a list of non-valid IDs:

{"id":_ad_campaign_ID_, "errors":"[WIDGETS_WITH_THESE_IDS_DO_NOT_EXIST]","data":["ttttts1","5676672rrr","eeeeee"]}

When sites not passed - it's a non-valid situation.

Editing browser language targeting

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_ad_campaign_ID/targetings/browserslanguage
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters send in the parameters of the request:

Parameter Value
targets* _ editing_method_ , _ browser_lang_id_,_ browser_lang_id_.....
enabledFlag* Enable / disable targeting. 0 – target off, 1 — target on

Request example:

api.adskeeper.co.uk/v1/goodhits/campaigns/{campaign id}/targetings/browserslanguage?enabledFlag=1&targets=include,3,7

Editing methods:

  • include - include in list

On success - returns the identifier of editable ad campaign:

{"id":_ad_campaign_ID_}

Possible errors:

[ERROR_CAMPAIGN_DOES_NOT_EXIST] - campaign or owner ids not exists or does not match the authorized one
[ERROR_NO_ENOUGH_PARAMETERS] - one of the parameters was not passed, the value of passed languages ids are incorrect, the value is not "include"
[ERROR_INVALID_PARAMETER] - the value is not "include"

Getting browser language targeting settings

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/_ad_campaign_ID/targetings/browserslanguage
Headers

Accept: application/json

Authorization: Bearer {token}

Request example:

api.adskeeper.co.uk/v1/goodhits/campaigns/{campaign id}/targetings/browserslanguage

On success - returns the list of languages id:

{
"targets": [
34,
49,
65
]
}

Possible errors:

[ERROR_CAMPAIGN_DOES_NOT_EXIST] - campaign or owner ids not exists or does not match the authorized one

 

Getting browser targeting settings

 

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/campaign_id/targetings/browsers
Headers

Accept: application/json

Authorization: Bearer {token}

Request example:

api.adskeeper.co.uk/v1/goodhits/campaigns/{campaign id}/targetings/browsers

On success - returns the list of browsers values:

{
  "targets": [
    "chrome",
    "operamobile",
    "firefox"
  ]
}

Possible errors:

[ERROR_CAMPAIGN_DOES_NOT_EXIST] - campaign or owner ids not exists or does not match the authorized one

Editing phone price range targeting

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/campaigns/campaign_id/targetings/phonePriceRange
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters send in the parameters of the request:

Parameter Value
targets* _ editing_method_ , _range_id_1_, _range_id_2_... Phone price ranges list
enabledFlag* Enable / disable targeting. 0 – target off, 1 — target on

Request example:

api.adskeeper.co.uk/v1/goodhits/campaigns/{campaign id}/targetings/phonePriceRange?enabledFlag=1&targets=include,3,4,5

Editing methods:

  • include - ranges you want to include in targeting
  • exclude - ranges you don't want to target to

 

Phone price ranges list:

id Price range
1 Up to 150$
2 From 150$ to 200$
3 From 200$ to 250$
4 From 250$ to 300$
5 From 300$ to 350$
6 From 350$ to 400$
7 From 400$ to 500$
8 From 500$ to 600$
9 From 600$ to 700$
10 From 700$ and more

On success - returns the identifier of editable ad campaign:

{"id":_ad_campaign_ID_}

Possible errors:

[ERROR_CAMPAIGN_DOES_NOT_EXIST] - campaign or owner ids not exists or does not match the authorized one
[ERROR_NO_ENOUGH_PARAMETERS] - one of the parameters was not passed, the value of passed phone price range ids are incorrect, the value is not "include" or "exclude"
[ERROR_INVALID_PARAMETER] - the value is not "include" or "exclude"

 

Getting phone price range targeting

Method GET
URL api.adskeeper.co.uk/v1/goodhits/campaigns/campaign_id/targetings/phonePriceRange
Headers

Accept: application/json

Authorization: Bearer {token}

 

Request example:

api.adskeeper.co.uk/v1/goodhits/campaigns/{campaign id}/targetings/phonePriceRange

On success - returns the list of price range ids:

{
  "targets": [
  1,
  2,
  3
  ]
}

Possible errors:

[ERROR_CAMPAIGN_DOES_NOT_EXIST] - campaign or owner ids not exists or does not match the authorized one

 

Working with client's teasers

 

Constants and identifiers in use

Currency code to display the price of the product:

id combname name_utf
1 rub руб
4 uah грн
5 usd $
6 eur
9 byn руб
12 inr
23 ils
35 gel
38 kzt
43 aed د.إ
46 inr


Teaser status:

Status Description
onModeration Teaser on moderation
rejected Teaser is rejected
active Teaser is active
new New teaser, don't have CTR yet
goodPerformance Teaser is in shows
badPerformance Teaser have no shows in one or more regions because have low rating. It is necessary to set a higher price per click or replace the teaser on the other, which could provide a higher CTR
blocked Blocked teaser
campaignBlocked Blocked campaign

 

Getting a list of client teasers

Method GET
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/teasers[/_teaser_ID_]
Headers

Accept: application/json

Authorization: Bearer {token}


If _teaser_ID_ is not passed, then method returns a list of client teasers. If _teaser_ID_ is passed, then method returns information about current teaser.

Transferred parameters (required parameters are marked with asterisk *):

Parameters Value
fields
(optional, use if passed _teaser_ID_)
Array of teaser properties, information
about which  necessary to obtain(for example:
fields=['title','url','statistics']).  If the parameter is not passed, then returns  all  Properties.
status Takes values from the table "Teaser statuses"; You can specify several statuses simultaneously (for example: status = ['active', 'onModeration']) to get all teasers with these statuses.
campaign Getting a list of client's teasers by campaign ID
limit limiting the number of teasers displayed on the page. If doesn't set - shows all teasers. Possible error when using the option limit: ["[ERROR_MAX_LIMIT_PER_PAGE_{max_allowed_limit}]"]
start sets the position of the element. Default - 0. For example: at the first request start = 0 limit = 700, the next request will be: start = 700 limit = 700. 

Answer returned:

{  
"_teaser_ID_":
        {
         "id":"_teaser_ID_",
         "title":"_teaser_titel_",
         "advertText":"_advertising text teaser_",
        "url":"_ advertising_link_",
         "imageLink":"_link_to_teaser_image_",
         "cropLeft":"_cropping_the_image_on_the_left _",
         "cropTop":"_cropping_the_image_on_top _",
         "cropWidth":"_width_of_cropping_part_",
        "priceOfClickByLocations":                
                [{"locationId":"_geo_group_id_",
                "locationName":"_geo_group_name_",
                "priceOfClick":"_price_of_click_by_geo_group_"},...]

         "goodPrice":_product_price_,
         "goodOldPrice":_ old_product_price _,
         "currency":_ currency_ID_to_display_the_price_of_product_,
         "category":
                 {
                "id":"_category_ID_", "name":"_category_name_"
                },
         "campaignId":_campaign_ID_,
         "status":"_teaser_status_",
"reason_if_drop_karantin": _reason_rejection_ (displayed if teaser a rejected),
         "statistics":
                 {
                 "clicks":_total_clicks_,
                 "clicks_today": _today_clicks_,
                 "clicks_yesterday": _yesterday_clicks_,  
                 "hits":_total_shows_,
                 "hits_today": _today_shows_,
                 "hits_yesterday": _yesterday_shows_,  
"spent":_spent_all_,
"spent_today":_spent_today_,
"spent_yesterday":_spent_yesterday_,
                 "ctr":"_teaser_CTR_",

    "ctr_by_locations":          
                [{"locationId":"_geo_group_id_",
                "locationName":"_geo_group_name_",
                "ctr":"_ctr_by_geo_group_"},...]

           },

         "conversion":
                {
                "interest_all": _number_of_achievements_interest_stage_ for_all_time_,
                "decision_all":  _number_of_achievements_decision_stage_ for_all_time_,
                "buying_all":  _number_of_achievements_buying_stage_ for_all_time_,
                "interest_yesterday": _number_of_achievements_interest_stage_ for_yesterday_,
                "decision_yesterday": _number_of_achievements_decision_stage_ for_yesterday_,
                "buying_yesterday": _number_of_achievements_buying_stage_ for_yesterday_

         }
        },
"_teaser_ID_2_":
{ . . . . . . },
. . . . . . . . . }

 

Teaser detailed daily statistics

Method GET
URL api.adskeeper.co.uk/v1/goodhits/clients/{authId}/teaser-stat/{teaserId}?dateInterval={interval}
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters (required parameters are marked with asterisk *):

Parameters Value
uid returns teaser statistics for specified widget uid
dateInterval

Period for which you need to get statistics. If interval is not specified, returns statistics for 30 days. Valid values are:

  • interval - need to 2 specify additional parameters: startDate and endDate in format yyyy-mm-dd
  • all - last 90 days
  • thisWeek - current week
  • lastWeek - last week
  • thisMonth - current month
  • lastMonth - last month
  • lastSeven - last 7 days
  • today - today
  • yesterday - yesterday
  • last30Days - last 30 days

Answer returned:

{
"dateInterval": "2021-01-11 - 2021-01-12",
"timezone": "Asia\/Ho_Chi_Minh",
"currency": "usd",
"status": "active",
"teaser-stat": {
"2021-01-11": {
"date": "2021-01-11",
"clicks": 47,
"shows": 33289,
"ctr": 0.141188,
"spent": 0.157888,
"cpc": 0.335932,
"interest": 0,
"decision": 0,
"buy": 11,
"interestCost": 0,
"decisionCost": 0,
"buyCost": 0.014353
},
"2021-01-12": {
"date": "2021-01-12",
"clicks": 263,
"shows": 123850,
"ctr": 0.212354,
"spent": 0.389839,
"cpc": 0.148228,
"interest": 0,
"decision": 0,
"buy": 14,
"interestCost": 0,
"decisionCost": 0,
"buyCost": 0.027846
}
}
}

If there are some errors:

{"errors":["[_error_]"]}

[THERE_NO_DATA_IN_CHOSEN_PERIOD] - if there is no data in chosen period

[INVALID_VALUE_FOR_INTERVAL] - invalid value for interval

[TEASER_DOES_NOT_EXIST] - teaser not exists

 

Creating a new teaser for ad campaign

Method POST
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/teasers
Headers

Accept: application/json

Authorization: Bearer {token}


Transfered parameters (required parameters are marked with asterisk * must be transferred in POST method body)

Parameters Value
url* URL advertising links. It's recommended to use %26 instead of & during parameters transmission
campaignId* Campaign ID to which is teaser added
title*

Teaser title

  • for content/product campaign type - up to 65 characters
  • for push campaign type - up to 30 characters
advertText

Advertising text. If this parameter is passed in the request, the validation will be as follows:

  • for content/product campaign type - up to 75 characters (optional)
  • for push campaign type - up to 40 characters (required)

If the parameter has not been passed, it will not be changed.

imageLink*

Link to teaser image.

  • Minimum size 492x328 pixels.
  • Recommended size 600x382 pixels and larger.
  • Available formats: .jpg/.jpeg/.png and .gif/.mp4/.mov.
categoryId*

Teaser category ID. This parameter must be passed for campaign types Content and Push only

priceOfClick* Price per click, cents, with tenths. As a separator
between the whole number and the fraction can use a comma or period.
whetherShowGoodPrice*

Flag display the price of goods (1/0)

If whetherShowGoodPrice = 1 parameters currency, goodPrice, goodOldPrice are required. If whetherShowGoodPrice = 0 then the following parameters will be ignored.

    currency Currency ID to display the price of the product
    goodPrice Price of the goods in a specified currency
    goodOldPrice Old price of the goods.

 

Categories list:

 
id name campaign types
100 Automotive product, video, offer, push, search_feed
101 Books and Literature product, video, offer, push, search_feed
103 Events product, video, offer, push, search_feed
105 Casinos and Gambling product, video, offer, push, search_feed
107 Marriage and Civil Unions product, video, offer, push, search_feed
108 Dating product, video, offer, push, search_feed
109 Pick up product, video, offer, push, search_feed
111 World Cuisines product, video, offer, push, search_feed
112 Alcoholic Beverages product, video, offer, push, search_feed
114 Nutrition product, video, offer, push, search_feed
115 Weight Loss product, video, offer, push, search_feed
116 Women's Health product, video, offer, push, search_feed
117 Children's Health product, video, offer, push, search_feed
118 Fitness and Exercise product, video, offer, push, search_feed
120 Alternative Medicine product, video, offer, push, search_feed
121 Smoking Cessation product, video, offer, push, search_feed
122 Muscle Building product, video, offer, push, search_feed
123 Brain Booster product, video, offer, push, search_feed
126 Home Security product, video, offer, push, search_feed
127 Home Improvement product, video, offer, push, search_feed
128 Gardening product, video, offer, push, search_feed
131 Sleep Disorders product, video, offer, push, search_feed
132 Diabetes product, video, offer, push, search_feed
133 Varicosis product, video, offer, push, search_feed
134 Bone and Joint Conditions product, video, offer, push, search_feed
135 Eye and Vision Conditions product, video, offer, push, search_feed
136 Psoriasis product, video, offer, push, search_feed
137 Papilloma product, video, offer, push, search_feed
138 Skin and Dermatology product, video, offer, push, search_feed
139 Medical Services product, video, offer, push, search_feed
141 Foot Health product, video, offer, push, search_feed
143 Hemorrhoid product, video, offer, push, search_feed
144 Prostatitis product, video, offer, push, search_feed
145 Sexual Health product, video, offer, push, search_feed
148 Stocks and Bonds product, video, offer, push, search_feed
149 Options product, video, offer, push, search_feed
150 Insurance product, video, offer, push, search_feed
151 Personal Debt product, video, offer, push, search_feed
152 Financial Assistance product, video, offer, push, search_feed
153 Retirement Planning product, video, offer, push, search_feed
154 Real Estate product, video, offer, push, search_feed
156 For Kids product, video, offer, push, search_feed
157 Gifts and Souvenirs product, video, offer, push, search_feed
159 Couponing product, video, offer, push, search_feed
161 Sporting Goods product, video, offer, push, search_feed
162 Fishing Sports product, video, offer, push, search_feed
165 Makeup and Accessories product, video, offer, push, search_feed
166 Natural and Organic Beauty product, video, offer, push, search_feed
167 Skin Care product, video, offer, push, search_feed
168 Hair Care product, video, offer, push, search_feed
169 Perfume and Fragrance product, video, offer, push, search_feed
170 Other Beauty Products product, video, offer, push, search_feed
172 Oral Care product, video, offer, push, search_feed
173 Shaving product, video, offer, push, search_feed
176 Women's Intimates and Sleepwear product, video, offer, push, search_feed
177 Women's Outfits product, video, offer, push, search_feed
179 Women's Jewelry and Watches product, video, offer, push, search_feed
180 Other Women's Accessories product, video, offer, push, search_feed
181 Women's Shoes and Footwear product, video, offer, push, search_feed
184 Men's Underwear and Sleepwear product, video, offer, push, search_feed
185 Men's Outfits product, video, offer, push, search_feed
187 Men's Jewelry and Watches product, video, offer, push, search_feed
188 Other Men's Accesories product, video, offer, push, search_feed
189 Men's Shoes and Footwear product, video, offer, push, search_feed
190 Children's Clothing product, video, offer, push, search_feed
193 Laptops product, video, offer, push, search_feed
194 Desktops product, video, offer, push, search_feed
195 Computer Peripherals product, video, offer, push, search_feed
196 Computer Software and Applications product, video, offer, push, search_feed
198 Smartphones product, video, offer, push, search_feed
199 Tablets and E-readers product, video, offer, push, search_feed
200 Cameras and Camcorders product, video, offer, push, search_feed
201 Wearable Technology product, video, offer, push, search_feed
202 Energysavers product, video, offer, push, search_feed
203 Self Defense product, video, offer, push, search_feed
204 Solar Panels product, video, offer, push, search_feed
205 Other Electronics product, video, offer, push, search_feed
206 Travel product, video, offer, push, search_feed
207 Video Gaming product, video, offer, push, search_feed
208 Automotive content
209 Business and Finance content, push
211 Education content, push
212 Events and Attractions content
213 Family and Relationships content
219 Cooking content
220 Alcoholic Beverages content
221 Healthy Living content
225 Hobbies and Interests content, push
229 Home and Garden content
230 Movies content, push
232 News and Politics content, push
237 News Ukraine content, push
238 Pets content
239 Pop Culture content, push
241 Science content, push
242 Sports content
243 Style and Fashion content
247 Technology and Computing content
249 Travel content
251 Pets product, offer, push, search_feed
252 Ear, Nose and Throat Conditions product, push, search_feed
254 Currencies product, offer, push, search_feed
258 Lottery product, video, offer, push, search_feed
260 Content Media Format product, push, search_feed
261 Other services product, push, search_feed
262 Charity Funds product, push, search_feed
263 Business Services product, push, search_feed
264 Education product, push, search_feed
265 Legal Services Industry product, push, search_feed
266 Language Learning product, push, search_feed
267 Delivery product, push, search_feed
268 Mobile Services product, push, search_feed
270 Blood Disorders product, push, search_feed
271 Digestive Disorders product, push, search_feed
272 Endocrine and Metabolic Diseases product, push, search_feed
278 Business I.T. product, push, search_feed
280 Infectious Diseases product, push, search_feed
281 Cancer product, push, search_feed
282 Contests and Competitions product, video, offer, push, search_feed
 

Answer returned:
Upon successful creation of the teaser response is returned:

{
"id":_new_teaser_ID_,
}

Returns an error name  if creating teaser attempt was a failure:

{"errors":["[_ error_name_ _]"] }

If a teaser has an irrelevant link format, the system returns an error:

{"errors":["[LS_IMAGE_WRONG_EXTANTION]"]}

If the teaser has a size less than the minimum, return an error (where X or Y - an irrelevant size for width or height)

"errors": [
"Minimum expected width for image '' should be '492' but 'X' detected,Minimum expected height for image
'' should be '328' but 'Y' detected"]

The list of possible errors returned in the creation and editing teaser of the campaign:

_ERROR_NAME_ specification
ERROR_PARAMETER_WHETHERSHO WGOODPRICE_CAN_NOT_BE_EMPTY Not passed a required parameter whetherShowGoodPrice
ERROR_PARAMETER_PRICEOFCLICK_ CAN_NOT_BE_EMPTY Not passed a required parameter priceOfClick
ERROR_PARAMETER_CATEGORY_CA N_NOT_BE_EMPTY Not passed a required parameter category
ERROR_ADVERT_TEXT_TOO_LONG Advertising text (parameter advertText) exceeds the maximum allowed length (no more than 75 characters)
ERROR_PARAMETER_TITLE_CAN_NO T_BE_EMPTY Not Transfered teaser title (required parameter title)
ERROR_TITLE_TOO_LONG Title teaser (parameter title) exceeds the maximum allowed length (no more than 65 characters)
ERROR_PARAMETER_IMAGELINK_CA N_NOT_BE_EMPTY Not assigned image link for the teaser (required parameter imageLink)
ERROR_PARAMETER_CAMPAIGNID_CA N NOT_BE_EMPTY Not transmitted campaign ID that creates teaser (required parameter campaignId)
ERROR_PARAMETER_URL_CAN_NOT_BE _EMPTY Not assigned to an advertising link to the teaser (required parameter url)
[ERROR_PARAMETER_CATEGORY_INCORRECT_FOR_THIS_CAMPAIGN_TYPE] Improperly selected category for this type of campaign
[ERROR_PARAMETER_POST_SEND] You must use method POST in this request
[ERROR_MGCLID_MGCLIDA_SYSTEM_PARAMETERS_CANNOT_USE_THEM] Cannot use adclid or adclida
[ONE_OR_MORE_REGIONS_HAVE_PRICE_HIGHER_THAN_ACCEPTABLE_PRICE] No valid CPC

 

Editing ad campaign teaser settings

Method PUT
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID_
Headers

Accept: application/json

Authorization: Bearer {token}


Transfered parameters (required parameters are marked with asterisk *):

Parameters Value
url* URL advertising links
campaignId* Campaign ID to which is teaser added
title*

Teaser title

  • for content/product campaign type - up to 65 characters
  • for push campaign type - up to 30 characters
advertText*

Advertising text. If this parameter is passed in the request, the validation will be as follows:

  • for content/product campaign type - up to 75 characters (optional)
  • for push campaign type - up to 40 characters (required)

If the parameter has not been passed, it will not be changed.

imageLink*

Link to teaser image.

  • Minimum size 492x328 pixels.
  • Recommended size 600x382 pixels and larger.
  • Available formats: .jpg/.jpeg/.png and .gif/.mp4/.mov.
category*

Teaser category ID. This parameter must be passed for campaign types Content and Push only

whetherShowGoodPrice*

Flag display the price of goods (1/0)

If whetherShowGoodPrice = 1 parameters currency, goodPrice, goodOldPrice are required. If whetherShowGoodPrice = 0 then the following parameters will be ignored.

    currency Currency ID to display the price of the product
    goodPrice Price of the goods in a specified currency
    goodOldPrice Old price of the goods.

If any of the required parameters weren't passed, system returns error.

For example, not transmitted campaignId :

 {"errors":["[ERROR_PARAMETER_CAMPAIGNID_CAN_NOT_BE_EMPTY]"]}

If teaser on moderation, return error.

{"errors":["[ERROR_EDITING_TEASER_ON_MODERATION_NOT_PERMITTED]"]}
Cannot use adclid or adclida
{"errors":["[ERROR_MGCLID_MGCLIDA_SYSTEM_PARAMETERS_CANNOT_USE_THEM]"]}

If a teaser has an irrelevant link format, the system returns an error:

{"errors":["[LS_IMAGE_WRONG_EXTANTION]"]}
If the teaser has a size less than the minimum, return an error (where X or Y - an irrelevant size for width or height)
"errors": [
"Minimum expected width for image '' should be '492' but 'X' detected,Minimum expected height for image
'' should be '328' but 'Y' detected"]

 

Changing advertising campaign teaser's CPC

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID_
Headers

Accept: application/json

Authorization: Bearer {token}

Transferred parameters send in the body of the request:

Parameter Value
priceOfClick Installed CPC in tenth of cents for all geo groups. Can be used a period or comma as a delimiter.
 

Answer returned.
If all done correctly, system return an answer:

{ 
"id":_teaser_ID_,
}

Some errors:
● if the parameter CPCs not specified or incorrect:

{"errors":["[EDIT_PRICE_REQUIRED_PRICES]"]}

● if the price is not indicated or specified is not a valid value:

{"errors":["[VALIDATION_NOT_FLOAT]","[VALIDATION_NOT_FLOAT]"]}

● if the price is less than minimum:

{"errors":["The price is not valid"]}

● if the price is higher than  maximum:

{"errors":["[LS_CAB_'51'_MORE_THAN_'50']","[LS_CAB_'51'_MORE_THAN_'50']"]}
  • if the CPC is not valid
    {"errors":["[ONE_OR_MORE_REGIONS_HAVE_PRICE_HIGHER_THAN_ACCEPTABLE_PRICE]"]}

 

Block / unblock a teaser for advertising campaign

Method PATCH
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID_
Headers

Accept: application/json

Authorization: Bearer {token}


Transferred parameters send in the body of the request:

Parameters Value
whetherToBlockByClient 1 — block
0 — unblock

Answer returned.
If the operation is successful, it returns teaser ID:

{
"id":"_teaser_ID_"
}

 

Removing teaser (move to bin)  

Method DELETE
URL api.adskeeper.co.uk/v1/goodhits/clients/_client_ID_/teasers/_teaser_ID_
Headers

Accept: application/json

Authorization: Bearer {token}

Answer returned:
If the operation is successful, it returns teaser ID which was moved to bin:

{
"id":"_teaser_ID_"
}

If a teaser with the specified ID does not exist in the system or have already been
moved to the bin, then the message will be returned:

[ERROR_RESOURCE_NOT_FOUND]