Ad Creative Scheduling API v4

Introduction

With the Ad Creative Scheduling API v4 you can:

  • Set scheduling information for Creatives attached to Placements' Ads
  • Get scheduling methods for Creatives attached to Placements' Ads

Resources

URIs

The Ad Creative Scheduling API v4 identifies two Uniform Resource Identifiers (URIs):

Environment

URI

Staging

https://api.stg.freewheel.tv/services/v4/ads/{ad_id}/scheduling

Production

https://api.freewheel.tv/services/v4/ads/{ad_id}/scheduling

Attributes

Name

Type

Description

Validations

Included in GET?

ad_id

FW_ID

Current network assigned Ad Unit Node ID

No

scheduling

See Scheduling Parameters below

Root node of ad scheduling settings

Required

Yes

Scheduling Parameters

All of the following parameters are included in GET requests.

Name

Type

Description

Validations when updated

schedulable

Boolean

Indicates whether the ad is schedulable or not

Not updatable

scheduling_method

The following options are supported:

  • EQUAL_WEIGHTING
  • PERCENTAGE_WEIGHTING
  • AB_TESTING
  • SEQUENCE
  • FLIGHTING
  • FLIGHTING_AND_WEIGHTING
  • AUDIENCE_TARGETING
  • ADVANCED_FLIGHTING_AND_WEIGHTING

The scheduling method

One selection is required.

Not all Scheduling Methods may be available based on your network functions and the number of schedulable creative instances the ad has.

scheduling_items

See Scheduling_Item Parameters below.

Details of scheduling setting

Required when scheduling_method is:

  • **EQUAL_WEIGHTING**
  • **PERCENTAGE_WEIGHTING**
  • **AB_TESTING**
  • **SEQUENCE**
  • **FLIGHTING**
  • **FLIGHTING_AND_WEIGHTING**

scheduling_sets

See Scheduling_Set Parameters below.

Details of scheduling setting

Required when scheduling method is AUDIENCE_TARGETING or ADVANCED_FLIGHTING_AND_WEIGHTING

When schedulingmethod is **AUDIENCE TARGETING, the order of the scheduling_set** items defines the priority of each audience match if a request matches more than one audience item. The last scheduling_set in the array list should represent the default behavior that occurs when no audience match is made.

scheduling_item Parameters

All of the following parameters are included in GET requests.

Name

Type

Description

Validations when update

creative_id

Integer

FreeWheel Creative ID

Required

weighting_factor

Integer

Percentage of weighting

Required when scheduling_method is:

  • **PERCENTAGE_WEIGHTING**
  • **AB_TESTING**
  • **FLIGHTING_AND_WEIGHTING**

sequence

Integer

Rotation Sequence

Required when scheduling_method is SEQUENCE

Yes

flighting_start

Date-Time (YYYY-MM-DD HH:MM:SS UTC)

The start date of the item in UTC.

Required when scheduling_method is:

  • **FLIGHTING**
  • **FLIGHTING_AND_WEIGHTING**

flighting_end

Date-Time (YYYY-MM-DD HH:MM:SS UTC).

The end date of the item in UTC.

Required when scheduling_method is:

  • **FLIGHTING**
  • **FLIGHTING_AND_WEIGHTING**

scheduling_set Parameters

When schedulingmethod is AUDIENCE TARGETING, the order of the scheduling_set items defines the priority of each audience match if a request matches more than one audience item. The last scheduling_set in the array list should represent the default behavior that occurs when no audience match is made.

The following parameters are included in GET requests.

Name

Type

Description

Validations when update

audience_item_id

Integer

FW Audience Item ID

Required for custom scheduling_set

Should not be duplicated for each custom scheduling_set

scheduling_set_items

List of scheduling_set_item

Details of scheduling_set_item

At least one item is required.

flighting_start

Date-Time (YYYY-MM-DD HH:MM:SS UTC)

The start date of the flighting period for the scheduling set, in UTC.

Required and available only when scheduling_method is ADVANCED_FLIGHTING_AND_WEIGHTING.

flighting_end

Date-Time (YYYY-MM-DD HH:MM:SS UTC)

The end date of the flighting period for the scheduling set, in UTC.

Required and available only when scheduling_method is ADVANCED_FLIGHTING_AND_WEIGHTING.

scheduling_set_item Parameters

The following parameters are included in GET requests.

Name

Type

Description

Validations when update

creative_id

Integer

FW Creative ID

Required

flighting_start

Date-Time (YYYY-MM-DD HH:MM:SS UTC)

The start date of the item in UTC.

Optional, , available only when scheduling_method is AUDIENCE_TARGETING.

flighting_end

Date-Time (YYYY-MM-DD HH:MM:SS UTC)

The end date of the item in UTC.

Optional, available only when scheduling_method is AUDIENCE_TARGETING.

weighting_factor

Integer

Percentage of weighting

Optional, available only when scheduling_method is ADVANCED_FLIGHTING_AND_WEIGHTING.