Custom Segment Retrieval API Guide
This document provides a technical overview of Custom Segment Retrieval API to return all the IAS custom segments on a Demand Side Platform (DSP) via a single web service query.
Overview
Integral Ad Science (IAS) developed the Custom Segment Retrieval API to return all the IAS custom segments on a Demand Side Platform (DSP) via a single web service query.
Use Case
An advertiser wants to sell hiking boots and targets positive sentiments like exercise, the outdoors, and camaraderie and wants positive news about their brand. The advertiser sets those preferences in their IAS setup. With the Custom Segment Retrieval API, you can retrieve an advertiser's specific segments to display in your DSP. Then the advertiser can select appropriate segments and positive contextual segments from your UI.
You can programmatically retrieve available IAS custom segments in a single API call to surface into an DSP in a drop-down without manual interaction or text input. Instead of customers typing a numeric custom segment ID in a text field, customers can select a human readable name from a list.
While building your UI, take note that this API does not return the unscored custom segment (1000000). Instead, IAS recommends you have a checkbox, on by default, letting advertisers optimize away from pages unscored by the IAS semantic intelligence engine when optimizing for other content avoidance segments. The unscored segment does not need to be applied for targeting segments or URL Exclusion lists.
Note: The unscored custom segment allows advertisers to optimize away from unscored pages; see the 'Pre-bid Targeting Segments for Platforms Reference Guide' for more information on the unscored custom segment.
This API avoids the usability challenge of needing an exact match of a numeric ID to ensure the customer can access the custom segments. Also, the Custom Segment Retrieval API allows your customers to see and select which segments are available. When a DSP integrates with this API, your customers can discover IAS custom segments to maximize their advertiser spend.
Segments Product Names
IAS applies multiple custom segments to the same campaign. The custom segments include the following product names:
Product Name | Targeting | Description |
BrandSuitability | Negative | Context Control Avoidance profiles designed specifically for the advertiser. |
PositiveContextualSegments | Positive | Context Control Targeting segments designed specifically for an advertiser. |
URLBlacklists | Negative | Segments which mimic the URL Exclusion settings specified by the agency on the IAS Open Web. |
ExtendedProtectionSegments | Negative | Context Control Avoidance segments allow advertisers to understand the true context, sentiment, and semantics of a given page at scale to avoid content that is not suitable for a given brand or campaign without over- blocking appropriate contexts. ExtendedProtectionSegments segments are available for all clients. |
ExtendedTargetingSegments | Positive | Context Control Targeting segments customized for non brand specific based targeting goals. For example, if an advertiser wants to target pages about cars in the context of luxury homes and goods. ExtendedTargetingSegments segments are available for all clients. |
QualitySyncPrebidSegments | Positive | Quality Sync segment. |
See the 'Pre-bid Targeting Segments for Platforms Reference Guide' for more information on the segments.
API Reference
This Custom Segment Retrieval API returns all the IAS custom segments for all advertisers on a DSP in a single query. You can access the custom segments available for the advertiser by searching for your own first party IDs for the advertiser or agency configuring the custom segments.
Note: IAS recommends you limit queries to less than once every 15 minutes.
Use the following URL to access the web service:
Area | URL |
Authentication Token URL | https://auth.adsafeprotected.com/uaa/oauth/token |
Base Endpoint | https://segment.adsafeprotected.com/api/v1/<DSP advertiser ID>/ |
Your IAS representative provides the DSP advertiser ID.
Authentication
This API uses OAuth 2.0 with the 'client_credentials' grant flow. Coordinate with your IAS representative to obtain a client ID and client secret.
Once generated, you can re-use the token with multiple requests to the reporting API until the token expires (which is indicated with the error 'invalid_token' and an error description 'Access token expired').
Output
This API returns JSON of all segment types from a single query. The JSON output is a Keys object, or an empty JSON (for example, {}) for any error.
The Keys object has an array of advertiser objects. Every advertiser object has a DSP entity ID, a DSP advertiser ID, a vendor Advertiser ID and an array of custom segment objects.
Advertisers
Keys has an array of Advertisers objects which contains:
Name | Description |
DSPAdvertiserID | The DSP seat ID for the advertiser (String). This is a required output except in the default array element case when the DSPAdvertsierID and VendorAdvertiserID are all set to "NULL". See 'Default Advertisers Array Element' for more information. If this value is not set to "NULL", then the CustomSegments for the products ExtendedProtectionSegments and ExtendedTargetingSegments have an empty Segments array. |
VendorAdvertiserID | The IAS advertiser ID in the IAS Signal (String). This is a required output except in the default array element case when the DSPAdvertsierID and VendorAdvertiserID are all set to "NULL". See 'Default Advertisers Array Element' for more information. If this value is not set to "NULL", then the CustomSegments for the products ExtendedProtectionSegments and ExtendedTargetingSegments have an empty Segments array. |
CustomSegments | An array of CustomSegments objects. The custom segment object has a product name, targeting logic, targeting type and an array of Segments objects. |
Advertisers Array Elements
See the sample below:
{"Keys": { "Advertisers": [ { "DSPAdvertiserID": "Advertiser ID", "VendorAdvertiserID": "12345", "CustomSegments": [ { "ProductName": "<One of the 6 product names>", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [ { "code": "1000131", "Name": "Advertiser_Keyword_List1", "Description": "Keyword Exclusion List 1 Advertiser 23464", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { ... ] }, { ... { ... { ... { ... ] }, { ... { ... ] }}Default Advertisers Array Element
The array of Advertisers has a default array item in which the DSPAdvertiserID and VendorAdvertiserID are set to "NULL". Since ExtendedProtectionSegments and ExtendedTargetingSegments are available for all clients, this array item returns the segments for those product names, as shown below:
{"Keys": { "Advertisers": [ { ... { ... { "DSPAdvertiserID": "NULL", "VendorAdvertiserID": "NULL", "CustomSegments": [ { ... { ... { ... { "ProductName": "ExtendedProtectionSegments", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [ { "code": "3500171", "Name": "Vaccine", "Description": "Target Content Related to Vaccine Breakthroughs", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { ... { ... ] }, { "ProductName": "ExtendedTargetingSegments", "TargetingLogic": "anyOf", "TargetingType": "positive", "Segments": [ { "code": "3500070", "Name": "pet owners", "Description": "target pet owners", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { ... { ... ] } ] } ] }}When you aren't able to match an advertiser ID with the IAS API output, IAS recommends you display the default segments for the ExtendedProtectionSegments and ExtendedTargetingSegments product names in your UI.
CustomSegments
Each object in a CustomSegments array contains the following names:
Name | Description |
ProductName | The product name is a String for one of the following custom segments: BrandSuitability PositiveContextualSegments URLBlacklists ExtendedProtectionSegments (available for all clients) ExtendedTargetingSegments (available for all clients) QualitySyncPrebidSegments See 'Segments Product Names' for more information on the product names. |
TargetingType | Indicates how the DSP must handle the custom segment. Whether partners should target toward or away from the custom segment. Possible values: negative or positive. |
TargetingLogic | Indicates how the DSP must handle the custom segment. The values are comma separated with the possible values: single, allOf, or anyOf. |
Segments | An array of Segments objects. |
Segments
Name | Description |
Name | The name of the custom segment. |
code | The number, as a String, for the custom segment. |
Description | A human readable description for the custom segment. |
SegmentType | Useful for tracking purposes, the segment type has the possible values of Keyword, seasonal, garm, Exclusion, custom, topical, audience_proxy, or vertical. |
See 'Sample Response' for an example of the output.
Sample Response
See the sample response below:
{ "Keys": { "Advertisers": [ { "DSPAdvertiserID": "advertiser ID 1", "VendorAdvertiserID": "23464", "CustomSegments": [ { "ProductName": "BrandSuitability", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [ { "code": "1000131", "Name": "Advertiser_Keyword_List1", "Description": "Keyword Exclusion List 1 Advertiser 23464", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { "code": "1500460", "Name": "Advertiser_Contextaul_Avoidance1", "Description": "Contextual Protection Segment Advertiser 23464", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" } ] }, { "ProductName": "PositiveContextualSegments", "TargetingLogic": "anyOf", "TargetingType": "positive", "Segments": [] }, { "ProductName": "URLBlacklists", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [ { "code": "2004243", "Name": "Advertiser_URL_List_23464", "Description": "URL Exclusion List 1 Advertiser 23464", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" } ] }, { "ProductName": "ExtendedProtectionSegments", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [] }, { "ProductName": "ExtendedTargetingSegments", "TargetingLogic": "anyOf", "TargetingType": "positive", "Segments": [] }, { "ProductName": "QualitySyncPrebidSegments", "TargetingLogic": "single", "TargetingType": "positive", "Segments": [] } ] }, { "DSPAdvertiserID": "advertiser ID 1", "VendorAdvertiserID": "9876", "CustomSegments": [ { "ProductName": "BrandSuitability", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [ { "code": "1000132", "Name": "Advertiser_Keyword_List1", "Description": "Keyword Exclusion List 1 Advertiser 9876", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { "code": "1500461", "Name": "Advertiser_Contextaul_Avoidance1", "Description": "Contextual Protection Segment Advertiser 9876", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" } ] }, { "ProductName": "PositiveContextualSegments", "TargetingLogic": "anyOf", "TargetingType": "positive", "Segments": [] }, { "ProductName": "URLBlacklists", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [ { "code": "2005243", "Name": "Advertiser_URL_List_9876", "Description": "URL Exclusion List 1 Advertiser 9876", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" } ] }, { "ProductName": "ExtendedProtectionSegments", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [] }, { "ProductName": "ExtendedTargetingSegments", "TargetingLogic": "anyOf", "TargetingType": "positive", "Segments": [] } ] }, { "DSPAdvertiserID": "NULL", "VendorAdvertiserID": "NULL", "CustomSegments": [ { "ProductName": "BrandSuitability", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [] }, { "ProductName": "PositiveContextualSegments", "TargetingLogic": "anyOf", "TargetingType": "positive", "Segments": [] }, { "ProductName": "URLBlacklists", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [] }, { "ProductName": "QualitySyncPrebidSegments", "TargetingLogic": "single", "TargetingType": "positive", "Segments": [] }, { "ProductName": "ExtendedProtectionSegments", "TargetingLogic": "anyOf", "TargetingType": "negative", "Segments": [ { "code": "3500171", "Name": "Vaccine", "Description": "Target Content Related to Vaccine Breakthroughs", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { "code": "1500170", "Name": "Auto_Recalls", "Description": "Avoid content related to auto recalls", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { "code": "1500170", "Name": "Auto_Recalls", "Description": "Avoid content related to auto recalls", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" } ] }, { "ProductName": "ExtendedTargetingSegments", "TargetingLogic": "anyOf", "TargetingType": "positive", "Segments": [ { "code": "3500070", "Name": "pet owners", "Description": "target pet owners", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { "code": "3500171", "Name": "Vaccine", "Description": "Target Content Related to Vaccine Breakthroughs", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" }, { "code": "3500170", "Name": "Family_Sedan", "Description": "Target Family Sedan Related Content", "SegmentType": "Keyword|seasonal|garm|Exclusion|custom|topical|audience_proxy|vertical" } ] } ] } ] }}