Third-party Pixel service

  • Article

The third-party pixel service allows you to upload and modify third-party creative pixels, and attach them to advertisers, or creatives. You can also attach third-party creative pixels to your member.

REST API

HTTP Method Endpoint Description
GET https://api.appnexus.com/thirdparty-pixel View all of your third-party pixels.
GET https://api.appnexus.com/thirdparty-pixel?id=THIRDPARTY-PIXEL_ID View a specific third-party pixel.
POST https://api.appnexus.com/thirdparty-pixel Add a new third-party pixel.
PUT https://api.appnexus.com/thirdparty-pixel?id=THIRDPARTY-PIXEL_ID Modify an existing third-party pixel.
DELETE https://api.appnexus.com/thirdparty-pixel?id=THIRDPARTY-PIXEL_ID Delete an existing third-party pixel.

JSON fields

Field Type Description
active boolean Flag indicating whether the pixel is active.

Default: true
adservers array of objects The adservers that the pixel calls. Required for pixels that serve on Google Ad Manager inventory. A full list of adservers can be retrieved from the ad server service.

Example:
"adservers":[{"id":11},{"id":12}]
advertisers array of objects If the pixel has an owning advertiser (i.e., advertiser_id is not null), this array must contain the ID (and only the ID) of the advertiser that owns the pixel. As a result, this pixel will render on all creatives owned by that advertiser. If the pixel does not have an owning advertiser, this array can contain multiple advertisers to which the pixel will be applied.

Example:
"advertisers":[{"id":3}]

Optional
advertiser_id int ID of the advertiser that owns the third-party-pixel.

Default: null
audit_status string The audit status of the pixel. Possible values are:
- "pending"
- "rejected"
- "approved"
- "exempt"

Note:
An unaudited pixel will not prevent a creative from serving, but it will not serve along with the creative until it has passed audit.

Read Only
Default: "pending"
content string If the pixel's format is "raw-js", this is the JavaScript content to serve with the creative. The content and/or secure_content fields are required on POST for raw-js pixels.
You can also add macros to your pixel. For a list of the creative macros that you may append to your pixel, see Creative Macros in the UI documentation .

Required On: POST if the pixel's format is "raw-js".
creatives array of objects The creatives to which a pixel is applied. The creatives must belong to the owning member/advertiser. To attach a third-party pixel to a creative, use the Creative Service.

Example:
"creatives":[{"id":860851}]

Read Only
format string The format of the pixel. Possible values for creatives:
- "raw-js"
- "url-html"
- "url-js"
- "url-image"
- "raw-url"

Required On: POST and PUT if changing content, secure_content, url, or url_secure fields.

Default: "raw-js"
id int The ID of the third-party pixel.

Required On: PUT and DELETE.
members array of objects Optional. If specified, this field will contain the ID of the member that owns the pixel and this pixel will render on all creatives owned by that member.

Example:
"members":[{"id":1}]
member_id int ID of the member/network that owns this pixel.

Required On: POST
name string The name of the third-party pixel.
secure_content string If the pixel's format is "raw-js", the JavaScript content to serve with the creative. The content and/or secure_content fields are required on POST for raw-js pixels.

You can also add macros to your pixel. For a list of the creative macros that you may append to your pixel; see Creative Macros in the UI documentation.

Required On: POST if the pixel's format is "raw-js".
secure_url string If the pixel's format is "url-html", "url-js", "url-image", or "raw-url", the URL of the HTML, JavaScript, or Image pixel to serve with the creative on a secure (https) call. The url and/or secure_url fields are required on POST for these pixel types. You can also add macros to your pixel.

You can also add macros to your pixel. For a list of the creative macros that you may append to your pixel, see Creative Macros in the UI documentation.

Required On: POST if the pixel's format is "url-html", "url-js", "url-image", or "raw-url".
supply_exceptions array of objects The names of members on which the pixel should not serve. "AdX" is currently the only acceptable value.

Example:
"supply_exceptions":[{"name":"AdX"}]
url string If the pixel's format is "url-html", "url-js", "url-image", or "raw-url", the URL of the HTML, JavaScript, or Image pixel to serve with the creative. The url and/or secure_url fields are required on POST for these pixel types.

You can also add macros to your pixel. For a list of the creative macros that you may append to your pixel, see Creative Macros in the UI documentation.

Examples

View a specific third-party pixel

In this example, we view a third-party pixel with ID 123.

$ curl -b cookies -X GET 'https://api.appnexus.com/thirdparty-pixel?id=123'
 
{
    "thirdparty-pixel":{
        "id":123,
        "active":true,
        "member_id":456,
        "advertiser_id": 789,
        "format":"raw-js",
        "content":"var img = new Image(); img.src="https://url.com/event/js?self=" + data;"
        "url":null,
        "secure_url":null,
        "members":null,
        "advertisers":[{"id":789}], 
        "creatives":null
        "audit_status":"unaudited" // admin only
        "supply_exceptions":[
            {"name":"AdX"},
        ]
        "adservers":[
            {"id":123}
        ]
  }
}

Add a new third-party pixel

In this example, we create a new sell-side third-party pixel with ID 123. Note that parent object information is "null" because the JSON file we passed into the API did not specify a parent object for the pixel.

$ cat thirdparty-pixel.json
{
  "thirdparty-pixel":
    {
      "format":"url-html",
      "secure_url":"https://secureurl.com"
    }
}  

$ curl -b cookies -c cookies -X POST -d @thirdparty_pixel 'https://api.appnexus.com/thirdparty-pixel'

{
    "response":{
        "status":"OK",
        "count":1,
        "id":123,
        "start_element":0,
        "num_elements":100,
        "thirdparty-pixel":{
            "id":123,
            "active":true,
            "name":null,
            "member_id":456,
            "advertiser_id":789,
            "publisher_id":null,
            "format":"url-html",
            "audit_status":"pending",
            "created_on":"2014-11-05 19:51:44",
            "last_modified":"2014-11-05 19:51:44",
            "url":null,
            "secure_url":"https://secureurl.com",
            "members":null,
            "advertisers":null,
            "publishers":null,
            "creatives":null,
            "supply_exceptions":null,
            "adservers":null
       
    }
}

Update a third-party pixel

In this example, we update a third-party pixel with the ID 123, applying it to all of the owning advertiser's creatives.

$ cat pixelupdate.json

{
  "thirdparty-pixel":
    {
      "advertisers":[{"id":789}]
    }
}  

$ curl -b cookies -c cookies -X PUT -d @pixelupdate 'https://api.appnexus.com/thirdparty-pixel?id=123'

{
   "response":{
      "status":"OK",
      "id":123
   }
}

Delete a third-party pixel

In this example, we delete a third-party pixel with the ID 123.

$ curl -b cookies -X DELETE 'https://api.appnexus.com/thirdparty-pixel?id=123'

{
   "response":{
      "status":"OK"
   }
}