/

Browse the help center

List what an entity's rules and links match

Reference

GET https://YOUR-NETWORK-DOMAIN/rest-api/matched/{entityType}/{entityId}.do

Lists the entities on the other side of the auction that the entity is matched with, as the console's Matched Placements card (on an advertiser, campaign or banner) and Matched Ads card (on a site, zone or placement) do. A demand-side entity (ADVERTISER, CAMPAIGN, BANNER) is matched with SITE, ZONE or PLACEMENT; a supply-side one with ADVERTISER, CAMPAIGN or BANNER — pick which with returnType (PLACEMENT or BANNER when omitted). matchByRules lists what the rules of the entity and of its parents match; matchLinked lists what is linked to it; with both, either counts. Only entities the caller may see are listed. Needs view rights on the entity, view rights on campaigns and inventory, and the Matched Inventory permission (for returnType SITE, ZONE or PLACEMENT) or the Matched Advertisers permission (for ADVERTISER, CAMPAIGN or BANNER).

Path Params

entityType string required

Type of the entity whose matches are listed

CAMPAIGN

entityId integer required

Id of the entity whose matches are listed

2001

Query Params

categories array<integer>

Category ids; only entities in one of them are listed

12

hideInactive boolean

Leave inactive entities out

false

labels array<string>

Label names; only entities carrying one of them are listed

premium

limit integer

Page size, 1 to 500

50

matchByRules boolean

List what the rules of the entity and its parents match

true

matchLinked boolean

List what is linked to the entity

true

name string

Substring of the name

Sports

parentId integer

Only the children of this entity, e.g. the zones of site 3001 (with parentType SITE)

3001

parentType string

Type of parentId

SITE

returnType string

Type of the matched entities to list: SITE, ZONE or PLACEMENT for a demand-side entity, ADVERTISER, CAMPAIGN or BANNER for a supply-side one. Omitted, it is PLACEMENT for a demand-side entity and BANNER for a supply-side one, the rows of the console's Matched Placements and Matched Ads cards

PLACEMENT

start integer

0-based offset of the first row

0

Responses

200

{total, data:[{id, name, and the ids of the row's parents: siteId/zoneId/placementId or advertiserId/campaignId/bannerId, parentId}]}

400

returnType is on the entity's own side, or start/limit is out of range

401

Authentication error

403

No view rights on the entity, or the matched-inventory/matched-advertisers permission is off

404

The entity does not exist or is deleted

Language

cURL Request

curl --request GET \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false' \
  --header 'X-Api-Key: YOUR_API_KEY'

Python Request

import requests

response = requests.request("GET", "https://YOUR-NETWORK-DOMAIN/rest-api/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false", headers={"X-Api-Key": "YOUR_API_KEY"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false', {
  method: 'GET',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
});

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

Java Request

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-NETWORK-DOMAIN/rest-api/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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("GET"), "https://YOUR-NETWORK-DOMAIN/rest-api/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");

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

Go Request

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://YOUR-NETWORK-DOMAIN/rest-api/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false", nil)
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")

	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/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: YOUR_API_KEY"]);

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

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/matched/CAMPAIGN/2001.do?name=Sports&categories=12&hideInactive=false")
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = 'YOUR_API_KEY'

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