Digital Platform API - 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).

REST API

JSON fields

Members

Brands

Creatives

Languages

Ad servers

Categories

Technical attributes

Frequency caps

Examples

Create a new ad profile

This is a fairly complex profile. Below we have used the cat command to output an ad profile JSON file example.

$ cat ad_profile
{
    "ad-profile": {
        "description": "Network Level ad profile",
        "member_id": 326,
        "brands": [
            {
                "id": "168",
                "status": "banned"
            },
            {
                "id": "255",
                "status": "banned"
            },
            {
                "id": "1072",
                "status": "trusted"
            },
            {
                "id": "1090",
                "status": "trusted"
            }
        ],
        "creatives": [
            {
                "id": "5",
                "approved": true
            }
        ],
        "notes": "This is a great ad profile",
        "default_language_status": "banned",
        "default_ad_server_status": "trusted",
        "default_category_status": "trusted",
        "default_technical_attribute_status": "trusted",
        "excluded_landing_page_urls": ["https://www.netflix.com","https://www.blockbuster.com"],
        "languages": [
            {
                "id": 1,
                "status": "trusted"
            }
        ],
        "ad_servers": null,
        "categories": [
            {
                "id": 41,
                "status": "banned"
            },
            {
                "id": 43,
                "status": "trusted"
            }
        ]
    }
}

Update an existing ad profile

Given the ad profile JSON in the first example, let's say you want to update the categories array to include another item. In a real-world use case there might be 47 categories in the array. The semantics of PUT mean that in order to add another category to the array, you'll need to pass in all 47 of the existing categories plus the new one.

You can avoid this extra work by adding the query string parameters append=true to your request as shown in the example below. For backwards compatibility reasons the parameters append_only=true will also work.

$ cat ad-profile-update.json
{
  "ad-profiles":
  [
    {
      "id": 984276,
      "categories" : [
        {
          "id" : 42,
          "status" : "banned"
        }
      ]
    }
  ]
}
$ curl -b cookies -X PUT -d '@/tmp/ad-profile-update.json' \
'https://api.appnexus.com/ad-profile?id=984276&member_id=1282&append=true'
{
   "response" : {
      "id" : 984276,
      "ad-profile" : {
         "id" : 984276,
         "description" : "Rich's Crazy Reseller - Network Ad Profile",
         "categories" : [
            {
               "id" : 41,
               "status" : "banned"
            },
            {
               "id" : 42,
               "status" : "banned"
            },
            {
               "id" : 43,
               "status" : "trusted"
            }
         ],
         // many other fields...
         "default_category_status" : "trusted"
      },
      "status" : "OK",
      "count" : 1,
      "start_element" : 0,
      "num_elements" : 100,
   }
}

Add an ad profile to your member

$ curl -b cookies -c cookies -X POST -d @ad_profile  "https://api.appnexus.com/ad-profile"
{
    "response": {
        "status": "OK",
        "id": "1317"
    }
}

View an ad profile

$ curl -b cookies -c cookies "https://api.appnexus.com/ad-profile?id=1317"
{
  "response": {
    "status": "OK",
    "ad-profile": {
      "id": 1317,
      "state": "active",
      "description": "Network Level ad profile",
      "member_id": 326,
      "default_brand_status": "trusted",
      "members": null,
      "brands": [
        {
          "id": "168",
          "status": "banned"
        },
        {
          "id": "255",
          "status": "banned"
        },
        {
          "id": "1072",
          "status": "trusted"
        },
        {
          "id": "1090",
          "status": "trusted"
        }
      ],
      "creatives": [
        {
          "id": "5",
          "approved": true
        }
      ],
      "total_creative_count": 8369,
      "approved_creative_count": 1,
      "banned_creative_count": 8368,
      "creatives_approved_percent": 0.011948858883977,
      "creatives_unreviewed": 8367,
      "brands_unreviewed": null,
      "exclude_unaudited": true,
      "exclude_unaudited_direct": false,
      "notes": "This is a great ad profile.",
      "publisher_id": null,
      "last_modified": "2010-07-23 16:15:49",
      "default_language_status": "banned",
      "default_ad_server_status": "trusted",
      "default_category_status": "trusted",
      "excluded_landing_page_urls": ["https://www.netflix.com","https://www.blockbuster.com"],
      "default_technical_attribute_status": "trusted",
      "languages": [
        {
          "id": 1,
          "status": "trusted"
        }
      ],
      "ad_servers": null,
      "categories": [
        {
          "id": 41,
          "status": "banned"
        },
        {
          "id": 43,
          "status": "trusted"
        }
      ],
      "technical_attributes": null
    }
  }
}

Creative attribute frequency capping examples

Add a frequency cap rule to an ad profile

The {{"frequency_caps"}} field will be {{null}} at first:

$ curl -b cookies -c cookies -X GET "https://sand.api.appnexus.com/ad-profile?id=199943"
{
  "response": {
    "status": "OK",
    "ad-profile": {
      "id": 199943,
      "state": "active",
      "description": null,
      "member_id": 941,
      ...
      "frequency_caps": null
    }
}

Add a frequency cap rule

$ cat add_freq_cap_rule.json
{
   "ad-profile": {
      "id": 199943,
      "frequency_caps": [
        {
          "max_day_imps": 5,
          "min_minutes_per_imp": 120,
          "technical_attributes": [ {"id":4},{"id":6} ],
          "categories": [ {"id":59},{"id":37} ]
        }
      ]
   }
}
$ curl -b cookies -c cookies -X PUT --data-binary @add_freq_cap_rule.json "https://sand.api.appnexus.com/ad-profile?id=199943"
{
  "response": {
    "status": "OK",
    "id": "199943"
  }
}

Ad profile will now have the frequency cap rule

$ curl -b cookies -c cookies -X GET "https://sand.api.appnexus.com/ad-profile?id=199943"
{
  "response": {
    "status": "OK",
    "ad-profile": {
      "id": 199943,
      "state": "active",
      "description": null,
      "member_id": 941,
      ...
      "frequency_caps": [
        {
          "id": 64,
          "max_session_imps": null,
          "max_day_imps": 5,
          "min_minutes_per_imp": 120,
          "member_id": 941,
          "technical_attributes": [
            {
              "id": 4,
              "name": "Video"
            },
            {
              "id": 6,
              "name": "Expandable"
            }
          ],
          "categories": [
            {
              "id": 37,
              "name": "Politics"
            },
            {
              "id": 59,
              "name": "Get Rich Quick"
            }
          ]
        }
      ]
      ...

Modify a frequency cap rule

Use the {{PUT}} command on the {{ad-profile}} service. The frequency cap's ID must be specified in the update JSON. If the frequency cap ID is not specified, the existing rule will be deleted, and a new rule will be created.

{code}
$ cat update_freq_cap_rule.json
{
   "ad-profile": {
      "id": 199943,
      "frequency_caps": [
        {
          "id": 64,
          "technical_attributes": [ {"id":4} ],
          "categories": [ ],
          "max_day_imps": 20
        }
      ]
   }
}
$ curl -b cookies -c cookies -X PUT --data-binary @update_freq_cap_rule.json "https://sand.api.appnexus.com/ad-profile?id=199943"
{
  "response": {
    "status": "OK",
    "id": "199943"
  }
}
{code}

Check the ad profile to see the updated rule

$ curl -b cookies -c cookies -X GET "https://sand.api.appnexus.com/ad-profile?id=199943"
{
  "response": {
    "status": "OK",
    "ad-profile": {
      "id": 199943,
      "state": "active",
      "description": null,
      "member_id": 941,
      ...
      "frequency_caps": [
        {
          "id": 64,
          "max_session_imps": null,
          "max_day_imps": 20,
          "min_minutes_per_imp": 120,
          "member_id": 941,
          "technical_attributes": [
            {
              "id": 4,
              "name": "Video"
            }
          ],
          "categories": null
        }
      ]
      ...