Skip to main content
Rulesets define targeting restrictions for offers. They control which traffic is accepted based on geography, device characteristics, connection type, scheduling, and IP addresses.

​
Rule categories

Geotargeting: countries, regions, cities, dmas, postal_codes, mobile_carriers Device: browsers, device_types, brands, os_versions, platforms Connection: isps, connection_types Other: ips, languages, is_block_proxy, day parting settings

​
Common fields

Every rule entry includes:
FieldValuesDescription
targeting_typeinclude, excludeWhether to allow or block matching traffic.
match_typeexact, minimum, maximum, rangeHow the value is compared.

​
Match type support

Match typeSupported by
exactcountries, regions, cities, dmas, postal_codes, mobile_carriers, browsers, device_types, brands, platforms, ips
minimumos_versions
maximumos_versions
rangeips

​
Geotargeting precedence

When combining geotargeting rules, more specific rules override less specific ones: City > DMA > ZIP/Postal Code > Region > Country For example, if you exclude the US but include New York City, traffic from New York City is still accepted.

​
Examples

{ "ruleset": {} }

{
  "ruleset": {
    "countries": [
      { "country_id": 227, "match_type": "exact", "targeting_type": "include" }
    ]
  }
}

{
  "ruleset": {
    "os_versions": [
      {
        "os_version_id": 34,
        "match_type": "minimum",
        "targeting_type": "include",
        "platform_id": 2
      }
    ]
  }
}
The following ruleset excludes all IPs in the 10.11.12.13–10.11.12.100 range as well as the single address 1.2.3.4:
{
  "ruleset": {
    "ips": [
      {
        "match_type": "range",
        "targeting_type": "exclude",
        "ip_from": "10.11.12.13",
        "ip_to": "10.11.12.100"
      },
      {
        "match_type": "exact",
        "targeting_type": "exclude",
        "ip_from": "1.2.3.4",
        "ip_to": "1.2.3.4"
      }
    ]
  }
}
Pair match_type: "maximum" with targeting_type: "exclude" to block everything up to and including a given version:
{
  "ruleset": {
    "os_versions": [
      {
        "os_version_id": 7,
        "match_type": "maximum",
        "targeting_type": "exclude",
        "platform_id": 1
      }
    ]
  }
}
Rules of different types can be combined — the resulting ruleset accepts traffic only when every rule matches. The following ruleset accepts:
  • Devices running iOS between version 9.0 and 11.4
  • Traffic from New York City
  • Mobile connection (not Wi-Fi)
  • Not from a known proxy
{
  "ruleset": {
    "os_versions": [
      { "os_version_id": 16, "match_type": "minimum", "targeting_type": "include", "platform_id": 2 },
      { "os_version_id": 33, "match_type": "maximum", "targeting_type": "include", "platform_id": 2 }
    ],
    "cities": [
      { "city_id": 479, "match_type": "exact", "targeting_type": "include" }
    ],
    "connection_types": [
      { "connection_type_id": 2, "match_type": "exact", "targeting_type": "include" }
    ],
    "is_block_proxy": true
  }
}

​
Day parting

Control when an offer accepts traffic by time of day and day of week.
FieldTypeDescription
is_use_day_partingbooleanEnable day parting.
day_parting_apply_tostringuser_timezone or selected_timezone.
day_parting_timezone_idintegerTimezone ID (when using selected_timezone).
days_partingarrayTime windows per day.
Each entry in days_parting:
FieldTypeDescription
day_of_weekinteger0 = Sunday, 1 = Monday, …, 6 = Saturday.
start_hourintegerStart hour (0–23).
start_minuteintegerStart minute (0–59).
end_hourintegerEnd hour (0–23).
end_minuteintegerEnd minute (0–59).

​
Day parting examples

{
  "ruleset": {
    "is_use_day_parting": true,
    "day_parting_apply_to": "user_timezone",
    "days_parting": [
      { "day_of_week": 1, "start_hour": 9, "end_hour": 18 },
      { "day_of_week": 2, "start_hour": 9, "end_hour": 18 },
      { "day_of_week": 3, "start_hour": 9, "end_hour": 18 },
      { "day_of_week": 4, "start_hour": 9, "end_hour": 18 }
    ]
  }
}
Use day_parting_apply_to: "selected_timezone" with day_parting_timezone_id to schedule based on a fixed timezone regardless of the device user’s local time:
{
  "ruleset": {
    "is_use_day_parting": true,
    "day_parting_apply_to": "selected_timezone",
    "day_parting_timezone_id": 67,
    "days_parting": [
      { "day_of_week": 6, "start_hour": 12, "end_hour": 14 }
    ]
  }
}

​
Complete ruleset reference

The following example exercises every rule type available. It’s unlikely you’d combine all of these in production, but it’s a useful reference for the full schema shape:
{
  "ruleset": {
    "platforms": [
      { "platform_id": 1, "match_type": "exact", "targeting_type": "include" }
    ],
    "device_types": [
      { "device_type_id": 3, "match_type": "exact", "targeting_type": "include" }
    ],
    "os_versions": [
      { "os_version_id": 32, "match_type": "minimum", "targeting_type": "include", "platform_id": 1 },
      { "os_version_id": 45, "match_type": "maximum", "targeting_type": "include", "platform_id": 1 }
    ],
    "browsers": [
      { "browser_id": 2, "match_type": "exact", "targeting_type": "include" }
    ],
    "brands": [
      { "brand_id": 23, "match_type": "exact", "targeting_type": "include" }
    ],
    "postal_codes": [
      { "postal_code": "90210", "match_type": "exact", "targeting_type": "include" },
      { "postal_code": "90211", "match_type": "exact", "targeting_type": "include" }
    ],
    "languages": [
      { "browser_language_id": 10, "match_type": "exact", "targeting_type": "include" }
    ],
    "countries": [
      { "country_id": 227, "match_type": "exact", "targeting_type": "include" }
    ],
    "regions": [
      { "region_id": 1140, "match_type": "exact", "targeting_type": "include" }
    ],
    "cities": [
      { "city_id": 555, "match_type": "exact", "targeting_type": "include" }
    ],
    "dmas": [
      { "dma_code": 807, "match_type": "exact", "targeting_type": "include" }
    ],
    "isps": [
      { "isp_id": 3827, "match_type": "exact", "targeting_type": "include" }
    ],
    "mobile_carriers": [
      { "mobile_carrier_id": 32, "match_type": "exact", "targeting_type": "include" }
    ],
    "connection_types": [
      { "connection_type_id": 2, "match_type": "exact", "targeting_type": "include" }
    ],
    "ips": [
      {
        "match_type": "range",
        "targeting_type": "exclude",
        "ip_from": "100.100.100.100",
        "ip_to": "100.100.100.255"
      }
    ],
    "is_use_day_parting": true,
    "is_block_proxy": true,
    "day_parting_apply_to": "selected_timezone",
    "day_parting_timezone_id": 90,
    "days_parting": [
      { "day_of_week": 1, "start_hour": 8, "end_hour": 17 },
      { "day_of_week": 2, "start_hour": 8, "end_hour": 17 }
    ]
  }
}