Rules Management API

You can create new competitor rules and/or risky content rules via the MAX dashboard. You do this one rule at a time. But you can also use the Ad Review Rules Management API described on this page to view or create many rules in one request.

See also

• “Gain Greater Control Over Ad Visibility with MAX Ad Review” from AppLovin’s Blog.
• “Competitor Monitoring” and “Risky Content Detection” from this documentation.

There are two endpoints in this API:

1. /v1/rules/competitors
   • Make a GET request to /v1/rules/competitors to view all your pre-defined competitor rules (active and paused rules).
   • Make a POST request to /v1/rules/competitors to create new competitor rules.
2. /v1/rules/risky
   • Make a GET request to /v1/rules/risky to view all your pre-defined risky content rules (active and paused rules).
   • Make a POST request to /v1/rules/risky to create new risky content rules.

The following sections of this page explain these endpoints in greater detail.

Note

You must authenticate each API request. To do so, add an Api-Key HTTP header to your request and set its value to your account’s Ad Review Key.

You can find your Ad Review Key in the Account > General > Keys section of the AppLovin dashboard.

The /v1/rules/competitors Endpoint

To create new competitor rules, make a POST request to the competitors endpoint. Put the required fields in the request body, as described below. You can create multiple competitor rules in each request. This creates each new rule with an active status.

If an identical active competitor rule already exists, the API does not add that rule a second time. Instead it includes the rule in the existing_rules array in the response. If an identical paused rule exists, its status changes to active. All new or reactivated rules appear in the updated_rules array in the response. If a rule contains invalid values, the API does not add that rule but includes it in the invalid_rules array in the response.

To view all your existing competitor rules (active and paused rules) make a GET request to the competitors endpoint.

Note

This endpoint does not allow you to edit or pause existing rules. Instead, do that in the UI.

Target URL

https://api-safedk.applovin.com/v1/rules/competitors

POST Request Body

Example

{
  "rules": [
    {
      "name": "android title rule",
      "platform": "android",
      "package_names": ["com.mytest.app"],
      "rule_type": "title",
      "value": ["com.examplegames.solitaire", "com.eg.Bricks"]
    },
    ⋮
  ]
}

Table of Request Body Elements

Name	Type	Description / Valid Values	Required on Creation (POST)
name	string	The rule name (you may use the same name for multiple rules). The maximum length is 35 characters. Rule names can contain alphanumeric characters, _, : , - , &, or .	true
platform	string	"android" or "ios"	true
package_names	string[]	The package names / bundle IDs of the publisher apps that are associated with this rule (e.g. "com.my.test.app"). If you pass an empty array here, your rule will apply to all of your apps for this platform. Note: If one of these names is for an app that does not match the selected platform, the entire rule is invalid.	false
rule_type	string	"title", "store_category", or "advertiser"	true
value	string[]	An array of possible values for the ad characteristic indicated by the rule_type field. If the ad matches any of these strings for that characteristic, this rule will flag the ad. Note: If one of the values is not appropriate for the selected platform (for example, your rule says it applies to Android apps, but you have passed an iTunes ID), the whole rule is invalid and the API will reject it. Correct values for the strings in this array depend on which platform and rule_type you select (see “Valid Rule Values” below).	true

Possible Errors

• 400 (Bad Request) if the request’s body structure is not valid.
• 401 (Unauthorized). You must authenticate each API request. To do so, add an Api-Key HTTP header to your request and set its value to your account’s Ad Review Key.

  You can find your Ad Review Key in the Account > General > Keys section of the AppLovin dashboard.

Response Format (POST)

The response includes a hash with three elements:

1. updated_rules—the newly-created rules, and any paused rules that this request reactivated
2. existing_rules
3. invalid_rules

Each of these elements includes:

1. total—an integer that indicates the total number of rules covered by this element
2. rules—an array containing the relevant rule objects (the same variety of rule object as is found in the POST request—see “Table of Request Body Elements” above for the elements of this object)

Response Format (GET)

A successful response includes an array of all existing custom competitors rule objects. This does not include any rules that were auto-generated by MAX Ad Review. Elements of this response object include the name, platform, package_names, rule_type, and value (see “Table of Request Body Elements” above for an explanation of these elements), as well as is_active which is true if the rule is currently active, or false otherwise.

Example

[
  {
    "name": "android title rule",
    "platform": "android",
    "package_names":["com.test.my_first_app","com.test.my_second_app"],
    "rule_type": "title",
    "value": ["solitaire", "block", "com.games.solitaire", "com.bestgames.Bricks"],
    "is_active": "true"
  },
  {
    "name": "ios title rule",
    "platform": "ios",
    "rule_type": "title",
    "value": ["1449713068"],
    "is_active": "false"
  }
]

The /v1/rules/risky Endpoint

To create new risky content rules, make a POST request to the risky endpoint. Include the required fields in the request body, as described below. You can create multiple risky content rules per request. This creates all the new rules with an active status.

If an identical active risky content rule already exists, the API does not add that rule a second time. Instead, it includes the rule in the existing_rules array in the response. If an identical paused rule exists, its status changes to active. All new or reactivated rules appear in the updated_rules array in the response. If a rule contains invalid values, the API does not add that rule but includes it in the invalid_rules array in the response.

To view all your existing risky content rules (active and paused rules) make a GET request to the risky endpoint.

Note

This endpoint does not allow you to edit or pause existing rules. Instead, do that in the UI.

Target URL

https://api-safedk.applovin.com/v1/rules/risky

POST Request Body

Example

{
  "rules": [
    {
      "name": "android title rule",
      "platform": "android",
      "package_names": ["com.my.android.test.app"],
      "rule_type": "title",
      "value": ["com.games.solitaire","com.games.Bricks"]
    },
    {
      "name": "ios title rule",
      "platform": "ios",
      "rule_type": "title",
      "value": ["1349713000"]
    },
    {
      "name": "store_category rule",
      "platform": "ios",
      "rule_type": "store_category",
      "value": ["Action", "Card"]
    },
    {
      "name": "advertiser ios rule",
      "platform": "ios",
      "rule_type": "advertiser",
      "value": ["ExampleAdvertiser1", "ExampleAdvertiser2"]
    },
    {
      "name": "content_rating ios rule",
      "platform": "ios",
      "rule_type": "content_rating",
      "value": ["12+", "17+"]
    },
    {
      "name": "advisory ios rule",
      "platform": "ios",
      "rule_type": "advisory",
      "value": ["Frequent/Intense Alcohol, Tobacco or Drug Use or References"]
    },
    {
      "name": "web_domain rule",
      "platform": "ios",
      "rule_type": "web_domain",
      "value": ["test.com", "example.com"]
    },
    {
      "name": "ios_platform_with_android_package_name_rule",  //invalid rule
      "platform": "ios",
      "package_names": "com.my.android.test.app",
      "rule_type": "title",
      "value": ["1449713068"]
    },
    {
      "name": "ios_platform_with_android_title_value",  //invalid rule
      "platform": "ios",
      "rule_type": "title",
      "value": ["1449713068", "com.games.solitaire1"]
    },
    {
      "name": "ios_platform_with_android_content_rating_value",  //invalid rule
      "platform": "ios",
      "rule_type": "content_rating",
      "value": ["Everyone"]
    }
  ]
}

See “Response Format (POST): Example” below to see how the invalid rules are reported in the response to this request.

Table of Request Body Elements

Name	Type	Description / Valid Values	Required on Creation (POST)
name	string	The rule name (you may use the same name for multiple rules). The maximum length is 35 characters. Rule names can contain alphanumeric characters, _, : , - , &, or	true
platform	string	"android" or "ios"	true
package_names	string[]	The package names / bundle IDs of the publisher apps that are associated with this rule (e.g. "com.my.test.app"). If you pass an empty array here, your rule will apply to all of your apps for this platform. Note: If one of these names is for an app that does not match the selected platform, the entire rule is invalid.	false
rule_type	string	"title", "store_category", "advertiser", "web_domain", "content_rating", or "advisory"	true
value	string[]	An array of possible values for the ad characteristic indicated by the rule_type field. If the ad matches any of these strings for that characteristic, this rule will flag the ad. Note: If one of the values is not appropriate for the selected platform (for example, your rule says it applies to Android apps, but you have passed an iTunes content rating value), the whole rule is invalid and the API will reject it. Correct values for the strings in this array depend on which platform and rule_type you select (see “Valid Rule Values” below).	true

Possible Errors

• 400 (Bad Request) if the request’s body structure is not valid.
• 401 (Unauthorized). You must authenticate each API request. To do so, add an Api-Key HTTP header to your request and set its value to your account’s Ad Review Key.

  You can find your Ad Review Key in the Account > General > Keys section of the AppLovin dashboard.

Response Format (POST)

The response includes a hash with three elements:

1. updated_rules—the newly-created rules and any paused rules that this request reactivated
2. existing_rules
3. invalid_rules

Each of these elements includes:

1. total—an integer that indicates the total number of rules covered by this element
2. rules—an array containing the relevant rule objects (the same variety of rule object as is found in the POST request—see “Table of Request Body Elements” above for the elements of this object)

Example

"updated_rules": {
  "total": 6
  "rules": {[
    {
      "name": "android title rule",
      "platform": "android",
      "package_names": ["com.my.android.test.app"],
      "rule_type": "title",
      "value": ["com.games.solitaire","com.games.Bricks"]
    }, {…},{…},{…},{…},{…}
  ]
},
"invalid_rules": {
  "total": 3
  "rules": [
    {
      "name": "ios_platform_with_android_package_name_rule",  //invalid rule
      "platform": "ios",
      "my_apps_package_name": "com.my.android.test.app",
      "rule_type": "title",
      "value": ["1449713068"]
    }, {…},{…}
  ]
},
"existing_rules": {
  "total": 1
  "rules":[
    {
      "name": "web_domain rule",
      "platform": "ios",
      "rule_type": "web_domain",
      "value": ["test.com", "example.com"]
    }
  ]
}

Response Format (GET)

A successful response includes an array of all existing custom risky content rule objects. This does not include any rules that were auto-generated by MAX Ad Review. Elements of this response object include the name, platform, package_names, rule_type, and value (see “Table of Request Body Elements” above for an explanation of these elements), as well as is_active which is true if the rule is currently active, or false otherwise.

Example

[
  {
    "name": "android title rule",
    "platform": "android",
    "package_names":["com.test.my_first_app","com.test.my_second_app"],
    "rule_type": "title",
    "value": ["solitaire", "block", "com.games.solitaire", "com.bestgames.Bricks"],
    "is_active": "true"
  },
  {
    "name": "ios title rule",
    "platform": "ios",
    "rule_type": "title",
    "value": ["1449713068"],
    "is_active": "false"
  }
]

Limiting GET Requests to Avoid Timeouts

If there are too many rules, a GET request to these endpoints may time out while it tries to retrieve and send them all. To fix this, you can limit the number of rules that these endpoints return. Do this by adding the limit query parameter. Then you can paginate through all rules by adding the offset query parameter. For example:

1. GET /v1/rules/risky?limit=10&offset=0—get the first ten risky content rules
2. GET /v1/rules/risky?limit=10&offset=10—get the next ten risky content rules
3. GET /v1/rules/risky?limit=10&offset=20—get the next ten risky content rules
4. ⋮

The response will be an empty array if you reach the end of the list and there are no more rules to return.

Valid Rule Values

Android

Table of Valid Values

rule_type	Valid Values
advertiser	Any valid advertiser name (e.g. "Super Lucky Casino"). Copy the exact advertiser from the store (this is case sensitive).
advisory	Advisory strings from Google Play (e.g. "Sexual Content"). See “Advisory Valid Values” below.
content_rating	Google Play content_rating in USA: "Everyone", "Everyone 10+", "Teen", "Mature 17+", or "Adults only 18+".
store_category	Google play categories strings. See “Store Categories Valid Values” below.
title	The app package name (free text rules are not supported by this API, only by the UI)
web_domain	A valid web domain (without “http(s)”, “www” or trailing slashes), for example: "apple.com"

Store Category Valid Values

• "Action"
• "Action & Adventure"
• "Adventure"
• "Arcade"
• "Art & Design"
• "Auto & Vehicles"
• "Beauty"
• "Board"
• "Books & Reference"
• "Brain Games"
• "Business"
• "Card"
• "Cards"
• "Casino"
• "Casual"
• "Comics"
• "Communication"
• "Creativity"
• "Dating"
• "Education"
• "Educational"
• "Entertainment"
• "Events"
• "Finance"
• "Food & Drink"
• "Health & Fitness"
• "House & Home"
• "Libraries & Demo"
• "Lifestyle"
• "Maps & Navigation"
• "Medical"
• "Music"
• "Music & Audio"
• "Music & Video"
• "Music Games"
• "News & Magazines"
• "Parenting"
• "Personalization"
• "Photography"
• "Pretend Play"
• "Productivity"
• "Puzzle"
• "Racing"
• "Role Playing"
• "Shopping"
• "Simulation"
• "Social"
• "Sports"
• "Strategy"
• "Tools"
• "Travel & Local"
• "Trivia"
• "Video Players & Editors"
• "Weather"
• "Word"
• "Word Games"

Advisory Valid Values

• "Alcohol Reference"
• "Alcohol and Tobacco Reference"
• "Blood"
• "Blood and Gore"
• "Cartoon Violence"
• "Comic Mischief"
• "Crude Humor"
• "Diverse Content: Discretion Advised"
• "Drug Reference"
• "Drug and Alcohol Reference"
• "Fantasy Violence"
• "Fear"
• "Gambling"
• "General"
• "Horror"
• "Implied Violence"
• "Intense Violence"
• "Language"
• "Mild Blood"
• "Mild Fantasy Violence"
• "Mild Language"
• "Mild Suggestive Themes"
• "Mild Swearing"
• "Mild Violence"
• "Moderate Violence"
• "Nudity"
• "Online Interactivity"
• "Parental Guidance Recommended"
• "Partial Nudity"
• "Real Gambling/Paid Contests"
• "Sexual Content"
• "Sexual Innuendo"
• "Sexual Themes"
• "Sexual Violence"
• "Simulated Gambling"
• "Strong Language"
• "Strong Sexual Content"
• "Strong Violence"
• "Suggestive Themes"
• "Tobacco Reference"
• "Use of Alcohol"
• "Use of Alcohol and Tobacco"
• "Use of Drugs"
• "Use of Drugs and Alcohol"
• "Use of Tobacco"
• "Violence"
• "Violent References"

iOS

Table of Valid Values

rule_type	Valid Values
advertiser	Any valid advertiser name (e.g. "Super Lucky Casino"). Copy the exact advertiser from the store (this is case sensitive).
advisory	Advisory strings from iTunes (e.g. "Frequent/Intense Alcohol, Tobacco or Drug Use or References"). See “Advisory Valid Values” below.
content_rating	iTunes content_rating values in USA: "4+", "9+", "12+", or "17+"
store_category	iTunes categories strings. See “Store Categories Valid Values” below.
title	The iTunes ID (free text rules are not supported by this API, only by the UI)
web_domain	A valid web domain (without “http(s)”, “www” or trailing slashes), for example: "apple.com"

Store Category Valid Values

• "Action"
• "Adventure"
• "Animals & Nature"
• "Arcade"
• "Art"
• "Board"
• "Book"
• "Books"
• "Business"
• "Card"
• "Casino"
• "Casual"
• "Celebrations"
• "Celebrities"
• "Comics & Cartoons"
• "Developer Tools"
• "Eating & Drinking"
• "Education"
• "Emoji & Expressions"
• "Entertainment"
• "Family"
• "Fashion"
• "Finance"
• "Food & Drink"
• "Games"
• "Gaming"
• "Graphics & Design"
• "Health & Fitness"
• "Kids & Family"
• "Lifestyle"
• "Magazines & Newspapers"
• "Medical"
• "Movies & TV"
• "Music"
• "Navigation"
• "News"
• "People"
• "Photo & Video"
• "Places & Objects"
• "Productivity"
• "Puzzle"
• "Racing"
• "Reference"
• "Role Playing"
• "Role-Playing"
• "Shopping"
• "Simulation"
• "Social Networking"
• "Sports"
• "Sports & Activities"
• "Stickers"
• "Strategy"
• "Travel"
• "Trivia"
• "Utilities"
• "Weather"
• "Word"

Advisory Valid Values

• "Frequent/Intense Alcohol, Tobacco or Drug Use or References"
• "Frequent/Intense Alcohol, Tobacco, or Drug Use or References"
• "Frequent/Intense Cartoon or Fantasy Violence"
• "Frequent/Intense Horror/Fear Themes"
• "Frequent/Intense Mature/Suggestive Themes"
• "Frequent/Intense Medical/Treatment Information"
• "Frequent/Intense Profanity or Crude Humor"
• "Frequent/Intense Profanity or Crude Humour"
• "Frequent/Intense Realistic Violence"
• "Frequent/Intense Sexual Content or Nudity"
• "Frequent/Intense Simulated Gambling"
• "Gambling and Contests"
• "Infrequent/Mild Alcohol, Tobacco or Drug Use or References"
• "Infrequent/Mild Alcohol, Tobacco, or Drug Use or References"
• "Infrequent/Mild Cartoon or Fantasy Violence"
• "Infrequent/Mild Horror/Fear Themes"
• "Infrequent/Mild Mature/Suggestive Themes"
• "Infrequent/Mild Medical/Treatment Information"
• "Infrequent/Mild Profanity or Crude Humor"
• "Infrequent/Mild Profanity or Crude Humour"
• "Infrequent/Mild Realistic Violence"
• "Infrequent/Mild Sexual Content and Nudity"
• "Infrequent/Mild Simulated Gambling"
• "Unrestricted Web Access"

Changelogs

Android

iOS