API: Retrieving Offer List (Technical Guide)

Label：API ,API key ,offer list ,technical guide ,developer guide

You need to use your Mintegral token to manage your offers. For more details, please check Token.

Retrieve your ad offer list, support inquiries according to campaign_id、campaign_name、offer_id、offer_name、offer_uuid、status、package_name、ext_fields.

Request address

https://ss-api.mintegral.com/api/open/v1/offers

Request method

GET

Request example

json Copy

GET /api/open/v1/offers
HTTP/1.1 Host: ss-api.mintegral.com
Content-Type: application/json
{ "page": 1, "campaign_id": "12,13,15", "limit": 10 }

Request Parameter

Fields	Type	Explanations	Default Value	Examples
campaign_id `Optional`	string	Campaign ID. Separate with commas for multiple IDs.	—	`"12,13,15"`
campaign_name `Optional`	string	Campaign name. Fuzzy query is supported.	""	`"campaign_test"`
offer_id `Optional`	string	Offer ID. Separate with commas for multiple IDs.	—	`"123,124,125"`
offer_name `Optional`	string	Offer name. Fuzzy query is supported.	""	`"offer_test"`
offer_uuid `Optional`	string	Unique offer name generated automatically	—	`"ss_offer_test"`
package_name `Optional`	string	Package name of promotion application. Fuzzy query is supported.	""	`"test"`
ext_fields `Optional`	string	Extended queries. Separate with commas for multiple queries. Supported queries: bid_rate_by_mtgid => bid rate for specific publisher target_app => The field is used for block or target specific apps	""	`"bid_rate_by_mtgid"`
page `Optional`	int	Page	1	`1`
limit `Optional`	int	Limit for each page Maximam: 50 >50, return to 50	10	`15`
status `Optional`	string	Unnecessary fields and support multiple status:Please check [ENUM-Offer Status]	""	`"RUNNING"`

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”. If fail, return to detailed wrong info.
page	int	current page
limit	int	quantity limit
total	int	total amount
list	array<json>
campaign_id	int	Unique id for campaign
campaign_name	string	Campaign Name
offer_id	int	Unique id for offer
uuid	string	Unique offer name generated automatically,it is commonly used to set tracking url
offer_name	string	Offer name you set
promote_timezone	number	Timezone setting for promotion period, such as -5
start_time	string	Timestamp of promotion start time
end_time	string	Timestamp of promotion end time
status	string	Offer Status.Enum value in [ENUM-Offer Status]
country_code	string	Target geos for promotion. Such as `"US,CN"`
stage	string	Offer dimension cold start phase
bid_type	string	Pricing model
bid_rate	float	Default bidding price value for all offer target geos and will apply only when no specific geo or application bid is set
bid_rate_by_location	array<json>	Bidding price value for specific geos. sample: [{"target_geo":"US","bid_rate":"8.010"},{"country_code":"CN","bid_rate":"3.920"}]
budget	array<json>	Budget info
offer_stop_reason	string	Reason why offer has been paused. For example, account balance is insufficient, no available creative can be used and click tracking link is invalid.
settlement_event	string	Settlement event for CPE promotion.
tracking_method	string	Tracking method. Enum value in [ENUM-Tracking Method]
click_url	string	Click attribution tracking URL
impression_url	string	View-through attribution tracking URL.
os_version_min	string	Minimum OS version
custom_ad_schedule	string	Promotion schedule
network	string	Target for device network status
target_ad_type	string	Ad type
currency	string	Settlement currency. Enum value: `"CNY"`, `"USD"`
target_device	string	Target device type
click_url_status	string	Testing status for click attribution tracking URL, Enum value: PENDDING => Click URL is waiting a test or click url has not passed and continue testing PASS => Click URL is available NOT_EXIST => Click URL is null
target_app	array<json>	The details of apps that has been blocked or targeted
switch	int	1=>for target apps；2=> for block apps；0=>unlimited
mtg_id	array<string>	mtgid
package	array<string>	package name
bid_rate_for_mtgid	array<json>	Bidding price value for specific publishers
apply_in_area	string	Targeted geos
mtgid	string	Unique id of publisher
bid_rate	string	Bidding price value for specific publisher in specific area
maintain_by	string	Access of modifying offer. If maintain_by="AM", it means you can only check the details of your campaign or offer. If maintain_by="ADV", you can change the setting of your campaign or offer freely.
include_ta_id	array<int>	include target audience id
exclude_ta_id	array<int>	exclude target audience id
target_mtg_event	array<string>	Objectives to optimize. Only Target-ROAS or Target-CPE will be returned.
target_original_event	string	Original event to optimize. Only Target-CPE will be returned.
target_goal_window	string	The time window of the optimization goal, enumeration value: D0, D7. Only Target-ROAS or Target-CPE will be returned.
target_goal	double	The offer dimension optimizes the goal value. Only Target-ROAS or Target-CPE will be returned.
target_goal_by_geo	array<json>	The geo dimension optimizes the objective value. Only Target-ROAS or Target-CPE will be returned.
geo	string	geo
target_goal	double	Optimize the target value

Response Example

json Copy

{
  "msg": "success",
  "code": 200,
  "data": {
    "page": 1,
    "limit": 10,
    "total": 520,
    "list": [
      {
        "campaign_id": 111,
        "campaign_name": "campaign_test",
        "offer_id": 10010,
        "uuid": "campaign_test",
        "offer_name": "campaign_test_1",
        "promote_timezone": 8,
        "start_time": "2019-10-01",
        "end_time": "2019-11-02",
        "status": "RUNNING",
        "country_code": "US,CN",
        "bid_type": "CPI",
        "bid_rate": "5.200",
        "currency": "CNY",
        "include_ta_id": [
          1,
          2,
          3
        ],
        "exclude_ta_id": [],
        "bid_rate_by_location": [
          { "country_code": "US", "bid_rate": "8.010" },
          { "country_code": "CN", "bid_rate": "3.920" }
        ],
        "budget": [
          {
            "country_code": "US",
            "total_budget": "OPEN"
            "daily_cap_type": "BUDGET",
            "daily_cap": "OPEN"
          },
          {
            "country_code": "CN",
            "total_budget": 5000
            "daily_cap_type": "CONVERSION",
            "daily_cap": "OPEN"
          }
        ],
        "maintain_by": "ADV"
      },
      {
        "campaign_id": 112,
        "campaign_name": "campaign_test",
        "offer_id": 10011,
        "uuid": "campaign_test",
        "offer_name": "campaign_test_2",
        "promote_timezone": 8,
        "start_time": "2019-10-01",
        "end_time": "2019-11-02",
        "status": "RUNNING",
        "country_code": "US,CN",
        "bid_type": "CPI",
        "bid_rate": "5.200",
        "currency": "CNY",
        "include_ta_id": [
          1,
          2,
          3
        ],
        "exclude_ta_id": [],
        "bid_rate_by_location": [
          { "country_code": "US", "bid_rate": "8.010" },
          { "country_code": "CN", "bid_rate": "3.920" }
        ],
        "budget": [
          {
            "country_code": "ALL",
            "total_budget": "OPEN"
            "daily_cap_type": "BUDGET",
            "daily_cap": "OPEN"
          }
        ],
        "maintain_by": "ADV"
      }
    ]
  }
}

API: Overview of Managing Offer (Technical Guides)

API: Creating Offers (Technical Guide)

Last modified: 2025-08-28

Outline