Skip to end of metadata
Go to start of metadata

Advertiser Service

The Advertiser service lets networks add, modify, and view the advertisers that interact with AppNexus. Direct marketers rarely use the Advertiser service because they have only one advertiser (themselves).

On This Page

REST API

Add a new advertiser:
POST https://api.appnexus.com/advertiser
(advertiser JSON)

Modify an existing advertiser:
PUT https://api.appnexus.com/advertiser?id=ADVERTISER_ID
PUT https://api.appnexus.com/advertiser?code=ADVERTISER_CODE
(advertiser JSON)

View all of your advertisers:
GET https://api.appnexus.com/advertiser

View a specific advertiser:
GET https://api.appnexus.com/advertiser?id=ADVERTISER_ID
GET https://api.appnexus.com/advertiser?code=ADVERTISER_CODE

View multiple advertisers by ID using a comma-separated list:
GET https://api.appnexus.com/advertiser?id=1,2,3

Search for advertisers with IDs or names containing certain characters:
GET https://api.appnexus.com/advertiser?search=SEARCH_TERM

Delete an advertiser:
DELETE https://api.appnexus.com/advertiser?id=ADVERTISER_ID

Deleting an advertiser will also delete all of its child insertion orders, line items, campaigns, creatives, conversion pixels, and segments. The deletions are permanent and cannot be reverted. Although deleted objects continue to be available in reporting, you will no longer have visibility into their specific settings, such as revenue budget for line items, cost budget and targeting for campaigns.

Find out which fields you can filter and sort by:
GET https://api.appnexus.com/advertiser/meta

JSON Fields

Field

Type (Length)

Description

Default

Required On

id

int

Read-only. The ID of the Advertiser

Auto-incremented number

PUT, in query string

code

string (100)

A custom code for the advertiser. AppNexus will assign a unique ID, but advertisers may want to use their own ID system. Either "code" or the AppNexus ID will be allowed fields in other services.

 

 

name

string (255)

The name of the advertiser.

 

POST

state

enum

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

"active"

 

default_brand_id

int

The internal ID of the default brand for all creatives for this advertiser. The brand for each creative will be checked during the auditing process.

 

 

remarketing_segment_id

int

A segment is marked as "remarketing" for reporting and filtering purposes only. If you mark a segment as remarketing in the UI, it will show up here. Or you can add segment IDs here, and they will be marked as remarketing for reporting purposes.

 

 

lifetime_budget

double

You can set all of the budget parameters at the advertiser level as well as the campaign and media buy levels. Budgets at the advertiser level will apply to all traffic for your advertiser. This is a dollar (media cost) budget.

 

 

lifetime_budget_imps

int

The lifetime impression budget for the advertiser. (See lifetime_budget above.)

 

 

daily_budget

double

The daily budget for the advertiser. (See lifetime_budget above.)

 

 

daily_budget_imps

int

The daily impression budget for the advertiser. (See lifetime_budget above.)

 

 

competitive_brands

array

An array of brand IDs. Creatives associated with the brands in this array will not serve together in /mtj auctions. The classic example of competing brands is Coke vs. Pepsi. For more information about the brands in our system, see the Brand Service. For an overview of /mtj auctions, see MultiTags (customer login required).

 

n/a

competitive_categories

array

An array of category IDs. Creatives associated with the categories in this array will not serve together in /mtj auctions, e.g., "Dating" and "Education". For more information about the categories we apply to creatives (and brands), see the Category Service. For an overview of /mtj auctions, see MultiTags (customer login required).

 

n/a

enable_pacing

boolean

If true, then spending will be paced for this advertiser over the course of the day.

 

 

allow_safety_pacing

boolean

Admin-only. If true, spend per minute is limited to a maximum of 1% of the lifetime budget and 5% of the daily budget.

  
profile_id

int

You can set an optional profile_id at the advertiser, line item, campaign and creative levels. A profile is a generic set of rules for targeting inventory. A profile set at the advertiser level will apply to all traffic for your advertiser, so you will probably want to keep this profile very broad. Ad calls must pass all profile targeting at any level. See the Profile Service for details.

 

 

control_pct

double

The percentage of users in the control group for this advertiser. This must be expressed as a number between 0 and 1, inclusive. These users will be shown a control creative in order to gauge effectiveness of other creatives. For more information, see Test and Control Targeting (customer login required).

 

 

timezone

enum

The timezone of the advertiser. See API Timezones for details and accepted values. For details on how to make the advertiser timzone "trickle down" to child objects, see Timezone for Dependent Objects below.

"EST5EDT", or the member's timezone

 

last_modified

timestamp

Timestamp of the last time this advertiser was modified.

 

 

stats

object

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

 

 

billing_internal_user

array

For reference. This is a list of people (strings) who work at this advertiser.

 

 

billing_name

string (100)

For reference. Value may be a maximum of 50 characters.

 

 

billing_phone

string (100)

For reference.

 

 

billing_address1

string (100)

For reference.

 

 

billing_address2

string (100)

For reference.

 

 

billing_city

string (100)

For reference.

 

 

billing_state

string (100)

For reference.

 

 

billing_country

string (100)

For reference.

 

 

billing_zip

string (100)

For reference.

 

 

default_currency

string (3)

The default currency to be used for the advertiser. This will be a three-letter code that you can retrieve from the read-only Currency Service. Please see Currency Support for details about the concept (customer login required).

As a best practice, align currency to the billing currency in order to achieve the best possible local currency experience.

Member's default currency

 

default_category

object

The default category applied to all creatives associated with this publisher. Can be overwritten at the creative level. 

 

 

labels

array

The optional labels applied to the advertiser. Currently, three labels are available for advertisers: "Salesperson", "Account Manager", and "Advertiser Type". See Labels below for more details.

You can report on advertiser labels with the Network Analytics report. For example, if you use the "Salesperson" label to specify the name of the salesperson responsible for each advertisers, you could run the Network Analytics report filtered by "salesperson_for_advertiser" to focus on the advertisers that a particular salesperson is responsible for, or grouped by "salesperson_for_advertiser" to rank the performance of your salespeople.

 

 

use_insertion_orders

boolean

If true, then the use of insertion orders, which contain collections of line items, will be enabled for this advertiser. Please see the Insertion Order Service for details.

Preexisting line items

If you set this field to true and have already created line items prior to enabling this setting, those line items will stop spending. To allow those line items to continue spending, create an insertion order (using the Insertion Order Service) and associate the line items with the insertion order (using the Line Item Service). All newly created line items will require an insertion order.

false

 

time_format

enum

The format in which you would like to see times displayed in the Console UI. Possible values: "12-hour" or "24-hour".

"12-hour"

 

default_brand

object

Information about the default brand. See Default Brand below for more details.

null

 

is_mediated
booleanAdmin-only. If true, the advertiser will not be displayed in the Console UI. AppNexus administrators can set this field to true when the Advertiser is associated with a mediated bid.false 
is_malicious

boolean

Admin-only. If true, the advertiser's status will be set to inactive. AppNexus administrators will set this field to true for advertisers determined to be directing users to malicious landing pages. Users will not be able to set the advertiser's status back to active until an AppNexus administrator sets the is_malicious field back to false.

false

 

object_stats

object

Read-only. The number of total, active, and inactive insertion orders, line items, campaigns, and creatives under the advertiser, as well as the number of creatives with particular audit statuses. To include this object in a GET response, pass object_stats=true in the query string.

 

 

thirdparty_pixels
arrayRead-only. An array of third-party pixels associated with the advertiser. You can automatically attach these pixels to all creatives owned by this advertiser using the Third-party Pixel service or attach them individually at the creative level using the Creative Service.null 

Third-party Pixels

The thirdparty_pixels array contains the fields in the table below. These fields are read-only. To update or create third-party pixels and/or attach third-party pixels to all creatives owned by the advertiser, use the Third-party Pixel service. To attach third-party pixels to individual creatives, use the Creative Service.

Field
Type
Description
id
intRead-only. The pixel's ID.
name
stringRead-only. The full name of the pixel.
active
booleanRead-only. The current status of the pixel (true = active).
audit_status
stringRead-only. Audit status of the pixel.

Stats

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

Labels

You can use the read-only Label Service to view all possible labels for advertisers, insertion orders, line items, campaigns, and publishers. This service also allows you to view the labels that have already been applied to your objects.

Field

Type (Length)

Description

id

int

The ID of the label. Possible values: 1 (Salesperson), 3 (Account Manager), or 12 (Advertiser Type).

name

enum

Read-only. The name of the label. Possible values: "Salesperson", "Account Manager", or "Advertiser Type".

value

string (100)

The value assigned to the label. For example, for the "Salesperson" label, this could be a name such as "Michael Sellers".

Pagination

You can request a certain number of objects through these fields:

Field

Type

Description

count

int

How many objects are in this service. E.g. 8 advertisers.

start_element

int

The number at which to start counting.

num_elements

int

How many elements to return. For example start at object # 4 and return 3 objects, or # 4, 5, 6.

Default Brand

Field

Type

Description

id

int

The brand's ID.

name

string

The name of the brand.

category_id

int

The ID of the brand's category.

Timezone for Dependent Objects

When you change an advertiser's timezone, you can choose whether or not to make the change "trickle down" to child objects (campaigns, line items, and creatives). To do this, you pass set_child_timezone=true in the query string of the URL during your request to create or update the timezone.

For example:

  • If true, then timezone on all child objects is set to the Advertiser's timezone. Note that any timezone settings on lower level objects (e.g., Insertion orders, Line Items, Campaigns) will be overridden with the Advertiser's timezone.
  • If false, timezone is only set on the advertiser.

Examples

Adding an advertiser
Updating an advertiser
Viewing all advertisers
View a specific advertiser