Working with Advertisements

API Updates for Advertisements (02.06.2025)

The following changes have been made to the Advertisement list, Create advertisement, and Get advertisement details API endpoints:

1. New parameter target_bots:
   Added the target_bots parameter for targeting configuration. See the body parameter descriptions in the method documentation, as well as the request and response examples.

2. Added bot validation method (/api/advertisement/bots/validate?validate?bots=bot_1&bots=bot_2&bots=bot_3&account_id={account_id}):

   {
   	"bots": [
   		{
   			"id": 123456789,
   			"title": "Bot name 1",
   			"url": "t.me/bot_1",
   			"photo_url": "https://cdn4.telesco.pe/file/path_to_photo_url_for_bot_1.jpg"
   		},
   		{
   			"id": 123456780,
   			"title": "Bot name 2",
   			"url": "t.me/bot_2",
   			"photo_url": "https://cdn4.telesco.pe/file/path_to_photo_url_for_bot_2.jpg"
   		}
   	],
   	"errors": [
   		{
   			"code": "advertisement__target_bot_daily_users_limit_error",
   			"detail": "Advertisement: Target bot must have 1000+ daily users",
   			"url": "bot_3"
   		}
   	]
   }

3. New parameter tg_event_id:

   Added the new tg_event_id parameter for Pixel Tag configuration. See the body parameter descriptions in the create and edit advertisement methods.

Advertisement list

WARNING

Update as of 04.09.2025: A limit has been introduced on the limit parameter — a maximum of 500 records in the response.

GET v2/advertisement/?show_deleted=false&period=today&offset=0&limit=50&advertisement_titles=&campaign_names=

Usage example

https://client.adstat.pro/api/v2/advertisement/?period=today

Query parameters

Parameter	Type	Description
period	String	Filter results by creation time: today, all, yesterday, starts_month.
offset	Number	Pagination offset (default: 0).
limit	Number	Number of records in the response (maximum: 500, default: 50). Previously, there was no cap.

Response example

{
	"data": [
		{
			"account_name": "SOME_test",
			"action_type": null,
			"ad_text": "example text",
			"ad_type": "target_bots",
			"advertisement_title": "example title",
			"balance": 0.0,
			"campaign_id": 12345,
			"campaign_name": "Default",
			"clicks": 0,
			"cpc": 0,
			"cpm": 3.0,
			"cps": 0,
			"created_dt": "09.01.1998 09:04:26",
			"ctr": 0,
			"cvr": 0,
			"goals": 0,
			"id": 1364756,
			"impressions": 0,
			"kktu_codes": [],
			"object": "t.me/example",
			"opened": null,
			"spent": 0,
			"status": "stopped",
			"status_updated_dt": "1998-01-09T09:29:27.311931+00:00",
			"target_topics": []
		}
	]
}

Response field descriptions

Field	Type	Description
account_name	String	Account name.
action_type	String/null	Target action type.
ad_text	String	Creative text.
ad_type	String	Advertisement type (target_channels, target_users, target_search, target_bots).
advertisement_title	String	Advertisement title.
balance	Number	Advertisement balance.
campaign_id	Number	Campaign ID.
campaign_name	String	Campaign name.
clicks	Number	Number of clicks.
cpc	Number	Cost per click.
cpm	Number	Cost per thousand impressions.
cps	Number	Cost per goal.
created_dt	String	Creation date and time.
ctr	Number	Click-through rate.
cvr	Number	Conversion rate.
goals	Number	Number of goals achieved.
id	Number	Unique advertisement ID.
impressions	Number	Number of impressions.
kktu_codes	Array of strings	KKTU codes.
object	String	Promoted object.
opened	Number/null	Video opens.
spent	Number	Amount spent.
status	String	Advertisement status.
status_updated_dt	String	Status update date and time.
target_topics	Array of strings	Targeting topic list.

Create advertisement

WARNING

Update as of 21.05.2026: Added the ad_object parameter. The field becomes required when targeting a channel invite link.

POST /api/advertisement/telegram/

Usage example

https://client.adstat.pro/api/advertisement/telegram/

Body parameters

Field	Type	Description
campaign_id	Number	Campaign ID.
title	String	Advertisement title.
text	String	Advertisement text.
promote_url	String	Promoted object URL.
ad_object	String	Required when targeting a channel invite link. URL of the destination Telegram channel.
cpm	Number	Cost per 1,000 impressions.
budget	Number	Advertising budget.
langs	Array of strings	Targeting languages.
topics	Array of numbers	Targeting topics.
topics_verbose	Array of strings	Topic identifiers.
channels	Array of numbers	Targeting channels.
channels_verbose	Array of strings	Channel identifiers.
exclude_topics	Array of numbers	Excluded topics.
exclude_topics_verbose	Array of strings	Excluded topic identifiers.
exclude_channels	Array of numbers	Excluded channels.
exclude_channels_verbose	Array of strings	Excluded channel identifiers.
media_token	String	Media file token.
other_info	String	ERID token (for manual labeling).
split_by	Array of strings	Targeting split parameters.
ad_source	String	Creation source (web_api).
ad_type	String	Targeting type (target_channels, target_users, target_bots).
countries	Array of strings	Targeting countries.
locations	Array of strings	Targeting cities.
locations_verbose	Array of strings	City identifiers.
audiences	Array of numbers	Targeting audiences.
exclude_audiences	Array of numbers	Excluded audiences.
website_name	String	Website name (for external links).
views_per_user	Number	Views per user limit.
show_picture	Boolean	Show avatar.
promote_url_picture_id	String	Object image ID.
exclude_politic	Boolean	Exclude political content.
all_topics_interested_users	Boolean	Target users interested in all topics.
device	String	Targeting device (all).
target_user_channels	Array of strings	User targeting channels.
target_user_channels_verbose	Array of strings	User channel identifiers.
exclude_target_user_channels	Array of strings	Excluded user channels.
exclude_target_user_channels_verbose	Array of strings	Excluded user channel identifiers.
button_type	String	Button type (open_website).
daily_budget	Number	Daily budget limit.
after_moderation_status	String	Status after moderation.
start_date	String (ISO 8601)	Start date.
end_date	String (ISO 8601)	End date.
schedule	Object	Delivery schedule.
use_selected_timezone	Boolean	Use timezone.
schedule_timezone	Number	Schedule timezone.
promote_url_type	String	URL type (website, channel).
currency_code	String	Currency code (EUR).
use_account_currency	Boolean	Use account currency.
only_crypto	Boolean	Show only in crypto channels.
exclude_crypto	Boolean	Exclude crypto channels.
kktu_ids	Array of strings	KKTU identifiers.
target_search	Array of strings/null	Search target queries.
target_bots	Array of objects/null	Bots for targeting.
tg_event_id	String/null	Pixel Tag event identifier

Body example

{
	"campaign_id": 4567123,
	"title": "123testBody_title",
	"text": "123testBody",
	"promote_url": "t.me/somechannel",
	"ad_object": "t.me/target_channel",
	"cpm": 2,
	"budget": 0.01,
	"only_crypto": false,
	"exclude_crypto": false,
	"media_token": "zHN9jkeds9KpcX34XoaslFXnKUqzyr3K5tBx0xAcr2_MGIisHaXA3BLnfB1yOcFudOa8qC",
	"audiences": [],
	"exclude_audiences": [],
	"langs": [],
	"topics": [1, 2],
	"topics_verbose": [],
	"channels": [],
	"channels_verbose": [],
	"exclude_topics": [],
	"exclude_topics_verbose": [],
	"exclude_channels": [],
	"exclude_channels_verbose": [],
	"split_by": [],
	"other_info": null,
	"ad_source": "web_api",
	"ad_type": "target_bots",
	"countries": [],
	"locations": [],
	"locations_verbose": [],
	"website_name": "",
	"views_per_user": 1,
	"show_picture": false,
	"promote_url_picture_id": null,
	"all_topics_interested_users": false,
	"device": "all",
	"target_user_channels": [],
	"target_user_channels_verbose": [],
	"exclude_target_user_channels": [],
	"exclude_target_user_channels_verbose": [],
	"button_type": null,
	"daily_budget": 0,
	"after_moderation_status": "on hold",
	"start_date": null,
	"end_date": null,
	"schedule": {
		"mon": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"tue": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"wed": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"thu": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"fri": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"sat": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"sun": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		]
	},
	"use_selected_timezone": true,
	"schedule_timezone": 10800,
	"promote_url_type": "channel",
	"currency_code": "EUR",
	"use_account_currency": false,
	"kktu_ids": ["some_uid_kktu"],
	"target_search": null,
	"target_bots": [
		{
			"id": 123456789,
			"url": "t.me/bot_1"
		},
		{
			"id": 123456780,
			"url": "t.me/bot_2"
		}
	],
	"tg_event_id": "JuKiaLISFD"
}

Get advertisement details

GET /api/advertisement/telegram/{ad_id}

Usage example

https://client.adstat.pro/api/advertisement/telegram/{ad_id}

Query parameters

Parameter	Type	Description
ad_id	Number	Advertisement identifier

Response example

{
	"ad_id": 0,
	"telegram_id": 999999999,
	"account_id": "ACCTEST_1111",
	"account_name": "TEST",
	"campaign_id": 56521378,
	"campaign_name": "Campaign test",
	"title": "Test promote title",
	"text": "Test promote text",
	"promote_url": "https://cryptosite.ru/",
	"promote_url_title": "Crypto Channel",
	"promote_url_photo": "/file/test_token.jpg",
	"media": {
		"token": "test_token",
		"url": "https://cdn4.telesco.pe/file/test_token.jpg",
		"type": "image"
	},
	"cpm": 1.5,
	"budget": 10.0,
	"langs": [],
	"topics": [],
	"channels": [],
	"exclude_topics": [],
	"exclude_channels": [],
	"other_info": "erid: test token",
	"decline_reason": [],
	"status": "active",
	"status_updated_dt": "2024-12-04T07:24:45.344358+00:00",
	"cannot_edit_fields": [],
	"ad_type": "target_bots",
	"countries": [],
	"user_locations": [],
	"audiences": [],
	"exclude_audiences": [],
	"is_audiences": false,
	"is_exclude_audiences": false,
	"website_name": "Crypto Site",
	"is_website": true,
	"views_per_user": 1,
	"show_picture": false,
	"exclude_politic": null,
	"promote_url_picture_id": "https://ads.telegram.org/file/test..asd",
	"all_topics_interested_users": null,
	"device": null,
	"target_user_channels": [],
	"exclude_target_user_channels": [],
	"button_type": "learn_more",
	"daily_budget": 2.0,
	"after_moderation_status": "active",
	"start_date": null,
	"end_date": null,
	"schedule": {
		"mon": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"tue": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"wed": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"thu": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"fri": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"sat": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		],
		"sun": [
			0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
			21, 22, 23
		]
	},
	"use_selected_timezone": true,
	"schedule_timezone": 10800,
	"website_photo_url": "test",
	"tg_account_type": 1,
	"currency": "EUR",
	"only_crypto": false,
	"exclude_crypto": false,
	"kktu_ids": ["some_uid_kktu"],
	"target_search": [],
	"target_bots": [
		{
			"url": "t.me/bot_1",
			"title": "Bot name 1",
			"photo_url": "https://cdn4.telesco.pe/file/path_to_photo_url_for_bot_1.jpg"
		},
		{
			"url": "t.me/bot_2",
			"title": "Bot name 2",
			"photo_url": "https://cdn4.telesco.pe/file/path_to_photo_url_for_bot_2.jpg"
		}
	],
	"event": { "tg_id": "KuliaGnSD", "name": "test1" }
}

Response field descriptions

Parameter	Type	Description
ad_id	Number	Unique advertisement ID.
telegram_id	Number	Advertisement ID in Telegram.
account_id	String	Account ID.
account_name	String	Account name.
campaign_id	Number	Campaign ID.
campaign_name	String	Campaign name.
title	String	Advertisement title.
text	String	Advertisement text.
promote_url	String	Promoted object URL.
promote_url_title	String	Promoted object title.
promote_url_photo	String	Path to the object image.
media	Object	Media data (token, url, type).
cpm	Number	Cost per 1,000 impressions.
budget	Number	Total budget.
langs	Array of strings	Targeting languages.
topics	Array of strings	Targeting topics.
channels	Array of strings	Targeting channels.
exclude_topics	Array of strings	Excluded topics.
exclude_channels	Array of strings	Excluded channels.
other_info	String	Additional information (ERID).
decline_reason	Array of objects	Rejection reasons.
status	String	Advertisement status.
status_updated_dt	String	Status update date.
cannot_edit_fields	Array of strings	Non-editable fields.
ad_type	String	Targeting type.
countries	Array of strings	Targeting countries.
user_locations	Array of strings	Targeting cities.
audiences	Array of numbers	Targeting audiences.
exclude_audiences	Array of numbers	Excluded audiences.
is_audiences	Boolean	Audience targeting is used.
is_exclude_audiences	Boolean	Excluded audiences are used.
website_name	String	Website name.
is_website	Boolean	Whether the promoted object is a website.
views_per_user	Number	Views per user limit.
show_picture	Boolean	Show avatar.
exclude_politic	Boolean	Exclude political content.
promote_url_picture_id	String	Object image ID.
all_topics_interested_users	Boolean	Target users interested in all topics.
device	String	Targeting device.
target_user_channels	Array of strings	User targeting channels.
exclude_target_user_channels	Array of strings	Excluded user channels.
button_type	String	Button type.
daily_budget	Number	Daily budget limit.
after_moderation_status	String	Status after moderation.
start_date	String (ISO 8601)	Start date.
end_date	String (ISO 8601)	End date.
schedule	Object	Delivery schedule.
use_selected_timezone	Boolean	Use timezone.
schedule_timezone	Number	Schedule timezone.
website_photo_url	String	Website image URL.
tg_account_type	Number	Telegram account type.
currency	String	Currency code.
only_crypto	Boolean	Show only in crypto channels.
exclude_crypto	Boolean	Exclude crypto channels.
kktu_ids	Array of strings	KKTU identifiers.
target_search	Array of strings/null	Search target queries.
target_bots	Array of objects/null	Bots for targeting.
event.tg_event_id	String/null	Pixel Tag event identifier
event.name	String/null	Pixel Tag event name

Edit advertisement

PUT /api/advertisement/telegram/{ad_id}

Usage example

https://client.adstat.pro/api/advertisement/telegram/{ad_id}

Query parameters

Parameter	Type	Description
ad_id	Number	Advertisement identifier

Body example

{
	"title": "123",
	"text": "test",
	"promote_url": "https://test.ru",
	"cpm": 2,
	"other_info": "erid: test",
	"media_token": null,
	"website_name": "Яндекс",
	"views_per_user": 1,
	"show_picture": false,
	"promote_url_picture_id": "test_token",
	"button_type": "open_website",
	"daily_budget": 0,
	"after_moderation_status": "active",
	"start_date": null,
	"end_date": null,
	"schedule": null,
	"use_selected_timezone": false,
	"schedule_timezone": null,
	"kktu_ids": ["some_uid_kktu"]
}

Body parameter descriptions

Parameter	Type	Description
title	String	Advertisement title.
text	String	Advertisement text.
promote_url	String	Promoted object URL.
cpm	Number	Cost per 1,000 impressions.
other_info	String	ERID token (for manual labeling).
media_token	String/null	Media file token.
website_name	String	Website name (for external links).
views_per_user	Number	Views per user limit.
show_picture	Boolean	Show avatar.
promote_url_picture_id	String	Object image ID.
button_type	String	Button type (open_website).
daily_budget	Number	Daily budget limit.
after_moderation_status	String	Status after moderation.
start_date	String (ISO 8601)	Start date.
end_date	String (ISO 8601)	End date.
schedule	Object/null	Delivery schedule.
use_selected_timezone	Boolean	Use timezone.
schedule_timezone	Number/null	Schedule timezone.
kktu_ids	Array of strings	KKTU identifiers.

Upload media

POST api/v1/advertising/telegram/upload_media?account_id={account_id}

Usage example

https://clientapi.adstat.pro/api/v1/advertising/telegram/upload_media?account_id=ACC0000222

Query parameters

Parameter	Type	Description
account_id	String	Account identifier (ACC0000222).

Body

The request body includes the media parameter with a binary file.

JavaScript example:

const mediaFormData = new FormData();
mediaFormData.append("media", file);

Response

{
	"media_token": "test_token",
	"content_type": "image/jpeg",
	"error": null
}

Parameter	Type	Description
media_token	String	Unique media file token.
content_type	String	File MIME type (image/jpeg, video/mp4).
error	String/null	Error description, or null on success.

ORD KKTU

Important information

For cabinets with automatic labeling, KKTU selection is required. An advertisement cannot be created without specifying a KKTU identifier.

Get available KKTU list

GET /api/kktu

Request example

https://clientapi.adstat.pro/api/kktu/

Response example

{
	"items": [
		{
			"id": "0193d46f-1888-7553-8d09-53116794ddb3",
			"tree_id": 1000000,
			"code": "1",
			"name": "АЛКОГОЛЬНЫЕ НАПИТКИ, ТАБАЧНЫЕ ИЗДЕЛИЯ",
			"children": [
				{
					"id": "0193d46f-1889-7cb1-b1a0-97f889d945ad",
					"tree_id": 1001000,
					"code": "1.1",
					"name": "АЛКОГОЛЬНЫЕ НАПИТКИ",
					"children": [
						{
							"id": "0193d46f-1889-7cb1-b1a0-9800191b62e9",
							"tree_id": 1001001,
							"code": "1.1.1",
							"name": "ВИНО",
							"children": []
						},
						{
							"id": "0193d46f-1889-7cb1-b1a0-98184fd25317",
							"tree_id": 1001002,
							"code": "1.1.2",
							"name": "КРЕПКИЕ АЛКОГОЛЬНЫЕ НАПИТКИ",
							"children": []
						},
						{
							"id": "0193d46f-1889-7cb1-b1a0-982f7acfc72c",
							"tree_id": 1001003,
							"code": "1.1.3",
							"name": "АЛКОГОЛЬНЫЕ НАПИТКИ (РАЗНОЕ)",
							"children": []
						},
						{
							"id": "0193d46f-1889-7cb1-b1a0-9830cb4b6bab",
							"tree_id": 1001004,
							"code": "1.1.4",
							"name": "СЛАБОАЛКОГОЛЬНЫЕ НАПИТКИ",
							"children": []
						}
					]
				},
				{
					"id": "0193d46f-1889-7cb1-b1a0-9842865b2e1b",
					"tree_id": 1002000,
					"code": "1.2",
					"name": "ТАБАЧНЫЕ ИЗДЕЛИЯ",
					"children": [
						{
							"id": "0193d46f-1889-7cb1-b1a0-985cd2f1e210",
							"tree_id": 1002001,
							"code": "1.2.1",
							"name": "ТАБАЧНЫЕ ИЗДЕЛИЯ",
							"children": []
						}
					]
				}
			]
		}
	]
}

How to fill kktu_ids

• The kktu_ids field is filled with the id from the third nesting level.
• You cannot use id values from the first or second level.
• Only one value may be selected when creating or editing an advertisement.

Pixel Tag

Get available Pixel Tag events

GET /api/pixel_events/?account_id={account_id}

Request example

https://clientapi.adstat.pro/api/pixel_events/?account_id={account_id}

Response example

{
	"items": [
		{
			"id": "test_event_some_property",
			"pixel_id": "test_event_some_property",
			"tg_event_id": "test_event_some_property",
			"title": "test_event_some_property",
			"type": "custom",
			"status": "inactive",
			"ads_count": 1,
			"created_at": "2025-06-04T14:36:45+00:00",
			"last_triggered_at": null,
			"code_snippet": "<script>\ntgp(\"event\",\"test_event_some_property\");\n</script>"
		}
	]
}

How to fill tg_event_id

• The tg_event_id field is filled with tg_event_id from the list of available Pixel Tag events.
• Each cabinet has its own set of Pixel Tag events.
• Only one value may be selected when creating or editing an advertisement.

---

Working with phone number audiences

Important: This functionality is available only for advertising cabinets with geolocation set to Uzbekistan.

---

Get available audiences

Method: GET

URL: /api/advertisement/telegram/{account_id}/audiences/

Request example:

GET https://clientapi.adstat.pro/api/advertisement/telegram/{account_id}/audiences/

Response example:

[
	{
		"telegram_id": 1,
		"title": "phone_numbers_1"
	},
	{
		"telegram_id": 2,
		"title": "phone_numbers_2"
	}
]

---

Create a new audience

Method: POST

URL: /api/advertisement/telegram/{account_id}/audiences

Creates a new audience list from an uploaded file with phone numbers.

Request example:

POST https://clientapi.adstat.pro/api/advertisement/telegram/ACC010101010101/audiences

Request parameters (Form Data):

Field	Type	Description	Required
title	String	Name of the audience being created	Yes
audience	File	Binary file containing phone numbers	Yes

File format:

You can upload a CVS or txt file up to 10 MB containing a list of phone numbers or their SHA256 hashes, separated by commas or line breaks. Rules for building the number database:

• Phone number format — digits only, without plus signs or other symbols.

• The number must be in international format, i.e. start with 998 for Uzbekistan.

• The file must contain at least 1,000 phone numbers.

Request body example:

(The body is sent as multipart/form-data, so it is not serialized as JSON. Below is a conditional representation:)

Content-Type: multipart/form-data

title=12345
audience=<file with phone numbers>