/

Browse the help center

Create placement capping

Creates a new capping rule for the specified placement, controlling how frequently events (impressions, clicks, or actions) occur within a time window.

Reference

POST https://YOUR-NETWORK-DOMAIN/rest-api/placement/capping/{placementId}.do

Creates a new capping rule for the specified placement, controlling how frequently events (impressions, clicks, or actions) occur within a time window. The capping type determines which event category is capped (e.g. PLACEMENT_FREQUENCY for impressions, PLACEMENT_CLICKS for clicks). The response JSON carries the new record, with its assigned id, under capping. Requires UPDATE permission on the placement's site, MANAGE_INVENTORY_CAPPING enabled, and the permission of the capping type and subject.

Path Params

placementId integer required

Numeric ID of the placement to add the capping rule to

3001

Form Params

type string required

Type of the capping to create. Only placement types are accepted: PLACEMENT_REQUEST, PLACEMENT_FREQUENCY, PLACEMENT_CLICKS, PLACEMENT_ACTIONS; any other value of the shared enum is rejected with 'Capping type is incompatible with entity'

PLACEMENT_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/placement/capping/3001.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=PLACEMENT_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/placement/capping/3001.do", headers={"X-Api-Key": "YOUR_API_KEY"}, data={"type": "PLACEMENT_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/placement/capping/3001.do', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({"type":"PLACEMENT_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/placement/capping/3001.do"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", HttpRequest.BodyPublishers.ofString("type=PLACEMENT_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/placement/capping/3001.do");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");
request.Content = new FormUrlEncodedContent(new Dictionary<string, string> { ["type"] = "PLACEMENT_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/placement/capping/3001.do", strings.NewReader(`type=PLACEMENT_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/placement/capping/3001.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=PLACEMENT_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/placement/capping/3001.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' => "PLACEMENT_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