Skip to end of metadata
Go to start of metadata

Ad Profile Service

A network may want to create "ad approval profiles" to define what kinds of brands and creatives can and cannot run on their publishers' pages. The Ad Profile Service lets you create your ad approval profiles at the member level or the publisher level. To create them at the publisher level, include a publisher ID. If no publisher ID is included, it will be a network-level profile available for use with all publishers.

Ad profiles consist of several elements: members, brands, creatives, language, technical attributes, categories, and ad servers. When creating an ad profile, you can approve or ban each creative in the system individually, but you may prefer to save time by approving or banning entire brands or members.

  • A member should be trusted if you believe their ads will always be acceptable. For instance, you may "trust" Network A to run quality ads, so you can mitigate the need to audit each of their creatives.
  • A brand should be trusted if you believe that ads of this brand will almost always be acceptable. However you will always have the ability to ban a specific creative even if it is part of a "trusted" brand. If the specific creative is not banned, it will run by default.
  • A brand should be banned if you believe that ads of this brand will never be acceptable. You will still have the ability to approve a specific creative assigned a "banned" brand, unless the member is banned.
  • The default profile (blank or ID set to 0) will ban unaudited ads from other members (i.e. where the member_id of the creative is different than the member_id of the TinyTag).

If a specific creative is manually approved, it will override all brand, language, technical attribute, category, and ad server bans. However, a manually approved creative will never override a member ban. Criteria set at the member level will override brand and creative settings.

On This Page

REST API

To see all ad profiles for a member:

To see a particular ad profile:

To see all ad profiles for a specific publisher:

To add a new ad profile at the member level:

To add a new ad profile at the publisher level:

To modify an existing ad profile:

To delete an existing ad profile:

Sort ad profiles alphabetically by description:

Search for an ad profile by its description:

JSON Fields

Fields

Type

Description

Default

Required On

id

int

Xandr ID assigned by the API to reference this ad_profile.

 

PUT, in query string

state

enum

The state of the ad profile. Possible values: "active" or "inactive".

"active"

 

member_id

int

The member ID that owns this ad_profile.

  

description

string

Optional description.

  

default_member_status

enum

The member status to be used by default when no explicit selection is made. Possible values:

  • "case-by-case" - This member's creatives must pass all brand, language, technical attribute, category, and ad server filtering defined on the ad profile
  • "banned" - None of this member's creatives are allowed to serve.
  

default_brand_status

enum

The brand status to be used by default when no explicit selection is made. Possible values: "trusted" or "banned".

  

default_language_status

enum

The language status to be used by default when no explicit selection is made. Possible values: "trusted" or "banned".

  

default_ad_server_status

enum

The ad server status to be used by default when no explicit selection is made. Possible values: "trusted" or "banned".

  

default_category_status

enum

The category status to be used by default when no explicit selection is made. Possible values: "trusted" or "banned".

  

default_technical_attribute_status

enum

The technical attribute status to be used by default when no explicit selection is made. Possible values: "trusted" or "banned".

  

default_audit_type

enum

The audit status to be used by default when no explicit selection is made. Possible values:

  • "platform" - Creatives must have undergone the Xandr platform audit.
  • "platform_or_self" - Creatives must have been self-audited by the member, or undergone Xandr audit.
  

members

array of objects

Array of members with their status. See Members below for more details.

  

brands

array of objects

Array of brands with their status. See Brands below for more details.

  

creatives

array of objects

Array of creatives with their status. See Creatives below for more details.

  

languages

array of objects

Array of languages with their status. See Languages below for more details.

  

ad_servers

array of objects

Array of ad servers with their status. See Ad Servers below for more details.

  

categories

array of objects

Array of categories with their status. See Categories below for more details.

  

technical_attributes

array of objects

Array of technical attributes with their status. See Technical Attributes below for more details.

  

frequency_caps

array of objects

Array of frequency/recency caps. See Frequency Caps below for more details.

  

total_creative_count

int

Number of creatives.

  

approved_creative_count

int

Number of approved creatives.

  

banned_creative_count

int

Number of banned creatives.

  

creatives_approved_percent

double

Percentage of total creatives which are approved.

  

creatives_unreviewed

int

Number of creatives pending review.

  

brands_unreviewed

int

The number of brands pending review.

  

exclude_unaudited

boolean

Whether or not to exclude creatives that have not been audited.

  

exclude_unaudited_direct

boolean

Whether or not to exclude creatives that have not been audited for direct advertisers.

  

audit_type_direct

string

   

check_attributes_direct

boolean

   

excluded_landing_page_urls

array of URLs

Not available. Bans for competitive exclusions should be effected through brand exclusions.

  

notes

string

Optional notes.

  

publisher_id

int

The ID of the publisher to associate with the ad profile.

  

last_modified

timestamp

Read-only. The timestamp of last modification to this ad profile.

  
require_seller_audit_defaultbooleanwhether or not seller audit is requiredfalse 

Members

Field

Type

Description

id

int

The ID of the member.

status

enum

Whether the member can or cannot run creatives on your publishers' pages. Allowed values:

    • "trusted" - Any of this member's creatives may serve.
    • "case-by-case" - This member's creatives must pass all brand, language, technical attribute, category, and ad server filtering defined on the ad profile
    • "banned" - None of this member's creatives are allowed to serve.

audit_type

enum

The type of audit you will require in order to serve creatives from this member. Allowed values:

    • "platform" - Creatives must have undergone Xandr platform audit.
    • "platform_or_self" - Creatives must have been self-audited by the member, or undergone Xandr audit.

exclude_unaudited

boolean

If true, unaudited creatives are excluded from this member.

require_seller_audit_statusenum

Whether the member can require its own audit for creatives from a given buyer:

    • "always" - This member can always require audit for creatives from a given buyer
    • "never" - This member can never require audit for creatives from a given buyer
    • "case-by-case" - Fall back to ad_profile.require_seller_audit_default for audit required status

The combination of the Member status, audit_type, and exclude_unaudited fields determines the buyer trust level shown in the Network Ad Quality profile in the UI.

status

audit_type

exclude_unauditedTrust Level in UI

banned

N/A

N/ABanned

case-by-case

platform

trueStandard

case-by-case

platform_or_self

trueMedium

trusted

platform

trueHigh

trusted

platform

falseMaximum

Brands

Field

Type

Description

id

int

The ID of the brand. You can use the Brand Service to retrieve brand IDs.

status

enum

Whether creatives of this brand can or cannot run on your publishers' pages. Possible values: "trusted" or "banned".

If a brand is marked as Eligible, creatives associated with this brand will serve even if the brand's category is Banned. For example, if you mark the brand "1 and 1 Internet (17310)" as Eligible it will serve even if you ban its overall category, "Telecommunications (27)".

Creatives

Field

Type

Description

id

int

The ID of the creative. You can use the Creative Service to retrieve creative IDs.

approved

boolean

If true, the creative can run on your publishers' pages.

Languages

Field

Type

Description

id

int

The ID of the language. You can use the Language Service to retrieve language IDs.

status

enum

Whether creatives of this language can or cannot run creatives on your publishers' pages. Possible values: "trusted" or "banned".

Ad Servers

Field

Type

Description

id

int

The ID of the ad server. You can use the Ad Server Service to retrieve ad server IDs.

status

enum

Whether the ad server can or cannot run creatives on your publishers' pages. Possible values: "trusted" or "banned".

Categories

Field

Type

Description

id

int

The ID of the category. You can use the Category Service to retrieve category IDs.

status

enum

Whether creatives with this category can or cannot run on your publishers' pages. Possible values: "trusted" or "banned".

Technical Attributes

Field

Type

Description

id

int

The ID of the technical attribute. You can use the Technical Attribute Service to retrieve technical attribute IDs.

status

enum

Whether creatives with this technical attribute can or cannot run on your publishers' pages. Possible values: "trusted" or "banned".

Frequency Caps

Field

Type

Description

id

int

Read-only. The ID of the frequency cap definition.

member_id

int

Read-only. The ID of the member that owns the ad profile.

max_session_imps

int

The maximum number of impressions per person per session for creatives with the specified technical_attributes or categories. If set, this value must be between 0 and 255.

max_day_imps

int

The maximum number of impressions per person per day for creatives with the specified technical_attributes or categories. If set, this value must be between 0 and 255.

min_minutes_per_imp

int

The minimum number of minutes between impressions per user for creatives with the specified technical_attributes or categories.

cap_users_without_cookie

boolean

If true, users without cookies will never be shown creatives with the specified technical_attributes or categories. They will be treated as if they've reached the frequency cap.

If false, no frequency cap for the specific technical_attributes or categories will apply to users without cookies. It will be possible for them to see an unlimited number of creatives with the specified technical_attributes or categories.

technical_attributes

array

The IDs of the technical attributes that you are limiting. You can use the Technical Attribute Service to get a complete list of technical attributes. The technical_attributes and categories fields have an OR-relationship.

categories

array

The IDs of the categories that you are limiting. You can use the Category Service to get a complete list of categories. The technical_attributes and categories fields have an OR-relationship.

Examples

Append on PUT

You will overwrite existing data with the contents of your PUT request unless you add the query string parameters append=true to the request. For more information, see API Semantics and the example Update an existing ad profile below.

 Create a new ad profile
Update an existing ad profile
 Add an ad profile to your member
 View an ad profile

Creative Attribute Frequency Capping Examples

 Add a frequency cap rule to an ad profile
 Add a frequency cap rule
 Modify a frequency cap rule