/

Browse the help center

Update capping by ID

Edits one capping rule of an advertiser, campaign, banner or placement - the id from that entity's capping list.

Reference

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

Edits one capping rule of an advertiser, campaign, banner or placement - the id from that entity's capping list. Updates an existing capping object identified by its numeric ID, replacing its amount, period, period type, flat distribution flag, and optionally its subject type. The capping type must match the type of the existing record (e.g. CAMPAIGN_FREQUENCY, BANNER_CLICKS). All required fields must be provided; partial updates are not supported by this endpoint. Requires UPDATE permission on the advertiser, campaign, banner or placement the capping belongs to, and the permission of the capping type and subject. Writes also need the section permission enabled: MANAGE_INVENTORY_CAPPING for a placement capping, MANAGE_CAPPING_AND_LIMITATIONS for the others.

Path Params

cappingId integer required

Numeric ID of the capping record to update

501

Form Params

type string required

Type of the capping record. Allowed values: CAMPAIGN_REQUEST, CAMPAIGN_FREQUENCY, CAMPAIGN_CLICKS, CAMPAIGN_ACTIONS, BANNER_REQUEST, BANNER_FREQUENCY, BANNER_CLICKS, BANNER_ACTIONS, PLACEMENT_REQUEST, PLACEMENT_FREQUENCY, PLACEMENT_CLICKS, PLACEMENT_ACTIONS, ADVERTISER_FREQUENCY

CAMPAIGN_FREQUENCY

amount integer required

Maximum number of events (impressions, clicks, or actions) 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 updated successfully

400

Bad request — invalid or missing parameters

401

Authentication error

403

The caller may not change the entity the capping belongs to

404

No capping of this type has this id, or the entity it belongs to is deleted

Language

cURL Request

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