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:
- Name
- 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 URI | URI |
|---|---|
| Production | https://api.freewheel.tv/services/v3/advertiser.xml?[parameter1]=[query1]&... |
| Staging | https://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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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') |