# Marketing API Integration

# I. Apply to create an external app

Steps to apply for access to the Marketing API:

  1. Contact the corresponding AM and provide the "account ID" and "account name" required to activate the Marketing API

  2. The AM makes the application

  3. After the application is approved, the AM provides the app details such as appId and appKey

# II. Token acquisition

# 1. Create token

​Interface:https://global.e.mi.com/foreign/token/createToken

Request method: POST

Content-Type:application/json

Request parameters:

Field
Type
Necessary to transfer or not
appId
String
Yes
appKey
String
Yes

Returned values:

Field
Type
Note
accessToken
String
token
expireDate
String
Token expiration time
refreshToken
String
Update token, only for token replacement
refreshExpireDate
String
Token replacement expiration time
{ "code": 0, "message": "Success", "result": { "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBJZCI6Indtc2oiLCJhcHBLZXkiOiJhYmMxMjMiLCJleHAiOjE2NjU3NDMyODR9.PqIZJbQdrgWe-pseyhJo3sxsGZroIBiasaSmKkh9QCM", "expireDate": "2022-10-14T10:28:04.570Z", "refreshExpireDate": "2022-10-21T09:28:04.570Z", "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJncmFudF90eXBlIjoicmVmcmVzaCIsImFwcElkIjoid21zaiIsImFwcEtleSI6ImFiYzEyMyIsImV4cCI6MTY2NjM0NDQ4NH0.uD3TAbgU6X8ouX-Ra7A4LVKMgb_qi7btNagaG2_2ccY" } }

# 2. Update token

​Interface:https://global.e.mi.com/foreign/token/refreshToken

Request method: POST

Content-Type:application/json

Request parameters:

Field
Type
Necessary to transfer or not
refreshToken
String
Yes

Returned values:

Field
Type
Note
accessToken
String
token
expireDate
String
Token expiration time
refreshToken
String
Update token, replace token
refreshExpireDate
String
Token replacement expiration time

# III. Setting public parameters

Parameter position:Cookie

Field
Type
Required or not
Note
access_token
String
Yes
token
timestamp
Long
Yes
Timestamp
uid
String
Yes
Request unique ID (unique for each request)
ip
String
No
Request IP

# IV. Ad interface

# 1. Campaign

# 1.1 Getting a campaign

Interface/foreign/marketing/campaign/list

Request methodGET

Content-Type:application/json

Request parameters:

Field
Type
Description
page
int
Current page number 1
pageSize
int
Page size Default: 10
accountIds
List<Long>
Account ID list
campaignIds
List<Long>
Campaign ID list

Returned values:

Field
Type
描Description述
accountId
long
Account ID
campaignId
int
Campaign ID
name
String
Campaign name
dayBudget
long
Daily budget Unit: USD\*100000
campaignType
int
11. App download 2. H5 3. Remarketing

Return example:

{ "code": 0, "message": "Success", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "campaignId": 100205030, "name": "Ad Group 1", "dayBudget": 3000000, "campaignType": 1, }, { "accountId": 1, "campaignId": 100205031, "name": "Ad Group 2", "dayBudget": 3000000, "campaignType": 2, } ] } }

# 1.2 Add a new campaign

Interface/foreign/marketing/campaign/add

Request methodPOST

Content-Type:application/json

Request parameters:

Field
Type
Required or not
Description
accountId
Long
Yes
Account ID
campaignName
String
No
Campaign name (default is M_promotion goal_creation time)
dayBudget
Long
No
Daily budget (Unit: USD\*100000)
campainType
Integer
Yes
Campaign type (1. App download 3. Remarketing)
uniKey
String
Yes
Unique string

Request example:

[ { "accountId": "1420", "campaignName":"Test Campaign", "campainType": 1, "dayBudget": 3000000, "uniKey": "hNtN5LseHtaAAG0G" }, { "accountId": "1420", "campaignName":"Test Campaign 1", "campainType": 1, "dayBudget": 10000000, "uniKey": "oCtdQktKeC6lsODu" } ]

Return example:

{ "code": 0, "message": "Success", "result":[ {"uniKey": "oCtdQktKeC6lsODu", "id":75312748}, {"uniKey": "hNtN5LseHtaAAG0G", "id":93472403} ] }

# 2. Ad group

# 2.1 Getting an ad group

Interface/foreign/marketing/group/list

Request methodGET

Content-Type:application/json

Request parameters:

Field
Type
Description
page
int
Current page number 1
pageSize
int
Page size Default: 10
accountIds
List<Long>
Account ID list
campaignIds
List<Long>
Campaign ID list
groupIds
List<Long>
Ad group ID list

Returned values:

Field
Type
Description
accountId
long
Account ID
groupId
int
Ad group ID
name
String
Ad group name
dayBudget
long
Daily budget Unit: USD\*100000
billingType
int
11. CPA 2. CPC
productType
int
1. GA 2. GP
bid
long
Bid Unit: USD\*100000
region
List<String>
Region
campaignId
long
Ad campaign ID

Return example:

{ "code": 0, "message": "Success", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "groupId": 100205030, "name": "Ad group 1", "dayBudget": 3000000, "billingType": 11, "productType": 1, "bid": 100000, "region": ["RU","afghanistan_badakhshan_new","616436"], "campaignId": 100205030 }, { "accountId": 1, "groupId": 100205031, "name": "Ad group 2", "dayBudget": 3000000, "billingType": 11, "productType": 1, "bid": 100000, "region": ["RU","afghanistan_badakhshan_new","616436"], "campaignId": 100205030 } ] } }

# 2.2 Add a new ad group

Interface/foreign/marketing/group/add

Request methodPOST

Content-Type:application/json

Request parameters:

Field
Type
Required or not
Description
accountId
Long
Yes
Account ID
campaignId
Long
Yes
Campaign ID
groupName
String
No
Ad group name (default is M_promotion goal_creation time)
packageName
String
Yes
Package name
productType
Integer
Yes
Promoted products (1.GA 2.GP)
settlementType
Integer
Yes
Settlement method (1. Xiaomi 2. Third party)
mediaAndTagIds
JSON
Yes
Publisher and ad placement
regions
List<String>
Yes
Target countries/regions
billingType
Integer
Yes
Bid type (11.CPA 2.CPC 1.OCPC)
bid
Long
Yes
Bid (Unit: USD\*100000)
dayBudget
Long
Yes
Daily budget (Unit: USD\*100000)
beginTime
Long
Yes
Placement start time
endTime
Long
Yes
Placement end time
uniKey
String
Yes
Unique string

Request example:

[ { "accountId": 1420, "campaignId": 75312748, "groupName": "Test Ad Group 1", "packageName": "a.b.c", "productType":1, "settlementType":1, "mediaAndTagIds":{ "all": false, "exclude": [ { "id": 1, "type": "mediaClass", "all": false, "subList": [ { "id": 386, "type": "media", "all": false, "subList": [ { "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] } ] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] }, "regions": ["IN","ID"], "billingType": 11, "dayBudget": 3000000, "bid": 10000, "timeZone": "+8", "beginTime": "", "endTime": "", "uniKey": "0ah0Ko2UCl48htsz" }, { "accountId": 1420, "campaignId": 93472403, "groupName": "Test Ad Group 2", "packageName": "a.b.c", "productType":1, "settlementType":1, "mediaAndTagIds":{ "all": false, "exclude": [ { "id": 1, "type": "mediaClass", "all": false, "subList": [ { "id": 386, "type": "media", "all": false, "subList": [ { "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] } ] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] }, "regions": ["IN","ID"], "billingType": 11, "dayBudget": 3000000, "bid": 10000, "beginTime": "1711612800000", "endTime": "1711785600000", "uniKey": "yAHqxOaIIw4wnV13" } ]

Return example:

{ "code": 0, "message": "Success", "result":[ {"uniKey": "oCtdQktKeC6lsODu", "id":39451985}, {"uniKey": "hNtN5LseHtaAAG0G", "id":98724407} ] }

# 2.3 Modify ad group

Interface/foreign/marketing/group/update

Request methodPOST

Content-Type:application/json

Request parameters:

Field
Type
Description
groupIds
List<Long>
Ad group ID list
regions
List<String>
Target countries/regions
dayBudget
Long
Daily budget Unit: (USD\*100000)
bid
Long
Bid

Request example:

{ "groupIds": [32434,2346], "regions": ["IN","ID"], "dayBudget": 500000, "bid": 100000 }

Return example:

{ "code": 0, "message": "Success" }

# 2.4 Retrieve country list

Interface/foreign/marketing/region/countryList

Request methodGET

Content-Type:application/json

Return example:

{ "code": 0, "message": "Success", "result": [ { "geoType": "COUNTRY", "id": "AF", "name": "Afghanistan" }, { "geoType": "COUNTRY", "id": "AX", "name": "Aland islands" } ] }

# 2.5 Retrieve the regions in a country

Interface/foreign/marketing/region/getByCountry

Request methodGET

Content-Type:application/json

Request parameters:

Field
Type
Description
country
String
Country/region

Return example:

{ "code": 0, "message": "Success", "result": [ { "geoType": "PROVINCE", "id": "afghanistan_badakhshan_new", "name": "badakhshan", "subGeo":[ { "geoType": "CITY", "id": "616418", "name": "ab barek" }, { "geoType": "CITY", "id": "616436", "name": "ab chanar" } ] }, { "geoType": "PROVINCE", "id": "afghanistan_badghis_new", "name": "badghis" } ] }

# 2.6 Retrieve media based on ad group ID (for modifications)

Interface/foreign/marketing/group/getMediaList

Request methodGET

Content-Type:application/json

Request parameters:

Field
Type
Description
groupIds
List<Long>
Ad group ID list

Return example:

Preferred placement:

[ { "groupId":123456, "desc": "Preferred placement", "description": "", "id": 1, "name": "Preferred placement", "subSelectOption": [ { "desc": "Internal media", "description": "", "id": 1, "name": "Internal media", "subSelectOption": [ { "desc": "Global App vault (widget)", "description": "", "id": 386, "name": "Global App vault (widget)", "subSelectOption": [ { "desc": "1.386.1.1", "description": "", "id": "1.386.1.1", "name": "1.386.1.1", "isSelected": true } ] } ] }, { "desc": "Affiliate media", "description": "", "id": 4, "name": "Affiliate media", "subSelectOption": [ { "desc": "Test App Android", "description": "", "id": 512, "name": "Test App Android", "subSelectOption": [ { "desc": "1.512.29.1", "description": "", "id": "1.512.29.1", "name": "1.512.29.1", "isSelected": false } ] } ] } ] } ]

or self-selected placement:

[ { "groupId":123456, "desc": "Self-selected Placement", "description": "", "id": 2, "name": "Self-selected Placement", "subSelectOption": [ { "desc": "Banner", "description": "", "id": 6, "name": "Banner", "subSelectOption": [ { "desc": "Internal media", "description": "", "id": 1, "name": "Internal media", "subSelectOption": [ { "desc": "MSASDK_DEMO", "description": "", "id": 300, "name": "MSASDK_DEMO", "subSelectOption": [ { "desc": "1.300.2.5", "description": "", "id": "1.300.2.5", "name": "1.300.2.5", "isSelected": false } ] } ] }, { "desc": "Affiliate media", "description": "", "id": 4, "name": "Affiliate media", "subSelectOption": [ { "desc": "Word Search Block Puzzle Game", "description": "", "id": 511, "name": "Word Search Block Puzzle Game", "subSelectOption": [ { "desc": "1.511.2.1", "description": "", "id": "1.511.2.1", "name": "1.511.2.1", "isSelected": true } ] } ] } ] } ] } ]

# 2.7 Retrieve media based on campaign ID (for new entries)

Interface/foreign/marketing/group/getMediaListByCampaign

Request methodGET

Content-Type:application/json

Request parameters:

Field
Type
Description
campaignIds
List<Long>
Campaign ID collection

Return example:

Preferred placement:

[ { "desc": "Preferred placement", "description": "", "id": 1, "name": "Preferred placement", "campaignId": 13682, "subSelectOption": [ { "desc": "Internal media", "description": "", "id": 1, "name": "Internal media", "subSelectOption": [ { "desc": "Global App vault (widget)", "description": "", "id": 386, "name": "Global App vault (widget)", "subSelectOption": [ { "desc": "1.386.1.1", "description": "", "id": "1.386.1.1", "name": "1.386.1.1", "isSelected": true } ] } ] }, { "desc": "Affiliate media", "description": "", "id": 4, "name": "Affiliate media", "subSelectOption": [ { "desc": "Test App Android", "description": "", "id": 512, "name": "Test App Android", "subSelectOption": [ { "desc": "1.512.29.1", "description": "", "id": "1.512.29.1", "name": "1.512.29.1", "isSelected": false } ] } ] } ] } ]

# 2.8 Modify media

Interface/foreign/marketing/group/media/update

Request methodPOST

Content-Type:application/json

Request parameters:

Field
Type
Description
groupIds
List<Long>
Ad group ID list
mediaAndTagIds
JSON
Publisher and ad placement
all
boolean
Select all
exclude
JSONARRAY
Required when preferred placement for the ad group is set
include
JSONARRAY
Required when the ad group does not have a custom placement
subList
JSONARRAY
Sub-publisher/Ad placement

Request example:

{ "groupIds": [12174], "mediaAndTagIds": { "all": false, "exclude": [{ "id": 1, "type": "mediaClass", "all": false, "subList": [{ "id": 386, "type": "media", "all": false, "subList": [{ "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] }, { "id": "1.386.1.4", "type": "tagId", "all": true, "subList": [] }, { "id": "1.386.4.1", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.1.3", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.1.22", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.4.10001", "type": "tagId", "all": false, "subList": [] } ] }, { "id": 665, "type": "media", "all": false, "subList": [] }, { "id": 666, "type": "media", "all": false, "subList": [] }, { "id": 668, "type": "media", "all": false, "subList": [] }, { "id": 670, "type": "media", "all": false, "subList": [] }, { "id": 673, "type": "media", "all": false, "subList": [] }, { "id": 674, "type": "media", "all": false, "subList": [] }, { "id": 676, "type": "media", "all": false, "subList": [] }, { "id": 678, "type": "media", "all": false, "subList": [] }, { "id": 301, "type": "media", "all": false, "subList": [] }, { "id": 302, "type": "media", "all": false, "subList": [] }, { "id": 303, "type": "media", "all": false, "subList": [] }, { "id": 304, "type": "media", "all": false, "subList": [] }, { "id": 305, "type": "media", "all": false, "subList": [] }, { "id": 433, "type": "media", "all": false, "subList": [] }, { "id": 306, "type": "media", "all": false, "subList": [] }, { "id": 307, "type": "media", "all": false, "subList": [] }, { "id": 308, "type": "media", "all": false, "subList": [] }, { "id": 309, "type": "media", "all": false, "subList": [] }, { "id": 310, "type": "media", "all": false, "subList": [] }, { "id": 311, "type": "media", "all": false, "subList": [] }, { "id": 312, "type": "media", "all": false, "subList": [] }, { "id": 313, "type": "media", "all": false, "subList": [] }, { "id": 314, "type": "media", "all": false, "subList": [] }, { "id": 315, "type": "media", "all": false, "subList": [] }, { "id": 317, "type": "media", "all": false, "subList": [] }, { "id": 319, "type": "media", "all": false, "subList": [] }, { "id": 323, "type": "media", "all": false, "subList": [] }, { "id": 324, "type": "media", "all": false, "subList": [] }, { "id": 325, "type": "media", "all": false, "subList": [] }, { "id": 328, "type": "media", "all": false, "subList": [] }, { "id": 329, "type": "media", "all": false, "subList": [] }, { "id": 330, "type": "media", "all": false, "subList": [] }, { "id": 460, "type": "media", "all": false, "subList": [] }, { "id": 332, "type": "media", "all": false, "subList": [] }, { "id": 333, "type": "media", "all": false, "subList": [] }, { "id": 334, "type": "media", "all": false, "subList": [] }, { "id": 335, "type": "media", "all": false, "subList": [] }, { "id": 336, "type": "media", "all": false, "subList": [] }, { "id": 337, "type": "media", "all": false, "subList": [] }, { "id": 338, "type": "media", "all": false, "subList": [] }, { "id": 339, "type": "media", "all": false, "subList": [] }, { "id": 340, "type": "media", "all": false, "subList": [] }, { "id": 343, "type": "media", "all": false, "subList": [] }, { "id": 344, "type": "media", "all": false, "subList": [] }, { "id": 347, "type": "media", "all": false, "subList": [] }, { "id": 349, "type": "media", "all": false, "subList": [] }, { "id": 350, "type": "media", "all": false, "subList": [] }, { "id": 351, "type": "media", "all": false, "subList": [] }, { "id": 352, "type": "media", "all": false, "subList": [] }, { "id": 353, "type": "media", "all": false, "subList": [] }, { "id": 354, "type": "media", "all": false, "subList": [] }, { "id": 355, "type": "media", "all": false, "subList": [] }, { "id": 356, "type": "media", "all": false, "subList": [] }, { "id": 357, "type": "media", "all": false, "subList": [] }, { "id": 358, "type": "media", "all": false, "subList": [] }, { "id": 359, "type": "media", "all": false, "subList": [] }, { "id": 360, "type": "media", "all": false, "subList": [] }, { "id": 361, "type": "media", "all": false, "subList": [] }, { "id": 362, "type": "media", "all": false, "subList": [] }, { "id": 363, "type": "media", "all": false, "subList": [] }, { "id": 364, "type": "media", "all": false, "subList": [] }, { "id": 365, "type": "media", "all": true, "subList": [] }, { "id": 366, "type": "media", "all": false, "subList": [] }, { "id": 367, "type": "media", "all": false, "subList": [] }, { "id": 368, "type": "media", "all": false, "subList": [] }, { "id": 369, "type": "media", "all": false, "subList": [] }, { "id": 370, "type": "media", "all": false, "subList": [] }, { "id": 371, "type": "media", "all": false, "subList": [] }, { "id": 628, "type": "media", "all": false, "subList": [] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] } }

Return example:

{ "code": 0, "message": "Success" }

Attribute meaning:

include: Used for custom placement exclude:Used for preferred placement all:Select all subList:Required when isAll is false; empty when isAll is true

# 3. Ad creative

# 3.1 Retrieve ad creative

Interface/foreign/marketing/creative/list

Request methodGET

Content-Type:application/json

Request parameters:

Field
Type
Description
page
int
Current page number 1
pageSize
int
Page size, Default: 10
groupIds
List<Long>
Ad group ID list

Returned values:

Field
Type
Description
accountId
long
Account ID
groupId
long
Ad group ID
creativeId
long
Ad creative ID
name
String
Ad creative name
landingUrl
String
Tracking URL
exposeMonitorUrl
String
Impression monitoring

Return example:

{ "code": 0, "message": "Success", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "groupId": 1234, "creativeId": 100205030, "name": "Ad Creative Name 1", "landingUrl": "https://s.click.aliexpress.com/e/_DC4tkHX", "exposeMonitorUrl": "https://s.click.aliexpress.com/e/_DC4tkHX34" }, { "accountId": 1, "groupId": 1234, "creativeId": 100205031, "name": "Ad Creative Name 2", "landingUrl": "https://s.click.aliexpress.com/e/_DC4tkHX", "exposeMonitorUrl": "https://s.click.aliexpress.com/e/_DC4tkHX34" } ] } }

# 33.2 Add a new ad creative

Interface/foreign/marketing/creative/add

Request methodPOST

Content-Type:application/json

Request parameters:

Field
Type
Required or not
Description
accountId
Long
Yes
Account ID
groupId
Long
Yes
Ad group ID
creativeName
String
No
Ad creative name (M_GA/GP_country/region_placement start time)
imgUrls
JSONARRAY
No
Ad creative images
vedioUrls
JSONARRAY
No
Ad creative video
iconUrl
JSON
No
Icon (required for the first instance)
title
String
Yes
Ad title
description
String
Yes
Ad description
button
String
Yes
Button text
landingUrl
String
Yes
Tracking URL
deeplinkUrl
String
No
deeplink
exposeMonitorUrl
String
No
Impression monitor
uniKey
String
Yes
Unique string

Request example:

[ { "accountId": 307, "groupId": 103038, "creativeName": "Test Ad Creative 1", "imgUrls": [{"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/041d8edcec8cf4635bc3e805fa21a28d8c31844de/041d8edcec8cf4635bc3e805fa21a28d8c31844de.png","materialId":153188815,"width":600,"height":500},{"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/08e6d9c772e28432990b3e71a53d0a6367327cc7f/08e6d9c772e28432990b3e71a53d0a6367327cc7f.png","materialId":153188881,"width":600,"height":500}], "iconUrl": {"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/jpeg/w1000/AdCenter/00f663f09d257480f9cbc309f8d0742f4cce661f1/00f663f09d257480f9cbc309f8d0742f4cce661f1.jpeg","materialId":168227440,"width":84,"height":84}, "title": "Title", "description": "Description", "button": "Install", "landingUrl": "https://magnifier.sng.link/B0dnr/pj8j?_dl=com.mobileguru.fruitgardenblast.free%3A%2F%2F&aifa={gaid}&pcid={groupId}&cl={ext}&pcn={campaignId}&pshid={tagId}", "deeplinkUrl": "lazada://sg/web/www/marketing/gateway/index.html?null&dsource=sml&exlaz=e_DoiSug0NEP7Gip8qo24MCfU%252BqLKrZhcY%252BYT1MfH074zCXvTKdNAtBekmwronlsSBS2AvU1L%252BAVXJaw5ibSqRgt7gRm2qOE7bD3WnASIas1Y%253D&os=Android&gps_adid={gaid}&device_make=xiaomi&adtype=Push&sub_id1={ext}&rta_event_id={triggerId}", "uniKey": "QFHJU2Xpa00nC4Tr" } ]

Return example:

{ "code": 0, "message": "Success", "result":[ {"uniKey": "QFHJU2Xpa00nC4Tr", "id":33858248} ] }

# 3.3 Modify ad creative

Interface/foreign/marketing/creative/update

Request methodPOST

Content-Type:application/json

Request parameters:

Field
Type
Description
creativeIds
List<Long>
Ad creative ID list
landingUrl
String
Tracking URL
exposeMonitorUrl
String
Impression detection

Request example:

{ "creativeIds": [32434,2346], "landingUrl": "https://xxxx", "exposeMonitorUrl": "https://xxxx" }

Return example:

{ "code": 0, "message": "Success" }

# 3.4 Upload files

Interface/foreign/marketing/upload

Request method: POST

Content-Type:application/json

Field
Type
Required or not
Description
file
MultipleFile
Yes
Uploaded file
accountId
Long
Yes
Account ID
fileType
int
Yes
1. Image 2. Video 3. Icon

Return example:

{ "code": 0, "message": "", "result": { "height": 261, "id": 41491554, "url": "https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/076eeb887cf3c41aa9e9f1d87d96ab372c716ecd3/076eeb887cf3c41aa9e9f1d87d96ab372c716ecd3.png", "width": 1080 } }

# Code reference table

code
Note
0
Transferred successfully
10001
Invalid token
10002
Invalid appId or appKey
10003
No account query permission
10004
Unauthorized accountId
20001
Request parameter error
20002
Interface call frequency is too high
100500
Server error