API setting
Contents
[hide]- 1 PHP SDK DEPRECATED
- 2 API authorization with a Bearer Token
- 3 API authorization with a signature DEPRECATED
- 4 Campaign Statistics
- 5 Statistics on sites in the advertiser's account
- 6 Change the multiplier for statistics on sites in the advertiser's account
- 7 Statistics on all campaign materials
- 8 Creating an advertising campaign
- 9 Editing ad campaigns
- 10 List of campaign advertising campaign
- 11 Archiving an advertising campaign
- 12 Receiving codes for CPA campaigns
- 13 Getting a list of categories for a given filter
- 14 Getting the list of ad formats
- 15 Getting the list of platforms
- 16 Getting Browser List
- 17 Getting a list of conversion notifications for the CPA
- 18 Getting a list of ages
- 19 Getting a list of countries
- 20 Getting a list of regions
- 21 Getting a list of cities
- 22 Getting a list of devices
- 23 Getting a list of browser languages
- 24 Creating advertising agency clients
- 25 Editing advertising agency clients
- 26 Getting a list of advertising agency clients
- 27 Archiving advertising agency clients
- 28 Tying a client to an advertising agency
- 29 Detaching a client from an advertising agency
- 30 Customer account replenishment
- 31 Creating advertisements
- 32 Update ad data
- 33 Archiving advertisements
- 34 Getting a list of advertisements
- 35 Getting a list of banner sizes
- 36 Getting the list of countries
- 37 Getting a list of regions for a given filter
- 38 Get a list of available payment systems
- 39 Download media files
- 40 Get the current server time
- 41 Money transfer for subsidiary accounts of the agency
PHP SDK DEPRECATED
Install from github: https://github.com/kadam-official/php-sdk
Install from composer:
composer require kadam/php-sdk
API authorization with a Bearer Token
To authorize in the system via API with Bearer Token you need to add to your request the "Authorization" header with "Bearer X" value where "X" is your personal token. You can get the token by asking your manager. The lifetime of token is not limited. You can change your token in the settings of your personal account.
API authorization with a signature DEPRECATED
Please use authorization with a Bearer Token
To access the API, you will need a user ID (app_id) and a signature (signature).
Calling different methods is carried out using queries on this template:
api.kadam.net?%action%.%method%?%params%
% action% - what are we turning to
% method% - type of treatment
get - get
put - write
post - update
delete - delete
% params% - request parameters
required parameters% params%
app_id - user id
signature - signature
Example:
[GET] http://api.kadam.net/campaigns.get?app_id=%app_id%&signature=%signature%
or
[GET] http://api.kadam.net/campaigns?app_id=%app_id%&signature=%signature%
[GET] - http access method
Signature (signature) is created using a temporary token (access_token), which can be obtained using the app_id and secret key parameters.
Parameters app_id (user ID) and the key "secret key" are available on request to support.
Getting a token:
[GET] http://api.kadam.net/auth.token?app_id=%app_id%&secret_key=%key%
-> {“access_token”: “...”}
Generating signature for the [GET] method:
md5 ( %sort_params% . %access_token% )
%sort_params% - all parameters passed (except signature) are sorted by name
Example:
app_id=1&campaign_id=3…
[PUT] http://api.kadam.net/campaigns?signature=%signature%
+post fields -> %params%
Example for php. Getting a list of campaigns:
<?
$your_secret_key = "jqhwekq8734quo37o498q3p498qp34";
$your_app_id = 1;
$auth_url = "http://api.kadam.net/auth.token?app_id={$your_app_id}&secret_key={$your_secret_key}";
$auth = file_get_contents($auth_url);
$auth = json_decode($auth, true);
if ( !is_array( $auth ) || !isset( $auth['access_token'] ) ) {
die( 'something wrong! ' . print_r( $res, true ) );
}
$token = $auth['access_token'];
$params = array(
'client_id' => $your_app_id,
'app_id' => $your_app_id,
);
ksort( $params );
$result = array ();
foreach( $params as $key => $value ) {
$result[] = $key . '=' . urlencode( $value );
}
$params = implode( '&', $result );
$signature = md5( $params . $token );
$campaign_url = 'http://api.kadam.net/ads.campaigns.get?' . $params . '&signature=' . $signature;
$campaigns = file_get_contents($campaign_url);
$campaigns = json_decode($campaigns, true);
if ( !is_array( $campaigns ) || !isset( $campaigns['response'] ) ) {
die( 'something wrong! ' . print_r( $campaigns, true ) );
}
print_r($campaigns);
Campaign Statistics
To get campaign statistics, use the method ads.stats.campaign.get
| Parameters | Values | Optional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| client_id | id of the client | int (numeric value), required parameter |
| campaigns | One or some campaign's id | int (numeric value), required parameter |
| group | Group by:
date - by dates campaign - by campaigns |
string, listed with a comma, required parameter |
| date_from | The starting date of the statistics to display. Different date formats are used for different parameter period values:
day: YYYY-MM-DD, example: 2011-09-27; month: YYYY-MM, example: 2011-09 |
required parameter, string |
| date_to | The final date of the displayed statistics. Different date formats are used for different parameter period values:
day: YYYY-MM-DD, example: 2011-09-27; month: YYYY-MM, example: 2011-09 |
required parameter, string |
| sort | One or some parameters for sorting data, listed with a comma. | optional parameter |
| limit | Number of rows returned | optional parameter, int (numeric value) |
| offset | Offset on returned rows (use with limit parameter) | optional parameter, int (numeric value) |
Example request URL:
http://api.kadam.net/ads.stats.campaign.get?app_id=127296&client_id=127296&campaigns=789484&date_from=2024-12-01&date_to=2024-12-31& group=date&sort=-views,-clicks,leads
Result:
Returns an object with data
{
"response":{
"count": %number rows returned%,
"items":[
{
“date” // date; if group by date
"id" // id campaign; if group by campaign
"views"
"clicks"
"conversions"
"rejections"
"holds"
"moneyOut" // spent
"moneyIn" // income
"ctr"
"cpm"
"cpc"
}
]
}
}
Sorting
Sort Ascending
sort = {parameter}
Example: api.kadam.net?sort=views
Sort descending
sort = - {parameter}
Example: api.kadam.net?sort=-views
Sort by several parameters
sort = {parameter1}, - {parameter2}, {parameter3}
Example: api.kadam.net?sort=views,-clicks,leads
Statistics on sites in the advertiser's account
Statistics on sites in the advertiser's account references statistics on views and clicks on the site in the context of each campaign.
To get statistics on sites, use the ads.stats.campaign.placement.get method (GET request)
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| client_id | id of the client | int (numeric value), required parameter |
| campaigns | One or some id campaigns, listed with a comma | string; mandatory parameter |
| date_from | Start date of the statistics output. | string, mandatory parameter, format YYYY-MM-DD (example: 2017-05-15), filter parameter |
| date_to | The end date of the statistics output. | string, mandatory parameter, format YYYY-MM-DD (example: 2017-05-15), filter parameter |
| sort | One or some parameters for sorting data, listed with a comma. | optional parameter |
| limit | Number of rows returned | optional parameter, int (numeric value) |
| offset | Offset on returned rows (use with limit parameter) | optional parameter, int (numeric value) |
Example request URL:
http://api.kadam.net/ads.stats.campaign.placement.get?app_id=127296&client_id=127296&campaigns=789484&date_from=2024-12-10&date_to=2024-12-22& sort=views,clicks,leads
Result:
Returns an object with data, example:
{
"response":{
"count": %количество возвращаемых элементов%,
"items":[
{
"id" // id campaign
"placement" // id placement
"views"
"clicks"
"conversions"
"rejections"
"holds"
"moneyOut"
"moneyIn"
"ctr"
"cpm"
"cpc"
"prelandvisit"
"prelanduseful"
"prelandscroll"
"landvisit"
"landuseful"
"landscroll"
"blackList"
"multiplier" // stake multiplier
}
]
}
}
Sorting
Sort Ascending
sort = {parameter}
Example: api.kadam.net?sort=views
Sort descending
sort = - {parameter}
Example: api.kadam.net?sort=-views
Sort by several parameters
sort = {parameter1}, - {parameter2}, {parameter3}
Example: api.kadam.net?sort=views,-clicks,leads
Filtration
{parameter} = {value}
Examples:
api.kadam.net?attr=10
api.kadam.net?attr=string
api.kadam.net?attr=string&date_from=01.05.2016&date_to=01.07.2016
Change the multiplier for statistics on sites in the advertiser's account
To change the multiplier for site statistics, use the ads.stats.campaign.placement.put method (GET request). Bearer-token authorization required. Parameters (all are required):
- app_id - user id, numeric value (int)
- campaign_id - campaign id, numeric value (int)
- multiplier - new multiplier value, numeric value (float)
- placement - place id, numeric value (int)
Example request URL:
http://api.kadam.net/ads.stats.campaign.placement.put?app_id=127296&campaign_id=789484&multiplier=x0.8&multiplierOld=0&placement=15078181151
The block and macros parameters in the account are not displayed, they can be obtained through the method described in the paragraph "Statistics by sites in the advertiser's account".
Statistics on all campaign materials
To get statistics on all campaign materials, use the ads.stats.creative.get method
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| client_id | id of the client | int (numeric value), required parameter |
| campaigns | One or some id campaigns, listed with a comma | string; mandatory parameter if not set creatives |
| creatives | One or some id creatives, listed with a comma | string; mandatory parameter if not set campaigns |
| group | Group by:
date - by dates creative - by creatives |
string, listed with a comma, required parameter |
| date_from | The starting date of the displayed statistics. Different date formats are used for different values of the period parameter:
1. day: YYYY-MM-DD, Example: 2011-09-27 2. month: YYYY-MM, example: 2011-09 | required parameter, string |
| date_to | End date of output statistics. Different date formats are used for different values of the period parameter:
1. day: YYYY-MM-DD, Example: 2011-09-27 2. month: YYYY-MM, example: 2011-09 | required parameter, string |
| sort | One or some parameters for sorting data, listed with a comma. | optional parameter |
| limit | Number of rows returned | optional parameter, int (numeric value) |
| offset | Offset on returned rows (use with limit parameter) | optional parameter, int (numeric value) |
Example request URL:
http://api.kadam.net/ads.stats.creative.get?app_id=127296&client_id=127296&creatives=7340006,7338000&group=date&date_from=2024-12-01& date_to=2024-12-22&sort=-views,clicks,leads
Result:
Returns an object with data
{
"response":{
"count": %количество возвращаемых элементов%,
"items":[
{
"date" // date; returned if group by dates
"id" // id creative; returned if group by creatives
"views"
"clicks"
"conversions"
"rejections",
"holds"
"moneyOut" // spent
"moneyIn" // income
"ctr"
"cpm"
"cpc"
}
]
}
}
Creating an advertising campaign
To create a new advertising campaign, use the ads.campaigns.put
method
Fifty (50) campaigns can be created with a single request.
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| data | a serialized JSON array of objects describing the campaigns being created. See the client_specification object description below. | required parameter, string |
| client_specification | ||
| client_id | id of the client in whose advertising account the campaign will be created. It can also take the value app_id (itself) | required parameter, int (numeric value) |
| ad_format | Ad Format:
10 - Teaser; 20 - Banner; 30 - Push Notifications; 40 - Clickunder; 60 - Contextual | required parameter, int (numeric value) |
| cost_type | Payment method:
0 - CPC; 1 - CPA; 2 - CPM | required parameter, int (numeric value) |
| name | campaign name | required parameter, string |
| Link_url | link to the advertised object in the format: http: //yoursite.cоm | required parameter, string |
| pushType | Push type:
1 - On-site Push; 2 - Classic; 4 - In-app push; |
int (numeric value) example: "pushType: 1,2,4" |
| real_url | link to the real domain of the advertised object in the format: http: //yoursite.cоm | required parameter, string |
| sex | Gender:
3 - any; 2 - male; 1 - female | required parameter, int (numeric value) |
| age | The age of the target audience. Age category number from 1 to 6 (up to 17, 18-25, 26-34, 35-49, 50-60, over 61) | required parameter, a sequence of numbers separated by a comma |
| countryTarget |
Countries id: /ads.targeting.countries.get |
required parameter array [country_id => [ bid => 0.1, leadCost => 0.2 ] ] |
| regionTarget |
ID regions: /ads.targeting.regions.get | required parameter, a sequence of numbers separated by a comma |
| cityTarget |
ID cities: /ads.targeting.cities.get |
required parameter, a sequence of numbers separated by a comma |
| cpa_mode | Type of conversion notifications for CPA: /ads.targeting.modes.get | int (numeric value), mandatory for CPA campaigns |
| categories | category IDs: /data.categories.get?ad_format =%
| required parameter, a sequence of numbers separated by a comma |
| tags | keyword targeting | required parameter, a sequence of keywords separated by a comma: [“key1”, “key2”, .., “keyN”] Keywords with price. Only for payment - for clicks or for views: {“key1”: “cost”, “key2”: “cost”, .., “keyN”: “cost”} cost - float example: "data [tags] [qwerty]: 1" is the qwerty keyword with a 1rub rate. |
| day_limit | Daily limit in rubles. For all types except clickunder | positive number |
| all_limit | Total limit in rubles. For all types except clickunder | positive number |
| click_limit | Maximum count. transitions per day. For all types except clickunder. For views and clicks. | positive number |
| conversion_limit | Maximum count. conversions per day. For all types except clickunder. Only for CPA | positive number |
| adult_content | presence of adult content in the advertising campaign:
0 - No; 1 - Yes | optional parameter, int (numeric value), default 0 |
| adult_site | Display campaign ads on adult content sites:
0 - No; 1 - Yes | optional parameter, int (numeric value), default 0 |
| time_show | Time Targeting:
& nbsp; & nbsp; * - display in any hours and days of the week & nbsp; & nbsp; {} is an array, where the key is the name of the day of the week ["Sn", "Mn", "Tu", "Wd", "Th", "Fr", "Sa"]: & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: ‘*’ - all watches are weekly & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: [0, .., 23] - hours, separated by commas | optional parameter, * default |
| platforms | platform targeting: /data.platforms | comma separated numbers |
| browsers | browser targeting: /data.browsers | comma separated numbers |
| black_list | black list of sites where ads will not be shown | comma separated site ID number sequence |
| white_list | white list of sites where ads will not be shown | comma separated site ID number sequence |
| black_list_ip | ip lock | sequence of ip addresses separated by a comma or an array |
| unique_day_count | frequency of material shown to one user (times) | positive number |
| unique_days | frequency of advertising material shown to one user (days) | positive number |
| deviceTarget |
ID devices: /ads.targeting.devices.get |
sequence of numbers separated by a comma |
| langTarget |
ID browser languages: /ads.targeting.langs.get |
sequence of numbers separated by a comma |
Example request URL:
http://api.kadam.net/ads.campaigns.put?app_id=127296&data={
"client_id": 127296,
"regionTarget": [1],
"ad_format": 10,
"cost_type": 0,
"name": "name123",
"link_url": "yayyy.ru",
"real_url": "ya.ru",
"sex": 2,
"age": "2,3",
"countryTarget": {
"1": { "bid": 0.1 },
"3": { "bid": 0.15 },
"16": { "bid": 0.2 }
},
"categories": [1001, 1125, 1126, 1127, 1128],
"day_limit": 500,
"all_limit": 5000,
"click_limit": 1000,
"conversion_limit": 50,
"adult_content": 1,
"adult_site": 1,
"time_show": {
"mn": "*",
"tu": [9, 10, 11],
"wd": [14, 15],
"th": "*",
"fr": [18, 19, 20],
"sa": "*",
"sn": "*"
},
"platforms": "1,2,4,16",
"browsers": "1,2,4,16,32,128",
"black_list": [1001, 1002, 1003],
"white_list": [2001, 2002, 2003],
"black_list_ip": ["192.168.1.1", "192.168.1.2"],
"unique_day_count": 3,
"unique_days": 7,
"deviceTarget": "1,2,3",
"langTarget": "1,2",
"cpa_mode": 2
}
Result:
Returns an array of responses to queries in the data array. The corresponding object in the output array contains the id of the created campaign, and the error_code and error_desc fields in case of an error.
Errors:
102 - unknown client 103 - overlimit campaigns
Editing ad campaigns
To edit ad campaigns, use the ads.campaigns.update
method
The maximum number of campaigns edited with a single query is 50.
Version log: 1.0.1 - added status parameter
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| data | is a serialized JSON array of objects describing changes in campaigns. Object descriptions client_mod_specification see below. | required parameter, string |
| client_specification | ||
| client_id | id of the client | int (numeric value), required parameter |
| campaign_id | id of the edited campaign | required parameter, positive number |
| name | campaign name | optional parameter, a string between 3 and 60 characters |
| link_url | link to the advertised object in the format http: //yoursite.com | optional parameter, string |
| real_url | link to the real domain of the advertised object in the format: http: //yoursite.cоm | optional parameter, string |
| sex | Gender:
3 - any; 2 - male; 1 - female | optional parameter, int (numeric value) |
| age | age: /data.ages | optional parameter, int (numeric value) |
| countryTarget |
Countries id: /ads.targeting.countries.get |
required parameter array [country_id => [ bid => 0.1, leadCost => 0.2 ] ] |
| regionTarget |
ID regions: /ads.targeting.regions.get | required parameter, a sequence of numbers separated by a comma |
| cityTarget |
ID cities: /ads.targeting.cities.get |
required parameter, a sequence of numbers separated by a comma |
| categories | category IDs:
/data.categories.get?ad_format =% category_id: {region_id: cost} | optional parameter |
| tags | keyword targeting | optional parameter, comma separated keyword sequence |
| day_limit | daily limit in rubles. for all types except clickunder | optional parameter, positive number |
| adult_content | presence of adult content in the advertising campaign:
0 - No; 1 - Yes | optional parameter, int (numeric value), default 0 |
| adult_site | display campaign ads on adult content sites:
0 - No; 1 - Yes | optional parameter, int (numeric value), default 0 |
| time_show | Time Targeting:
& nbsp; & nbsp; * - display in any hours and days of the week & nbsp; & nbsp; {} is an array, where the key is the name of the day of the week ["Sn", "Mn", "Tu", "Wd", "Th", "Fr", "Sa"]: & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: ‘*’ - all watches are weekly & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: [0, .., 23] - hours, separated by commas | optional parameter, * default |
| platforms | platform targeting: /data.platforms | comma separated numbers |
| browsers | browser targeting: /data.browsers | comma separated numbers |
| black_list | black list of sites where ads will not be shown | comma separated site ID number sequence |
| white_list | white list of sites where ads will not be shown | comma separated site ID number sequence |
| black_list_ip | ip lock | sequence of ip addresses separated by a comma or an array |
| status | start /pause campaign:
0 - suspended; 1 - running | optional parameter, int (numeric value), default 1 |
| deviceTarget |
ID devices: /ads.targeting.devices.get |
sequence of numbers separated by a comma |
| langTarget |
ID browser languages: /ads.targeting.langs.get |
sequence of numbers separated by a comma |
Example request URL:
http://api.kadam.net/ads.campaigns.update?app_id=127296&data={
"client_id": 127296,
"campaign_id":791229,
"regionTarget": [1],
"name": "test-native",
"link_url": "https://test.example.com/?campaign_id={campaign_id}%26browser={browser}%26price_model={price_model}",
"real_url": "https://test.example.com",
"sex": 2,
"age": "2,3",
"countryTarget": {
"1": { "bid": 0.1 },
"3": { "bid": 0.15 },
"16": { "bid": 0.2 }
},
"categories": [1001, 1125, 1126, 1127, 1128],
"day_limit": 500,
"all_limit": 5000,
"click_limit": 1000,
"conversion_limit": 50,
"adult_content": 1,
"adult_site": 1,
"time_show": {
"mn": "*",
"tu": [9, 10, 11],
"wd": [14, 15],
"th": "*",
"fr": [18, 19, 20],
"sa": "*",
"sn": "*"
},
"platforms": "1,2,4,16",
"browsers": "1,2,4,16,32,128",
"black_list": [1001, 1002, 1003],
"white_list": [2001, 2002, 2003],
"black_list_ip": ["192.168.1.1", "192.168.1.2"],
"deviceTarget": "1,2,3",
"langTarget": "1,2",
"status":1
}
Result:
Returns an array of responses to each request in the data array. The corresponding object in the output array contains the id of the client being changed and, in case of an error, the error_code and error_desc fields.
Errors:
100 - unknown campaign 102 - unknown client
List of campaign advertising campaign
To get a list of campaign advertising campaigns use the method ads.campaigns.get
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| client_id | Client ID from which ad campaigns are requested | int (numeric value) |
| include_archive | A flag that specifies whether to display archived ads:
0 - show only active campaigns; 1 - show all campaigns | Flag, can be 1 or 0 |
| campaign_ids | Filter for displayed ad campaigns.
Serialized JSON array containing campaign id. Only campaigns that are present in the campaign_ids and are campaigns of the specified advertising cabinet will be displayed. If the parameter is null, then all campaigns will be displayed. | String |
| with_bwlist | Black and white list transfer flag | any value (for example 1) |
| with_tags | Keyword Transfer Flag | any value (for example 1) |
| limit | limit on the number of campaigns returned. Used only if the campaign_ids parameter is null | int (numeric value) |
| offset | offset. Used in the same cases as the limit parameter | int (numeric value) |
Example request URL:
http://api.kadam.net/ads.campaigns.get?app_id=127296&client_id=127296&campaign_ids="[794221,791229,791504,789484,789012]"&include_archive=1& with_bwlist=1&with_tags=1
Result:
Returns an array of campaign objects, each of which contains the following fields:
response: {
count:% total%
items: [{
id - campaign identifier
name - campaign name
status - campaign status (0 - campaign stopped, 1 - campaign started, 2 - campaign deleted)
day_limit - campaign daily limit in rubles (0 - no limit is set)
all_limit - total campaign limit in rubles (0 - no limit is set)
ad_format - ad format
cost_type - payment type
link_url - link to the advertised object
sex
age - age
regions - region identifiers
categories - category identifiers.
adult_content - the presence of adult content
adult_site - display campaign ads on adult content sites
tags - keywords
bw_list - black and white list
}, ..]
}
Errors:
102 - unknown client
Archiving an advertising campaign
To archive an existing advertising campaign, use the ads.campaigns.delete
method
Ten (10) campaigns can be archived with a single request.
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| ids | Campaign id list separated by comma or array with id campaigns.
For example: “id1, id2, ..., idn“ or [id1, id2, ..., idn] | required parameter, string |
Example request URL:
http://api.kadam.net/ads.campaigns.delete?app_id=127296&ids="[794221,794222,791229]"
Result:
Returns an array of responses to each request. Each answer is either 0, which means successful deletion, or an error array.
Errors:
100 - unknown campaign 101 - campaign already archive 102 - unknown client
Receiving codes for CPA campaigns
Use the ads.campaigns.cpa.mode.get
method to get the codes for the CPA campaigns
| Parameters | Value | Additional attributes |
|---|---|---|
| campaign_id | campaign id | int (numeric value), required parameter |
Result:
Returns an object with data.
{
response: {
url:% url%
}
}
Getting a list of categories for a given filter
To return the list of categories for a given filter, use the ads.campaigns.categories.get
method
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| ad_format | ad format:
ads.campaigns.formats.get | required parameter, int (numeric value) |
| category_id | category id. limits displaying only by category id | optional parameter, int (numeric value) |
Example request URL:
http://api.kadam.net/ads.campaigns.categories.get?app_id=127296&ad_format=20
Result:
Returns an array of responses to queries in the response array.
response: {
count:% total%
items: [{
% category_id%: {
% region_id%: {
min:% min_cost%
max:% max_cost%
}
}
}, ..]
}
Getting the list of ad formats
Use the ads.campaigns.formats.get
method to get the list of ad formats.
Example request URL:
http://api.kadam.net/ads.campaigns.formats.get?app_id=127296
Result:
Returns an array of responses to queries in the response array.
response: {
count:% total%
items: [{
id:% format_id%
title: ‘% format title%’
}, ..]
}
Getting the list of platforms
For a list of platforms, use the ads.targeting.platforms.get
method
Result:
Returns an array of responses to queries in the response array.
response: {
count:%
items: [{
id:% platform_id%
title:% platform_name%,
mobile:% is mobile%
}, ..]
}
Getting Browser List
For a list of browsers, use the ads.targeting.browsers.get
method
Result:
Returns an array of responses to queries in the response array.
response: {
count:%
items: [{
id:% browser_id%,
title:% browser_name%,
}, ..]
}
Getting a list of conversion notifications for the CPA
To get a list of conversion notifications for CPA, use the ads.targeting.cpa.modes.get
method
Result:
Returns an array of responses to queries in the response array.
response: {
count:% total%
items: [{
id:% mode_id%
title: ‘% mode title%’
}, ..]
}
Getting a list of ages
To get the list of views, use the ads.targeting.ages.get
method
Result:
Returns an array of responses to queries in the response array.
response: {
count:%
items: [{
id:% age_id%
title:% age_name%
}, ..]
}
Getting a list of countries
To get the list of countries, use the ads.targeting.countries.get method
Result:
Returns an array of responses to queries in the response array.
response: {
count: %total%,
items: [{
id: %format_id%,
title: ‘%format title%’
},..]
}
Getting a list of regions
To get the list of regions, use the ads.targeting.regions.get method
Result:
Returns an array of responses to queries in the response array.
response: {
count: %total%,
items: [{
id: %format_id%,
title: ‘%format title%’
},..]
}
Getting a list of cities
To get the list of cities, use the ads.targeting.cities.get method
Result:
Returns an array of responses to queries in the response array.
response: {
count: %total%,
items: [{
id: %format_id%,
title: ‘%format title%’
},..]
}
Getting a list of devices
To get the list of devices, use the ads.targeting.devices.get method
Result:
Returns an array of responses to queries in the response array.
response: {
count: %total%,
items: [{
id: %format_id%,
title: ‘%format title%’
},..]
}
Getting a list of browser languages
To get the list of devices, use the browser languages ads.targeting.langs.get method
Result:
Returns an array of responses to queries in the response array.
response: {
count: %total%,
items: [{
id: %format_id%,
title: ‘%format title%’
},..]
}
Creating advertising agency clients
To create ad agency clients, use the ads.clients.put method
The allowable number of clients created with a single request is 50.
| Parameters | Value | Additional attributes |
|---|---|---|
| data | a serialized JSON array of objects describing the campaigns being created. See the client_specification object description below. | required parameter, string |
| client_specification | ||
| name | client name | string from 3 to 60 characters, required parameter |
| day_limit | daily limit in rubles | int (numeric value) |
Result:
Returns an array of responses to queries in the data array. The corresponding object in the output array contains the client information or the error array in case of an error (for each client separately).
{
client_id - client identifier;
name - the name of the client;
day_limit - client's daily limit in rubles;
}
Editing advertising agency clients
To edit ad agency clients, use the ads.clients.update method
The maximum number of clients edited with a single query is 50.
| Parameters | Value | Additional attributes |
|---|---|---|
| data | is a serialized JSON array of objects describing changes in clients. Description of client_mod_specification objects see below. | required parameter, string |
| client_mod_specification | ||
| client_id | ID of the client being edited | required parameter, positive number |
| name | client name | a string between 3 and 60 characters |
| day_limit | daily limit in rubles | positive number |
Result:
Returns an array of responses to each request in the data array. The corresponding object in the output array contains the id of the client being changed and, in case of an error, the error_code and error_desc fields.
Getting a list of advertising agency clients
To return the list of clients of an advertising agency, use the ads.clients.get method
| Parameters | Value | Additional attributes |
|---|---|---|
| client_ids | A list of client ids separated by commas. For example: “id1, id2, ..., idn“ | optional parameter, string |
Result:
Returns an array of client objects of the agency, each of which contains the following fields:
response: {
count:% total%
items: [{
client_id - client identifier;
name - the name of the client;
day_limit - client's daily limit in rubles;
balance - client's balance
}, ..]
}
Archiving advertising agency clients
For archiving ad agency clients, use the ads.clients.delete method
| Parameters | Value | Additional attributes |
|---|---|---|
| ids | List of clients' id by comma or array with id clients.
For example: “id1, id2, ..., idn“ or [id1, id2, ..., idn] | required parameter, string |
Result:
Returns an array of responses to each request. Each answer is either 0, which means successful deletion, or an error array.
Tying a client to an advertising agency
To bind a client to an advertising agency, use the ads.clients.bind.put method
| Parameters | Value | Additional attributes |
|---|---|---|
| client email address | string from 3 to 60 characters, required parameter | |
| password | client password (from account) | string from 3 to 60 characters, required parameter |
Result:
Returns:
{
“Bind”: true
}
in case of success. Or error in case of an error.
Detaching a client from an advertising agency
To detach a client from an advertising agency, use the ads.clients.unbind.put method
| Parameters | Value | Additional attributes |
|---|---|---|
| client_id | client id | int (numeric value) |
Result:
Returns:
{
“Unbind”: true
}
in case of success. Or error in case of an error.
Customer account replenishment
To replenish the client’s account, use the ads.clients.balance.put method
| Parameters | Value | Additional attributes |
|---|---|---|
| client_id | customer id to replenish | int (numeric value), required parameter |
| sum | rubles in rubles | int (numeric value) |
| back_url | url where the recharge system forwards the client | string (string) |
| system_id | replenishment system id:
data.balance.systems.get | int (numeric value), required parameter |
Result:
Returns the url for payment:
{
response: {
url:% url%
}
}
Creating advertisements
To create ads using the method ads.materials.put
The maximum allowable number of ads generated by a single request is 20.
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| data | is a serialized JSON array of objects describing the created ads. The description of ad_specification objects is given below. | required parameter, string |
| ad_specification | ||
| client_id | id of the client | int (numeric value), required parameter |
| campaign_id | id of the campaign in which the ad will be created | required parameter, int (numeric value) |
| title | ad title | required parameter |
| text | ad description | Required |
| link_url | link of the advertised object in the format: http://yoursite.com/ | |
| link_media | previously loaded media object (jpg, gif):
data.upload.media | |
| pause_after_moderate | pause posting moderation | |
| size | for banners only:
ads.materials.banner.sizes | |
| categories | Stacks by category, similar to campaigns:
array [category_id => cost] |
Not required if you do not set bids from campaign categories |
Example request URL:
http://api.kadam.net/ads.materials.put?app_id=127296&data={
"client_id": 127296,
"title": "testtest",
"link_url": "https://example.vre4/viewpage.action?pageId=3595534412",
"link_media": "http://my.kadam.net/uploads/afupre/678139c998762t1736522185r6423.jpg",
"link_media_rect": "http://my.kadam.net/uploads/afupre/678139c998762t1736522185r6423.jpg",
"campaign_id": 791504,
"pause_after_moderate": 1
}
Update ad data
Use the ads.materials.update
method to update ad data.
The maximum allowable number of ads generated by a single request is 20.
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| data | is a serialized JSON array of objects describing the created ads. The ad_specification object description is below. | required parameter, string |
| ad_specification | ||
| material_id | ad id | required parameter, int (numeric value) |
| status | start /pause material:
0 - suspended; 1 - running | optional parameter, int (numeric value), default 1 |
| bids | Geo bids:
array "bids":{"countryID":{"bid":cost}} coutries ID list - /ads.targeting.countries.get |
optional parameter |
| link_url | link of the advertised object in the format: http://yoursite.com/ | optional parameter |
Example request URL:
http://api.kadam.net/ads.materials.update?app_id=114863&data={"material_id":7090294, "status":1}
Archiving advertisements
For advertising ads using the method ads.materials.delete
The maximum number of clients edited with a single query is 50.
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| client_id | id of the client | int (numeric value), required parameter |
| account_id | advertising account ID | required parameter, int (numeric value) |
| ids | serialized JSON array containing ad IDs | required parameter, string |
Example request URL:
http://api.kadam.net/ads.materials.delete?app_id=127296&client_id=127296&account_id=127296&ids="[7359329,7339988,7339987]"
Result:
Returns an array of responses to each request. Each answer is either 0, which means successful deletion, or an error array.
Getting a list of advertisements
Use the ads.materials.get method to get the list of ads.
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| account_id | advertising account ID | required parameter, int (numeric value) |
| client_id | For advertising agencies. Client ID from which advertisements are requested. | int (numeric value) |
| archive | A flag that specifies whether to display archived ads:
0 - display only active ads; 1 - display all ads | Flag, can be 1 or 0 |
| campaign_ids | ad campaign filter.
Serialized JSON array containing campaign id. If the parameter is null, advertisements of all campaigns will be displayed. | string |
| material_ids | ad campaign filter.
Serialized JSON array containing ad id. If the parameter is null, all advertisements will be displayed. | string |
| limit | limit on the number of ads returned. Used only if the ad_ids parameter is null, and the campaign_ids parameter contains the id of only one campaign. | int (numeric value) |
| offset | offset. Used in the same cases as the limit parameter | int (numeric value) |
| ad_format | ad format: ads.campaigns.formats.get | required parameter, int (numeric value) |
Example request URL:
http://api.kadam.net/ads.materials.get?app_id=127296&account_id=127296&client_id=127296&archive=0&material_ids="7340006,7338000"&ad_format=20
Result:
Returns an array of ad objects, each of which contains the following fields:
- id - ad id
- name - the name of the ad
- campaign_id - Campaign ID
- link_url
- arhive
- ad_format - ad format
- cost_type - payment type
- all_limit - total ad limit in rubles
- 0 - no limit is set
- status - ad status:
- 0 - ad stopped;
- 1 - the ad is running;
- 2 - ad deleted
- approved - ad moderation status:
- 0 - the ad is awaiting moderation;
- 10 - Ad has been approved.
- 20 - ad disapproved
Getting a list of banner sizes
For a list of banner sizes, use the ads.materials.banner.sizes.get method
Example request URL:
http://api.kadam.net/ads.materials.banner.sizes.get?app_id=127296&client_id=127296
Result:
Returns an array of responses to requests in the response array:
response: {
count:% total%
items: [{
id:% banner_id%,
title: ‘% banner title%’
}, ..]
}
Getting the list of countries
To get the list of countries, use the data.geo.countries.get
method
Result:
Returns an array of responses to requests in the response array:
response: {
count:%
items: [{
id:% country_id%,
title:% country_name%
}, ..]
}
Getting a list of regions for a given filter
To get a list of regions for a given filter, use the data.geo.regions.get
method
| Parameters | Value | Additional attributes |
|---|---|---|
| country_id | country identifier obtained in the ads.geo.countries method | positive number, required parameter |
Result:
Returns an array of responses to requests in the response array:
response: {
count:%
items: [{
id:% region_id%
title:% region_name%
}, ..]
}
Get a list of available payment systems
To get a list of available payment systems, use the data.balance.systems.get
method
Result:
Returns an array of responses to requests in the response array:
response: {
count:% total%
items: [{
id:% pay_system_id%,
title: pay% pay system title% ’
}, ..]
}
Download media files
To upload media files (jpg, png, gif), use the data.upload.media.update
method
| Parameters | Value | Additional attributes |
|---|---|---|
| app_id | user id | int (numeric value), required parameter |
| ad_format | ad format: /ads.formats.get | int (numeric value) |
| file | CURLFile object or url or base64 |
Example cURL:
curl --location 'https://api.kadam.net/data.upload.media.update' \ --header 'Authorization: Bearer fdr6chfjfj8kjghgu99mdhh' \ --form 'ad_format="10"' \ --form 'file=@"/Users/user/Downloads/222 1 (2) (1).jpg"' \ --form 'app_id="127296"'
Result:
Returns an array with a reference to the target object or error in case of an error.
response: {
image: “% link%”
}
An example of sending a file using curl in php:
$ token = ‘received token’;
$ ad_format = объявления ad format ’;
$ app_id = ‘your app id’;
$ file = '@ /full path to file';
$ finfo = finfo_open (FILEINFO_MIME_TYPE);
$ finfo = finfo_file ($ finfo, $ link);
$ cFile = new \ CURLFile ($ link, $ finfo, basename ($ link));
$ post = array ('file' => $ cFile, 'ad_format' => $ ad_format, 'app_id' => $ app_id);
$ ignoreParams = array ('file'); //file field is not involved in the construction of the signature
ksort ($ post);
$ result = array ();
foreach ($ post as $ key => $ value) {
if (false == in_array ($ key, $ ignoreParams)) {
$ result [] = $ key. '='. urlencode ($ value);
}
}
$ result = implode ('&', $ result);
$ signature = md5 ($ result. $ token);
$ target_url = 'http://api.kadam.net/data.upload.media?signature='. $ signature;
$ ch = curl_init ();
curl_setopt ($ ch, CURLOPT_URL, $ target_url);
curl_setopt ($ ch, CURLOPT_POST, true);
curl_setopt ($ ch, CURLOPT_POSTFIELDS, $ post);
curl_setopt ($ ch, CURLOPT_RETURNTRANSFER, 1);
$ result = curl_exec ($ ch); //server response
Get the current server time
To get the current server time in ISO 8601 format, use the server.time.get
method
Result:
Returns an array of responses to requests in the response array:
{
iso8601:% time%
}
Money transfer for subsidiary accounts of the agency
To transfer money, use the ads.clients.balance.update method
| Parameters | Value | Additional attributes |
|---|---|---|
| client_id | Customer ID, money will be transferred to it. | Required |
| sum | transfer amount | Required |
| type | Operation Type | Required - always type = "transfer" |
| comment | Comment | Required - null value allowed |
The operation can be performed only if there are sufficient funds on the account
Money will be withdrawn from the user specified in the app_id
Result:
The result of the operation will be the withdrawal of funds from the primary user - an output transaction. And the transfer of money to the agency account is an input transaction.
Returns data as
Array
(
[status] => "success"
)
In case of error - error code
