/

Browse the help center

Create advertiser capping

Creates a new capping rule for the specified advertiser, typically used for advertiser-level frequency capping across all campaigns.

Reference

POST https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/{advertiserId}.do

Creates a new capping rule for the specified advertiser, typically used for advertiser-level frequency capping across all campaigns. The capping type should be ADVERTISER_FREQUENCY for advertiser-level rules. The response JSON carries the new record, with its assigned id, under capping. Requires UPDATE permission on the advertiser, MANAGE_CAPPING_AND_LIMITATIONS enabled, and the permission of the capping type and subject.

Path Params

advertiserId integer required

Numeric ID of the advertiser to add the capping rule to

1001

Form Params

type string required

Type of the capping to create. Only ADVERTISER_FREQUENCY is accepted; any other value of the shared enum is rejected with 'Capping type is incompatible with entity'

ADVERTISER_FREQUENCY

amount integer required

Maximum number of events allowed within the specified period

1000

period integer required

Length of the capping time window, expressed in units defined by periodType

24

periodType string required

Unit of the capping period. Allowed values: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR

HOUR

flat boolean required

When true, events are distributed evenly (flat) across the period instead of being served/counted as fast as possible

true

subject string

Entity used to identify unique users for capping. Optional; allowed values: USER_COOKIE, USER_SERVER_SIDE, USER_MIXED, IP, LES_IP

USER_COOKIE

Responses

200

Capping created: {success, capping:{id, type, amount, period, periodType, flat, subject, ...}}

400

Bad request — invalid or missing parameters

401

Authentication error

403

Forbidden — insufficient permissions

404

Not found — resource does not exist

Language

cURL Request

curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=ADVERTISER_FREQUENCY' \
  --data-urlencode 'amount=1000' \
  --data-urlencode 'period=24' \
  --data-urlencode 'periodType=HOUR' \
  --data-urlencode 'flat=true' \
  --data-urlencode 'subject=USER_COOKIE'

Python Request

import requests

response = requests.request("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do", headers={"X-Api-Key": "YOUR_API_KEY"}, data={"type": "ADVERTISER_FREQUENCY", "amount": "1000", "period": "24", "periodType": "HOUR", "flat": "true", "subject": "USER_COOKIE"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({"type":"ADVERTISER_FREQUENCY","amount":"1000","period":"24","periodType":"HOUR","flat":"true","subject":"USER_COOKIE"}),
});

console.log(await response.json());

Java Request

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", HttpRequest.BodyPublishers.ofString("type=ADVERTISER_FREQUENCY&amount=1000&period=24&periodType=HOUR&flat=true&subject=USER_COOKIE"))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C# Request

using var client = new HttpClient();

var request = new HttpRequestMessage(new HttpMethod("POST"), "https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");
request.Content = new FormUrlEncodedContent(new Dictionary<string, string> { ["type"] = "ADVERTISER_FREQUENCY", ["amount"] = "1000", ["period"] = "24", ["periodType"] = "HOUR", ["flat"] = "true", ["subject"] = "USER_COOKIE" });

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Go Request

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do", strings.NewReader(`type=ADVERTISER_FREQUENCY&amount=1000&period=24&periodType=HOUR&flat=true&subject=USER_COOKIE`))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

PHP Request

<?php
$ch = curl_init("https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: YOUR_API_KEY", "Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'type=ADVERTISER_FREQUENCY&amount=1000&period=24&periodType=HOUR&flat=true&subject=USER_COOKIE');

echo curl_exec($ch);
curl_close($ch);

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/advertiser/capping/1001.do")
request = Net::HTTP::Post.new(uri)
request['X-Api-Key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/x-www-form-urlencoded'
request.set_form_data('type' => "ADVERTISER_FREQUENCY", 'amount' => "1000", 'period' => "24", 'periodType' => "HOUR", 'flat' => "true", 'subject' => "USER_COOKIE")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.body