API ReferenceCommunity DiscussionAnnouncements
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsLog In
API Reference
Start typing to search…

Content & Safety Targeting

Overview

Content and safety targeting allows you to control where your video campaigns appear and ensure brand safety. You can target specific domains, content categories, and set brand safety params.

The restrictions object

The restrictions object contains an array of targeting rules that define which content and safety settings your video campaign will target or exclude.

A sample object

{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["example.com"],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}

type

Possible values:

typeDescription
"INCLUDE"Target only the specified content/safety settings
"EXCLUDE"Block the specified content/safety settings
"ALL"No restrictions (target all content/safety settings)

value

An array of content and safety targeting values that correspond to the restriction_name. The array can contain multiple values for broader targeting or a single value for precise targeting.

restriction_name

Possible values:

DOMAINTarget or exclude specific domains where your video ads can appear.
KEYWORDS_IN_URLTarget pages based on keywords in the URL.
CATEGORYTarget specific content categories.
IAS_BRAND_SAFETYIntegral Ad Science (IAS) brand safety categories.
BRAND_SAFETY_LEVELGeneral brand safety level settings.
BRAND_QUALITY_LEVELBrand quality level settings.

Targeting

Domain

Target or exclude specific domains where your video ads can appear (DOMAIN).

Set domain targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "EXCLUDE",
      "value": ["example-news.com", "demo-publisher.net"],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Domain Excluded Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "EXCLUDE",
      "value": ["example-news.com", "demo-publisher.net"],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Keywords in URL

Target pages based on keywords in the URL (KEYWORDS_IN_URL).

Set keyword targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "INCLUDE",
      "value": ["sports", "technology", "business"],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Keyword Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "INCLUDE",
      "value": ["sports", "technology", "business"],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Category

Target specific content categories (CATEGORY).

Set category targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "INCLUDE",
      "value": ["news", "entertainment", "sports"],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Category Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "INCLUDE",
      "value": ["news", "entertainment", "sports"],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

IAS brand safety

Integral Ad Science (IAS) brand safety categories (IAS_BRAND_SAFETY).

Set IAS brand safety targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "INCLUDE",
      "value": ["501", "505", "507", "509", "511", "531"],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "IAS Brand Safety Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "INCLUDE",
      "value": ["501", "505", "507", "509", "511", "531"],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Common IAS brand safety values

CategoryValueDescription
Adult Content501Adult content
Alcohol505Alcohol-related content
Gambling507Gambling content
Hate Speech509Hate speech content
Violence511Violent content
User Generated Content531User-generated content

Brand safety level

General brand safety level settings (BRAND_SAFETY_LEVEL).

Set brand safety level targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "INCLUDE",
      "value": ["1", "2"],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Brand Safety Level Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "INCLUDE",
      "value": ["1", "2"],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Brand safety levels

LevelDescription
1High brand safety
2Medium brand safety
3Low brand safety

Brand quality level

Brand quality level settings (BRAND_QUALITY_LEVEL).

Set brand quality level targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "INCLUDE",
      "value": ["2"],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Brand Quality Level Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "INCLUDE",
      "value": ["2"],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Brand quality levels

LevelDescription
1Premium quality
2Standard quality
3Basic quality

A complete example

{
  "restrictions": [
    {
      "type": "EXCLUDE",
      "value": ["example-news.com", "demo-publisher.net"],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "INCLUDE",
      "value": ["technology", "business"],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "INCLUDE",
      "value": ["news", "technology"],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "INCLUDE",
      "value": ["501", "505", "507"],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "INCLUDE",
      "value": ["1", "2"],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "INCLUDE",
      "value": ["2"],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}

This example:

  • Excludes specific domains (example-news.com, demo-publisher.net)
  • Targets technology and business keywords in URLs (technology, business)
  • Includes news and technology categories (news, technology)
  • Excludes adult content, alcohol, and gambling (IAS categories 501, 505, 507)
  • Targets high and medium brand safety levels (1, 2)
  • Targets standard brand quality level (2)

Making updates

You can update content and safety targeting by passing a restrictions object with the targeting options you want to modify. When you pass a subset of targeting options, the other targeting options will remain unchanged.

Update existing targeting

Example 1 - pass a complete set

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["example.com"],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
📘

POST

To update a video campaign, use the POST operation.

Example 2 - pass a subset

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["example.com"],
      "restriction_name": "DOMAIN"
    }
  ]
}

Clear existing targeting

Remove all content and safety targeting restrictions by setting "type": "ALL" and "value": [] (empty array). You must provide a complete set of restrictions - an empty collection will result in an error.

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Broad Content Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "DOMAIN"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "KEYWORDS_IN_URL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CATEGORY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "IAS_BRAND_SAFETY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_SAFETY_LEVEL"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "BRAND_QUALITY_LEVEL"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Related pages