---
title: REST API Adskeeper for advertisers
description: Advertising campaigns daily statistics for video campaigns Getting an available CTA for an advertiser's campaign   REST API allows you to integrate external applications with Adskeeper online   advert
---

[Skip to content](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#main-content)

English

Show submenu for translations

![AdsKeeper\_Logo\_Help\_Center.svg\]](https://help.adskeeper.com/hubfs/AdsKeeper_Logo_Help_Center.svg)

Open main navigation

Close main navigation

- English
  
  Show submenu for translations
- [Login](https://dashboard.adskeeper.co.uk/user/signin)

[Login](https://dashboard.adskeeper.co.uk/user/signin)

 Hello. How can we help you?

- There are no suggestions because the search field is empty.

1. [Help Center](https://help.adskeeper.com/?hsLang=en)
2. [API](https://help.adskeeper.com/api?hsLang=en)

# REST API Adskeeper for advertisers

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

### **Table of contents**

- [The main provisions of REST API](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc1)
- [Identification](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc2)
- [Adskeeper REST API answer](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc3)
- [Working with clients](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc4)<https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc4-1> 
    - [Getting information about the current financial status of the client](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc4-2)<https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc4-3><https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc4-4>
- [Working with client's advertising campaigns](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5)  
    - [Getting a collection of client's advertising campaigns](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5)
    - [Getting advertising campaign statistics by site](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-2)<https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-2-1>
    - [Advertising campaigns detailed daily statistics](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-3)
    - [Advertising campaigns daily statistics](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-4)
    - [Advertising campaigns daily statistics for video campaigns](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-4-1)
    - [Creating a new ad campaign (with all settings)](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-5)
    - [Creating a new ad campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-6)
    - [UTM markup settings for ad campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-7)
    - [Setting limits on advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-8)
    - [Block / unblock advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-9)
    - [Getting creation date of ad campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-10)
    - [Setting the coefficient of a selective auction of an advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-11)<https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-12>
    - [Setting the coefficient of a selective auction to all sub-sources](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-12)

- - [Retrieving conversion targets for a client](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-133)
    - [Retrieving conversion settings for an advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-13)
    - [Creating conversion targets for an advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-144)
    - [Editing conversion settings for an advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-14)
    - [Delete conversion target](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-155)
    - [Removing campaign to trash](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-15)
    - [Getting an available CTA for an advertiser's campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-16)

- [Advertising campaigns targeting settings](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6) 
    - [Setting up the geo targeting of advertising campaigns](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-1)
    - [Getting a list of available countries for setting up geo targeting](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-2)
    - [Getting a list of available regions (cities) for geo targeting settings](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-3)
    - [Editing geo targeting settings for advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-4)
    - [Editing advertising campaign browser targeting](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-5)
    - [Editing advertising campaign IP targeting](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-6)
    - [Editing advertising campaign operating system targeting](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-7)
    - [Getting advertising campaign operating system targeting settings](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-7-1)
    - [Editing the filter settings on the sites for advertising campaign by UID](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-8)
    - [Editing browser language targeting](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-9)
    - [Getting browser language targeting settings](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-10)
    - [Getting browser targeting settings](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-11)
- [Working with client's teasers](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7)

- - [Constants and identifiers in use](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-1)
    - [Getting a list of client teasers](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-2)
    - [Teaser detailed daily statistics](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-21)
    - [Creating a new teaser for ad campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-3)
    - [Editing ad campaign teaser settings](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-4)
    - [Changing advertising campaign teaser's CPC](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-5)
    - [Block / unblock a teaser for advertising campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-6)
    - [Removing teaser (move to bin)](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc7-7)

 

### **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.com/v1*

**In general, the query looks like this:**  
*https://api.adskeeper.com/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. You should get a valid token from the dashboard.

| 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 **information about the current financial status of the client***

| **Method** | GET |
| --- | --- |
| **URL** | *api.adskeeper.com/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.com/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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#lang) - **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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#Editing_advertising_campaign_operating_system_targ) - **languageTargeting** - language filter settings. [Ad campaign language id](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#lang) - **browserTargeting** - browsers filter settings. [Possible browser values](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-5) - **category** - campaign [category](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#categories) |
| 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 | no |
| 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_"      },      "startDate": "YYYY-MM-DD",      "endDate": null,      },   },   ...........}
```

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 declined to proceed and rejected it |
| 19 | Campaign stopped due to a 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.com/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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-5) |
| os | Filters data by OS. 1 value to a parameter can be passed. [OS codes list](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-7) |
| country | Filters data by country. 1 value to a parameter can be passed. [Countries codes list](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc6-2) |

Request example:

```
api.adskeeper.com/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.com/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 correct, it returns an array of data in the following 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_",            "sourceId":"_source_id_",            "informerUid":"_informer_uid_",            "country":"_two_letter_country_code",            "region":"_region_",            "price":"_click_price_"         },         ….      ]   }}
```

If an invalid parameter is provided, return the error:

```
[ERROR_NOT_VALID_PARAMETER_NAME]
```

#### Advertising campaigns daily statistics

| **Method** | GET |
| --- | --- |
| **URL** | *api.adskeeper.com/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.com/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.com/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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#lang) |
| languageTargets | Filter by [language\_code](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#lang) 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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#categories) |

**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}, {user\_id}, {geo}, {geo\_region}, {ifa}, {gdpr}, {gdpr\_consent}, {click\_id}, {click\_price}, {client\_id}, {title}, {referrer} |

**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 - off, 1 - on |

**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.com/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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#lang) |
| languageTargets | Filter by [language\_code](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#lang) of an ad campaign in include mode. IDs of languages separated by a comma. |
| startDate | campaign start date YYYY-MM-DD |
| endDate | campaign end 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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#categories) |

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.com/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}, {user\_id}, {geo}, {geo\_region}, {ifa}, {gdpr}, {gdpr\_consent}, {click\_id}, {click\_price}, {client\_id}, {title}, {referrer}**.*  

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.com/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 v**alue 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 - off, 1 - on |

- The minimal daily budget limit depends on the currency
- 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.com/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.com/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.com/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\_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.com/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\_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 targets for a client*

| **Method** | GET |
| --- | --- |
| **URL** | *https://api.adskeeper.com/v1/goodhits/clients/312772/conversions-targets* |
| **Headers** | Accept: application/json Authorization: Bearer {token} |

Response:

```
{    "stages": {        "decision": {            "cpa": 3.99,            "unique": true,            "targetType": "url",            "categoryId": 5,            "condition":{                "type":"contain",                "value":"testerovich"            }        },        "interest": {            "cpa": 2.34,            "unique": true,            "targetType": "url",            "categoryId": 4,            "condition":{                "type":"contain",                "value":"testerovich2"            }        }    }}
```

 

#### *Retrieving conversion settings for an advertising campaign*

| **Method** | GET |
| --- | --- |
| **URL** | *api.adskeeper.com/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    }]
```

#### *Creating conversion targets for an advertising campaign*

| **Method** | POST |
| --- | --- |
| **URL** | *api.adskeeper.com/v1/goodhits/campaigns/\_campaign\_ID\_/conversions* |
| **Headers** | Accept: application/json Authorization: Bearer {token} |

Transferred parameters send in the body:

| **Parameter** | **Value** |
| --- | --- |
| buy | settings for stage buy |
| decision | settings for stage decision |
| interest | settings for stage interest |

Each stage has next values:

- cpa: float;
- unique: boolean;
- targetType: url, event, postback;
- categoryId: number; 
    - ID: 1 (Registration)
    - ID: 2 (Lead)
    - ID: 3 (Click)
    - ID: 4 (Install)
    - ID: 5 (Download)
    - ID: 6 (Sale)
    - ID: 7 (Add To Cart)
    - ID: 8 (Deposit)
    - ID: 9 (Other)

- condition type: starts, contain, ends;
- condition value: string;
- identifier: string (event name for event targetType)

Example:

```
{    "stages": {        "decision": {            "cpa": 3.99,            "unique": true,            "targetType": "url",            "categoryId": 5,            "condition":{                "type":"contain",                "value":"test"            }        },        "interest": {            "cpa": 2.34,            "unique": true,            "targetType": "url",            "categoryId": 4,            "condition":{                "type":"contain",                "value":"test2"            }        }    }}
```

#### *Editing conversion settings for an advertising campaign*

| **Method** | PATCH |
| --- | --- |
| **URL** | *api.adskeeper.com/v1/goodhits/campaigns/\_campaign\_ID\_/conversions* |
| **Headers** | Accept: application/json Authorization: Bearer {token} |

Transferred parameters send in the body:

| **Parameter** | **Value** |
| --- | --- |
| buy | settings for stage buy |
| decision | settings for stage decision |
| interest | settings for stage interest |

Value format: id: number (target\_id); cpa: float; unique: boolean

- \_id\_ - ID of an existing target (target\_id)
- \_cpa\_ - cpa in the client's currency. Either a number or null
- \_unique\_ - marks stage as unique. Can be true or false

Example:

```
{    "stages": {        "buy": {            "id": 2987,            "cpa": 3.99,            "unique": true        },        "interest": {            "id": 753455,            "cpa": 2.34,            "unique": true        }    }}
```

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

#### *Delete conversion target*

| **Method** | DELETE |
| --- | --- |
| **URL** | *api.adskeeper.com/v1/goodhits/campaigns/\_campaign\_ID\_/conversions* |
| **Headers** | Accept: application/json Authorization: Bearer {token} |

Transferred parameters:

| **Parameter** | **Value** |
| --- | --- |
| stages | buy, decision, interest |

Example:

```
{    "stages": ["buy", "interest"]}
```

#### *Removing campaign to trash*

Only stopped ad campaigns can be removed.

| **Method** | DELETE |
| --- | --- |
| **URL** | *api.adskeeper.com/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

 

#### Getting an available CTA for an advertiser's campaign

| **Method** | GET |
| --- | --- |
| **URL** | [api.adskeeper.com/v1/goodhits/campaigns/](http://api.adskeeper.com/v1/goodhits/campaigns/)*campaign\_ID*/call-to-actions |
| **Headers** | Accept: application/json Authorization: Bearer {token} |

The endpoint returns a list of available call-to-action options for the specified campaign.

Answer returned:

```
{   "_call_to_action_",   ... }
```

 

 

### **Advertising campaigns targeting settings**

 

#### ***Setting up the geo targeting of advertising campaigns***

Getting geotargeting settings ad campaign of client:

| **Method** | GET |
| --- | --- |
| **URL** | *api.adskeeper.com/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.com/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.com/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.com/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.com/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.com/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.com/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 | 2.3 | android23mobile |
| 13 | Android | 3.хх | android3mobile |
| 14 | Android | 4.0 | android40mobile |
| 15 | Android | 4.1 | android41mobile |
| 16 | Android | 4.2 | android42mobile |
| 17 | Android | 4.3 | android43mobile |
| 18 | Android | 4.4 | 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 | 2.3 | android23tablet |
| 27 | Android | 3.хх | android3tablet |
| 28 | Android | 4.0 | android40tablet |
| 29 | Android | 4.1 | android41tablet |
| 30 | Android | 4.2 | android42tablet |
| 31 | Android | 4.3 | android43tablet |
| 32 | Android | 4.4 | 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 | 8.1 | 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 | Roku OS |  | 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 | iOS | 15.xx | ipados15tablet |
| 96 | iOS | 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 |
| 103 | Android | 15.xx | android15mobile |
| 104 | Android | 15.xx | android15tablet |
| 105 | iOS | 18.xx | ios18mobile |
| 106 | iOS | 18.xx | ipados18tablet |
| 107 | Mac OS | 15 Sequoia | macos150 |
| 108 | Android | 16.xx | android16mobile |
| 109 | Android | 16.xx | android16tablet |
| 110 | iOS | 26.xx | ios26mobile |
| 111 | iOS | 26.xx | ipados26tablet |
| 112 | Mac OS | 26 Tahoe | macos260 |
| 113 | Android | 17.xx | android17mobile |
| 114 | Android | 17.xx | android17table |

 

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.com/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.com/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**... Available filter types: only / except / off |
| 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.com/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

On success - returns the identifier of editable ad campaign

```
{"id":_ad_campaign_ID_}
```

Error - invalid filter type (off | only | except) or missing parameters: 

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

Error - invalid filter method (include | exclude) or missing parameters:

```
{"errors":["[ERROR_NOT_VALID_METHOD]"]}
```

Error - sites not transferred:

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

Error - non-existing sites id transferred:

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

If transferred valid & non-valid IDs ("widgetsFilter": "include, only, ttttts1, 5676301111, 5676672rrr, eeeeee") - valid IDs will be written in the 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 are not passed - it's a non-valid situation.

#### Editing browser language targeting

| **Method** | PUT |
| --- | --- |
| **URL** | *api.adskeeper.com/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\_](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#lang)..... |
| enabledFlag\* | Enable / disable targeting. 0 – target off, 1 — target on |

Request example:

```
api.adskeeper.com/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.com/v1/goodhits/campaigns/\_ad\_campaign\_ID/targetings/browserslanguage* |
| **Headers** | Accept: application/json Authorization: Bearer {token} |

Request example:

```
api.adskeeper.com/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.com/v1/goodhits/campaigns/campaign\_id/targetings/browsers |
| **Headers** | Accept: application/json Authorization: Bearer {token} |

Request example:

```
api.adskeeper.com/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

 

### **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.com/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. |
| blockedBy | This parameter is an additional option that works together with the status filter. It allows checking and filtering teasers by the entity that applied the action leading to the current status. Supported statuses: onModeration, rejected, active, new, blocked. Possible values: - client: blocked by the client (dashboard / API action); - account\_manager: blocked by an Adskeeper Account Manager user; - system:  blocked by the system (e.g., cron, schedule, automation); - moderator: blocked by a moderator or scheduled moderation action. |
| creationDate | Allows filtering creatives by their creation date range. It is designed to help retrieve only those creatives that were created within a specific time period. Format: The parameter accepts two optional sub-parameters: - creationDate\[dateFrom\] — start date (\>=) - creationDate\[dateTo\] — end date (\<) Date format: Y-m-d (e.g., 2025-08-01) |
| 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. |
| ctrGuard\* | Returns appropriate teasers created with CTR Guard. Value: 1. \*If this filter is used, all other filters except "campaign" are ignored. |

Request example for the blockedBy parameter to show teasers blocked by the client:

```
api.adskeeper.com/v1/goodhits/clients/{clientId}/teasers/status=["blocked"]&blockedBy=client
```

Request example for the blockedBy parameter to show active and blocked teasers blocked by a moderator:

```
api.adskeeper.com/v1/goodhits/clients/{clientId}/teasers/status=["active", "blocked"]&blockedBy=moderator
```

Request example for the creation Date parameter:

```
api.adskeeper.com/v1/goodhits/clients/{clientId}/teasers/?creationDate[dateFrom]=2025-08-27&creationDate[dateTo]=2025-09-05
```

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_":{ . . . . . . },. . . . . . . . . }
```

If there are some errors:

\[ERROR\_INVALID\_CUSTOM\_DATES\] - invalid date has been specified.

 

 

#### ***Teaser detailed daily statistics***

| **Method** | GET |
| --- | --- |
| **URL** | api.adskeeper.com/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.com/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/search feed campaign type - up to 90 characters - for push campaign type - up to 30 characters - supported macros: {City}, {Country}, {Region} - the macro must be capitalized, use curly braces, and be specified only in English. It is forbidden to use macros for a push campaign type |
| *advertText* | Advertising text. If this parameter is passed in the request, the validation will be as follows: - for content/product/search feed campaign type - up to 90 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 static 492x328 pixels. - Recommended size 600x382 pixels and larger. - Available formats static: .jpg/.jpeg/.png /.webp - Minimum dimension motion 680×680 px - Available formats motion:.gif/.mp4/.mov. |
| *categoryId\** | [Teaser category ID](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#categories). This parameter must be passed for Push campaign type only. For Product, Content, and SearchFeed campaign types category will be set automatically |
| *priceOfClick\** | Price per click, cents, with tenths. As a separator between the whole number and the fraction can use a comma or period. |
| *whetherShowGoodPric*e\* | 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. |
| callToAction | Optional field. One of the call-to-action options available for a teaser, selected from the predefined dictionary (see: *“[Getting an available CTA for an advertiser's campaign](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#toc5-16)”*). |

 

**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 macros in the teaser title or description for Push campaign:

```
{"errors":["[VALIDATION_MACRO_WAS_FOUND_TITLE_PUSH]"] }
```

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.com/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](https://help.adskeeper.com/rest-api-adskeeper-for-advertisers#categories). |
| *whetherShowGoodPric*e*\** | 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.com/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.com/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.com/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]
```

- [Advertisers / Affiliates](https://help.adskeeper.com/advertisers-affiliates?hsLang=en#main-content)

    - [Adskeeper Basics](https://help.adskeeper.com/advertisers-affiliates?hsLang=en#adskeeper-basics)
    - [Campaign Setup and Management](https://help.adskeeper.com/advertisers-affiliates?hsLang=en#campaign-setup-and-management)
    - [Conversion Tracking](https://help.adskeeper.com/advertisers-affiliates?hsLang=en#conversion-tracking)
- [Publishers](https://help.adskeeper.com/publishers?hsLang=en#main-content)

    - [General](https://help.adskeeper.com/publishers?hsLang=en#general)
    - [Websites and widgets](https://help.adskeeper.com/publishers?hsLang=en#websites-and-widgets)
    - [Compliance](https://help.adskeeper.com/publishers?hsLang=en#compliance)
    - [Payment](https://help.adskeeper.com/publishers?hsLang=en#payment)
- [Compliance and Creatives](https://help.adskeeper.com/compliance-and-creatives?hsLang=en#main-content)

    - [Compliance and Creatives Basics](https://help.adskeeper.com/compliance-and-creatives?hsLang=en#compliance-and-creatives-basics)
    - [High Safety Ranking](https://help.adskeeper.com/compliance-and-creatives?hsLang=en#high-safety-ranking)
    - [Low Safety Ranking](https://help.adskeeper.com/compliance-and-creatives?hsLang=en#low-safety-ranking)
    - [AI Image Generation](https://help.adskeeper.com/compliance-and-creatives?hsLang=en#ai-image-generation)
    - [Moderation Process](https://help.adskeeper.com/compliance-and-creatives?hsLang=en#moderation-process)
- [Advertisers Super Client Account](https://help.adskeeper.com/advertisers-super-client-account?hsLang=en#main-content)

    - [Clients](https://help.adskeeper.com/advertisers-super-client-account?hsLang=en#clients)
- [API](https://help.adskeeper.com/api?hsLang=en)
- [DSP](https://help.adskeeper.com/dsp?hsLang=en)

[![Chill listening crop-3](https://help.adskeeper.com/hubfs/AdsKeeper_Logo_Help_Center_Footer.svg "Chill listening crop-3")](https://www.adskeeper.com/)

The key to tailored ad recommendations

Copyright © 2026, Adskeeper