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
• Identification
• Adskeeper REST API answer
• Working with clients
  • Getting information about the current financial status of the client
  • Getting a collection of client's source filters
  • Setting filters on an account level
• Working with client's advertising campaigns
  
  • Getting a collection of client's advertising campaigns
  • Getting advertising campaign statistics by site
  • Getting advertising campaign statistics by source
  • Advertising campaigns detailed daily statistics
  • Advertising campaigns daily statistics

  • Advertising campaigns daily statistics for video campaigns

  • Creating a new ad campaign (with all settings)
  • Creating a new ad campaign
  • UTM markup settings for ad campaign
  • Setting limits on advertising campaign
  • Block / unblock advertising campaign
  • Getting creation date of ad campaign
  • Setting the coefficient of a selective auction of an advertising campaign
  • Setting the coefficient of a selective auction to all sub-sources
  • Retrieving conversion targets for a client
  • Retrieving conversion settings for an advertising campaign
  • Creating conversion targets for an advertising campaign
  • Editing conversion settings for an advertising campaign
  • Delete conversion target
  • Removing campaign to trash

• Advertising campaigns targeting settings
  • Setting up the geo targeting of advertising campaigns
  • Getting a list of available countries for setting up geo targeting
  • Getting a list of available regions (cities) for geo targeting settings
  • Editing geo targeting settings for advertising campaign
  • Editing advertising campaign browser targeting
  • Editing advertising campaign IP targeting
  • Editing advertising campaign operating system targeting
  • Getting advertising campaign operating system targeting settings
  • Editing the filter settings on the sites for advertising campaign by UID/source
  • Editing browser language targeting
  • Getting browser language targeting settings
  • Getting browser targeting settings
  • Editing phone price range targeting
  • Getting phone price range targeting
• Working with client's teasers

• • Constants and identifiers in use
  • Getting a list of client teasers
  • Teaser detailed daily statistics
  • Creating a new teaser for ad campaign
  • Editing ad campaign teaser settings
  • Changing advertising campaign teaser's CPC
  • Block / unblock a teaser for advertising campaign
  • 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):    

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.

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. 

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

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.

Getting a collection of client's source filters

Request example:

api.adskeeper.co.uk/v1/clients/{client id}/sources-blocklist

Returned answer:

{
    "id": _client_id_,
    "sourceFilters": {
        "filterType": "blocklist",
        "sources": [
            "Homepage Lifestyle",
            "Homepage News",
            "domain.com",
            "domain2.com"
        ],
        "sourcesIds": [
            1088,
            1089,
            10001,
            10002
        ]
    }
}

Filter type - blocklist, off (off - no data)

Setting filters on an account level

Affects all client's campaigns using sources optimization

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

Request example:

api.adskeeper.co.uk/v1/clients/{client id}?sourceFilters=include,blocklist,domain1.com,domain2.com

Editing methods:

• include — enables the source.
• exclude — disables the source.

Filter types:

• blocklist — applies a blocklist to the sources.
• off — turns off the filter for the sources.

Returned answer:

{
   "msg":"success",
}

Error - nonexistent source IDs or names or invalid sources (e.g., non-integer or incorrect format):

{"errors":["[SOURCES_DO_NOT_EXIST]"]}

Error - sources are not passed:

{"errors":["[SOURCES_CANNOT_BE_EMPTY]"]}

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

Error - invalid filter type or missing parameters:

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

Working with client's advertising campaigns

Getting a collection of client's advertising campaigns

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 *):

Languages list:

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_"
      },
      "sourceFilters": {
        "filterType": "blocklist",
        "sources": [
            "domain.com"
        ],
        "sourcesIds": [
            4114
        ]
      }
   },
   ...........
}

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:

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

Transfered parameters (required parameters marked with asterisk *):

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

Getting advertising campaign statistics by source

Transfered parameters (required parameters marked with asterisk *):

Request example:

api.adskeeper.co.uk/v1/goodhits/campaigns/campaign_id/quality-analysis-sources/?dateInterval=interval&startDate=2024-10-27&endDate=2024-10-29&source=Somesource+-+iOS&widgetId=ON

Answer returned:

{
    "_campaign_ID_": {
        "2024-11-16_2024-11-16": {
            "20001": {
                "sourceName": "domain.com",
                "sourceId": 100001,
                "clicks": 0,
                "adRequests": 0,
                "impressions": 0,
                "viewability": 0,
                "spent": 0,
                "dataFee": 0,
                "cpcWithoutDataFee": 0.573333,
                "ctr": 0,
                "cpc": 0.573333,
                "cpm": 0,
                "conversionsRateInterest": 0,
                "conversionsRateDecision": 0,
                "conversionsRateBuy": 0,
                "conversionsCostInterest": 0,
                "conversionsCostDecision": 0,
                "conversionsCostBuy": 0,
                "revenue": 0,
                "profit": 0,
                "roas": 0,
                "epc": 0,
                "vCpm": 0,
                "vCtr": 0,
                "etr": 0,
                "winRate": 96.22,
                "conversionsInterest": 0,
                "conversionsDecision": 0,
                "conversionsBuy": 0,
                "toggle": true,
                "canChangeToggle": true,
                "qualityFactor": 1.3,
                "qualityFactorUpdatedAt": "01.11.2024 01:56:01",
                "previousQualityFactor": 0.11,
                "isBlocked": false
            }
        }
    }
}

If an ID that does not belong to a sources optimization campaign, return the error:

[ERROR_CAMPAIGN_IS_NOT_TRANSPARENCY]

If a nonexistent source ID or name is provided, or if the parameter is empty, return the error: 

[ERROR_SOURCES_DO_NOT_EXIST]

If an invalid parameter is provided, return the error: 

[ERROR_NOT_VALID_parameter_name]

Advertising campaigns detailed daily statistics

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

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_",
            "source":"_source_"
            "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

Transferred parameters:

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

Transferred parameters:

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)

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

[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

[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]

[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]

"[ERROR_NO_ENOUGH_PARAMETERS]"

{
     "id":_campaign_id_,
}

Creating a new ad campaign

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

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

Transferred parameters:

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}, {source}, {source_id}, {teaser_id}, {campaign_id}, {category_id}, {user_id}, {geo}, {geo_region}, {ifa}, {gdpr}, {gdpr_consent}, {click_id}, {click_price}, {client_id}, {title}, {price_range}, {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

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

• 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

Transferred parameters send in the body of the request:

Getting creation date of ad campaign

Transferred parameters:

Answer returned:

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

Setting the coefficient of a selective auction of an advertising campaign

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

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_
• WIDGETS OPTIMIZATION IS NOT AVAILABLE FOR THIS CAMPAIGN. THIS CAMPAIGN IS ALREADY USING SOURCES OPTIMIZATION - when users attempt to modify settings via old routes for campaign using sources optimization
• ERROR_CAMPAIGN_IS_NOT_TRANSPARENCY_CANT_CHANGE_QF - isn't a transparency campaign
• ERROR_SOURCE_INVALID_FORMAT - wrong data format in parameter sourceName or sourceId

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

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

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_
• WIDGETS OPTIMIZATION IS NOT AVAILABLE FOR THIS CAMPAIGN. THIS CAMPAIGN IS ALREADY USING SOURCES OPTIMIZATION - when users attempt to modify settings via old routes for campaign using sources optimization

Retrieving conversion targets for a client

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

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

Transferred parameters send in the body:

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

Transferred parameters send in the body:

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

Transferred parameters:

Example:

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

Removing campaign to trash

Only stopped ad campaigns can be removed.

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:

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

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

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

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

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

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

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

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

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

Possible values for _browser_ :

Upon successful saving settings system returns campaign ID:

{
 "id":_campaign_ID_
}

Editing advertising campaign IP targeting   

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

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

Transferred parameters:

Operating systems:  

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

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/source

Transferred parameters send in the body of the request:

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

On success - returns the identifier of editable ad campaign

{"id":_ad_campaign_ID_}

Example response when users attempt to modify settings via old routes for a campaign using sources optimization:

{"errors":["[ERROR_CAMPAIGN_IS_NOT_TRANSPARENCY_CANT_CHANGE_FILTER]"]}

Error - sources are not passed:

{"errors":["[SOURCES_CANNOT_BE_EMPTY]"]}

Error - nonexistent source IDs or names or invalid sources (e.g., non-integer or incorrect format):

{"errors":["[SOURCES_DO_NOT_EXIST]"]}

Error - invalid filter type (off|blocklist|allowlist|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]"]}

If both valid and invalid sources are passed, valid ones will be saved to the database, and invalid ones will be returned in the error response: 

{"id":_ad_campaign_ID_, "errors":["[SOURCES_DO_NOT_EXIST]"], "data":["1000000","111111","uuuuuu"]}

Changing from "blocklist" to "allowlist" is not allowed. The error:

[FILTER_TYPE_CANT_BE_CHANGED]

When a source is blocked at the client level, any attempt to include or exclude it will result in the error:

[SOURCE_CANT_BE_CHANGED_ADDED_TO THE CLIENT_BLOCKLIST]

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

Transferred parameters send in the parameters of the request:

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

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

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

Transferred parameters send in the parameters of the request:

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:

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

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:

Teaser status:

Getting a list of client teasers

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 *):

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

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

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

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

Categories list:

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:

Editing ad campaign teaser settings

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

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

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

"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

Transferred parameters send in the body of the request:

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

Transferred parameters send in the body of the request:

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

{
 "id":"_teaser_ID_"
}

Removing teaser (move to bin)  

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]