Search...
Menu
API: Creating Offers (Technical Guide)
Label：API key ,API ,creating offers ,technical guide ,developer guide
You need to use your Mintegral token to manage your offers. For more details, please check Token.
Here's how to create ad offers you want to promote. Please note that ad offers fall under under ad campaigns. For example, when promoting an app, you may need to create different ad offers in accordance to different geos, price per offer and creatives.
Request address
https://ss-api.mintegral.com/api/open/v1/offer
Request method
POST
Request example
json
POST /api/open/v1/offer
HTTP/1.1 Host: ss-api.mintegral.com
Content-Type: application/json
{
"campaign_id": "25",
"offer_name": "cqf_testtttt",
"promote_timezone": 7,
"start_time": 1578455012,
"target_geo": "ALL",
"bid_type": "CPI",
"bid_rate": 5,
"daily_cap_type": "BUDGET",
"daily_cap": "50",
"total_budget": "50",
"settlement_event": "",
"os_version_min": "8.8",
"custom_ad_schedule": {"1":"0,1,23","2":"3,4,5","3":"3,6,5"},
"custom_ad_schedule_timezone": 0,
"network": "WIFI",
"target_ad_type": "BANNER",
"creatives_sets": [
{"creative_set_name":"demo1","geos":["ALL"],"ad_outputs":[111],"creatives":[{"creative_name":"material1","creative_md5":"c09d944dcf2d6ded1acd6eb2237f8bad"},{"creative_name":"icon_512x512","creative_md5":"5a42fed89d97cfe253c2f7b6be86f8ed"},{"creative_name":"1200x627","creative_md5":"ea5c9ca2f16cace9c133bb327e1c83dd"}]}
],
"target_device": "PHONE"
}Request Parameter
| Fields | Type | Explanations | Default Value | Examples | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| campaign_id | int | Related Campaign id | — | 1234 |
||||||||||
| offer_name | string | Unique name for offer. Only alphabets, underscores and numbers are allowed. Length within 3~95. | "" | "offer_test" |
||||||||||
| promote_timezone | number | Timezone setting for the promotion period. [ENUM-Timezone] |
"" | 5.5 |
||||||||||
| start_time | int | Timestamp of promotion start time. Must be earlier than end_time (if any). PS:start time must be after 946656000 |
— | 1578455012 |
||||||||||
end_time Optional |
int | Timestamp of promotion end time. Must be after start_time (if any). | 0 | 1578455169 |
||||||||||
| target_geo | string | Target geos for promotion. Set "ALL" for global promotion. Separate with commas for multiple geos. | — | "CN" |
||||||||||
bid_type Deprecated |
string | Pricing model, Enum value in ： [ENUM-Pricing Model] Note: available bid type is determine by permission, if returns "permission denied"，please contact AM to get access. |
"" | "CPC" |
||||||||||
| billing_type | string | Pricing model, Enum value in ： [ENUM-Pricing Model] Note: available billing_type is determine by permission, if returns "permission denied"，please contact AM to get access. |
"" | "CPC" |
||||||||||
bid_goal When billing_type is set to OCPI, it is a must to fill in the required field. |
string | Optimized Target types: Target-ROAS, Target-CPE, Install, impression, with the following relationship to billing_type:
|
Target-ROAS |
|||||||||||
target_mtg_event When bid_goal is set as Target-ROAS or Target-CPE, it is mandatory to fill in. |
array<string> | Objectives to optimize. [Update Target Goal] |
["Ad Revenue"] |
|||||||||||
target_original_event When bid_goal is set as Target-CPE, it is mandatory to fill in. |
string | Original event to optimize. [Update Target Goal] |
"ad_revenue" |
|||||||||||
target_goal_window When bid_goal is set as Target-ROAS or Target-CPE, it is mandatory to fill in. |
string | The time window of the optimization goal, enumeration value: D0, D7, the time window supported by different bid_goal is as follows: Target-ROAS: D0, D7 Target-CPES: D0, D7 |
D0 |
|||||||||||
target_goal When bid_goal is set as Target-ROAS or Target-CPE, it is required to be filled in. |
double | The offer dimension optimizes the goal value, and the different bid_goal ranges are as follows: Target-ROAS: This value is in the range [1, 1000] with two decimal places in percentage. Target-CPE: This value is in the range [0.1, 2000] with three decimal places in percentage. |
80 |
|||||||||||
| target_goal_by_geo | array<json> | The geo dimension optimizes the objective value | ||||||||||||
| geo | string | geo | ||||||||||||
| target_goal | double | Optimize the target value | ||||||||||||
| bid_rate | number | Default bidding price value for all target geos. Float with 3 decimal places greater than 0 is allowed. For CPE/CPI/CPM bid type, value must be greater than 0.01. For CPC bid type, value must be greater than 0.001. | "" | 0.04 |
||||||||||
daily_cap_type Optional |
string | Daily budget setting type. Enum value："BUDGET"、 "CONVERSION"。 |
"BUDGET" | "CONVERSION" |
||||||||||
daily_cap Optional |
number | Daily budget value. Set null for open daily budget. Value must be greater than 50. | — | 100 |
||||||||||
total_budget Optional |
number | Total budget value with 3 decimal places. Set null for open total budget. If daily_cap_type= "BUDGET", value must be greater than 50. | — | 50.12 |
||||||||||
settlement_event Optional |
string | Settlement event for CPE promotion. Only alphabets, underscores and numbers are allowed. Maximum length is 50. Must be filled when bid_type = CPE. Ps: minimum length of this field is 3 | "" | "purchase" |
||||||||||
os_version_min Optional |
string | Minimum OS version allowed in format of /^[0-9](\.[0-9]){0,2}$/ . "x" as in natural number. If set null, OS version requirement will be same as campaign by default. If no minimum version is specified, the value should be set to 0.0.0. |
— | "9.0" |
||||||||||
os_version_max Optional |
string | Maximum OS version allowed in format of /^[0-9](\.[0-9]){0,2}$/ . "x" as in natural number. If set null, OS version requirement will be same as campaign by default. If no maximum version is specified, the value should be set to 99.0.0. |
— | "9.0" |
||||||||||
custom_ad_schedule Optional |
json | Promotion schedule. Key means weekday (1-7) and value means hour (0-23). Set null to select all weekdays and all hours. | — | {"1":"0,1,23","2":"3,4,5"} |
||||||||||
custom_ad_schedule_timezone Deprecated |
number | Timezone setting for promotion schedule. Enum value in [ENUM-Timezone] This field has been deprecated, use the 'promote_timezone' field instead. |
— | -5.5 |
||||||||||
network Optional |
string | Target for device network status. Enum value in [ENUM-Network] |
— | "2G,3G,4G,5G" |
||||||||||
| target_ad_type | string | Target ad types. Separate with commas for multiple ad types. Enum value in ： [ENUM-ad type(static)] [ENUM-ad type(video)] |
— | "REWARDED_VIDEO,INTERSTITIAL_VIDEO" |
||||||||||
target_device Optional |
string | Target device type. ENUM value in："PHONE" 、"TABLET。 |
"PHONE,TABLET" | "PHONE,TABLET" |
||||||||||
| creatives | array<json> | Creative info，Obsolete, please use creative_sets |
— | [{"creative_name":"1200x627.jpg","creative_md5":"ad7667f1faf1c14d13c4e03ed8f08e6c","apply_in_area":"ALL"},{"creative_name":"512x512.png","creative_md5":"77c561b05d00559671a5a462c077fb5b", "apply_in_area":"ALL"}] |
||||||||||
| creatives_sets | array<json> | Creative Set info Api - Create Creative Set | — | [{"creative_set_name":"demo1","geos":["ALL"],"ad_outputs":[111],"creatives":[{"creative_md5":"c09d944dcf2d6ded1acd6eb2237f8bad"},{"creative_name":"icon_512x512","creative_md5":"5a42fed89d97cfe253c2f7b6be86f8ed"},{"creative_name":"1200x627","creative_md5":"ea5c9ca2f16cace9c133bb327e1c83dd"}]}] |
Response
| Fields | Type | Explanations |
|---|---|---|
| code | int | 200 code, is success. Others, are fail. |
| msg | string | If success, return to "success". If fail, return to detailed wrong info. |
| data | json | If success, return to offer data. If fail, return to detailed wrong info. |
| campaign_id | int | Unique id for each campaign |
| offer_id | int | Unique id for offer |
| offer_name | string | Unique name for offer |
| promote_timezone | number | Timezone setting for promotion period |
| start_time | int | Timestamp of promotion start time |
| end_time | int | Timestamp of promotion end time |
| target_geo | string | Target geos for promotion |
bid_type Deprecated |
string | Pricing model |
| bid_rate | string | Default bidding price value for all offer target geos |
| daily_cap_type | string | Daily budget setting type |
| daily_cap | string | Value of daily cap |
| total_budget | string | Value of total budget |
| settlement_event | string | Settlement event for CPE promotion |
| os_version_min | string | Minimum OS version allowed |
| os_version_max | string | Maximum OS version allowed |
| custom_ad_schedule | string | Promotion schedule |
custom_ad_schedule_timezone Deprecated |
number | Timezone setting for promotion scheduleThis field has been deprecated, use the 'promote_timezone' field instead. |
| network | string | Target for device network status |
| target_ad_type | string | Target ad types |
creatives Deprecated |
array<json> | Creative info, Obsolete, usecreative_sets |
| creative_sets | array<json> | Creative Set Info |
| target_device | string | Target device type |
Response Example
json
{
"code": 200,
"msg": "success",
"data": {
"campaign_id": "25",
"offer_id": 18496,
"offer_name": "cqf_testtttt",
"promote_timezone": 7,
"start_time": "1578455012",
"end_time": "0",
"target_geo": "ALL",
"bid_type": "CPI",
"bid_rate": "5",
"daily_cap_type": "BUDGET",
"daily_cap": "50",
"total_budget": "50",
"settlement_event": "",
"os_version_min": "8.8",
"custom_ad_schedule": "{\"1\":\"0,1,23\",\"2\":\"3,4,5\",\"3\":\"3,6,5\"}",
"custom_ad_schedule_timezone": 0,
"network": "WIFI",
"target_ad_type": "BANNER",
"creative_sets": [
{
"creative_set_name": "demo1",
"geos": [
"ALL"
],
"ad_outputs": [
111
],
"creatives": [
{
"creative_name":"material1",
"creative_md5": "c09d944dcf2d6ded1acd6eb2237f8bad"
},
{
"creative_name": "icon_512x512",
"creative_md5": "5a42fed89d97cfe253c2f7b6be86f8ed"
},
{
"creative_name": "1200x627",
"creative_md5": "ea5c9ca2f16cace9c133bb327e1c83dd"
}
]
}
],
"target_device": "PHONE"
}
}Previous
API: Retrieving Offer List (Technical Guide)
Next
API: Managing Offers (Technical Guide)
Last modified: 2025-08-28
Outline