You can create and manage API Keys via
https://dashboard.mybid.io/key-gateways
Each request returns a response in the format:
{
"code": int,
"message": text,
"data": json
}
code - Status code of the responsemessage - Error messagedata - Data returned in response to the request200 - Request completed successfully400 - Validation error401 - Authorization issues500 - Internal errorThe following rules apply to data from /gateway/v1/api/application/* and to request fields that
reference those dictionaries (campaign updates, change-task creation, and similar).
value vs labelDo not use label as an identifier. A dictionary row may look like this:
{
"value": "mobile",
"label": "Mobile devices"
}
Use only value (here: "mobile") in API requests and targeting.
From GET /gateway/v1/api/application/usage-types, each item may include several fields. When you
send usage_type or usage_type_black, pass only the string from type:
{
"type": "mainstream",
"label": "Mainstream"
}
Example in a request: "usage_type": ["mainstream"] — not the label text.
Versions may be any values you need; each version must be a JSON string (for example a decimal like
"120.5"). Example whitelist shape:
{
"browser_families_versions_whitelist": {
"chrome": ["120.5", "131", "142.25"]
}
}
Each skin row from GET /gateway/v1/api/application/skins looks like:
{
"id": 1,
"name": "skin-a"
}
In creatives[].skins when creating an inpage campaign, pass only the name string
(here: "skin-a"), not id.
From POST /gateway/v1/api/application/cities, data is an array of city name strings.
Pass those strings in cities / cities_black when creating or updating a campaign.
From GET /gateway/v1/api/application/isp, data is an array of ISP name strings. Pass
those strings in provider / provider_black when creating or updating a campaign.
GET /gateway/v1/api/current-balanceOnly the API key needs to be passed in the request.
{
"code": int,
"message": text,
"data": {
"current_balance": float
}
}
current_balance - current balance
curl --location 'http://api.mybid.io/gateway/v1/api/current-balance' \
--header 'X-Auth-Token: {{api_key}}'
{
"code": 401,
"message": "api key is not valid",
"data": null
}
curl --location 'http://api.mybid.io/gateway/v1/api/current-balance' \ --header 'X-Auth-Token: *****MRCP'
{
"code": 200,
"message": "",
"data": {
"current_balance": 6849.651174751568
}
}
GET /gateway/v1/api/campaignsOnly the API key needs to be passed in the request.
{
"code": int,
"message": text,
"data": [{
"id": int,
"name": text,
"adtype": text,
"budget": float,
"status": text,
"tracking_url": text,
"daily_budget": float,
"Total_spend": float,
"daily_spend": float,
"bid": float,
"traffic_stop_reason": text
}]
}
id - campaign IDname - campaign nameadtype - campaign typebudget - campaign budgetstatus - campaign statustracking_url - URL to which users are redirecteddaily_budget - campaign daily budgetTotal_spend - campaign total spenddaily_spend - campaign daily spendbid - campaign bidtraffic_stop_reason - the reason for stopping the campaign from receiving traffic (no stop
reason, daily budget exceeded, total budget exceeded, advertiser balance exceeded) curl --location 'http://api.mybid.io/gateway/v1/api/campaigns' \ --header 'X-Auth-Token: *****MRCP'
{
"code": 200,
"message": "",
"data": [{
"id": 502,
"name": "test_inpage_adv_direct",
"adtype": "inpage",
"budget": 0,
"status": "active",
"tracking_url": "https://mybid.io/campaigns/new",
"daily_budget": 0,
"total_spend": 86.03763403306333,
"daily_spend": 0,
"bid": 0.00015,
"traffic_stop_reason": "total_budget_exceeded"
},
{
"id": 509,
"name": "test_c_mng_dir",
"adtype": "push",
"budget": 0,
"status": "paused",
"tracking_url": "https://mybid.io/campaigns/new",
"daily_budget": 0,
"total_spend": 111.12182032043002,
"daily_spend": 0,
"bid": 0.001,
"traffic_stop_reason": "daily_budget_exceeded"
},
{
"id": 510,
"name": "test_inpage_adv_direct1",
"adtype": "inpage",
"budget": 0,
"status": "paused",
"tracking_url": "https://mybid.io/campaigns/new",
"daily_budget": 0,
"total_spend": 185.07603906435966,
"daily_spend": 0,
"bid": 0.001,
"traffic_stop_reason": "no_stop_condition"
}]
}
GET /gateway/v1/api/campaign/status/:idYou need to pass the API key and specify the campaign ID in the request parameters to get the campaign status.
{
"code": int,
"message": text,
"data": {
"id": int,
"status": text
}
}
id - campaign IDstatus - campaign statuscurl --location 'http://api.mybid.io/gateway/v1/api/campaign/status/382' \ --header 'X-Auth-Token: *****MRCP'
{
"code": 200,
"message": "",
"data": {
"id": 382,
"status": "active"
}
}
curl --location 'http://api.mybid.io/gateway/v1/api/campaign/status/3820000' \ --header 'X-Auth-Token: *****MRCP'
{
"code": 204,
"message": "content not found",
"data": null
}
GET /gateway/v1/api/campaign/:idYou need to pass the API key and specify the campaign ID in the request parameters to get the campaign data.
{
"code": int,
"message": text,
"data": {
"id": int,
"name": text,
"adtype": text,
"budget": float,
"status": text,
"tracking_url": text,
"os_type_familie_version_whitelist": {"os_type": {"family": [1,2,3 ("version")]}},
"os_type_familie_version_blacklist": {"os_type": {"family": [1,2,3 ("version")]}},
"capping_settings": [text],
"capping_unique_settings": string,
"daily_budget": float,
"hourly_budget": float,
"bid": float,
"bid_by_source": {text: float, text: float},
"black_list": [text],
"white_list": [text],
"smart_purchase": boolean,
"traffic_qualities": [text],
"countries": [text],
"countries_black": [text],
"cities": [text],
"cities_black": [text],
"provider": [text],
"provider_black": [text],
"ip_range": [object],
"ip_range_black": [object],
"browser_families_versions_whitelist": object,
"browser_families_versions_blacklist": object,
"work_schedule": object,
"work_schedule_black": object,
"creatives": [
{
"id": int,
"title": text,
"description": text,
"is_active": boolean,
"skins": [text],
"image": text,
"icon": text,
"is_mandatory_skins": boolean
}
]
}
}
id - campaign IDname - campaign nameadtype - campaign ad formatbudget - campaign budgetstatus - campaign statustracking_url - tracking URLos_type_familie_version_whitelist - whitelist for OS type, family, and version filteringos_type_familie_version_blacklist - blacklist for OS type, family, and version filteringcapping_settings - capping settingscapping_unique_settings - type of user uniqueness determination (“ip“ or “ip+ua“)daily_budget - daily campaign budgethourly_budget - campaign spend limit per calendar hour (UTC); 0 means no limitbid - campaign bidbid_by_source - campaign bid by source listblack_list - blacklist sourcewhite_list - whitelist sourcesmart_purchase - SmartCPC traffic purchase. Use only for adtype: popunder, inpagetraffic_qualities - traffic quality values selected for the campaign: an array with
"premium", "optimum" or both.countries, countries_black - ISO 3166-1 alpha-2 country codescities, cities_black - city name stringsprovider, provider_black - ISP (internet service provider) name stringsip_range, ip_range_black - arrays of
{ "ip_range_min": text, "ip_range_max": text }. Only IPv4 is supported; IPv6 and CIDR masks (for
example 1.1.1.0/24) are not allowed. Example:
[{ "ip_range_min": "1.1.1.1", "ip_range_max": "1.1.1.10" }]
browser_families_versions_whitelist, browser_families_versions_blacklist - object:
browser family → list of version stringscreatives - campaign creatives (may be empty). Use id to reuse a creative when
creating a new campaign via Create Campaign. Fields:
id - creative IDtitle, description - creative textis_active - whether the creative is activeskins - skin namesimage, icon - CDN URLs of creative assetsis_mandatory_skins - skins delivery modecurl --location 'http://api.mybid.io/gateway/v1/api/campaign/15964' \ --header 'X-Auth-Token: *****MRCP'
{
"code": 200,
"message": "",
"data": {
"id": 15964,
"name": "test_push",
"adtype": "push",
"budget": 0,
"status": "paused",
"tracking_url": "https://mybid.io/campaigns",
"os_type_familie_version_whitelist": {
"mobile": {
"android": [3, 5, 7]
}
},
"os_type_familie_version_blacklist": {},
"capping_settings": [
{
"type": "impression",
"limit": 1,
"duration": 2
},
{
"type": "click",
"limit": 1,
"duration": 2
}
],
"capping_unique_settings": "ip+ua",
"daily_budget": 95.07,
"bid": 0.4,
"bid_by_source": {
"123": 0.1,
"124": 0.1
},
"black_list": ["11", "12", "14", "15", "16"],
"white_list": ["1", "2"],
"smart_purchase": false,
"countries": ["US", "DE"],
"countries_black": ["RU"],
"cities": ["New York"],
"cities_black": ["Moscow"],
"provider": ["Armtech"],
"provider_black": ["Avanti"],
"ip_range": [
{ "ip_range_min": "1.1.1.1", "ip_range_max": "1.1.1.10" }
],
"ip_range_black": [
{ "ip_range_min": "10.0.0.1", "ip_range_max": "10.0.0.10" }
],
"browser_families_versions_whitelist": {
"chrome": ["131"]
},
"browser_families_versions_blacklist": {
"firefox": ["120"]
},
"creatives": [
{
"id": 21858,
"title": "Promo",
"description": "desc",
"is_active": true,
"skins": ["skin-a"],
"image": "https://cdn.example/img.png",
"icon": "",
"is_mandatory_skins": false
}
]
}
}
curl --location 'http://api.mybid.io/gateway/v1/api/campaign/15964000' \ --header 'X-Auth-Token: *****MRCP'
{
"code": 204,
"message": "content not found",
"data": null
}
POST /gateway/v1/api/statisticPass the required fields in the request body:
{
"campaigns": [int],
"ad_types": [text],
"countries": [text],
"os_types": [text],
"os_families": [text],
"date_from": "YYYY-MM-DD",
"date_to": "YYYY-MM-DD",
"group_by": text
}
campaigns - list of campaign IDsad_types - list of ad types ("push", "native", "popunder", "inpage", "banner", "video")countries - list of countries (ISO
3166-1 alpha-2)os_types - list of operating system types ("computer", "tablet", "mobile", "console",
"wearable", "smarttv") limitation with group_by (see the last point)os_families - list of operating system families ("windowsphone", "windows", "macosx", "ios",
"android", "blackberry", "chromeos", "kindle", "webos", "playstation", "xbox", "nintendo", "linux") limitation
with group_by (see the last point) date_from - start date of the statistic (format: YYYY-MM-DD)date_to - end date of the statistic (format: YYYY-MM-DD)group_by - how the data should be grouped (options: "campaign", "os", "country", "day",
"source", "spot", "creative", "country_source_campaign")group_by with os_types or os_families filter - how the data should be grouped (options: "os",
"spot", "creative"). Not allowed with "source" or "country_source_campaign"{
"code": 200,
"message": "ok",
"data": {
"goals": [],
"stats": [
{
"campaign_id": int, // if you choose group by campaign or country_source_campaign
"creative_id": int, // if you choose group by creative
"source_id": text, // if you choose group by source or country_source_campaign
"spot_id": text, // if you choose group by spot
"date": text, // if you choose group by day
"country": text, // if you choose group by country or country_source_campaign
"platform": text, // if you choose group by os
"clicks": int,
"conversions": int,
"cr": float,
"ctr": float,
"impressions": int,
"platform": text,
"revenue": float,
"spent": float,
"cv": float,
"roi": float,
"ecpa": float,
"goals": [
{
"id": int,
"conversions": float,
"ecpa": float,
"cr": float,
"cv": float,
"revenue": float,
"roi": float
}
]
}
],
"summary": {
"clicks": int,
"conversions": int,
"cr": float,
"ctr": float,
"cpl": float, // deprecated
"impressions": int,
"revenue": float,
"spent": float,
"cv": float,
"roi": float,
"ecpa": float
}
}
}
stats - List of statistics based on the group_by parameter. For
group_by: "country_source_campaign" each row contains country,
source_id and campaign_id together
summary - Summary statistics of the entire responsecurl --location --request POST 'http://api.mybid.io/gateway/v1/api/statistic' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"campaigns": [480],
"ad_types": ["push", "inpage"],
"countries": ["LK", "US"],
"os_types": ["mobile", "computer"],
"os_families": ["android", "ios"],
"date_from": "2024-09-01",
"date_to": "2024-09-20",
"group_by": "country"
}'
{
"code": 200,
"message": "ok",
"data": {
"goals": [],
"stats": [
{
"country": "US",
"clicks": 1508488,
"conversions": 2494,
"cr": 0.165,
"ctr": 4.42,
"cpl": 0.028,
"impressions": 34125286,
"platform": "ios",
"revenue": 0,
"spent": 3207.648458369033,
"cv": 0,
"roi": -100,
"goals": [
{
"id": 1,
"conversions": 0.02,
"ecpa": 0.3,
"cr": 0.001,
"cv": 0.01,
"revenue": 0.001,
"roi": 0.5
}
]
}
],
"summary": {
"clicks": 1508488,
"conversions": 2494,
"cr": 0.165,
"ctr": 4.42,
"cpl": 0.028,
"impressions": 34125286,
"revenue": 0,
"spent": 3207.648458369033,
"cv": 1,
"roi": -99
}
}
}
curl --location --request POST 'http://api.mybid.io/gateway/v1/api/statistic' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"campaigns": [480, 490],
"countries": ["US", "DE"],
"date_from": "2024-09-01",
"date_to": "2024-09-20",
"group_by": "country_source_campaign"
}'
{
"code": 200,
"message": "ok",
"data": {
"stats": [
{
"country": "US",
"source_id": "839",
"campaign_id": 480,
"clicks": 12000,
"conversions": 30,
"cr": 0.25,
"ctr": 1.2,
"impressions": 1000000,
"revenue": 0,
"spent": 45.5
}
],
"summary": {
"clicks": 12000,
"conversions": 30,
"cr": 0.25,
"ctr": 1.2,
"impressions": 1000000,
"revenue": 0,
"spent": 45.5
}
}
}
curl --location --request POST 'http://api.mybid.io/gateway/v1/api/statistic' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"campaigns": [480, 490],
"ad_types": ["push", "inpage"],
"countries": ["LK", "US"],
"os_types": ["mobile" , "computer"],
"os_families": ["android", "ios"],
"date_from": "2024-09-01",
"date_to": "2024-09-20",
"output_format": "csv",
"group_by": "country"
}'
{
"code": 200,
"message": "ok",
"data": {
"filename": "assets/uploads/by_country_from_2024-09-01_to_2024-09-19_report_time_2024-09-23T07:37:38Z.csv"
}
}
PUT /gateway/v1/api/campaign/statusYou need to pass the API key and:
{
"id": int,
"status": text
}
id - campaign ID for which you need to change the statusstatus - campaign status to set (only 'active' and 'paused' statuses can be set){
"code": int,
"message": text,
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/status' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"id": 382,
"status": "active"
}'
{
"code": 200,
"message": "Ok",
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/status' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"id": 382,
"status": "blabla"
}'
{
"code": 400,
"message": "status is not valid",
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/status' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"id": 382,
"status": "blabla"
}'
{
"code": 500,
"message": "try again later",
"data": null
}
PUT /gateway/v1/api/campaign/:idYou need to pass the API key, specify the campaign ID in the request parameters, and pass in the Body:
{
"bid": float,
"black_list": [text],
"white_list": [text],
"bid_by_source": {text: float, text: float},
"smart_purchase": boolean,
"tracking_url": text (optional),
"traffic_quality": text (optional),
"budget": float (optional),
"daily_budget": float (optional),
"hourly_budget": float (optional),
"countries": [text] (optional),
"countries_black": [text] (optional),
"cities": [text] (optional),
"cities_black": [text] (optional),
"provider": [text] (optional),
"provider_black": [text] (optional),
"ip_range": [object] (optional, IPv4 only),
"ip_range_black": [object] (optional, IPv4 only),
"browser_families_versions_whitelist": object (optional),
"browser_families_versions_blacklist": object (optional),
"work_schedule": object (optional),
"work_schedule_black": object (optional)
}
bid - campaign bidblack_list - blacklist setting (only numbers, "-". Example: 132, 543-123)white_list - whitelist setting (only numbers, "-". Example: 823, 452-33)bid_by_source - bid by source settingsmart_purchase - SmartCPC traffic purchase. Use only for adtype: popunder, inpagetracking_url - click URL. Allowed here without a moderation change task when the host/domain
stays the same (for example a macro or path change). If the domain changes, create a moderation change task
with type: "update_campaign" instead — see Create / Update
Campaign Change Task.traffic_quality - a single string, allowed values: "premium",
"optimum". Applied directly, without a moderation change task. If the domain in
tracking_url changes together with traffic_quality, create a change task with
type: "update_campaign" instead — traffic_quality is then applied after the task is
approved. Arrays are rejected.budget, daily_budget - campaign total and daily budgethourly_budget - spend limit per calendar hour (UTC). 0 removes the limit,
otherwise at least 1. Omit the key to leave the value unchanged. Values between
0 and 1, negative or non-numeric values are rejected with 400countries, countries_black - ISO 3166-1 alpha-2 codes from
GET /gateway/v1/api/application/countries
cities, cities_black - city name strings from
POST /gateway/v1/api/application/cities
provider, provider_black - ISP name strings from
GET /gateway/v1/api/application/isp
ip_range, ip_range_black - arrays of IP range objects. Each object has
ip_range_min and ip_range_max. Only IPv4 is supported; IPv6 and CIDR masks (for
example 1.1.1.0/24) are not allowed. Example:
[{ "ip_range_min": "1.1.1.1", "ip_range_max": "1.1.1.10" }]
work_schedule, work_schedule_black - time range targeting: allowed and blocked
time ranges. Object with seven weekday keys (Monday ... Sunday), each an array of
[start, end] pairs as HH:MM. Format is the same as in
Create Change Task. Omit the key to leave the value unchanged.browser_families_versions_whitelist, browser_families_versions_blacklist - object:
browser family value from GET /gateway/v1/api/application/browser → list of version
stringsOmit a field to leave it unchanged. Send an empty array ([]) or empty object where applicable to
clear a list/map field.
{
"code": int,
"message": text,
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/382' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"bid": 0.1,
"smart_purchase": boolean
}'
{
"code": 200,
"message": "Ok",
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/15964' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"bid_by_source": {
"2": 0.1,
"3": 0.2,
"smart_purchase": true
}
}'
{
"code": 200,
"message": "Ok",
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/382' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"black_list": [
"1-11",
"111",
"222"
],
"white_list": [
"6-66",
"666",
"777"
],
"smart_purchase": true
}'
{
"code": 200,
"message": "Ok",
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/382' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"budget": 1000,
"daily_budget": 100,
"countries": ["US", "DE"],
"cities": ["New York"],
"provider": ["Armtech"],
"ip_range": [
{ "ip_range_min": "1.1.1.1", "ip_range_max": "1.1.1.10" }
],
"browser_families_versions_whitelist": {
"chrome": ["131"]
}
}'
{
"code": 200,
"message": "Ok",
"data": null
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaign/382' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"tracking_url": "https://example.com/click?sub={%source_id%}&camp={%campaign_id%}"
}'
{
"code": 200,
"message": "Ok",
"data": null
}
PUT /gateway/v1/api/campaigns/multiupdateYou need to pass the API key and a JSON body. This updates several of your campaigns in one call. Only the fields below are accepted; any other field is ignored.
{
"campaigns_ids": [int],
"attributes": {
"status": text (optional),
"budget": float (optional),
"daily_budget": float (optional),
"bid": float (optional),
"countries": [text] (optional),
"countries_black": [text] (optional),
"cities": [text] (optional),
"cities_black": [text] (optional),
"provider": [text] (optional),
"provider_black": [text] (optional),
"browser_families_versions_whitelist": object (optional),
"browser_families_versions_blacklist": object (optional),
"black_list": [text] (optional),
"white_list": [text] (optional),
"list_update_mode": text (optional),
"bid_by_source": {text: float, text: float} (optional),
"ip_range": [object] (optional, IPv4 only),
"ip_range_black": [object] (optional, IPv4 only)
}
}
campaigns_ids - campaign IDs to update. Required. If it is missing, the request returns
400 and no campaign changes.attributes - the fields to change. Required, and at least one field inside it must be set.
Omitted fields stay unchanged on every campaign in campaigns_ids.status - active or pausedbudget, daily_budget, bid - same meaning as in Update Campaigncountries, countries_black, cities, cities_black,
provider, provider_black, browser_families_versions_whitelist,
browser_families_versions_blacklist, ip_range, ip_range_black - same
values as in Update Campaignblack_list, white_list - source lists, same format as in Update Campaign. Send only one of them. If the campaign already has a
white_list and you send a black_list, the white_list is cleared. If it
already has a black_list and you send a white_list, the black_list is
cleared. list_update_mode is required
together with either list and must not be sent without a list. Values:
replace - the campaign list becomes exactly the list you sentappend - the values you sent are added to the current listremove - the values you sent are deleted from the current listbid_by_source - map of source id to bid, for example {"2": 0.1, "3": 0.2}
A successful update and a validation error return:
{
"messages": text
}
messages - how many campaigns were updated, or why the request was rejected. A validation error
may also include errors with field details.
Send only the fields you want to change. white_list is sent the same way as
black_list, but not together with it. Sending black_list clears an existing
white_list, and sending white_list clears an existing black_list.
list_update_mode is required with either list.
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaigns/multiupdate' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"campaigns_ids": [382, 383],
"attributes": {
"status": "paused",
"budget": 1000,
"daily_budget": 100,
"bid": 0.1,
"countries": ["US", "DE"],
"countries_black": ["RU"],
"cities": ["New York"],
"cities_black": ["Moscow"],
"provider": ["Armtech"],
"provider_black": ["Avanti"],
"browser_families_versions_whitelist": {
"chrome": ["131"]
},
"browser_families_versions_blacklist": {
"firefox": ["120"]
},
"black_list": ["11", "111"],
"list_update_mode": "replace",
"bid_by_source": {
"2": 0.1,
"3": 0.2
},
"ip_range": [
{ "ip_range_min": "1.1.1.1", "ip_range_max": "1.1.1.10" }
],
"ip_range_black": [
{ "ip_range_min": "10.0.0.1", "ip_range_max": "10.0.0.10" }
]
}
}'
{
"messages": "2 campaigns have been updated."
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/campaigns/multiupdate' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"attributes": {
"bid": 0.1
}
}'
{
"messages": "The campaigns ids field is required."
}
{
"code": 400,
"message": "problem with json payload data",
"data": null
}
{
"code": 401,
"message": "api key is not valid",
"data": null
}
{
"code": 500,
"message": "try again later",
"data": null
}
GET /gateway/v1/api/change-taskPass the API key. Optional query parameters are passed through unchanged (filters, pagination, sorting, etc.). Common parameters include:
status - filter by task status; allowed values: open, rejected,
approved
pagination[page] - page numberpagination[per_page] - number of items per pageJSON with code, message, and data. Example when tasks exist:
{
"code": 200,
"message": "OK",
"data": {
"data": [
{ "id": 1, "type": "create_campaign", "status": "open", ... },
...
],
"meta": { "total": 1, "total_pages": 1 }
}
}
The status field on each item in data.data is one of: open,
rejected, approved.
If there is nothing to return, the HTTP status may be 404.
curl --location 'http://api.mybid.io/gateway/v1/api/change-task?status=open' \ --header 'X-Auth-Token: *****MRCP'
curl --location 'http://api.mybid.io/gateway/v1/api/change-task?status=open&pagination[page]=2&pagination[per_page]=10' \ --header 'X-Auth-Token: *****MRCP'
GET /gateway/v1/api/change-task/:idPass the API key and the numeric change-task id in the path.
Example:
{
"code": 200,
"message": "OK",
"data": {
"change_task": {
"id": 42,
"type": "create_campaign",
"status": "open",
...
}
}
}
change_task.status is one of: open, rejected, approved.
curl --location 'http://api.mybid.io/gateway/v1/api/change-task/42' \ --header 'X-Auth-Token: *****MRCP'
PUT /gateway/v1/api/change-task/reject/:idPass the API key, the numeric change-task id in the path, and a JSON body:
{
"status": "rejected",
"reject_reason": text (optional)
}
status - must be exactly "rejected"reject_reason - optional; leading and trailing spaces are trimmedReturns HTTP 200 with this JSON body:
{
"code": 204,
"message": "OK",
"data": {}
}
curl --location --request PUT 'http://api.mybid.io/gateway/v1/api/change-task/reject/42' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"status": "rejected",
"reject_reason": "does not meet guidelines"
}'
POST /gateway/v1/api/change-taskCreates a change task. type is required and must be one of:
"create_campaign" — create a new campaign (goes to moderation)"update_campaign" — update an existing campaign's click URL when the domain changes, optionally
together with the same targeting/budget fields as Update Campaigntype: "create_campaign"Pass the API key and a JSON body. The gateway validates the fields below and submits the task.
{
"type": "create_campaign",
"name": text,
"tracking_url": text,
"bid": float,
"budget": float (optional),
"daily_budget": float (optional),
"hourly_budget": float (optional),
"ad_type": text,
"category": [text],
"traffic_quality": text,
"price_type": text,
"countries": [text] (optional),
"countries_black": [text] (optional),
"cities": [text] (optional),
"cities_black": [text] (optional),
"provider": [text] (optional),
"provider_black": [text] (optional),
"ip_range": [object] (optional, IPv4 only),
"ip_range_black": [object] (optional, IPv4 only),
"black_list": [text] (optional),
"white_list": [text] (optional),
"usage_type": [text] (optional),
"usage_type_black": [text] (optional),
"os_type_familie_version_whitelist": object (optional),
"os_type_familie_version_blacklist": object (optional),
"browser_families_versions_whitelist": object (optional),
"browser_families_versions_blacklist": object (optional),
"capping_settings": json (optional),
"work_schedule": json (optional),
"work_schedule_black": json (optional),
"capping_unique_settings": text (optional),
"creatives": [object] (required for inpage)
}
type - required; "create_campaign" or "update_campaign"name, tracking_url, category - required; category is an
array of stringscategory - allowed values are AD (adult) and MS (mainstream)traffic_quality - allowed values: "premium", "optimum". We populate
this field automatically using the best available option. If you would prefer to manage this field yourself,
please contact your account manager to have this option enabled.tracking_url - must be a valid URL with scheme and hostad_type - "popunder" or "inpage" (case-insensitive)price_type - "cpc" (case-insensitive)budget, daily_budget - if present, must be >= 0hourly_budget - optional; spend limit per calendar hour (UTC). 0 means no
limit, otherwise at least 1. If omitted, the campaign is created without a limit. Values between
0 and 1, negative or non-numeric values are rejected with 400ad_type = "inpage", forbidden for "popunder")The creatives array defines creatives for the campaign. Each entry is either a new
creative or a reuse by id of an existing creative. At least one entry is required
for inpage (reuse-only is allowed).
Create new creative — pass create fields (no id):
{
"title": text (required),
"description": text (optional),
"is_active": bool (required),
"image_url": text (optional),
"icon_url": text (optional),
"skins": [text] (optional),
"is_mandatory_skins": bool (optional)
}
Reuse existing creative — when attaching an existing creative, pass id (from Get Campaign Data creatives):
{
"id": 12345
}
id - positive integer id of an existing creative to attachtitle - creative title, cannot be empty (create-new only)description - optional description textis_active - required for create-new; must be explicitly set to true or
false
image_url - optional; external URL to the creative image (http/https)icon_url - optional; external URL to the creative icon (http/https)skins - optional array of skin names. Each value must be the name field from Get skins dictionary (do not send id). If omitted or empty,
no skins are targeted.is_mandatory_skins - optional; controls how selected skins affect delivery. Default:
false if omitted.
false — preferred: the ad is more likely to be shown in the chosen skins,
but may also appear elsewhere.true — mandatory: the ad will appear exclusively in the selected skins.
You may mix reuse and create-new entries in the same creatives array (for example one
{"id": 123} and one new creative object).
File requirements (validated on the server, apply to create-new assets only):
| Field | Allowed formats | Max size |
|---|---|---|
image |
jpg, jpeg, png, gif, webp | 720 KB |
icon |
jpg, jpeg, png, gif, webp | 200 KB |
countries, countries_black - arrays of ISO 3166-1 alpha-2 country codes. Take
values from GET /gateway/v1/api/application/countries (the data.countries array).
Example: ["US", "DE"].cities, cities_black - arrays of city name strings. Take values from
POST /gateway/v1/api/application/cities (the data array). Example:
["Andorra la Vella"].
provider, provider_black - arrays of ISP (internet service provider) name strings.
Take values from GET /gateway/v1/api/application/isp (the data array). Example:
["Armtech"].
usage_type, usage_type_black - arrays of strings. Take only the type
field from each object returned by GET /gateway/v1/api/application/usage-types (do not send
label or other fields). Example: ["mainstream"].
os_type_familie_version_whitelist, os_type_familie_version_blacklist - nested
object: OS type → OS family → list of OS versions. Keys at each level must use the same string codes as in
GET /gateway/v1/api/application/os-platform (use value, not label,
wherever the dictionary exposes them). Version entries are numeric, same shape as in Get Campaign Data.
browser_families_versions_whitelist, browser_families_versions_blacklist - object:
browser family → list of version strings. Family keys must use value from
GET /gateway/v1/api/application/browser (not label). Each version is a string, for
example "131" or "120.5".
creatives[].skins - array of skin name strings from
GET /gateway/v1/api/application/skins?ad_type=inpage. Example:
"skins": ["skin-a", "skin-b"].
black_list, white_list - source allow/block lists (numeric source IDs and ranges,
same rules as Update Campaign).ip_range, ip_range_black - arrays of IP range objects. Each object has
ip_range_min and ip_range_max. Only IPv4 is supported; IPv6 and CIDR masks (for
example 1.1.1.0/24) are not allowed. Example:
[{ "ip_range_min": "1.1.1.1", "ip_range_max": "1.1.1.10" }]
os_type_familie_version_whitelist (illustrative):
{
"mobile": {
"android": [10, 11, 12]
},
"computer": {
"windows": [10, 11]
},
"tablet": {
"xbox": []
},
"smartTv": {}
}
browser_families_versions_whitelist (family keys must match value from the browser
dictionary):
{
"chrome": ["120.5", "131"],
"firefox": ["115.0"],
"qq": []
}
capping_settings (array of rules; same idea as campaign capping):
[
{ "type": "impression", "limit": 1, "duration": 24 },
{ "type": "click", "limit": 2, "duration": 48 }
]
work_schedule and work_schedule_black — optional objects that define when the
campaign is allowed (work_schedule) or blocked (work_schedule_black) to run. Each
field is an object with exactly seven keys — one per weekday: Monday,
Tuesday, Wednesday, Thursday, Friday, Saturday,
Sunday. Each day maps to an array of [start, end] time ranges as HH:MM
strings.
Important: do not send a bare empty array or empty object for either field.
The following are invalid and return 400:
"work_schedule": [] or "work_schedule_black": []"work_schedule": {} or "work_schedule_black": {}If you do not need a custom schedule, omit the field entirely — the server applies the default (all days, no time ranges). To express “no restriction / nothing blocked”, send the full default object with empty arrays for every day:
{
"Monday": [],
"Tuesday": [],
"Wednesday": [],
"Thursday": [],
"Friday": [],
"Saturday": [],
"Sunday": []
}
work_schedule — only the listed time ranges are allowed; days with empty arrays mean the campaign
does not run on those days. Example fragment:
{
"Monday": [["09:00", "12:00"], ["13:00", "18:00"]],
"Tuesday": [["09:00", "18:00"]],
"Wednesday": [],
"Thursday": [],
"Friday": [],
"Saturday": [],
"Sunday": []
}
work_schedule_black — same shape as work_schedule; listed ranges are excluded. Empty
day arrays mean nothing is blocked for that day. Example:
{
"Monday": [],
"Tuesday": [],
"Wednesday": [],
"Thursday": [],
"Friday": [],
"Saturday": [["00:00", "23:59"]],
"Sunday": []
}
capping_unique_settings - optional string: ip or ip+ua (user uniqueness
for capping).
{
"type": "create_campaign",
"name": "My popunder campaign",
"tracking_url": "https://example.com/click",
"bid": 0.05,
"budget": 1000,
"daily_budget": 100,
"ad_type": "popunder",
"category": ["AD"],
"traffic_quality": "premium",
"price_type": "cpc",
"countries": ["US", "DE"],
"countries_black": ["RU"],
"cities": ["New York"],
"cities_black": ["Moscow"],
"provider": ["Armtech"],
"provider_black": ["Avanti"],
"ip_range": [
{ "ip_range_min": "1.1.1.1", "ip_range_max": "1.1.1.10" }
],
"ip_range_black": [
{ "ip_range_min": "10.0.0.1", "ip_range_max": "10.0.0.10" }
],
"black_list": ["100-200"],
"white_list": ["300"],
"usage_type": ["mainstream"],
"usage_type_black": ["incentive"],
"os_type_familie_version_whitelist": {
"mobile": { "android": [11, 12, 13] }
},
"browser_families_versions_whitelist": {
"chrome": ["120.5", "131"]
},
"capping_settings": [
{ "type": "impression", "limit": 1, "duration": 24 }
],
"capping_unique_settings": "ip+ua"
}
{
"type": "create_campaign",
"name": "My inpage campaign",
"tracking_url": "https://example.com/click",
"bid": 0.02,
"budget": 500,
"daily_budget": 50,
"ad_type": "inpage",
"category": ["MS"],
"traffic_quality": "premium",
"price_type": "cpc",
"countries": ["US"],
"creatives": [
{
"title": "Special offer",
"description": "Limited time deal",
"is_active": true,
"image_url": "https://advertiser.example/banner.png",
"icon_url": "https://advertiser.example/icon.png",
"skins": ["skin-a"],
"is_mandatory_skins": false
},
{
"title": "New product",
"is_active": true,
"image_url": "https://advertiser.example/banner2.png",
"skins": ["skin-b", "skin-c"],
"is_mandatory_skins": true
}
]
}
type: "update_campaign"Use this to change the campaign click URL (tracking_url) when the domain changes (requires
moderation). If only macros or path change and the host/domain stays the same, prefer Update Campaign — no change task is needed. You may also send any of the
targeting/budget fields supported by Update Campaign in the same request; omitted
fields are left unchanged.
{
"type": "update_campaign",
"campaign_id": int,
"tracking_url": text,
"traffic_quality": text (optional),
"bid": float (optional),
"bid_by_source": {text: float} (optional),
"black_list": [text] (optional),
"white_list": [text] (optional),
"budget": float (optional),
"daily_budget": float (optional),
"hourly_budget": float (optional),
"countries": [text] (optional),
"countries_black": [text] (optional),
"cities": [text] (optional),
"cities_black": [text] (optional),
"provider": [text] (optional),
"provider_black": [text] (optional),
"ip_range": [object] (optional, IPv4 only),
"ip_range_black": [object] (optional, IPv4 only),
"browser_families_versions_whitelist": object (optional),
"browser_families_versions_blacklist": object (optional),
"work_schedule": object (optional),
"work_schedule_black": object (optional)
}
type - must be "update_campaign"campaign_id - required; ID of the existing campaigntracking_url - required; must be a valid URL with scheme and hosttraffic_quality - optional; "premium" or "optimum".hourly_budget - optional; 0 removes the limit, otherwise at least
1. Omit the key to leave the value unchanged.work_schedule, work_schedule_black - optional; same format as in
Update Campaign. Omit the key to leave the value unchanged.Example:
{
"code": 201,
"message": "OK",
"data": {
"change_task": { "id": 99, "type": "create_campaign", "status": "open", ... }
}
}
curl)curl --location --request POST 'http://api.mybid.io/gateway/v1/api/change-task' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"type": "create_campaign",
"name": "My popunder campaign",
"tracking_url": "https://example.com/click",
"bid": 0.05,
"ad_type": "popunder",
"category": ["MS"],
"traffic_quality": "premium",
"price_type": "cpc",
"countries": ["US", "DE"]
}'
curl)curl --location --request POST 'http://api.mybid.io/gateway/v1/api/change-task' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"type": "create_campaign",
"name": "My inpage campaign",
"tracking_url": "https://example.com/click",
"bid": 0.02,
"ad_type": "inpage",
"category": ["MS"],
"traffic_quality": "premium",
"price_type": "cpc",
"countries": ["US"],
"creatives": [
{
"title": "Best deal",
"is_active": true,
"image_url": "https://advertiser.example/banner.png",
"icon_url": "https://advertiser.example/icon.png",
"skins": ["skin-a"],
"is_mandatory_skins": false
}
]
}'
curl)curl --location --request POST 'http://api.mybid.io/gateway/v1/api/change-task' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"type": "update_campaign",
"campaign_id": 382,
"tracking_url": "https://example.com/new-click"
}'
curl)curl --location --request POST 'http://api.mybid.io/gateway/v1/api/change-task' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"type": "update_campaign",
"campaign_id": 382,
"tracking_url": "https://example.com/new-click",
"bid": 0.1,
"countries": ["US", "DE"],
"budget": 1000,
"daily_budget": 100
}'
GET /gateway/v1/api/application/skinsPass the API key. Required query parameter:
ad_type - must be inpage (skins are available for inpage campaigns only)Example (structure illustrative):
{
"code": 200,
"message": "OK",
"data": [
{ "id": 1, "name": "skin-a" },
{ "id": 2, "name": "skin-b" },
...
]
}
id - internal skin identifier (do not use in API requests)name - skin code to pass in creatives[].skins when creating an inpage campaign
Use only name in skins, not id.
curl --location 'http://api.mybid.io/gateway/v1/api/application/skins?ad_type=inpage' \ --header 'X-Auth-Token: *****MRCP'
GET /gateway/v1/api/application/os-platformPass the API key.
Example (structure illustrative):
{
"code": 200,
"message": "OK",
"data": [
{ "value": "mobile", "label": "Mobile" },
{ "value": "computer", "label": "Desktop" },
...
]
}
Use only value in later requests, not label.
curl --location 'http://api.mybid.io/gateway/v1/api/application/os-platform' \ --header 'X-Auth-Token: *****MRCP'
GET /gateway/v1/api/application/browserPass the API key.
Example (structure illustrative):
{
"code": 200,
"message": "OK",
"data": [
{ "value": "chrome", "label": "Google Chrome" },
{ "value": "firefox", "label": "Mozilla Firefox" },
...
]
}
Use only value for browser family keys in targeting, not label. Version arrays use
strings, for example ["120.5", "131"].
curl --location 'http://api.mybid.io/gateway/v1/api/application/browser' \ --header 'X-Auth-Token: *****MRCP'
GET /gateway/v1/api/application/countriesPass the API key.
Example:
{
"code": 200,
"message": "OK",
"data": {
"countries": ["AD", "AE", "AF", "US", ...]
}
}
countries is a sorted list of ISO 3166-1 alpha-2 codes for use in API requests.
curl --location 'http://api.mybid.io/gateway/v1/api/application/countries' \ --header 'X-Auth-Token: *****MRCP'
GET /gateway/v1/api/application/usage-typesPass the API key. The list is returned for the authenticated account.
Example (structure illustrative):
{
"code": 200,
"message": "OK",
"data": [
{ "type": "mainstream", "label": "Mainstream" },
{ "type": "incentive", "label": "Incentive" },
...
]
}
When you send usage_type or usage_type_black elsewhere, use only the
type field of each object, for example "usage_type": ["mainstream"].
curl --location 'http://api.mybid.io/gateway/v1/api/application/usage-types' \ --header 'X-Auth-Token: *****MRCP'
POST /gateway/v1/api/application/citiesPass the API key and a JSON body:
{
"countries": [text],
"name": text (optional)
}
countries - required array of ISO 3166-1 alpha-2 country codes (from
GET /gateway/v1/api/application/countries)
name - optional name filter (prefix / substring search as in the cabinet){
"code": 200,
"message": "OK",
"data": ["Andorra", "Andorra la Vella", ...]
}
data is an array of city name strings. Use these values in cities /
cities_black when creating or updating a campaign.
curl --location --request POST 'http://api.mybid.io/gateway/v1/api/application/cities' \
--header 'X-Auth-Token: *****MRCP' \
--header 'Content-Type: application/json' \
--data '{
"countries": ["AD"],
"name": "a"
}'
GET /gateway/v1/api/application/ispPass the API key. Optional query parameter:
name - name filter for internet service providers{
"code": 200,
"message": "OK",
"data": ["Armtech", "Avanti of Forsyth Management Contracts", ...]
}
data is an array of ISP name strings. Use these values in provider /
provider_black when creating or updating a campaign.
curl --location 'http://api.mybid.io/gateway/v1/api/application/isp?name=a' \ --header 'X-Auth-Token: *****MRCP'