Advertiser API V3

Introduction

An advertiser is the entity for which an advertisement speaks and which originates the payment for an advertisement.

The Advertiser API manages advertisers in your network. Version 3 of the Advertiser API enables you to execute the following operations on advertisers and their related attributes:

  • Obtain a high-level view of active campaigns, divided by advertiser
  • View a list of information about a specific advertiser, such as its contact information or financial information
  • Return a list of advertisers when you are de-duplicating, consolidating, or reconciling an advertiser list
  • Create an advertiser
  • Edit an advertiser
  • Set Parent Agency and Brand relationships
  • Add new campaigns to an advertiser

Related Documentation

Refer to the following documentation for more information about FreeWheel products and APIs:

Before You Begin

Set up your agency/advertiser relationships before you create a campaign.

How to Create a New Advertiser

You can find instructions for creating and approving a new advertiser here.

In MRM, an advertiser has two required fields:

  1. Name
  2. Industry Assignment

You can also include other metadata such as contact details.

Resources

URI(s)

The Agency API v3 identifies two Uniform Resource Identifiers (URIs) as identified in the following table:

Type of URIURI
Productionhttps://api.freewheel.tv/services/v3/advertiser.xml?[parameter1]=[query1]&...
Staginghttps://api.stg.freewheel.tv/services/v3/advertiser.xml?[parameter1]=[query1]&...

Advertiser Attributes

Basic Attributes

This attribute set identifies and defines an advertiser. Basic attributes describe fundamental properties of an advertiser.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

Included in basic GET?

Comments

id

Resource ID

FW_ID

No

No

Yes

Assigned automatically during POST

name

The name of the advertiser

string

Required

Yes

Yes

external_id

External ID for the advertiser

string

Yes

Yes

Yes

billing_term

BILLING Term for the advertiser in the MRM system

string

Yes

Yes

Yes

metadata

Metadata for the advertiser in MRM

string

Yes

Yes

No

contacts

Contacts for the advertiser

contacts attributes

Yes

Yes

No

assignments

User Assignments of the advertiser

assignment attributes

Yes

Yes

No

address

Address of the advertiser

address attributes

Yes

Yes

No

status

Status for the advertiser

  • **APPROVED**
  • **INACTIVE**

No

No

Yes

These values must be provided in ALL CAPITAL letters.

Metadata Attributes

Metadata attributes include additional advertiser data fields that are unique to your business. You can use custom fields to categorize, label, and organize advertisers, agencies, campaigns, insertion orders, and placements. No default values exist because each item is specific to each business.

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

Comments

field_id

The ID of metadata label in FreeWheel database

Integer

Yes

Yes

IDs are not shown on UI. Contact FreeWheel to get the field ID mapping list.

value

The value of the metadata field

String

Yes

Yes

The default value will be set if no value is given and a default value exists for current field.

primary

If "true": Current metadata is the primary metadata for the current field; If "false": Current metadata is NOT the primary metadata for the current field.

TRUE, FALSE

Yes

Yes

If a metadata field is set to multi-occurence, then one instance must be primary and only one field can be set as primary. Only one metadata field can be set for single-occurrence field and it will always be primary metadata.

Contacts Attributes

This attribute set identifies contacts for an advertiser. Contacts attributes identify various contacts for the advertiser, including ID, type of contact, name, title, address, email address, phone, and website. Use code similar to the Contacts POST example when you want to add a contact to the advertiser. You can add multiple contacts to each advertiser, as necessary.

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

contact_id

FreeWheel ID

No

No

contact_type

  • **PRIMARY**
  • **BILLING**
  • **ADDITIONAL** (Default setting)

Yes

Yes

first_name

string

Yes

Yes

last_name

string

Yes

Yes

title

string

Yes

Yes

address_1

string

Yes

Yes

address_2

string

Yes

Yes

city

string

Yes

Yes

state_id

State from Geography Data

integer

Yes

Yes

postal_code

string

Yes

Yes

country_id

Country ID from Geography Data

integer

Yes

Yes

email_address_1

string

Yes

Yes

email_address_2

string

Yes

Yes

email_address_3

string

Yes

Yes

work_phone

string

Yes

Yes

home_phone

string

Yes

Yes

fax_phone

string

Yes

Yes

other_phone

string

Yes

Yes

im_type

string

Yes

Yes

im_id

string

Yes

Yes

url

string

Yes

Yes

Assignment Attributes

This attribute set identifies an assignment and user role/group for the advertiser. Assignment attributes define the assigned users for this advertiser in combination with the Assigned User attributes set below.

Assigned User Attributes - Child Attributes of Assignment Attributes

This attribute set assigns a user for this advertiser. Assigned User attributes define a user ID, name, and relates to the primary user role for an advertiser.

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

user_id

Valid user ID

integer

Yes

Yes

user_full_name

User full name

string

No

No

Address Attributes

This attribute set identifies an address for the advertiser. Address attributes define the Advertiser's address. This attribute set is unrelated to the contacts' address fields.

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

address_1

string

Yes

Yes

address_2

string

Yes

Yes

city

string

Yes

Yes

postal_code

Local postal code

Integer

Yes

Yes

state_id

State ID from Geography Data

string

Yes

Yes

country_id

Country ID from Geography Data

Integer

Yes

Yes

Financial Attributes

This attribute set identifies financial conditions for the advertiser. Financial attributes describes the terms and conditions for this advertiser in combination with the following related attribute sets:

  • Inherit Term Condition
  • Term Condition Info
  • Recurrence Params

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

Comments

inherited_type

The inherited Terms and Conditions type of this advertiser

  • **INHERITED**
  • **CUSTOM**

Yes

Yes

inherit_term_condition

The ID of the advertiser term condition

Inherit Term Condition attributes

Yes

Yes

Valid and Required when inherited_type='INHERITED'

term_condition_info

Custom term condition information

Term Condition Info attributes

Yes

Yes

Valid and Required when inherited_type='CUSTOM'

description

Description of the Terms and Conditions

string

Yes

Yes

Limited to 1024 characters

viewable_notes

Viewable notes of the terms and conditions

string

Yes

Yes

Limited to 1024 characters

additional_footers

Additional footers of the terms and conditions

string

Yes

Yes

Limited to 1024 characters

Inherit Term Condition Attributes - Child Attributes of Financial Attributes

This attribute set identifies the terms and conditions inherited for the advertiser. Inherit Term Condition attributes describe inherited term conditions for the related financial attribute set, which includes an ID, name, type, and status.

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

|id

Inherited terms and conditions ID

FW_ID

Required

Required

name

Inherited terms and conditions name

String

No

No

type

Inherited terms and conditions type

'ADVERTISER', 'AGENCY', 'DEFAULT'

No

No

status

Inherited terms and conditions status

ACTIVE'

No

No

Term Condition Info Attributes - Child Attributes of Financial Attributes

This attribute set identifies new terms and conditions for the advertiser. Term Condition Info attributes describe term condition information for the related financial attribute set, which includes a type, parameters for the period of invoice generation, a billing scenario ID, and payment terms.

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

Comments

recurrence_type

Invoice generation periodicity

  • **DAILY**
  • **WEEKLY**
  • **MONTHLY**
  • **BROADCAST_CALENDAR**
  • **AT_END**

Yes

Yes

recurrence_params

The settings for invoice generation periodicity

Recurrence Params Attributes

Yes

Yes

Valid and required when recurrence_type IN ('DAILY', 'WEEKLY', 'MONTHLY')

billing_scenario_id

The ID of the billing scenario

FW_ID

Yes

Yes

payment_terms

The payment terms (in days)

Integer

Yes

Yes

controlling_measure

Bill of Whose #s

  • **INTERNAL**
  • **THIRD_PARTY**

Yes

Yes

Recurrence Params Attributes - Child Attributes of Term Condition Info Attributes

This attribute set identifies recurrence definitions for financial reporting data for the advertiser. Recurrence Params attributes define recurrence parameters for the recurrence of financial reporting data for the related financial attribute set.

All of the parameters below are included in the basic GET.

Function/Node

Description

Data Type(s)

Creatable?

Updateable?

Comments

every

Indicates the recurrence cycle

  • **DAY**
  • **WEEKDAY**
  • **WEEK**
  • **MONTH**
  • <

Required

Required

Every = 'DAY' and 'WEEKLY' is only valid when recurrence_type = 'DAILY'; every = 'WEEK' is only valid when recurrence_type = 'WEEKLY"; every = 'MONTH' is only valid when recurrence_type = 'MONTHLY'

interval

Indicates the recurrence interval of the cycle

Integer

Required

Required

Valid and required when every IN('DAY', 'WEEK', 'MONTH')

on

Indicates the particular day within the cycle

['MONDAY, ..., 'SUNDAY'] when 'every' = 'WEEK'; Integer when 'every' = 'MONTH' and 'weekday' is not present; ['FIRST', 'SECOND', 'THIRD'. 'FOURTH', 'LAST'] when 'every' = 'MONTH' and 'weekday' is present.

Required

Required

Valid and required when every IN('WEEK', 'MONTH')

weekday

Indicates the weekday

'MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY'

Required

Required

Valid and required with 'every' = 'MONTH' and 'on' IN ('FIRST', 'SECOND', 'THIRD', 'FOURTH', 'LAST')