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/NodeDescriptionData Type(s)Creatable?Updateable?Included in basic GET?Comments
idResource IDFW_IDNoNoYesAssigned automatically during POST
nameThe name of the advertiserstringRequiredYesYes
external_idExternal ID for the advertiserstringYesYesYes
billing_termBILLING Term for the advertiser in the MRM systemstringYesYesYes
contactsContacts for the advertisercontacts attributesYesYesNo
assignmentsUser Assignments of the advertiserassignment attributesYesYesNo
addressAddress of the advertiseraddress attributesYesYesNo
statusStatus for the advertiser
  • APPROVED
  • INACTIVE
NoNoYesThese values must be provided in ALL CAPITAL letters.

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/NodeDescriptionData Type(s)Creatable?Updateable?
contact_idFreeWheel IDNoNo
contact_type

  • PRIMARY

  • BILLING

  • ADDITIONAL (Default setting)

YesYes
first_namestringYesYes
last_namestringYesYes
titlestringYesYes
address_1stringYesYes
address_2stringYesYes
citystringYesYes
state_idState from Geography DataintegerYesYes
postal_codestringYesYes
country_idCountry ID from Geography DataintegerYesYes
email_address_1stringYesYes
email_address_2stringYesYes
email_address_3stringYesYes
work_phonestringYesYes
home_phonestringYesYes
fax_phonestringYesYes
other_phonestringYesYes
im_typestringYesYes
im_idstringYesYes
urlstringYesYes

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/NodeDescriptionData Type(s)Creatable?Updateable?
user_idValid user IDintegerYesYes
user_full_nameUser full namestringNoNo

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/NodeDescriptionData Type(s)Creatable?Updateable?
address_1stringYesYes
address_2stringYesYes
citystringYesYes
postal_codeLocal postal codeIntegerYesYes
state_idState ID from Geography DatastringYesYes
country_idCountry ID from Geography DataIntegerYesYes

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/NodeDescriptionData Type(s)Creatable?Updateable?Comments
inherited_typeThe inherited Terms and Conditions type of this advertiser

  • INHERITED

  • CUSTOM

YesYes
inherit_term_conditionThe ID of the advertiser term conditionInherit Term Condition attributesYesYesValid and Required when inherited_type='INHERITED'
term_condition_infoCustom term condition informationTerm Condition Info attributesYesYesValid and Required when inherited_type='CUSTOM'
descriptionDescription of the Terms and ConditionsstringYesYesLimited to 1024 characters
viewable_notesViewable notes of the terms and conditionsstringYesYesLimited to 1024 characters
additional_footersAdditional footers of the terms and conditionsstringYesYesLimited 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/NodeDescriptionData Type(s)Creatable?Updateable?
|idInherited terms and conditions IDFW_IDRequiredRequired
nameInherited terms and conditions nameStringNoNo
typeInherited terms and conditions type'ADVERTISER', 'AGENCY', 'DEFAULT'NoNo
statusInherited terms and conditions statusACTIVE'NoNo

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/NodeDescriptionData Type(s)Creatable?Updateable?Comments
recurrence_typeInvoice generation periodicity
  • DAILY
  • WEEKLY
  • MONTHLY
  • BROADCAST_CALENDAR
  • AT_END
YesYes
recurrence_paramsThe settings for invoice generation periodicityRecurrence Params AttributesYesYesValid and required when recurrence_type IN ('DAILY', 'WEEKLY', 'MONTHLY')
billing_scenario_idThe ID of the billing scenarioFW_IDYesYes
payment_termsThe payment terms (in days)IntegerYesYes
controlling_measureBill of Whose #s
  • INTERNAL
  • THIRD_PARTY
YesYes

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/NodeDescriptionData Type(s)Creatable?Updateable?Comments
everyIndicates the recurrence cycle
  • DAY
  • WEEKDAY
  • WEEK
  • MONTH
  • <
RequiredRequiredEvery = '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'
intervalIndicates the recurrence interval of the cycleIntegerRequiredRequiredValid and required when every IN('DAY', 'WEEK', 'MONTH')
onIndicates 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.RequiredRequiredValid and required when every IN('WEEK', 'MONTH')
weekdayIndicates the weekday'MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY'RequiredRequiredValid and required with 'every' = 'MONTH' and 'on' IN ('FIRST', 'SECOND', 'THIRD', 'FOURTH', 'LAST')