diff --git a/OpenDirect.v2.0.final.md b/OpenDirect.v2.1.final.md similarity index 50% rename from OpenDirect.v2.0.final.md rename to OpenDirect.v2.1.final.md index e78214a..073bcc5 100644 --- a/OpenDirect.v2.0.final.md +++ b/OpenDirect.v2.1.final.md @@ -1,10 +1,6 @@ -![IAB Tech Lab](https://drive.google.com/uc?id=10yoBoG5uRETSXRrnJPUDuONujvADrSG1) + ![IAB Tech Lab](https://drive.google.com/uc?id=10yoBoG5uRETSXRrnJPUDuONujvADrSG1) -# **OpenDirect Specification v2.0** - -#### FINAL v2.0 - -**February 2019** +# **OpenDirect Specification v2.1** **About the IAB Technology Lab** @@ -15,7 +11,7 @@ Learn more about IAB Tech Lab here: [www.iabtechlab.com](https://www.iabtechlab. **License** -OpenDirect Specification the IAB Tech Lab is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit [creativecommons.org/licenses/by/3.0/](http://creativecommons.org/licenses/by/3.0/) or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA. +OpenDirect Specification the IAB Tech Lab is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit [creativecommons.org/licenses/by/3.0/](http://creativecommons.org/licenses/by/3.0/) or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA. ![](https://drive.google.com/uc?id=1GsSz9KPUksmllzcn4v4v0rFxizNNXt-S) @@ -30,9 +26,10 @@ OpenDirect Specification the IAB Tech Lab is licensed under a Creative Commons A - [How it works](#how_it_works) - [Authorization](#authorization) - [SPECIFICATION](#specification) - - [Object: Ad](#object_ad) + - [Object: Account](#object_account) - [Object: AdUnit](#object_adunit) - [Object: Address](#object_address) + - [Object: AdvertiserBrand](#object_advertiserbrand) - [Object: Assignment](#object_assignment) - [Object: ChangeRequest](#object_changerequest) - [Object: Contact](#object_contact) @@ -43,7 +40,15 @@ OpenDirect Specification the IAB Tech Lab is licensed under a Creative Commons A - [Object: Organization](#object_organization) - [Object: Placement](#object_placement) - [Object: Product](#object_product) + - [Object: ProductsAvailsSearch](#object_productavailssearch) + - [Object: ProductSearch](#object_productsearch) + - [Object: Avails](#object_avails) + - [Object: AvailsStatus](#object_availsstatus) + - [Object: ProductTargeting](#object_producttargeting) + - [Object: ProviderData](#object_providerdata) - [Object: Stats](#object_stats) + - [Object: EID](#object_eid) + - [Object: UID](#object_uid) - [Collection Objects](#collection_objects) - [General Support Requirements](#general_support_requirements) - [Authentication](#authentication) @@ -55,6 +60,8 @@ OpenDirect Specification the IAB Tech Lab is licensed under a Creative Commons A - [Custom Headers](#custom_headers) - [INTERFACES](#interfaces) - [URI Summary Table](#uri_summary_table) + - [URI Filter Guidance](#uri_filter_guidance) + - [Path: AdvertiserBrands](#path_advertiserbrands) - [Path: Accounts](#path_accounts) - [Path: Accounts Assignments](#path_accounts_assignments) - [Path: Accounts Creatives](#path_accounts_creatives) @@ -77,6 +84,7 @@ OpenDirect Specification the IAB Tech Lab is licensed under a Creative Commons A - [Uploading a Creative and Assigning It to a Placement](#uploading_a_creative_and_assigning_i_to_a_placement) - [Reserving, Booking, and Canceling a Line](#beserving_booking_and_canceling_a_line) - [Diagrams](#diagrams) + - [ProductTargeting for Physical Media](#producttargetingdetails) # OVERVIEW @@ -116,7 +124,7 @@ design and build their interfaces for offering automated guaranteed inventory. As OpenDirect becomes more adopted in the marketplace, the movement of premium inventory becomes more fluid. -## What’s New in Version 2.0 +## What’s New in Version 2.1 OpenDirect 1.0 was released in January 2015. While a handful of companies have already started adopting the API, more features are needed to encourage wider adoption. @@ -126,6 +134,15 @@ added more context, clarification, bug fixes, and feature updates Version 2.0 Adopts the OpenMedia/AdCOM object definitions for consistency between protocols in addition to a basic messaging protocol for communication between buyers and sellers. +Version 2.1 +Formally embraces product targeting for ‘real world media’ with support for: +* Deal targeting as frames that see audience, or audience that see frames +* Investment as fixed, frame or CPT pricing +* Pacing a campaign over a period of time, location, budget and audience distribution. +* Temporal delivery standards such as spot/break length, share of time +* Identification and transparency for third party inventory, audience, location and venue standards to support global media trading. +* Upsite/playout/posting/display statistics made available at account, order and orderline level. + ## OpenMedia Mission @@ -141,7 +158,7 @@ To assist in reuse of objects across different specifications and to enable spec Given this layered concept, the IAB Tech Lab has defined an overall organization of related specifications as "OpenMedia". The landscape of these specifications and how they may be organized into protocol layers is illustrated as follows. -![](https://drive.google.com/uc?id=1oJ7_sDwDzVKbu3vXXIifjc-Ki7LiOkvI) +![](images/image_3.2.png) There are a number of objects that are common to multiple transaction specifications. For example, both OpenRTB and OpenDirect share a common concept of a “site”, a “placement”, an “ad”, and other so-called domain objects. These objects describe the subject of a transaction; those concepts upon which the transaction operates. Factoring them into their own model enables multiple transaction protocol specifications to reuse these common objects rather than each of them redefining similar but needlessly different versions of core concepts. @@ -184,13 +201,14 @@ OpenDirect users include: * **Organization:** All organizations that work with the publisher must obtain an Organization ID, whether they are a buyer, or a brand advertiser. * **Buyer:** The buyer is the organization that places orders and usually represents an agency acting on behalf of the advertiser, or the advertiser that places orders directly. If the buyer represents advertisers, the buyer must obtain formal consent for acting on behalf of the advertiser and provide proof of that consent to the publisher. * **Advertisers:** Advertisers represent the brands that purchase publisher inventory for advertising their brands. An advertiser may also be a buyer, but if the advertiser works with a buyer, the advertiser must provide formal consent to allow the buyer to act on its behalf. The Advertiser ID can be used to set up advertiser accounts in an agency or publisher’s OpenDirect system. +* **Intermediary:** An intermidiary is a non-advertiser organization upon who's behalf an order is being placed (e.g. a group media agency). # SPECIFICATION ![Entity Relationship Diagram](images/ODv2EntityRelationshipDiagram.png) -## Object: Account +## Object: Account An account defines a buyer-advertiser relationship. A buyer is typically an agency that places orders on behalf of several advertisers. Each account associates a buyer with one advertiser and is used to manage orders for one publisher. An advertiser may also work with several buyers, and therefore, advertisers have a separate account for each buyer they work with. If an advertiser represents itself, the account identifies the advertiser as both the buyer and the advertiser. @@ -204,23 +222,27 @@ The Account owns the orders and creative. |**id*** | A system-generated opaque ID that uniquely identifies this resource.| string _(36)_ | |**advertiserid***|An Id that identifies the organization that is acting as the advertiser.

Advertiser ID may be generated by the buyer (agency) or by the publisher if the advertiser is also the buyer.

An advertiser that is representing itself must have an AdvertiserId and BuyerId that match.|string _(36)_ | |**buyerid*** |An Id that identifies the organization that is acting as the buyer. The Publisher generates the BuyerId. If the advertiser is performing their own buys, AdvertiserId and BuyerId must be the same.|string _(36)_ | +|**intermediaryid** |An ID that identifies the organization upon who's behalf an Order is being placed (e.g. a group media agency).|string _(36)_ | |**name***|The name of the account. Used for display purposes. |string _(255)_ | +|**status** | A value that indicates the current state of the Account. The following are the possible values.
• Pending – The account is yet to be approved; however, the buyer may create a draft order and have the ability to reserve this order at the publishers discretion.
• Approved – The account is approved and can be used for trading.
• Disapproved – The account’s identity could not be verified. The account may not create and book orders.
| enum (Pending, Approved, Disapproved)| |**ext**|Optional vendor-specific extensions. |ext object| + _* required_ ## Object: AdUnit -Ad Unit contains exactly one AdCOM Ad Specification +Ad Unit contains exactly one AdCOM Placement |Attribute|Description|Type| |---|---|---| -|**id***|An Id to uniquely identify this Ad Unit within the product|string _(36)_| +|**gpid**|Distinct, persistent id for each ad unit within the product|[**Global Placement** string](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/gpid.md#global-placement-idgpid)| |**name** |A name to identify this Ad Unit |string _(255)_ | |**spec*** |The technical specifications of this Ad Unit|[AdCOM **Placement** object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_placement) -| + _* required_ + ## Object: Address The address object is used to provide values for the [ORGANIZATION](#object:_organization) resource. @@ -234,9 +256,23 @@ The address object is used to provide values for the [ORGANIZATION](#object:_org |**addressline2** |The optional second line of the address. |string _(255)_ | |**postalcode**|The postal or ZIP code for the address. |string _(15)_ | |**state** |The state or province for the address. |string _(36)_ | + _* required_ +## Object: AdvertiserBrand + +Defines the details of a Brand associated with an organization + +| Attribute | Description | Type | +| -------------------- | --------------------------------------------------------------- | ------------ | +| **id*** | A system-generated opaque ID that uniquely identifies the brand | String (36) | +| **name*** | The brand's display name | String (255) | +| **organizationid*** | The ID of the organization that owns the brand | String (36) | +| **eids** | array of extended ids (EID) that detail third party datasources and ids that may be referenced to identify the AdvertiderBrand to the buyer | Array | + +_* required_ + ## Object: Assignment Defines an Assignment resource. An Assignment associates a creative with a line of the order. A creative may be assigned to one or more lines and a line may be assigned one or more creative. @@ -246,14 +282,17 @@ Notes: The assignment must fail if the following are true. |Attribute|Description|Type| |---|---|--- -|**id** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ | +|**id*** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ | |**creativeid***|The ID of the creative to display when the line runs.|string _(36)_ | |**placementid***|The ID of the placement that will display the creative.|string _(36)_ | |**status**|A value that determines whether the creative serves.

The status may not transition from Inactive to Active.|enum (Active, Inactive) -|**weight** |Determines how much the creative is displayed relative to the other creative assigned to the same line.

To provide even rotation, do not specify a weight.

If weight is specified, all assignments that specify the same line must specify a weight and the weight of all the assignments must add up to 100. If the weight of all assignments does not add up to 100, even rotation is applied.

Assignments with heavier weight get proportionally more rotation compared to those with lesser weight.

For example, if the line has 2 creative, A and B, assigned with the same dates, and A has weight 25 and B has weight 75, B will serve three times as often as A.| integer (1-100) +|**sov** |Determines how much the creative is displayed relative to the other creative assigned to the same line.

To provide even rotation, do not specify a share of voice.

If share of voice is specified, all assignments that specify the same line must specify a share of voice and the share of voice of all the assignments must add up to 100. If the share of voice of all assignments does not add up to 100, even rotation is applied.

Assignments with heavier share of voice get proportionally more rotation compared to those with lesser share of voice.

For example, if the line has 2 creative, A and B, assigned with the same dates, and A has share of voice 25 and B has share of voice 75, B will serve three times as often as A.| integer (1-100) +|**producttargeting**|The producttargeting object is used to discover and target the real-life dimensional and temporal aspect of physical media. Full details on the use of the ProductTargeting object can be found in the section [ProductTargeting for Physical Media](#producttargetingdetails) |producttargeting array| |**ext**|Optional vendor-specific extensions. |ext object| + _* required_ + ## Object: ChangeRequest When an order has already been placed and a change is needed, the ChangeRequest resource can be used to request a change and subsequently modify the order pending the approval of the change request. @@ -261,15 +300,18 @@ The OrderSearch object can be used to search for orders that have an order statu |Attribute|Description|Type| |---|---|---| -|**id**|A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ | +|**id***|A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ | |**accountid***|The ID of the account that identifies the advertiser and buyer that own the Change. This must be the same as the AccountId for the Order.|string _(36)_ | |**comments**|Optional comments as to why the Change is being requested/proposed. |string _(1000)_ | |**contacts**|The list of contacts to use for this change. This list of contacts is in addition to the buyer’s and advertiser’s list of contacts.

The list must contain unique contact types (for example, only one billing contact).|[CONTACT](#object_contact) array |**orderid***|The ID of the Order that the Change is Requested for.| string _(36)_ | +|**lineid**|The ID of the Line in the Order that the Change is Requested for (if the Change Request is needed at line level)| string _(36)_ | |**requesterid***|The OrganisationID of the Change Requester usually the AgencyID if the change was requested by an Agency or the PublisherID if the change was requested by the Vendor. | string _(36)_ | +|**providerdata**|The ProviderData object is used for buyers to detail structured information that may be used to identify their order in a seller's system using their own IDs or references. |object| |**status**|Specifies the Status of the Change Request. |enum (PENDING, APPROVED, REJECTED) |**webhook**|URI which is called when the change is approved, rejected or modified by the Seller.

URI is called with a PUT request containing the Change Request ID. | string _(36)_ | |**ext**|Optional vendor-specific extensions. |ext object| + _* required_ @@ -287,6 +329,7 @@ Defines an agency or advertiser contact. |**phone** |The contact’s phone number |string _(20)_| |**title** |The contact’s job title. |string _(30)_| |**type** |Defines the possible types of Contacts.|enum (Billing, Buyer, Creative, Sales)| + _* required_ ## Object: Creative @@ -299,8 +342,9 @@ See Assignment for instructions on updating a creative. | **accountid*** | The ID of the account that owns the creative. |string _(36)_| | **name** | Name used to identify this Creative |string _(255)_| | **ad** | The metadata and content of this creative Ad|[AdCOM **Ad** object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_ad)| -| **creativeapprovals** | Any array of pairs describing the approval status for each publisher in the form PublisherId : Status where the approval status is either:

- PENDING

- APPROVED

- REJECTED | Key/Value array | +| **creativeapprovals** | Any array of pairs describing the approval status for each publisher in the form PublisherId : Status where the approval status is either:

- PENDING

- APPROVED

- REJECTED | enum (PENDING, APPROVED, REJECTED) | |**ext**|Optional vendor-specific extensions. |ext object| + _* required_ @@ -314,7 +358,7 @@ _Notes: The user may update a line only if it’s in the Draft state. If the lin |Attribute|Description|Type| |---|---|---| -|**id** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ | +|**id*** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ | |**name***|The line’s display name.

Should be unique.|string _(200)_ | |**orderid***|The ID of the order that this line belongs to.|string _(36)_ | |**productid***|The ID of the product where the creatives run.|string _(36)_ | @@ -324,15 +368,19 @@ _Notes: The user may update a line only if it’s in the Draft state. If the lin |**enddate***|The date and time that the line will stop.

If the time is missing, 11:59:59 PM is assumed.

The line end date must be later than the line start date and should be less than or equal to the order’s end date.

If the line end date is later than the order’s end date, the order’s end date should be extended to match the line’s end date.|string (date-time) |**ratetype***|Defines a unit of measure that a cost (i.e. BasePrice) is expressed in. The API may support all or a subset of the specified values.|enum (CPM, CPMV, CPC, CPD, FlatRate) |**rate***|The price per unit of impressions. For example, $10 per 1,000 impressions (CPM).

The rate is determined each time the line is saved (added, updated, booked, or reserved).

Value in currency for the order.|number -|**quantity***|The quantity requested for the specified date range. This value will differ based on various cost types. For CPM, for examples, the value would be impressions.

The line must contain a quantity before the user may reserve or book it. If the requested quantity is not available, reserving or booking the line must fail and bookingStatus must be set to Declined.|integer +|**qty***|The quantity requested for the specified date range. This value will differ based on various cost types. For CPM, for examples, the value would be impressions.

The line must contain a quantity before the user may reserve or book it. If the requested quantity is not available, reserving or booking the line must fail and bookingStatus must be set to Declined.|integer |**cost***|The projected cost of the line is based on the specified quantity, rate and targeting. The actual cost (the amount billed) is based on the actual number of impressions.

The cost is specified in the currency for the order. If the order uses a different currency than what the product uses, the cost for the line must be converted to the order’s currency.

The cost is determined at the time the line is saved with the following statuses: Drafted, Reserved, or Booked.|number |**comment** |User notes related to this line. |string _(255)_ | |**frequencycount** |The maximum number of times that a unique user must see ads from this line during the specified interval (see FrequencyInterval).|integer |**frequencyinterval**|Defines the frequency cap intervals that the API supports.

The frequency interval specifies the units in which the frequency count is expressed. For example, if a line’s frequency count is 2 and interval is Day, display the ad to the same user a Max 2 times in the same calendar day.|enum (Day, Month, Week, Hour, LineDuration) |**reservedexpirydate** |The date and time that the reserved inventory will expire.

If the line is reserved, the expiry date must be set.|string (date-time) |**targeting**|The creative assigned to the LINE resource is display when the line includes user segments and the delivery engine can determine whether the user matches the specified segments.|[AdCOM **Segment** object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_segment) array | +|**producttargeting**|Array of objects used to determine product availability.|producttarget array | +|**providerdata**|The ProviderData object is used for buyers to detail structured information that may be used to identify their order in a seller's system using their own IDs or references. |object| +|**specialinstructions**|Free text box to capture any special intructions relating to the orderline. If this field is used, the orderline should be set to requested/pending status for manual intervention e.g. this could be used for special posting/display instructions such as 'blank after orderline end time'|string (255) |**pmp** | | | |**ext**|Optional vendor-specific extensions. |ext object| + _* required_ ## Object: Message @@ -342,7 +390,7 @@ Mesages are used for communication between a buyer are a seller around an Order |Attribute|Description|Type| |---|---|---| -|**id** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ +|**id*** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ |**sender** |The sender of the message| [Contact](#object_contact) object | |**recipient**|The intended recipient of the message|[Contact](#object_contact) object | |**messagedate** |Time and date the mesage was sent|string (date-time) @@ -354,8 +402,9 @@ Mesages are used for communication between a buyer are a seller around an Order |**replytomessageid** |Id of the message that this message is in reply to| string _(36)_ |**replywebhook** |URI which is called when there is a reply to this message.

URI is called with a PUT request containing the new MessageId in a JSON object. |string _(1024)_ |**ext**|Optional vendor-specific extensions. |ext object| -_* required_ +_* required_ + ## Object: Order The Order resource specifies the plan’s start and end dates, estimated budget, currency, and preferred billing method for all line items in the order. @@ -365,7 +414,7 @@ To specify the individual line item details of the order, use the [LINE](#object |Attribute|Description|Type| |---|---|---| -|**id** |A system-generated opaque ID that uniquely identifies this resource.| string _(36)_ +|**id*** |A system-generated opaque ID that uniquely identifies this resource.| string _(36)_ |**name*** |The order’s display name.

Must be unique within the account’s list of orders.|string _(100)_ |**accountid*** |The ID of the account that identifies the advertiser and buyer that own the order.|string _(36)_ |**publisherid*** |The Id of the Publisher providing this Order| string _(36)_ @@ -375,10 +424,13 @@ To specify the individual line item details of the order, use the [LINE](#object |**orderstatus*** |Specifies the Status of the Order.|enum (PENDING, APPROVED, REJECTED) |**packageonly** |Identifies whether the order is only available as a package or if specific items can be separated from the inventory.

A value of TRUE means the inventory is only available as a package.

A value of FALSE allows the buyer to select specific items from inventory.|boolean |**preferredbillingmethod** |The preferred billing method for this order.

The default is Electronic.

If the billing contact is not specified in the order, the billing contact comes from buyer’s list of contacts.|enum (Electronic, Postal) +|**providerdata**|The ProviderData object is used for buyers to detail structured information that may be used to identify their order in a seller's system using their own IDs or references. |object| +|**advertiserbrandid***|id of the brand being advertised by the advertiser organisation |string _(36)_| |**startdate** |The date and time that the order will start. The start date is directional and may be updated by the publisher to match the earliest start date found in the order’s list of lines.

If the time is missing, 12:00 AM is assumed.

When creating the order, the date and time must be greater than or equal to now.

Start dates that have past may not be updated.|string (date-time) |**enddate** |The date and time that the order will end. The end date is directional and may be updated by the publisher to match the latest end date found in the order’s lines.

If the time is missing, 11:59:59 PM is assumed.

The end date must be later than the start date.

End dates that have past cannot be updated.|string (date-time) |**orderexpirydate**|The date and time for when the order expires. Publisher will only hold inventory up until the date and time indicated.|string (date-time) |**contacts** |The list of contacts to use for this order. This list of contacts is in addition to the buyer’s and advertiser’s list of contacts.

The list must contain unique contact types (for example, only one billing contact).| [Contact](#object_contact) array +|**specialinstructions**|Free text box to capture any special intructions relating to the order. If this field is used, the order should be set to requested/pending status for manual intervention|string (255) |**ext**|Optional vendor-specific extensions. |ext object| _* required_ @@ -392,7 +444,7 @@ A publisher may also create an organization for itself for the purpose of reques |Attribute|Description|Type| |---|---|---| -|**id**|A system-generated opaque ID that uniquely identifies this resource.| string _(36)_ +|**id***|A system-generated opaque ID that uniquely identifies this resource.| string _(36)_ |**address** | The primary address of the organization|[Address](#object_address) object |**contacts** |A list of one or more contacts within the organization. The list must contain unique contact types (for example, only one billing contact). At least one billing contact is required.|[Contact](#object_contact) array |**disapprovalreason**|The reason why the organization was not registered. Must be specified if Status is Disapproved. |string _(255)_ @@ -401,8 +453,12 @@ A publisher may also create an organization for itself for the purpose of reques |**name*** |The organization’s display name.

Cannot be an empty string. Must be unique. |string _(120)_ |**phone** |The organization’s phone number. |string _(20)_ |**status*** |A value that indicates the current state of the approval process.

The approval process confirms the organization’s identity. |enum (Pending, Approved, Disapproved, Limited) +|**organizationtype***| The core activity that an organisation undertakes as a business e.g. Advertiser, Intermediary or Agency| enum (advertiser, intermediary, agency, publisher) | +|**advertiserbrands**| Array of one or more advertiserbrand objects associated with an advertiser organisationtype| Array | +| **eids** | array of extended ids (EID) that detail third party datasources and ids that may be referenced to identify the organization to the buyer | Array | |**url** |A URL to the organization’s website. |string _(1024)_ |**ext**|Optional vendor-specific extensions. |ext object| + _* required_ ## Object: Placement @@ -411,11 +467,12 @@ The Placement resource is usd to store the specifications for an individual AdUn |Attribute|Description|Type |---|---|---| -|**id** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ +|**id*** |A system-generated opaque ID that uniquely identifies this resource.|string _(36)_ |**lineid*** |The Id of the line the placement belongs to|string _(36)_ |**adunitid*** |The Id of the Ad unit this placement is for|string _(36)_ |**spec** |The technical specifications for this line.

If empty, the technical specifications for the Ad Unit are used|[AdCOM **Placement** object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_placement)| |**ext**|Optional vendor-specific extensions. |ext object| + _* required_ @@ -432,7 +489,7 @@ A Product resource identifies anything from an ad placement to a Run of Network |**allownocreative** |A Boolean value that indicates whether line items assigned to this order may be booked before creative is assigned.

A value of TRUE allows lines to be booked without creative assigned.

Default value is FALSE and prevents lines from being booked when no creative is assigned.|boolean |**currency*** |Identifies the currency for BasePrice and MinSpend.

Using ,ISO-4217 currency code|string _(3)_ |**baseprice*** |The product’s base retail price; this is not the rate card price.

The actual price may be more if targeting is specified.|number -|**deliverytype** |Defines the possible types of delivery.|<<_opendirect_product_deliverytype,deliverytype>> +|**deliverytype** |Defines the possible types of delivery.
• Exclusive – 100% share of voice.
• Guaranteed – Guaranteed delivery of all booked display and/or impressions
• Non-Guaranteed - Non-Guaranteed delivery of all booked display and/or impressions
| enum (exclusive, guaranteed, non-guaranteed) |**estdailyavails** |An estimated range of available daily impressions.

The ranges should be of the form: Thousands, Tens of Thousands, Hundreds of Thousands, and so on.|string |**domain** |Common definition for a domain name.| string _(1024)_ |**icon** |URL to a thumbnail icon of the product. May be used to display next to the product in the product catalog.

Publishers should support icons that are 150x150 or less. The maximum size is 10 KB.|string _(1024)_ @@ -445,13 +502,150 @@ A Product resource identifies anything from an ad placement to a Run of Network |**ratetype***|Defines a unit of measure that a cost (i.e. BasePrice) is expressed in. The API may support all or a subset of the specified values.|enum (CPM, CPMV, CPC, CPD, FlatRate) |**adunit** | Details of the Ad Units comprising this Product | [AdUnit](#object_adunit) array |**alladunits** |Describes whether all child Ad Units are severed together as a group or just one of the Ad Units is served|integer -|**retirementaate** |The date and time, in UTC, that the product may be removed from the bookable inventory.|string (date-time) +|**retirementdate** |The date and time, in UTC, that the product may be removed from the bookable inventory.|string (date-time) |**tz** |The time zone that the product runs in.|string |**url** |A URL to the specification that describes the creative requirements.|string -|**context** | | [AdCOM **Context** Object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_context)| -|**source** ||<> -|**pmp** ||<> +|**context** |Indicates the type of content being used or consumed by the user in which ads may appear. This table has values derived from the TAG Inventory Quality Guidelines (IQG). | [AdCOM **Context** Object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--content-contexts-)| +|**source** |This object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the exchange itself does not control the final decision. A common example of this is header bidding, but it can also apply to upstream server entities such as another RTB exchange, a mediation platform, or an ad server combines direct campaigns with 3rd party demand in decisioning.|[OpenRTB Source](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3222---object-segment-) +|**pmp** |This object is the private marketplace container for direct deals between buyers and sellers that may pertain to this Product|[OpenRTB PMP](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3211---object-pmp-) +|**producttargeting** | Array of producttargeting objects used to describe the product inventory and sales rules | producttargeting object | +|**availsgroupby** | Array of producttargeting objects that describe the grouped fields that that the Availability data can be returned in | producttargeting object | +|**reservedexpirytime** | Defines a duration that represents the cut off point for expiry of an OrderLine from when it is “reserved”. | ISO-8601 | +|**advertiseridaccess**| List of AdvertiserIDs with access to this Product. NULL = all accounts can access this product. | Array | +|**buyeridaccess**| List of BuyerIDs with access to this Product. NULL = all accounts can access this product. | Array | +|**intermediaryidaccess**| List of IntermediaryIDs with access to this Product. NULL = all accounts can access this product. | Array | +|**ext**|Optional vendor-specific extensions. |ext object| + +_* required_ + + +## Object: ProductAvailsSearch + +Defines search criteria used for requesting product availability and pricing within the given search criteria. + +| Attribute | Description | Type | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | +| **productids*** | A list of IDs that identify the products on which to get availability and pricing information | Array | +| **targeting** | The segments to target. For example, behavioral, age, and gender segments. | [AdCOM **Segment** object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_segment) array | +| **producttargeting** | The Inventory, Delivery, Investement and Distribution ProductTargeting objects to be targeted for the availability request | producttargeting object array | +| **accountid*** | The ID of the account that identifies the buyer, advertiser and any other stakeholders | String(36) | +| **currency** | The currency used to specify Price. Currency is set for the PRODUCT resource specified in section 2.7 and uses CURRENCY reference data specified in section 4.6. | Max 3 Char | +| **advertiserbrandid*** | An ID that uniquely identifies the Brand being advertised | String (36) | +| **availabilityfields** | Defines the ProductTargeting object metrics that availability is returned as | producttargeting object array | +| **grouping** | Defines the ProductTargeting object metrics that the availability output is grouped as | producttargeting object array | +| **startdate*** | The desired start date for inventory delivery | ISO-8601 | +| **enddate*** | The desired end date for inventory delivery | ISO-8601 | + +_* required_ + +## Object: ProductSearch + +An object that is used to identify search criteria used for finding appropriate products in the product catalouge + +|Attribute|Description|Type +|---|---|---| +|**publisherid** |The Id of the Publisher providing this Product|string _(36)_ +|**name** |The product’s name.|string _(100)_ +|**description** |The product’s description. |string _(255)_ +|**activedate** |The date and time, in UTC, that the product may become part of the bookable inventory.|string (date-time) +|**allownocreative** |A Boolean value that indicates whether line items assigned to this order may be booked before creative is assigned.

A value of TRUE allows lines to be booked without creative assigned.

Default value is FALSE and prevents lines from being booked when no creative is assigned.|boolean +|**currency** |Identifies the currency for BasePrice and MinSpend.

Using ,ISO-4217 currency code|string _(3)_ +|**baseprice** |The product’s base retail price; this is not the rate card price.

The actual price may be more if targeting is specified.|number +|**deliverytype** |Defines the possible types of delivery.
• Exclusive – 100% share of voice.
• Guaranteed – Guaranteed delivery of all booked display and/or impressions
• Non-Guaranteed - Non-Guaranteed delivery of all booked display and/or impressions
| enum (exclusive, guaranteed, non-guaranteed) +|**estdailyavails** |An estimated range of available daily impressions.

The ranges should be of the form: Thousands, Tens of Thousands, Hundreds of Thousands, and so on.|string +|**domain** |Common definition for a domain name.| string _(1024)_ +|**languages** |A list of creative languages that the product supports from ISO-639-1|string array +|**leadtime** |The number of days (n) from today that a line that reference this product can begin running; the line’s start date must be equal to or later than today + n.|integer +|**minspend** |The minimum order value of this Product in the specified currency|number +|**minflight**|The minimum number of days that the product must be booked for. The line must enforce the duration.|integer +|**maxflight**|The maximum number of days that the product may be booked for. The line must enforce the duration.|integer +|**producttags**|List of tags used for searching the product catalog.| string array +|**ratetype**|Defines a unit of measure that a cost (i.e. BasePrice) is expressed in. The API may support all or a subset of the specified values.|enum (CPM, CPMV, CPC, CPD, FlatRate) +|**adunit** | Details of the Ad Units comprising this Product | [AdUnit](#object_adunit) array +|**alladunits** |Describes whether all child Ad Units are severed together as a group or just one of the Ad Units is served|integer +|**retirementdate** |The date and time, in UTC, that the product may be removed from the bookable inventory.|string (date-time) +|**tz** |The time zone that the product runs in.|string +|**context** |Indicates the type of content being used or consumed by the user in which ads may appear. This table has values derived from the TAG Inventory Quality Guidelines (IQG). | [AdCOM **Context** Object](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--content-contexts-)| +|**producttargeting** | Array of producttargeting objects used to describe the product inventory and sales rules | producttargeting object | +|**availsgroupby** | Array of producttargeting objects that describe the grouped fields that that the Availability data can be returned in | producttargeting object | +|**reservedexpirytime** | Defines a duration that represents the cut off point for expiry of an OrderLine from when it is “reserved”. | ISO-8601 | |**ext**|Optional vendor-specific extensions. |ext object| + + +## Object: Avails + +Defines the response to a request for product availability and pricing information at product Level + +| Attribute | Description | Type | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| **productid*** | ID that identifies the product for which availability and pricing information is provided | String(36) | +| **accountid*** | The ID of the account that identifies the buyer, advertiser and any other stakeholders. | String(36) | +| **availability** | The quantity available for booking for the specified date range. Availability for a given date range may vary. In order for products to be returned in a PRODUCT AVAILS SEARCH, product availability must be equal to or less than the value provided in the quantity property of the PRODUCT AVAILS SEARCH object. For example, if quantity is set to 500,000 in PRODUCT AVAILS SEARCH, impression availability for the product must be at least 500,000. However, if only 250,000 impressions are available, the product is not returned. Publishers may set an artificial limit on the maximum number of available impressions. If the quantity field in PRODUCT AVAILS SEARCH is not provided, all products matching other criteria are returned showing maximum availability. | Integer | +| **availsstatus** | An object that groups the inventory availbility into Available, Partially Available and Unavailable arrays of ProductTargeting objects | productavailability Object | +| **currency** | The currency used to specify Price. Currency is set for the PRODUCT resource specified in section 2.7 and uses CURRENCY reference data specified in section 4.6. | String (3) \[ISO-4217\] | +| **price*** | The product’s price | Decimal | +| **startdate*** | The requested start date for inventory delivery | ISO-8601 | +| **enddate*** | The requested end date for inventory delivery | ISO-8601 | + +_* required_ + +## Object: AvailsStatus + +An object that groups the inventory availbility into Available, Partially Available and Unavailable arrays of producttargeting objects + +| Attribute | Description | Type | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| **status*** | Summary definition of the inventory described in the Targeting Array as

| enum(Available, Partially Available, Unavailable) | +| **reason** | State the reason if Partially Available or Unavailable from the list | String | +| **comment** | Free text for an availability comment | String | +| **context** | Array of ProductTargeting objects describing the context of any Partially Available or Unavailable status e.g. this could be a frame that is causing a duplication error | Object | +| **producttargeting*** | Array of ProductTargeting objects describing the inventory that is at Available, Partially Available or Unavailable status | Object | + +_* required_ + +## Object: ProductTargeting + +OpenDirect (and OpenRTB) trades with real time Audience impressions, whereas physical media such as Out-Of-Home can be sold in the wider dimensions of time, share of time, location and audience. + +Physical media manifests itself as display of the advert on a 'frame' at a defined location and time which then gives an audience in the vicinity of that event an opportunity to see the advertising. + +The producttargeting object is used to discover and target the real-life dimensional aspect of physical media. Full details on the use of the ProductTargeting object can be found in the section [ProductTargeting for Physical Media](#producttargetingdetails) + +| Attribute | Description | Type | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| **name*** | The key objects for describing physical media campaigns and products are:
• Inventory: What a media owner / publisher sells in terms of Audience or Frames.
• Delivery: How adverts are displayed from a start and end time, and the share of that display time.
• Distribution: How the adverts are distributed across the times and locations booked by audience and/or investment.
• Investment: How the campaign is quantified for trading purposes (Fixes price, Cost Per Thousand Audience, Cost Per Frame).
• Prohibitions: Information about any brand safety prohibitions that will affect the playout of certain brand types in certain locations e.g. fast food prohibitions on certain locations. | enum (Inventory, Delivery, Distribution, Investment, Prohibitions) | +| **type*** | How the producttargeting is being quantified:
• Frames
• Audience
• Investment | enum (Frames, Audience, Investment, Total) | +| **datasource*** | The identification and inclusion of third party data sources into the schema, which both buyside and sell side may use to describe and discover their available Inventory, location and audiences in accordance with the third party schema | String (255) | +| **target*** | Description of the producttargeting Metric | String (255) | +| **targetvalues*** | Array of one or more values | String (255) Array | +| **selectable*** | Defines whether a Buyer can select from the given list of targetvalues or whether the targetvalues are fixed | Boolean | +| **count** | Count of targetvalues | number | +| **minimum** | Defines the minimum number of targetvalues that must be selected | number | +| **maximum** | Defines the maximum number of targetvalues that must be selected | number | +| **increment** | Defines the increments that are permitted for the targeting values | number | +| **default** | Defines the default targetvalues(s) that are selected if the Buyer does not specify any TargetValue(s) or the target is not selectable | String (255) or Number | + +_* required_ + +## Object: ProviderData + +The ProviderData object is used for Buyers to detail information that may be used to identify their order in a Seller's system using their own IDs or references. This would be mainly used for manually identifying orders in the event of the automated process needing manual intervention. + +At Order level, ProviderData is generated by the buyer when the order is created. At Line level, ProviderData created by the buyer when Line is created. Both objects can then be updated by the Buyer via a change request. + +If the Seller has their own commercial rules that requires a Order and/or Line to have a Purchase Order Number attached to make a booking, the Sell Side can send an explicit error response if the buyer tries to book without a Purchase Order Number. + +It is proposed that a Seller should publish such commercial rules in a text file accessible via the Collection Objects facility e.g. call URI / collectionobjects/businessrules + +| Attribute | Description | Type | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | +| **campaignid*** | Provided by the Buyer to uniquely identify the Advertising Campaign for which the Order is being placed | String (255) | +| **campaignname*** | A descriptive name provided by the Buyer which is associated with the Advertising Campaign for which the Order is being placed | String (255) | +| **ponumber** | Provided by Buyer as a reference to be used by Buyers for any offline contact related to the Order | String (255) | +| **salesorderreference** | Provided by the Media Owner as a reference to be used by Buyers for any offline contact related to the Order | String (255) | +| **barterorganizationid** | The OrganizationID of a Barter Company can be added here to flag a Barter transaction | String (255) | +| **other** | An opaque CLOB of provider-defined data. Providers may use this field as needed (for example, to store an ID that correlates this object with resources within their system). Note that any provider that edits this object may override the data in this field. The data should include a marker that you can identify to ensure the data is yours. | CLOB (10000) | + _* required_ ## Object: Stats @@ -460,12 +654,90 @@ The Stats resource contains reporting data about a Line. |Attribute|Description|Type| |---|---|---| -|**reportdate**|A system-generated opaque ID that uniquely identifies this resource.|string _datetime_ | -|**impressions:**| **The number of impressions served to date.

The value must be zero if no impressions have been served | integer -|**clicks**|**The number of clicks to date. The value must be zero if no clicks have occurred.| integer +|**reportdate***|A system-generated opaque ID that uniquely identifies this resource.|string _datetime_ | +|**impressions**| The number of impressions served to date.

The value must be zero if no impressions have been served | integer +|**clicks**|The number of clicks to date. The value must be zero if no clicks have occurred.| integer |**ctr**|The click through rate to date. The formula to calculate CTR is (clicks / impressions) x 100 | number |**spend**|The amount spent to date. | number +|**tagid*** | A unique Publisher ID for describing the inventory where the advert appeared e.g. FrameID | String (128) | +|**deviceref** | The MAC Address or other reference uniquely identifying a digital player or device | Max length 32 characters | +|**startdate*** | The UTC start time of the spot. | ISO-8601 | +|**startutcoffset*** | Time zone offset for the spot start time (e.g. +01:00 for BST; Z or :00:00 can be used for GMT.) | ±hh:mm
Z | +|**enddate*** | The UTC end time of the spot. | ISO-8601 | +|**endutcoffset*** | Time zone offset for the spot end time. (e.g. +01:00 for BST; Z or :00:00 can be used for GMT.) | ±hh:mm
Z | +|**spotlength** | Spot Length in milliseconds. | number | +|**shareoftime** | Share of time as a % out of 100. This must be provided for scrollers, but its presence is not policed by Playout. Media Owners must determine when this must be supplied. | number (decimal) | +|**creativeid** | Media Owner-defined creative identifier. | String (64) | +|**creativename** | Creative title, to assist with reporting. Usually a filename. | String (128) | +|**crid** | Creative reference provided by a third-party such as the creative agency. This might be a URL or a GUID, for example. | String (128) | +|**creativetriggerevent** | The creative trigger event, indicating what prompted the given creative to be used. | String (64) | +|**publisherplayoutref** | A publisher or media owner-defined reference representing this record. This should uniquely identify this record across all time. (Note that records supplied by other Publsher/Media Owners may happen to use the same ID.) | String (48) | + +_* required_ + +## Object: EID + +Extended identifiers support in the OpenDirect specification allows buyers to use third party identifiers in ther trading process. This object can contain one or more UIDs from a single source or a technology provider. The publisher should ensure that business agreements allow for the sending of this data. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Attribute        Type                    Description
source*stringSource or technology provider responsible for the set of included IDs. Expressed as a top-level domain.
name*stringName of third party ID.
uids*object arrayArray of third party IDs UID objects from the given source. Refer to Object: UID
extobjectPlaceholder for exchange-specific extensions to OpenDirect.
+ +_* required_ +## Object: UID + +This object contains a single third party identifier provided as part of extended identifiers. The publisher should ensure that business agreements allow for the sending of this data. + + + + + + + + + + + + + + + + + + + + +
Attribute        Type                    Description
id*stringThe identifier for the Third Party.
extobjectPlaceholder for specific extensions to this object.
+ +_* required_ # Collection Objects @@ -474,14 +746,15 @@ For GET calls that return a collection of resources, such as /accounts/{id}/orde | Call | Property Name | Resource | | ---- | ------------- | -------- | | /organizations
/organizations?$filter | organizations | Organization | +| /advertiserbrands
/advertiserbrands?$filter | advertiserbrands | AdvertiserBrand | | /accounts
/accounts?$filter | accounts | Account | | /accounts/{id}/assignments
/accounts/{id}/assignments?$filter | assignments | Assignment | -| /accounts/{id}/creatives
/accounts/{id}/creatives?$filter | creatives | Creative_Assignment | -| /accounts/{id}/orders
/accounts/{id}/orders?$filter | orders | Order_Campaign_Assignment | -| /accounts/{id}/orders/{id}/lines
/accounts/{id}/orders/lines?$filter | lines | Lines_Assignment | -| /accounts/{id}/orders/{id}/lines/{id}/placements
/accounts/{id}/orders/lines{id}/placements?$filter | placements | Placement_Assignment | -| /products
/products/search (POST) | products | Product_Assignment | -| /products/avails (POST) | avails | ProductAvails_Assignment +| /accounts/{id}/creatives
/accounts/{id}/creatives?$filter | creatives | Creative Assignment | +| /accounts/{id}/orders
/accounts/{id}/orders?$filter | orders | Order Campaign Assignment | +| /accounts/{id}/orders/{id}/lines
/accounts/{id}/orders/lines?$filter | lines | Lines Assignment | +| /accounts/{id}/orders/{id}/lines/{id}/placements
/accounts/{id}/orders/lines{id}/placements?$filter | placements | Placement Assignment | +| /products
/products/search (POST) | products | Product Assignment | +| /products/avails (POST) | avails | Avails The following shows an example response for _**/accounts**_. ```json @@ -584,13 +857,23 @@ For example, you have 100 records and wish to return 25 per page, you would spec Recommended Count Limit: _**250**_ -## Custom Headers -When using paging, the consumer may need to know how many total records there are so this should be part of the response. There are two options here. One would be to return the total count in an outer json object to the request. The other is to use a custom header. The custom header is preferable because it does not become part of the model represented by the json. The con is, many frown upon custom headers. +## Paging Object vs Custom Headers -Header Name: _**X-Total-Count**_ +When using paging, the consumer may need to know how many total records there are so this should be part of the response. There are two options here. One would be to return the countdetails in an outer json object to the request e.g. + +```json +"paging": { + "offset": 0, + "count": 25, + "totalrecords": 100, + "countlimit": 100 +} +``` +The other is to use a custom header. The custom header is suggested because it does not become part of the model represented by the json. The con is, many frown upon custom headers. +Header Name: _**X-Total-Count**_ # INTERFACES @@ -602,6 +885,9 @@ Header Name: _**X-Total-Count**_ | Account | /accounts | GET, POST | Yes | | Account | /accounts/{id} | GET | Yes | | Account | /accounts?$filter= | GET | Yes | +| AdvertiserBrands | /advertiserbrands | GET | No | +| AdvertiserBrands | /advertiserbrands/{id} | GET | No | +| AdvertiserBrands | /advertiserbrands?$filter= | GET | No | | Assignment | /accounts/{id}/assignments | GET, POST | Yes | | Assignment | /accounts/{id}/assignments/{id} | GET, PUT or
PATCH, DELETE | Yes | | Assignment | /accounts/{id}/assignments/{id}?disable | PUT or PATCH | Yes | @@ -634,6 +920,290 @@ Header Name: _**X-Total-Count**_ | ChangeRequestLine | /accounts/{id}/changesrequests//lines/{id} | GET, PUT or
PATCH | Yes | | ChangeRequestLine | /accounts/{id}/changesrequests//lines?$filter= | GET | Yes | +## URI Filter Guidance +The following examples show the reccomended implememtiation support for the url filter function + +#### Wildcards +/brands?name=\*gucci\*
+/organizations?name=\*procter\* + +#### Boolean (AND) Logic +/brands/?eids_name=SPACE&eids_uids_id=1234
+/organizations?eids_name=SPACE&eids_uids_id=4567
+/organizations?eids_source=https://oohspace.co.uk&eids_uids_id=8879 + +#### Ability to retrieve all data if pagination is implemented +/brands?offset=0&count=50000
+/organizations?offset=0&count=50000 + + +## Path: AdvertiserBrands +The advertiserbrand associates brands to an advertiser. advertiserbrand URIs enables the buyer to identify the brands linked to the advertiser they are buying for. Its important for Publishers that they know what brand is being user in the transaction so that the publisher can give availbility based on prohibition and duplication considerations. + +### /advertiserbrands ### +Gets a list of advertiserbrands that the user has access to. The response must support pagination. See Paging Query Parameters. + +#### Verbs #### + +* **GET**: Gets a list of all advertiserbrands +* **POST**: Adds an advertiserbrand + +#### Rules #### +For an advertiser, the list of advertiserbrands will include only brands that they own. However, for an agency, the list of advertiserbrands will include the advertiserbrands that they manage on behalf of advertisers. + +#### Example POST Request ##### +```json +POST https://///advertiserbrands HTTP/1.1 +Content-Type: application/json +AccessToken: +{ + "name": "Walkers", + "organizationid": "889", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "84585608" + } + ] + } + ] +} +``` + +#### Example POST Response #### +```json +HTTP/1.1 200 OK +Location: https://///accounts/23873345 +Content-Type: application/json +Content-Length: 379 +{ + "id": "1234", + "name": "Walkers", + "organizationid": "889", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "84585608" + } + ] + } + ] +} +``` + + +#### Example GET Request #### +```json +GET https://///advertiserbrands HTTP/1.1 +Accept: application/json +AccessToken: +``` + +#### Example GET Response #### +```json +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: 2079 +{ + "advertiserbrands": [ + { + "id": "1173", + "name": "Marmite", + "organizationid": "345", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "14789" + } + ] + } + ] + }, + { + "id": "1174", + "name": "PGTips", + "organizationid": "345", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "567" + } + ] + } + ] + }, + { + "id": "1175", + "name": "Lynx", + "organizationid": "345", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "8890" + } + ] + } + ] + }, + { + "id": "1176", + "name": "Walls", + "organizationid": "345", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "3562" + } + ] + } + ] + }, + { + "id": "1234", + "name": "Walkers", + "organizationid": "889", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + + "id": "84585608" + } + ] + } + ] + } + ] +} +``` + +### /advertiserbrands/{id} ### +Gets the specified Account. + +#### Verb #### +* **GET**: Gets the specified advertiserbrand. + +#### Rules #### +The user must have permissions to perform the requested action. For example, advertisers and agencies may get the advetiserbrands that they own. In addition, an agency may get the advertiserbrands that they manage on behalf of advertisers. + +#### Example GET Request #### +```json +GET https://///advertiserbrands/1234 HTTP/1.1 +Accept: application/json +AccessToken: +``` + +#### Example GET Response #### +```json +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: 187 +{ + "id": "1234", + "name": "Walkers", + "organizationid": "889", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "84585608" + } + ] + } + ] +} + +``` + +### /advertiserbrands?$filter= ### +The response must support pagination. See Paging Query Parameters. + +#### Verb #### +* **GET**: Gets a list of advertiserbrands that match the specified filter criteria. The user may use filter expressions with any of the Account properties: + * id + * name + * organizationid + * eidssource + * eidsname + * eidsuidsid + + +#### Rules #### +User should be able to filter the advertiserbrands by any of the fields or field values of the advertisers they have access to. Logical AND/OR condition of the fields may be allowed. + +#### Example Request #### +```json +GET https://///accounts?name=*wa* HTTP/1.1 +Accept: application/json +AccessToken: +``` + +#### Example Response #### +```json +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: 187 +{ + "advertiserbrands": [ + { + "id": "1176", + "name": "Walls", + "organizationId": "345", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "3562" + } + ] + } + ] + }, + { + "id": "1234", + "name": "Walkers", + "organizationid": "889", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + + "id": "84585608" + } + ] + } + ] + } + ] +} +``` + ## Path: Accounts The account resource associates an organization ID for a buyer with an organization ID for an advertiser. Account URIs enable account creation and account search. @@ -661,6 +1231,7 @@ AccessToken: { "advertiserid":"1234987", "buyerid":"34587", + "intermediaryid":"9876543", "name":"Brand A" } ``` @@ -674,8 +1245,10 @@ Content-Length: 379 { "advertiserid":"1234987", "buyerid":"34587", - "id":"23873345", - "name":"Brand A" + "intermediaryid":"9876543", + "name":"Brand A", + "status":"Approved", + "id":"23873345" } ``` @@ -698,14 +1271,17 @@ Content-Length: 187 { "advertiserid":"1234987", "buyerid":"1234987", - "id":"9876542", - "name":"Brand B" + "name":"Brand B", + "status":"Pending", + "id":"9876542" }, { "advertiserid":"1234987", "buyerid":"34587", - "id":"23873345", - "name":"Brand A" + "intermediaryid":"9876543", + "name":"Brand A", + "status":"Approved", + "id":"23873345" } ] } @@ -735,8 +1311,10 @@ Content-Length: 187 { "advertiserid":"1234987", "buyerid":"34587", - "id":"23873345", - "name":"Brand A" + "intermediaryid":"9876543", + "name":"Brand A", + "status":"Approved", + "id":"23873345" } ``` @@ -744,18 +1322,22 @@ Content-Length: 187 The response must support pagination. See Paging Query Parameters. #### Verb #### -* **GET**: Gets a list of accounts that match the specified filter criteria. The user may use OData expressions with the following Account properties: +* **GET**: Gets a list of accounts that match the specified filter criteria. The user may use filter expressions with any of the Account properties: * AdvertiserId * BuyerId + * intermediaryid + * name + * status + * id May also support getting a list of IDs. #### Rules #### -Only an advertiser or a buyer who own the accounts can issue the request. User should be able to filter the accounts by any of the fields or field values of the owned account. Logical AND/OR condition of the fields shall be allowed. +Only an advertiser or a buyer who own the accounts can issue the request. User should be able to filter the accounts by any of the fields or field values of the owned account. Logical AND/OR condition of the fields may be allowed. #### Example Request #### ```json -GET Error! Hyperlink reference not valid.Error! Hyperlink reference not valid. HTTP/1.1 +GET https://///accounts?name=*Brand* HTTP/1.1 Accept: application/json AccessToken: ``` @@ -768,16 +1350,19 @@ Content-Length: 187 { "Accounts":[ { - "advertiserid":"1234568", - "buyerid":"34587", - "id":"23873450", - "name":"Brand B" + "advertiserid":"1234987", + "buyerid":"1234987", + "name":"Brand B", + "status":"Pending", + "id":"9876542" }, { "advertiserid":"1234987", "buyerid":"34587", - "id":"23873345", - "name":"Brand A" + "intermediaryid":"9876543", + "name":"Brand A", + "status":"Approved", + "id":"23873345" } ] } @@ -809,7 +1394,32 @@ AccessToken: { "creativeid":"394857", "placementid":"394578", - "weight":75 + "sov":75, + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "dataSource": "Space", + "target": "tv_area", + "targetvalues": [ + "North East" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ + "1", + "2", + "3", + "8", + "9", + "10" + ] + } + ] } ``` @@ -818,12 +1428,37 @@ AccessToken: HTTP/1.1 200 OK Location: https://///accounts/23873345/assignments/34534 Content-Type: application/json -Content-Length: 187 +Content-Length: 689 { "creativeid":"394857", - "Pplacementid":"394578", + "placementid":"394578", + "sov":75, + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "dataSource": "Space", + "target": "tv_area", + "targetvalues": [ + "North East" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ + "1", + "2", + "3", + "8", + "9", + "10" + ] + } + ], "id":"34534", - "weight":75, "status":"Active" } ``` @@ -839,20 +1474,44 @@ AccessToken: ```json HTTP/1.1 200 OK Content-Type: application/json -Content-Length: 387 +Content-Length: 1171 { "assignments":[ { "creativeid":"394857", "placementid":"394578", - "weight":75, - "id":"34534", - "status":"Active" + "sov":75, + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "dataSource": "Space", + "target": "tv_area", + "targetvalues": [ + "North East" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ + "1", + "2", + "3", + "8", + "9", + "10" + ] + } + ], + "id":"34534", + "status":"Active" }, { "creativeid":"54345", "placementid":"394578", - "weight":25, "id":"453365", "status":"Active" } @@ -888,18 +1547,17 @@ Content-Length: 108 { "creativeid":"54345", "placementid":"394578", - "weight":25, "id":"453365", "status":"Active" } ``` #### Example PATCH Request #### ```json -PATCH https://///accounts/23873345/assignments/453365 HTTP/1.1 +PATCH https://///accounts/23873345/assignments/34534 HTTP/1.1 Content-Type: application/json AccessToken: { - "weight":30 + "sov":80 } ``` @@ -907,12 +1565,37 @@ AccessToken: ```json HTTP/1.1 200 OK Content-Type: application/json -Content-Length: 108 +Content-Length: 689 { - "creativeid":"54345", + "creativeid":"394857", "placementid":"394578", - "weight":30, - "id":"453365", + "sov":80, + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "dataSource": "Space", + "target": "tv_area", + "targetvalues": [ + "North East" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ + "1", + "2", + "3", + "8", + "9", + "10" + ] + } + ], + "id":"34534", "status":"Active" } ``` @@ -928,7 +1611,7 @@ The user must have permissions to access the assignment. For example, advertiser #### Example Request #### ```json -PATCH https://///accounts/23873345/assignments/453365 HTTP/1.1 +PATCH https://///accounts/23873345/assignments/453365?disable HTTP/1.1 Content-Type: application/json AccessToken: ``` @@ -941,7 +1624,6 @@ Content-Length: 108 { "creativeid":"54345", "placementid":"394578", - "weight":30, "id":"453365", "status":"Inactive" } @@ -952,38 +1634,65 @@ Content-Length: 108 Gets a list of Assignments that match the specified filter criteria. #### Verb #### -* **GET**: The response must support pagination. See Paging Query Parameters. The caller may use OData expressions with the following Assignment properties: - * CreativeId - * PlacementId - * StartDate - * EndDate +* **GET**: The response must support pagination. See Paging Query Parameters. The user may use filter expressions with any of the Assignment properties: + * creativeid + * placementid + * status + * sov + * producttargeting + #### Rules #### The user must have permissions to access the assignment. For example, advertisers and agencies may get assignments that they own. In addition, an agency may get assignments that belong to the accounts that they manage on behalf of advertisers. #### Example GET Request #### ```json -GET https://///accounts/23873345/assignments?$filter=LineId+eq+394578 HTTP/1.1 +GET https://///accounts/23873345/assignments?placementid=394578 HTTP/1.1 Accept: application/json AccessToken: ``` #### Example GET Response #### ```json -HTTP/1.1 200 OK Content-Type: application/json Content-Length: 108 +HTTP/1.1 200 OK Content-Type: application/json +Content-Length: 1171 { "assignments":[ { "creativeid":"394857", "placementid":"394578", - "weight":75, - "id":"65433", + "sov":75, + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "dataSource": "Space", + "target": "tv_area", + "targetvalues": [ + "North East" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ + "1", + "2", + "3", + "8", + "9", + "10" + ] + } + ], + "id":"34534", "status":"Active" - }, + }, { "creativeid":"54345", "placementid":"394578", - "weight":25, "id":"453365", "status":"Active" } @@ -991,6 +1700,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 108 } ``` + ## Path: Accounts Creatives Account creative hold all creative for the advertiser identified for an account. These creative can be assigned to one or more lines for one or more orders under the account using the assignment object. @@ -1330,7 +2040,7 @@ Adds an Order or gets a list of orders that the user has access to. The response An advertiser or agency may add orders to accounts that they own. In addition; an agency may add orders to accounts that they manage on behalf of advertisers. For advertisers, the list will include only orders that they own. For agencies, the list will include the orders that they own and the orders that belong to accounts that they manage on behalf of advertisers. -#### Example POST Request +#### Example POST Request ```json POST https://///accounts/23873345/orders HTTP/1.1 @@ -1340,6 +2050,7 @@ AccessToken: "accountid":"23873345", "publisherid":"7987654", "brand":"Four Wakes", + "advertiserbrandid": "123456", "budget":50000, "currency":"USD", "enddate":"2014-12-24T18:00:00.000Z", @@ -1360,6 +2071,7 @@ Content-Length: 108 "accountid":"23873345", "publisherid":"7987654", "brand":"Four Wakes", + "advertiserbrandid": "123456", "budget":50000, "currency":"USD", "enddate":"2014-12-24T18:00:00.000Z", @@ -1389,6 +2101,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 187 "accountid":"23873345", "publisherid":"7987654", "brand":"Four Wakes", + "advertiserbrandid":"123456", "budget":50000, "currency":"USD", "enddate":"2014-12-24T18:00:00.000Z", @@ -1396,7 +2109,29 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 187 "orderstatus":"PENDING", "preferredbillingmethod":"Electronic", "startdate":"2014-11-24T06:00:00.000Z" - } + }, + { + "id":"1235873", + "accountid":"23873345", + "publisherid":"7987654", + "brand":"Four Candles", + "advertiserbrandid":"123455", + "budget":100000, + "currency":"USD", + "enddate":"2014-12-24T18:00:00.000Z", + "name":"Two Ronnies Trading", + "orderstatus":"APPROVED", + "preferredbillingmethod":"Electronic", + "startdate":"2014-11-24T06:00:00.000Z", + "providerdata": { + "campaignid":"A00123", + "campaignname":"Goodnight From Him", + "ponumber":"PO80X", + "salesorderreference":"SO678", + "barterorganisationid":"BO808", + "other":{} + } + } ] } ``` @@ -1433,6 +2168,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 158 "id":"1235872", "accountid":"23873345", "brand":"Four Wakes", + "advertiserbrandid":"123456", "budget":50000, "currency":"USD", "enddate":"2014-12-24T18:00:00.000Z", @@ -1463,6 +2199,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 358 "id":"1235872", "accountid":"23873345", "brand":"Four Wakes", + "advertiserbrandid":"123456", "budget":50000, "currency":"USD", "enddate":"2014-12-24T18:00:00.000Z", @@ -1479,7 +2216,7 @@ The response must support pagination. See Paging Query Parameters. #### Verbs -* **GET**: (optional) Gets a list of orders that match the specified filter criteria. The user may use OData expressions with the following Order properties: +* **GET**: (optional) Gets a list of orders that match the specified filter criteria. The user may use expressions with the following Order properties: * accountid * publisherid * orderstatus @@ -1515,6 +2252,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 187 "accountid":"23873345", "publisherid":"7987654", "brand":"Four Wakes", + "advertiserbrandid":"123456", "budget":50000, "currency":"USD", "enddate":"2014-12-24T18:00:00.000Z", @@ -1522,7 +2260,29 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 187 "orderstatus":"PENDING", "preferredbillingmethod":"Electronic", "startdate":"2014-11-24T06:00:00.000Z" - } + }, + { + "id":"1235873", + "accountid":"23873345", + "publisherid":"7987654", + "brand":"Four Candles", + "advertiserbrandid":"123455", + "budget":100000, + "currency":"USD", + "enddate":"2014-12-24T18:00:00.000Z", + "name":"Two Ronnies Trading", + "orderstatus":"APPROVED", + "preferredbillingmethod":"Electronic", + "startdate":"2014-11-24T06:00:00.000Z", + "providerdata": { + "campaignid":"A00123", + "campaignname":"Goodnight From Him", + "ponumber":"PO80X", + "salesorderreference":"SO678", + "barterorganisationid":"BO808", + "other":{} + } + } ] } ``` @@ -1546,7 +2306,7 @@ Adds a Line to an order or gets a list of lines that the user has access to. The An advertiser or agency may add lines to orders that they own. In addition; an agency may add lines to orders that they manage on behalf of advertisers. For advertisers, the list will include only lines that they own. For agencies, the list will include the lines that they own and the lines that belong to accounts that they manage on behalf of advertisers. -#### Example POST Request +#### Example POST Request (Display) ```json POST https://///accounts/23873345/orders/1235872/lines HTTP/1.1 @@ -1558,10 +2318,10 @@ AccessToken: "frequencycount":3, "frequencyinterval":"Day", "name":"My Line 1", - "productid":"456366", + "productid":"888899", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-05T06:00:00.000Z", "targeting":[ @@ -1579,25 +2339,25 @@ AccessToken: } ``` -#### Example POST Response +#### Example POST Response (Display) ```json HTTP/1.1 200 OK -Location: https://///accounts/23873345/orders/1235872/lines/345233 +Location: https://///accounts/23873345/orders/1235872/lines/345234 Content-Type: application/json Content-Length: 878 { - "id":"345233", + "id":"345234", "bookingstatus":"Draft", "comment":"Free form comment", "enddate":"2014-12-10T18:00:00.000Z", "frequencycount":3, "frequencyinterval":"Day", "name":"My Line 1", - "productid":"456366", + "productid":"888899", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-05T06:00:00.000Z", "targeting":[ @@ -1615,6 +2375,121 @@ Content-Length: 878 } ``` + + +#### Example POST Request (OOH) + +```json +POST https://///accounts/23873345/orders/1235872/lines HTTP/1.1 +Content-Type: application/json +AccessToken: +{ + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["20"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["5"] + + } + + ] +} +``` + +#### Example POST Response + +```json +HTTP/1.1 200 OK +Location: https://///accounts/23873345/orders/1235872/lines/345233 +Content-Type: application/json +Content-Length: 1234 +{ + "id":"345233", + "bookingstatus":"Draft", + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["20"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["5"] + + } + + ] +} +``` + #### Example GET Request ```json @@ -1626,37 +2501,85 @@ AccessToken: #### Example GET Response ```json -HTTP/1.1 200 OK Content-Type: application/json Content-Length: 587 +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 1240 { "lines":[ { - "id":"345233", - "bookingstatus":"Booked", + "id":"345233", + "bookingstatus":"Draft", + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["20"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["5"] + + } + ] + }, + { + "id":"345234", + "bookingstatus":"Draft", "comment":"Free form comment", "enddate":"2014-12-10T18:00:00.000Z", "frequencycount":3, "frequencyinterval":"Day", "name":"My Line 1", - "productid":"456366", + "productid":"888899", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-05T06:00:00.000Z", "targeting":[ - { - "id":"ABCD1234", - "name":"Age", - "value":"25-34" - }, - { - "id":"ABCD1235", - "name":"Gender", - "value":"Male" - } - ] - } - ] + { + "id":"ABCD1234", + "name":"Age", + "value":"25-34" + }, + { + "id":"ABCD1235", + "name":"Gender", + "value":"Male" + } + ] + } + ] } ``` @@ -1683,34 +2606,56 @@ GET https://///accounts/23873345/orders/1235872/lines/34523 Accept: application/json AccessToken: Example GET Response -HTTP/1.1 200 OK Content-Type: application/json Content-Length: 158 +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 1234 { "id":"345233", "bookingstatus":"Draft", - "comment":"Free form comment", - "enddate":"2014-12-10T18:00:00.000Z", - "frequencycount":3, - "frequencyinterval":"Day", - "name":"My Line 1", - "productid":"456366", - "ratetype":"CPM", - "rate":25.00, - "quantity":3000000, - "cost": 75000.00, - "startdate":"2014-12-05T06:00:00.000Z", - "targeting":[ - { - "id":"ABCD1234", - "name":"Age", - "value":"25-34" - }, - { - "id":"ABCD1235", - "name":"Gender", - "value":"Male" - } - ] -} + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["20"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["5"] + + } + + ] +} ``` #### Example PATCH Request @@ -1720,40 +2665,89 @@ PATCH https://///accounts/23873345/orders/1235872/lines/345 Content-Type: application/json AccessToken: { - "frequencycount":NULL, - "frequencyinterval":NULL, + "producttargeting": [ + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6", "7","8" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["30"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["10"] + + } + + ] } ``` #### Example PATCH Response ```json -HTTP/1.1 200 OK Content-Type: application/json Content-Length: 458 +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 1240 { "id":"345233", "bookingstatus":"Draft", - "comment":"Free form comment", - "enddate":"2014-12-10T18:00:00.000Z", - "name":"My Line 1", - "productid":"456366", - "ratetype":"CPM", - "rate":25.00, - "quantity":3000000, - "cost": 75000.00, - "startdate":"2014-12-05T06:00:00.000Z", - "targeting":[ - { - "id":"ABCD1234", - "name":"Age", - "value":"25-34" - }, - { - "id":"ABCD1235", - "name":"Gender", - "value":"Male" - } - ] -} + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6", "7", "8" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["30"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["10"] + + } + + ] +} ``` ### /accounts/{id}/orders/{id}/lines?$filter= @@ -1812,32 +2806,56 @@ AccessToken: #### Example Response ```json -HTTP/1.1 200 OK Content-Type: application/json Content-Length: 458 +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 1239 { "id":"345233", "bookingstatus":"PendingBooking", - "comment":"Free form comment", - "enddate":"2014-12-10T18:00:00.000Z", - "name":"My Line 1", - "productid":"456366", - "ratetype":"CPM", - "rate":25.00, - "quantity":3000000, - "cost": 75000.00, - "startdate":"2014-12-05T06:00:00.000Z", - "targeting":[ - { - "id":"ABCD1234", - "name":"Age", - "value":"25-34" - }, - { - "id":"ABCD1235", - "name":"Gender", - "value":"Male" - } - ] -} + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6", "7", "8" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["30"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["10"] + + } + + ] +} ``` ### /accounts/{id}/orders/{id}/lines/{id}?reserve @@ -1874,28 +2892,52 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 458 { "id":"345233", "bookingstatus":"PendingReservation", - "comment":"Free form comment", - "enddate":"2014-12-10T18:00:00.000Z", - "name":"My Line 1", - "productid":"456366", - "ratetype":"CPM", - "rate":25.00, - "quantity":3000000, - "cost": 75000.00, - "startdate":"2014-12-05T06:00:00.000Z", - "targeting":[ - { - "id":"ABCD1234", - "name":"Age", - "value":"25-34" - }, - { - "id":"ABCD1235", - "name":"Gender", - "value":"Male" - } - ] -} + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6", "7", "8" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["30"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["10"] + + } + + ] +} ``` ### /accounts/{id}/orders/{id}/lines/{id}?cancel @@ -1927,29 +2969,53 @@ AccessToken: HTTP/1.1 200 OK Content-Type: application/json Content-Length: 658 { "id":"345233", - "bookingstatus":"Canceled", - "comment":"Free form comment", - "enddate":"2014-12-10T18:00:00.000Z", - "name":"My Line 1", - "productid":"456366", - "ratetype":"CPM", - "rate":25.00, - "quantity":3000000, - "cost": 75000.00, - "startdate":"2014-12-05T06:00:00.000Z", - "targeting":[ - { - "id":"ABCD1234", - "name":"Age", - "value":"25-34" - }, - { - "id":"ABCD1235", - "name":"Gender", - "value":"Male" - } - ] -} + "bookingstatus":"Cancelled", + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6", "7", "8" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["30"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["10"] + + } + + ] +} ``` ### /accounts/{id}/orders/{id}/lines/{id}?reset @@ -1982,28 +3048,52 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 458 { "id":"345233", "bookingstatus":"Draft", - "comment":"Free form comment", - "enddate":"2014-12-10T18:00:00.000Z", - "name":"My Line 1", - "productid":"456366", - "ratetype":"CPM", - "rate":25.00, - "quantity":3000000, - "cost": 75000.00, - "startdate":"2014-12-05T06:00:00.000Z", - "targeting":[ - { - "id":"ABCD1234", - "name":"Age", - "value":"25-34" - }, - { - "id":"ABCD1235", - "name":"Gender", - "value":"Male" - } - ] -} + "comment": "Free form comment", + "enddate": "2014-12-10T18:00:00.000Z", + "name": "My Line 1", + "productid": "456366", + "providerdata": { "ponumber": "88873" } , + "startdate": "2014-12-05T06:00:00.000Z", + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6", "7", "8" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["30"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["10"] + + } + + ] +} ``` ## Path: Organizations @@ -2065,13 +3155,25 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 1879 "type":"Billing" } ], - "Fax":"2065551212", + "fax":"2065551212", "id":"12345678", "cat": [ 599, 602, 611 ], "name":"Contoso", "phone":"2065550100", "status":"Approved", - "url":"http://contoso.com" + "url":"http://contoso.com", + "organizationtype":"advertiser", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "14789" + } + ] + } + ] } ] } @@ -2131,13 +3233,25 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 1879 "type":"Billing" } ], - "Fax":"2065551212", + "fax":"2065551212", "id":"12345678", "cat": [ 599, 602, 611 ], "name":"Contoso", "phone":"2065550100", "status":"Approved", - "url":"http://contoso.com" + "url":"http://contoso.com", + "organizationtype":"advertiser", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "14789" + } + ] + } + ] } ``` @@ -2204,13 +3318,25 @@ Content-Type: application/json Content-Length: 1879 "type":"Billing" } ], - "Fax":"2065551212", + "fax":"2065551212", "id":"12345678", "cat": [ 599, 602, 611 ], "name":"Contoso", "phone":"2065550100", "status":"Approved", - "url":"http://contoso.com" + "url":"http://contoso.com", + "organizationtype":"advertiser", + "eids": [ + { + "source": "https://oohspace.co.uk", + "name": "SPACE", + "uids": [ + { + "id": "14789" + } + ] + } + ] } ``` @@ -2265,7 +3391,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 "ratetype":"CPM", "currency":"USD", "baseprice":25.00, - "deliveryyype":"Guaranteed", + "deliveryyype":"guaranteed", "domain":"mydomain.com", "estdailyavails":"Hundreds of Thousands", "icon":"http:////icon.jpg", @@ -2279,7 +3405,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 "display": { "pos": 6, "w": 300, - "h": 250, + "h": 250 } } }, @@ -2290,7 +3416,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 "display": { "pos": 6, "w": 160, - "h": 600, + "h": 600 } } } @@ -2304,12 +3430,127 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 "site": { "name": "Awesome Example Site", "domain": "examplesitedomain.com", - "amp": 0, + "amp": 0 } }, "tz":"Eastern Standard Time", "url":"http:////creativespec.aspx" + }, + { + "activedate": "2012-12-10T18:00:00.000Z", + "allownocreative": true, + "baseprice": 10000, + "currency": "GBP", + "deliverytype": "guaranteed", + "description": "All Digital 6-sheets in Metropolis", + "id": "456367", + "languages": ["EN"], + "leadtime": 1, + "name": "Metro", + "reservedexpirytime": "P7D", + "advertiseridaccess": ["adid1","adid2","adid3"], + "buyeridaccess": ["Buyidx"], + "intermediaryidaccess": [], + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547", + "1234931569", + "1235202465" + ], + "selectable": false + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "selectable": false, + "default": 16.6 + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "selectable": false, + "default": 5 + }, + { + "Name": "prohibitions", + "Type": "frames", + "datasource": "SPACE", + "target": "Schools", + "targetvalues": [ + "1234931339", + "1235190735" + ] + }, + { + "Name": "Prohibitions", + "Type": "Frames", + "DataSource": "Space", + "Target": "HFSS", + "TargetValues": [ + "1234931569", + "1235202465" + ] + } + ], + "availsgroupby": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id" + }, + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_type" + }, + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "format" + } + ], + "tz": "GMT", + "url": "http:////creativespec.aspx", + "adunits":[ + { + "id": "HDPS", + "name": "HD Portrait Static", + "spec": { + "display": { + "pos": 7, + "w": 1080, + "h": 1920 + } + } + }, + { + "id": "HDPV", + "name": "HD Portrait Video", + "spec": { + "video": { + "pos": 7, + "w": 1080, + "h": 1920 + } + } + } + ], } ] } @@ -2361,7 +3602,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 "display": { "pos": 6, "w": 300, - "h": 250, + "h": 250 } } }, @@ -2372,7 +3613,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 "display": { "pos": 6, "w": 160, - "h": 600, + "h": 600 } } } @@ -2386,7 +3627,7 @@ HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 "site": { "name": "Awesome Example Site", "domain": "examplesitedomain.com", - "amp": 0, + "amp": 0 } }, @@ -2401,14 +3642,11 @@ Gets a list of Products from the product catalog that matches the specified filt #### Verbs -* **POST**: (required) Gets a list of products from the publisher’s product catalog based on the criteria specified in the body of the request. For a list of the filter criteria that a caller may specify, see ProductSearch. The body of the response contains a collection of Product objects that match the filter criteria. +* **POST**: (required) Gets a list of products from the publisher’s product catalog based on the criteria specified in the body of the request. The body of the request is a ProductSearch object that contains the search criteria. For example, the client may search the catalog for products that use a specific ad format. The response includes a collection object that contains an array Product objects that match the search criteria. If no products match the search criteria, the array is empty. #### Rules -Product selection uses a logical AND between fields and a logical OR between field values. For example, the product is selected if it supports the Flash OR Image OR Text ad format, AND supports USD currency, AND specifies the foo OR bar product tag. - -_**Note: Where possible, use a simple GET call with filter that supports logical AND/OR functions. For example:**_ -> GET https://\/\/\/products?publisherid=7987654&producttags=Foo +Product search can use a logical AND or OR between productsearch object arrays. For example, the product is selected if it supports the Flash OR Image OR Text ad format, AND supports USD currency, AND specifies the foo OR bar product tag. #### Example Request @@ -2416,95 +3654,392 @@ _**Note: Where possible, use a simple GET call with filter that supports logical POST https://///products/search HTTP/1.1 Accept: application/json AccessToken: { - "spec": { - "display": { - "w": 300, - "h": 250, + "$or": [ + { + "adunit": { + "spec": { + "display": { + "w": 300, + "h": 250 + } + } + } + }, + { + "adunit": { + "spec": { + "display": { + "w": 600, + "h": 500 + } + } + } } - } + ] } ``` #### Example Response ```json -HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 1066 { - "products":[ - { - "id":"456366", - "publisherid":"7987654", - "name":"Unique Product Name", - "descripion":"Mrec and Skyscraper combination", - "producttags":"Foo Bar Zoo", - "ratetype":"CPM", - "currency":"USD", - "baseprice":25.00, - "deliveryyype":"Guaranteed", - "domain":"mydomain.com", - "estdailyavails":"Hundreds of Thousands", - "icon":"http:////icon.jpg", - "languages":["EN"], - "minspend":1000.00, - "adunits":[ + "products": [ { - "id": "1", - "name": "MRec", - "spec": { - "display": { - "pos": 6, - "w": 300, - "h": 250, - } - } - }, - { - "id": "2", - "name": "Skyscraper", - "spec": { - "display": { - "pos": 6, - "w": 160, - "h": 600, - } - } + "id": "456366", + "publisherid": "7987654", + "name": "Unique Product Name", + "description": "Mrec and Skyscraper combination", + "producttags": "Foo Bar Zoo", + "ratetype": "CPM", + "currency": "USD", + "baseprice": 25.00, + "deliverytype": "guaranteed", + "domain": "mydomain.com", + "estdailyavails": "Hundreds of Thousands", + "icon": "http:////icon.jpg", + "languages": [ + "EN" + ], + "minspend": 1000.00, + "adunit": [ + { + "id": "1", + "name": "MRec", + "spec": { + "display": { + "pos": 6, + "w": 300, + "h": 250 + } + } + }, + { + "id": "2", + "name": "Skyscraper", + "spec": { + "display": { + "pos": 6, + "w": 160, + "h": 600 + } + } + } + ], + "alladunits": 1, + "context": { + "regs": { + "gdpr": 0, + "coppa": 0 + }, + "site": { + "name": "Awesome Example Site", + "domain": "examplesitedomain.com", + "amp": 0 + } + }, + "tz": "Eastern Standard Time", + "url": "http:////creativespec.aspx" } - ], - "alladunits":1, - "context":{ - "regs": { - "gdpr": 0, - "coppa": 0 - }, - "site": { - "name": "Awesome Example Site", - "domain": "examplesitedomain.com", - "amp": 0, - } - - }, - "tz":"Eastern Standard Time", - "url":"http:////creativespec.aspx" - } - ] + ] } ``` ### /products/avails -Gets pricing and avails information (see ProductAvails) for the specified products (see ProductAvailsSearch). The response must support pagination. See Paging Query Parameters. +Gets pricing and avails information (see Avails) for the specified products. The response must support pagination. See Paging Query Parameters. #### Verbs -* **POST**: (required) Gets the availability and pricing information for a specified list of products based on flight dates, quantity and targeting. The body of the request contains the list of products and flight details (See ProductAvailsSearch). The body of the response contains a collection of - -ProductAvails objects (one for each product specified in the request). +* **POST**: (required) Gets the availability and pricing information for a specified list of products based on flight dates, quantity and targeting. The body of the request contains the list of products and flight details (See ProductAvailsSearch). The body of the response contains a collection of Avails objects (one for each product specified in the request). #### Rules Only organizations that have an Approved or Limited status may search for avails. -#### Example Request +#### Example Request (Out-Of-Home) + +```json +POST https://///products/avails HTTP/1.1 Accept: application/json +AccessToken: +{ + "AccountId": "23873345", + "EndDate": "2014-12-10T18:00:00.000Z", + "ProductIds": [ "456367" ], + "StartDate": "2014-12-05T06:00:00.000Z", + + "availabilityfields": [ + + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id" + }, + { + "name": "inventory", + "type": "frames", + "datasource": "time", + "target": "days" + }, + { + "name": "inventory", + "type": "frames", + "datasource": "time", + "target": "hours" + }, + { + "name": "delivery", + "type": "frames", + "dataSource": "shareofdisplay", + "target": "shareoftime" + }, + { + "name": "inventory", + "type": "audience", + "datasource": "metrics", + "target": "impacts" + }, + { + "name": "investment", + "type": "frames", + "datasource": "GBP", + "target": "fixed" + } + + + ], + + + "grouping": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id" + } + ], + + "producttargeting": [ + { + "name": "inventory", + "type": "frames", + "dataSource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339", + "1235190735", + "1234931338", + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues": [ "5", "6" ] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues": ["20"] + + }, + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues": ["5"] + + } + + ] +} +``` + +#### Example Response (Out-Of-Home) + +```json +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 +{ + "avails": [ + { + "currency": "GBP", + "productid": "456366", + "availsstatus": [ + { + "status": "available", + "reason": "", + "comment": "", + "context": [], + "producttargeting": [ + [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931339" + ] + }, + { + "name": "delivery", + "type": "frames", + "dataSource": "shareofdisplay", + "Target": "shareoftime", + "targetvalues": [ + "20" + ] + }, + { + "name": "inventory", + "type": "audience", + "datasource": "metrics", + "target": "impacts", + "targetvalues": [ + "15000" + ] + }, + { + "name": "investment", + "type": "frames", + "datasource": "GBP", + "target": "fixed", + "targetvalues": [ + "150" + ] + } + ], + [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1235190735" + ] + }, + { + "name": "delivery", + "type": "frames", + "dataSource": "shareofdisplay", + "Target": "shareoftime", + "targetvalues": [ + "20" + ] + }, + { + "name": "inventory", + "type": "audience", + "datasource": "metrics", + "target": "impacts", + "targetvalues": [ + "25000" + ] + }, + { + "name": "investment", + "type": "frames", + "datasource": "GBP", + "target": "fixed", + "targetvalues": [ + "250" + ] + } + ], + [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1234931338" + ] + }, + { + "name": "delivery", + "type": "frames", + "dataSource": "shareofdisplay", + "Target": "shareoftime", + "targetvalues": [ + "20" + ] + }, + { + "name": "inventory", + "type": "audience", + "datasource": "metrics", + "target": "impacts", + "targetvalues": [ + "10000" + ] + }, + { + "name": "investment", + "type": "frames", + "datasource": "GBP", + "target": "fixed", + "targetvalues": [ + "100" + ] + } + ], + [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "frame_id", + "targetvalues": [ + "1235191547" + ] + }, + { + "name": "delivery", + "type": "frames", + "dataSource": "shareofdisplay", + "Target": "shareoftime", + "targetvalues": [ + "20" + ] + }, + { + "name": "inventory", + "type": "audience", + "datasource": "metrics", + "target": "impacts", + "targetvalues": [ + "30000" + ] + }, + { + "name": "investment", + "type": "frames", + "datasource": "GBP", + "target": "fixed", + "targetvalues": [ + "300" + ] + } + ] + ] + } + ], + "price": 800 + } + ] +} +``` + +#### Example Request (Display) ```json POST https://///products/avails HTTP/1.1 Accept: application/json @@ -2515,7 +4050,7 @@ AccessToken: "enddate":"2014-12-10T18:00:00.000Z", "frequencycount":3, "frequencyinterval":"Day", - "Quantity":3000000, + "qty":3000000, "productids":["456366"], "targeting":[ { @@ -2532,7 +4067,7 @@ AccessToken: } ``` -#### Example Response +#### Example Response (Display) ```json HTTP/1.1 200 OK Content-Type: application/json Content-Length: 5899 @@ -2867,7 +4402,7 @@ AccessToken: "productid":"456366", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-09T06:00:00.000Z", "targeting":[ @@ -2899,7 +4434,7 @@ AccessToken: "productid":"456366", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-09T06:00:00.000Z", "targeting":[ @@ -2941,7 +4476,7 @@ AccessToken: "productid":"456366", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-09T06:00:00.000Z", "targeting":[ @@ -2997,7 +4532,7 @@ AccessToken: "productid":"456366", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-09T06:00:00.000Z", "targeting":[ @@ -3040,7 +4575,7 @@ AccessToken: "productid":"456366", "ratetype":"CPM", "rate":25.00, - "quantity":3000000, + "qty":3000000, "cost": 75000.00, "startdate":"2014-12-03T06:00:00.000Z", "targeting":[ @@ -3080,23 +4615,100 @@ Get the delivery statistics for a specific Line in an Order #### Verbs * **GET**: Gets the delivery information -#### Example GET Request +#### Example GET Request (Display) ```json GET https://///accounts/23873345/orders/1235872/lines/345233/stats HTTP/1.1 Content-Type: application/json AccessToken: ``` -#### Example GET Response +#### Example GET Response (Display) ```json HTTP/1.1 200 OK Content-Type: application/json Content-Length: 658 -{ +stats:[ + { "reportdate": "2014-12-25T18:00:00.000Z", "impressions": 2853232, "clicks": 25434, "ctr": 0.8914, "spend": 71330.80 -} + } +] + +``` +#### Example GET Request (DOOH) +```json +GET https://///accounts/23873345/orders/1235873/lines/345234/stats HTTP/1.1 +Content-Type: application/json +AccessToken: +``` +#### Example GET Response (DOOH) +```json +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 658 +stats : [ + { + "reportdate": "2023-08-05T00:00:00Z", + "frame_id":"1234567890" + "player_ref":"001B638445E6" + "spot_start_utc":"2023-07-05T11:00:00Z" + "spot_start_tz":"+01:00Z" + "spot_end_utc":"2023-07-05T11:00:10Z" + "spot_end_tz":"+01:00Z" + "spot_length":"10" + "share_of_time":"" + "creative_id":"C73839587" + "creative_name":"Balloon Door" + "third_party_creative_ref":"Balloon Door Final Final Final" + "creative_trigger_event":"Windy Weather" + "media_owner_playout_ref":"123456789020230705T110000" + }, + { + "reportdate": "2023-08-05T00:00:00Z", + "frame_id":"1234567890" + "player_ref":"001B638445E6" + "spot_start_utc":"2023-07-05T11:01:00Z" + "spot_start_tz":"+01:00Z" + "spot_end_utc":"2023-07-05T11:01:10Z" + "spot_end_tz":"+01:00Z" + "spot_length":"10" + "share_of_time":"" + "creative_id":"C73839588" + "creative_name":"Parma Door" + "third_party_creative_ref":"Parma Door Final Final Final Final" + "creative_trigger_event":"Hot Weather" + "media_owner_playout_ref":"123456789020230705T110100" + }, + {...} +] +``` + +#### Example GET Request (Traditional OOH) +```json +GET https://///accounts/23873345/orders/1235874/lines/345235/stats HTTP/1.1 +Content-Type: application/json +AccessToken: ``` +#### Example GET Response (Traditional OOH) +```json +HTTP/1.1 200 OK Content-Type: application/json Content-Length: 658 +stats : [ + { + "reportdate": "2023-08-05T00:00:00Z", + "frame_id":"1234567890" + "player_ref":"" + "spot_start_utc":"2023-07-05T00:00:00Z" + "spot_start_tz":"+01:00Z" + "spot_end_utc":"2023-07-18T00:00:00Z" + "spot_end_tz":"+01:00Z" + "spot_length":"" + "share_of_time":"33.33" + "creative_id":"P73839588" + "creative_name":"Balloon Door Print" + "third_party_creative_ref":"Balloon_Door_Final.pdf" + "creative_trigger_event":"" + "media_owner_playout_ref":"123456789020230705T000000" + } +] + ## Path: Account Messages @@ -3331,9 +4943,9 @@ To search the product catalog, send a POST request to /products/search. The body To get product availability and pricing information for specific products, send a POST request to /products/avails. You should make this call only to determine actual availability just before adding and booking a line; you should not use this call to present availability as part of a product catalog. -* The body of the request is a ProductAvailsSearch object. The client must specify a date range, quantity, list of product IDs and may optionally specify frequency and targeting information. To get custom rates and availability for an advertiser, include the account ID, which identifies the advertiser and agency. +* The body of the request is an Avails object. The client must specify a date range, quantity, list of product IDs and may optionally specify frequency and targeting information. To get custom rates and availability for an advertiser, include the account ID, which identifies the advertiser and agency. -The response includes a collection object that contains an array of ProductAvails objects. Each ProductAvails object contains the available quantity and pricing information for a product. The number of available impressions returned will be either the specified quantity, if the requested quantity is available, or less if there is fewer quantity available. +The response includes a collection object that contains an array of Avails objects. Each Avails object contains the available quantity and pricing information for a product. The number of available impressions returned will be either the specified quantity, if the requested quantity is available, or less if there is fewer quantity available. Note that the caller should not use this call to determine the maximum available impressions. Instead, they should use /products or /products/search which returns the estimated daily availability and base pricing details. If they use the avails search for product catalog purposes, they will likely display inaccurate pricing information to the user. For example, the pricing for 500,000,000 impressions may be less than the pricing for 100,000 impressions, which may lead the user to mistakenly believe that they’re getting the impressions for $5.00 CPM instead of $15.00 CPM. @@ -3355,7 +4967,7 @@ To upload a creative, send a POST request to /accounts/{id}/creatives. The body In most cases, the creative must pass editorial review before it may be assigned to a line. The requirement to add creative before assignment is specified for the product. To determine whether the creative passed editorial review, send a GET request to /accounts/{id}/creative/{id}. The response contains a Creative object. The creative passed editorial review if AdStatus is set to Approved. -To assign the creative to a line after it passes editorial review, send a POST request to /accounts/{id}/assignments. The body of the request is an Assignment object. The Assignment object specifies the creative ID and placement ID. If you assign more than one creative to a line, the creatives are rotated evenly. To control the rotation, set the optional weight property. +To assign the creative to a line after it passes editorial review, send a POST request to /accounts/{id}/assignments. The body of the request is an Assignment object. The Assignment object specifies the creative ID and placement ID. If you assign more than one creative to a line, the creatives are rotated evenly. To control the rotation, set the optional share of voice property. Note that a line must have a creative assigned to it before it may be booked. The creative may be the actual creative that the advertiser plans to run or a placeholder creative that is later replaced with the actual creative when it becomes available. However, the line will run with whichever creative is assigned to it (the actual creative or placeholder creative). @@ -3398,4 +5010,525 @@ The following diagram shows the relationships between the OpenDirect resources. ![Entity Relationship Diagram](images/ODv2EntityRelationshipDiagram.png) +## ProductTargeting for Physical Media + +OpenDirect (and OpenRTB) trades with real time Audience impressions, whereas Physical Media such as Out-Of-Home (OOH) media can be sold in the wider dimensions of time, share of time, location and audience. + +OOH Media physically manifests itself as display of the advert on a frame at a defined location and time which then gives an audience in the vicinity of that event an opportunity to see the advertising. + +OpenDirect 2.1 introduces the ProductTargeting object to discover and target the multidimensional aspect of physical media. + +The use of an array of ProductTargeting objects to describe an OpenDirect Product is at the discretion of the media owner/publisher. The simplest Physical Media OpenDirect Product could be described as display time on a single frame. + +The ProductTargeting Object has a core structure which acts as a matrix that accommodates the core physical, temporal and monetary dimensions of Physical Media trading + + +```json +"producttargeting": [ + { + "name": "", + "type": "", + "datasource": "", + "target": "", + "targetvalues":[] + } +] +``` + + +![ProductTargeting Summary](images/OOHbject_Summary.png) + + +The primary **name** dimensions for Physical Media trading are: + +- inventory: What a media owner / publisher sells in terms of Audience or Frames. +- delivery: How adverts are displayed from a start and end time, and the share of that display time. +- distribution: How the adverts are distributed across the times and locations booked by audience and/or investment. +- investment: How the campaign is quantified for trading purposes (Fixes price, Cost Per Thousand Audience, Cost Per Frame). +- prohibitions: Information about any brand safety prohibitions that will affect the playout of certain brand types in certain locations e.g. fast food prohibitions on certain locations. + +The use of the **datasource** in the ProductTargeting object allows the identification and inclusion of third party data sources into the OpenDirect schema, which both buyside and sell side may use to describe and discover their available Inventory, location and audiences in accordance with the third party schema. The third party schema may also be published and made discoverable as a collection object as detailed in Section 5 of this document. + +Examples of third-party **datasource** for Physical Media includes: + +- SPACE (UK OOH Industry frame inventory registry) +- ROUTE (UK OOH Industry audience measurement JIC) +- Geopath (US OOH Industry audience measurement) +- Nielson Total Audience Framework +- Quividi /AdMobilize computer vision analytics segment + + +### ProductTargeting: Inventory + +The Inventory **name** ProductTargeting Object allows a Physical Media owner to describe (and Physical Media buyer to understand) their inventory in terms of *frames* and *audience* then define the audience metrics that are available to targeted. + +#### Summary + +![Inventory ProductTargeting](images/name_inventory.png) + +#### inventory,frames,SPACE,x + +```json +"producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "SPACE", + "target": "FrameID", + "targetvalues": ["2000118775", "2000152956", "2000152957"] + } +] +``` + +As the initial implementation of OpenDirect 2.1 is in the UK, this object would use the UK Outsmart industry bodies' SPACE register for the identification of Frame inventory. + +SPACE has created a single source data point to coordinate and categorise the unique identification characteristics of all UK OOH inventory. This register identifies a frame with a common id and also allows media owners to attach frame details to the record in terms of dimension, media type, format and location. + +Further information can be found at [https://www.outsmart.org.uk/news/welcome-space](https://www.outsmart.org.uk/news/welcome-space) + +These classifications could be taken and used as a common format in countries/markets where no common standards currently exist. + +Alternatively, the Inventory.Frames ProductTargeting Object can reference a Media Owner / Publisher's own description of inventory e.g. +Inventory.Frames..TramWraps + +#### inventory,audience,Route,x + +```json +"producttargeting": [ + { + "name": "inventory", + "type": "audience", + "datasource": "Route", + "target": "demographic_custom", + "targetvalues":["sex=1 AND marital_status=1 AND social_grade<=3"] + } +] +``` + +As the initial implementation of OpenDirect 2.1 is in the UK, this object would use the Route dataset to describe and segment OOH audiences. + +Route produces audience estimates for out-of-home advertising in Britain. The data Route publishes tell subscribers how many and what type of people see an advertising campaign, and how often they do so. The information is used as the currency for planning, trading and valuing advertising investment in the medium at frame level. + +The trade associations for the buyers and sellers of the medium underwrite Route jointly. The IPAO represents the interests of the specialist OOH agencies (or planners & buyers) working on behalf of advertisers. Outsmart represents the interests of the media owners (or sellers). + +The underwriting agencies are [Kinetic Worldwide](http://www.kineticww.com/), [Mediacom Outdoor](http://www.mediacom.com/en/home), [Posterscope](http://www.posterscope.com/), [Rapport Worldwide](http://www.rapportww.com/uk/) and [Talon Outdoor](http://talonoutdoor.com/). The media owner guarantors are [Clear Channel Outdoor](http://www.clearchannel.co.uk/), [JCDecaux](http://www.jcdecaux.co.uk/) and [Global](http://global.com/outdoor/). + +Route has over 400 categories of audience classification and reports the audience metrics at both pedestrian and vehicular level as impacts, ratings, reach and cover. + +Further information on route can be found at [www.route.org.uk](http://www.route.org.uk/) + +#### inventory,frames,metrics,framecount + +```json +"producttargeting": [ + { + "name": "inventory", + "type": "frames", + "datasource": "metrics", + "target": "framecount", + "targetvalues":["1000"] + } +] +``` + +Allows the Media Owner / Publisher to define the total number of frames to be targeted and allows the buyer to specify this metric when performing an availability check or setting up an order line. + +#### inventory,audience,metrics,x + +```json +"producttargeting": [ + { + "name": "inventory", + "type": "audience", + "datasource": "metrics", + "target": "impacts", + "targetvalues":["5000000"] + } +] +``` + +Allows the Media Owner / Publisher to define the audience metrics that are available to targeted and allows the buyer to specify these metrics when performing an availability check or setting up an order line. +These metrics may be identified as: +* impacts +* cover +* reach +* frequency + + +### ProductTargeting: Delivery + +The Delivery ProductTargeting Object allows a Physical Media owner to describe (and media buyer to understand) how their campaign is delivered to selected inventory. + +#### Summary + +![Delivery ProductTargeting](images/name_delivery.png) + +#### delivery,frames,time,days + +If this is made available, this dynamic ProductTargeting Object details an array of numbered days that can be targeted within in the product. This dynamic array takes the form of the days available from the booking line start and end date + +e.g. + +Booking line date 08/11/20 to 17/11/20 + +```json +"producttargeting": [ + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues":["0","1","2","3","4","5","6"] + } +] +``` + +The ProductTargeting Object field *Selectable* indicates if this array based on ISO 8601 is further targetable e.g. the days array of ["0","1","2","3","4","5","6"] is returned, and if the days are flagged as *selectable*, the buyer may select days ["5","6"]. + +#### delivery,frames,time,hours + +If this is made available, this dynamic ProductTargeting Object details an array of numbered hours that can be targeted within in the product. This dynamic array takes the form of the hours available from the specified booking line start and end date + +e.g. + +Booking line date 08/11/20 00:00 to 17/11/20 00:00 + +```json +"producttargeting": [ + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "days", + "targetvalues":["0","1","2","3","4",……,"24","25","26",…..,"48",……,"72",…..,"96",……,"120",….,"144","145",….,"167"] + } +] +``` + +The OOHbject field *Selectable* indicates if this array is further targetable e.g. the hours array is returned, and if the hours are flagged as *selectable*, the buyer may select Hours ["6","7","8","9","30","31","32","33"]. + +The example below shows how the hours of 10am to 2pm on Day 1 and Day 2 would be targeted as an array selection. + +Hours["10","11","12","13","34","35","36","37"] + +![Time Array](images/time_array.png) + +Practically, the booking UI should convert the days/hours selected from a calendar based UI into the hour array in the background. + +#### delivery,frames,time,timezone + +```json +"producttargeting": [ + { + "name": "delivery", + "type": "frames", + "datasource": "time", + "target": "timezone", + "targetvalues":["Local"] + } +] +``` + +This ProductTargeting Object can be used in the targeting array to indicate if the days and/or hour delivery of the campaign happens in the local time zone (e.g. the local time of where the advert is displayed) or Coordinated Universal Time (e.g. UTC playout would ensure the advert plays at the same exact moment around the world). +The TargetValues are "Local" or "UTC". The default is "Local" time + +#### delivery,frames,shareofdisplay,shareoftime + +```json +"producttargeting": [ + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "shareoftime", + "targetvalues":["25"] + } +] +``` + +This ProductTargeting Object details the *shareoftime* that can be targeted within the product. The *shareoftime* can be described as the percentage of time the advert appears on screen vs the time the advert does not appear on screen over the flight of the campaign. + +e.g. + +A fixed 1 in 4 loop/scrolling billboard will have a *shareoftime* value of 25 + +A classic paper/vinyl billboard will have a *shareoftime* value of 100 + +#### delivery,frames,shareofdisplay,spot + +```json +"producttargeting": [ + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spot", + "targetvalues":["10"] + } +] +``` + +This ProductTargeting Object details the *Spot* length (or array of lengths) in seconds that a digital advert can run for each time it appears on a frame. The *Spot* length will affect the frequency of play out within the campaign flight. + +e.g. if the Campaign flight is 10 hours, the *shareoftime* value is 20(%) and the creative is 1 hour long, the *spot* will play 2 times. + +if the Campaign flight is 10 hours, the *shareoftime* value is 20(%) and the creative is 10s long, the *spot* will play 720 times. + +If the Campaign flight is 10 hours, the *shareoftime* value is 100(%) and the creative is 10s long, the *spot* will play 3600 times. + +#### delivery,frames,shareofdisplay,spotbreaklength (Optional) + +```json +"producttargeting": [ + { + "name": "delivery", + "type": "frames", + "datasource": "shareofdisplay", + "target": "spotbreaklength", + "targetvalues":["50"] + } +] +``` + +If the product delivers the campaign within a fixed loop, the *spotbreaklength* ProductTargeting Object details the length of time in seconds between the Spots being played. + +e.g. in a 30 second loop where the Spot length is 5 Seconds: + +Spot = 5 + +SpotBreakLength = 25 + +#### delivery,audience,datasource,shareofimpacts + +```json +"producttargeting": [ + { + "name": "delivery", + "type": "audience", + "datasource": "Route", + "target": "shareofimpacts", + "targetvalues":["30"] + } +] +``` + +An average % share of viewed impacts across the targeted ProductTargeting Object according to the Audience DataSource identified. + +e.g. the campaign needs to be delivered to 30% of the available 'Affluent Female Shopper Audience' over the flight of the campaign + + + +### ProductTargeting: Investment + +The Investment ProductTargeting Object allows a Physical Media owner to describe (and a media buyer to discover) their inventory in terms of *Frames* and *Audience* Investment. + +#### Summary + +![Investment ProductTargeting](images/name_investment.png) + +*local_currency* is defined as the currency that the order is going to be transacted in to ISO 4217 currency codes e.g. GBP, USD, EUR + +#### investment,frames,local_currency,CPF + +```json +"producttargeting": [ + { + "name": "investment", + "type": "frames", + "datasource": "local_currency", + "target": "CPF", + "targetvalues":["100"] + } +] +``` + +If this is made available, this dynamic ProductTargeting Object details (in terms of the local currency) the requested *cost per frame* price or a target *cost per frame* price based on the other ProductTargeting Object values given. + +#### investment,frames,local_currency,fixed + +```json +"producttargeting": [ + { + "name": "investment", + "type": "frames", + "datasource": "local_currency", + "target": "fixed", + "targetvalues":["5000"] + } +] +``` + +If this is made available, this dynamic ProductTargeting Object details (in terms of the local currency) the requested total Product price or given total Product price based on the other ProductTargeting Object values given. + +#### investment,audience,local_currency,CPT + +```json +"producttargeting": [ + { + "name": "investment", + "type": "frames", + "datasource": "local_currency", + "target": "CPT", + "targetvalues":["18"] + } +] +``` + +If this is made available, this dynamic ProductTargeting Object details (in terms of the local currency) the requested *cost per thousand* price or a target *cost per thousand* price based on the other ProductTargeting Object values given. + +#### investment,audience,local_currency,fixed + +```json +"producttargeting": [ + { + "name": "investment", + "type": "audience", + "datasource": "local_currency", + "target": "fixed", + "targetvalues":["6000"] + } +] +``` + +If this is made available, this dynamic ProductTargeting Object details (in terms of the local currency) the requested total Product price or given total Product price based on the other ProductTargeting Object values given. + + + +### ProductTargeting: Distribution + +The Distribution ProductTargeting Object allows an Physical Media owner to describe (and a media buyer to understand and specify) if their campaign Delivery is Distributed evenly or flexibly across the Campaign flight in terms of Time, audience and/or investment. + +Specific targets for Audience, Location and Display Time would be made using arrays of Inventory and Delivery ProductTargeting Objects, rather than the Distribution ProductTargeting Object itself. + +#### Summary + +![Distribution ProductTargeting](images/name_distribution.png) + +The segment array for every Distribution.z.x.y object gives a choice of an even *fixed* distribution or a *flexible* distribution that achieves the Campaign Inventory and Delivery targets over the campaign flight. + +#### Distribution,Frames,x,y + +```json +"producttargeting": [ + { + "name": "distribution", + "type": "frames", + "datasource": "shareofdisplay", + "target": "day" + } +] +``` + +This ProductTargeting Object describes how the delivery of the campaign display is distributed over the campaign to frames, times or (DataSource) locations. + +The default setting for this Distribution ProductTargeting Object is *flexible* meaning that the targeted *shareofdisplay* and/or frame volumes will be achieved in total over the campaign flight. + +e.g. +- shareofdisplay,day = Fixed, the ShareOfTime and/or total Spot Frequency will be delivered over each selected Day over the campaign flight +- shareofdisplay,hour = Fixed, the averaged ShareOfTime and/or total Spot Frequency will be delivered on each selected Hour over the campaign flight +- time,days = fixed, the same volume of Frames will be delivered on each selected Day over the campaign flight +- time,hours = fixed, the same volume of Frames will be delivered on each selected Hour over the campaign flight +- (datasource),frame_id = Fixed, a fixed volume of frames will deliver the campaign targeting objectives. +- (datasource),region = Fixed, a fixed volume of frames per region will deliver the campaign targeting objectives (there will be fliexibility within the region which frames are actually used to deliver the campaign targets) + +#### Distribution,Audience,x,y + +```json +"producttargeting": [ + { + "name": "distribution", + "type": "audience", + "datasource": "time", + "target": "day" + } +] +``` + +This ProductTargeting Object describes how the delivery of the targeted campaign audience is distributed over the campaign flight to audience, time or (DataSource) locations. + +The default setting for this Distribution ProductTargeting Object is *flexible*; meaning that the total targeted audience impact volume will be delivered over the campaign flight time, but different days, hours and/or locations may have different audience delivery volumes. + +e.g. +- time,day = fixed, the same volume of audience impacts will be delivered on each day to achieve the total audience target +- time,hour = fixed, the same volume of audience impacts will be delivered on hour +- (datasource),frame_id = Fixed, the same volume of audience impacts will be delivered at each Frame location over the campaign flight. +- (datasource),postal_sector = Fixed, the same volume of audience impacts will be delivered within each Postal Sector over the campaign flight. +- (datasource),town = Fixed, the same volume of audience impacts will be delivered within each Town over the campaign flight. +- (datasource),conurbation = Fixed, the same volume of audience impacts will be delivered within each Conurbation over the campaign flight. +- (datasource),tv_area = Fixed, the same volume of audience impacts will be delivered within each TV Area over the campaign flight. +- (datasource),region = Fixed, the same volume of audience impacts will be delivered within each TV Area over the campaign flight. + +The addition of Inventory,Audience,Metrics,x ProductTargeting Object to the targeting array determines the Audience metrics being used e.g. + +- inventory,audience,metrics,cover (percentage of the population that saw the advert) +- inventory,audience,metrics,reach (Unique Audience Count) +- inventory,audience,metrics,frequency (eNumber of times the Audience reached sees the Advert) + +It is up to the Media Owner if they can support such campaign metrics & scheduling distribution in each product they make available to the Media Buyer. + +#### Distribution,Investment,x,y + +```json +"producttargeting": [ + { + "name": "distribution", + "type": "investment", + "datasource": "time", + "target": "day" + } +] +``` + + +This ProductTargeting Object describes how the delivery of the targeted campaign investment is distributed over time and locations in the campaign flight. + +The default setting for this Distribution OOHbject is *flexible* meaning that the targeted campaign investment will be delivered over the campaign flight time. Individual days, hours or locations may have different investment pacing. + +e.g. +- time,day = fixed, the same investment will be delivered on each day to achieve the total investment target +- time,hour = fixed, the same investment will be delivered in each hour to achieve the same investment target +- (datasource),frame_id= Fixed, the same investment will be delivered at each Frame location over the campaign flight to achieve the campaign investment target. +- (datasource),postal_sector = Fixed, the same investment will be delivered within each Postal Sector over the campaign flight to achieve the campaign investment target. +- (datasource),town = Fixed, the same investment will be delivered within each Town over the campaign flight to achieve the campaign investment target. +- (datasource),conurbation = Fixed, the same investment will be delivered within each Conurbation over the campaign flight to achieve the campaign investment target. +- (datasource),tv_area = Fixed, the same investment will be delivered within each TV Area over the campaign flight to achieve the campaign investment target. +- (datasource),region = Fixed, the same investment impacts will be delivered within each TV Area over the campaign flight to achieve the campaign investment target. + + + +### ProductTargeting: Prohibitions + +The Prohibitions ProductTargeting Object allows an OOH media owner to describe (and OOH media buyer to understand) their inventory in terms of frame prohibitions from a named DataSource that will affect if their brand or advert can be displayed at a certain product locations. + +#### Summary + +![Prohibitions ProductTargeting](images/name_prohibitions.png) + +This ProductTargeting Object is used to expose all FrameIDs (via the Segment) which may be affected by any of the prohibitions listed. + +e.g. if the product contains the datasource:SPACE frame ids of + +1234931339, 1235190735, 1234931338, 1235191547,1234931569 and 1235202465 + +and the frames + +1234931339, 1235190735 + +are prohibited from displaying alcohol brands, + +this could be shown as: + +```json +"producttargeting": [ + { + "name": "prohibitions", + "type": "frames", + "datasource": "SPACE", + "target": "Alcohol" + "targetvalues":["1234931339", "1235190735"] + } +] +``` + +This is for descriptive purpose only and the master frame to prohibitions table may be managed elsewhere by the publisher/media owner. diff --git a/images/AppendixB.png b/images/AppendixB.png new file mode 100644 index 0000000..d3543c6 Binary files /dev/null and b/images/AppendixB.png differ diff --git a/images/Avails2Orderline.png b/images/Avails2Orderline.png new file mode 100644 index 0000000..8737c8b Binary files /dev/null and b/images/Avails2Orderline.png differ diff --git a/images/Avails2Orderline_old.png b/images/Avails2Orderline_old.png new file mode 100644 index 0000000..25d3de9 Binary files /dev/null and b/images/Avails2Orderline_old.png differ diff --git a/images/OOHbject_Summary.png b/images/OOHbject_Summary.png new file mode 100644 index 0000000..4a75d92 Binary files /dev/null and b/images/OOHbject_Summary.png differ diff --git a/images/OpenDirectComparison_1_0.png b/images/OpenDirectComparison_1_0.png new file mode 100644 index 0000000..6b87968 Binary files /dev/null and b/images/OpenDirectComparison_1_0.png differ diff --git a/images/OpenDirectComparison_1_1_new.png b/images/OpenDirectComparison_1_1_new.png new file mode 100644 index 0000000..1858ebe Binary files /dev/null and b/images/OpenDirectComparison_1_1_new.png differ diff --git a/images/OpenDirectSummary.png b/images/OpenDirectSummary.png new file mode 100644 index 0000000..fc805e1 Binary files /dev/null and b/images/OpenDirectSummary.png differ diff --git a/images/advertiser_workflow.png b/images/advertiser_workflow.png new file mode 100644 index 0000000..2597857 Binary files /dev/null and b/images/advertiser_workflow.png differ diff --git a/images/booking_state_ooh.png b/images/booking_state_ooh.png new file mode 100644 index 0000000..ff0a2af Binary files /dev/null and b/images/booking_state_ooh.png differ diff --git a/images/change_request.png b/images/change_request.png new file mode 100644 index 0000000..d37c748 Binary files /dev/null and b/images/change_request.png differ diff --git a/images/change_request_old.png b/images/change_request_old.png new file mode 100644 index 0000000..9b3cd45 Binary files /dev/null and b/images/change_request_old.png differ diff --git a/images/image_3.1.png b/images/image_3.1.png new file mode 100644 index 0000000..c389397 Binary files /dev/null and b/images/image_3.1.png differ diff --git a/images/image_3.2.png b/images/image_3.2.png new file mode 100644 index 0000000..73a4624 Binary files /dev/null and b/images/image_3.2.png differ diff --git a/images/image_3.png b/images/image_3.png new file mode 100644 index 0000000..1746ca0 Binary files /dev/null and b/images/image_3.png differ diff --git a/images/minimum_resources.png b/images/minimum_resources.png new file mode 100644 index 0000000..06c2edd Binary files /dev/null and b/images/minimum_resources.png differ diff --git a/images/name_delivery.png b/images/name_delivery.png new file mode 100644 index 0000000..b9b130c Binary files /dev/null and b/images/name_delivery.png differ diff --git a/images/name_distribution.png b/images/name_distribution.png new file mode 100644 index 0000000..e6c7ef5 Binary files /dev/null and b/images/name_distribution.png differ diff --git a/images/name_inventory.png b/images/name_inventory.png new file mode 100644 index 0000000..043ad4d Binary files /dev/null and b/images/name_inventory.png differ diff --git a/images/name_investment.png b/images/name_investment.png new file mode 100644 index 0000000..5a6df20 Binary files /dev/null and b/images/name_investment.png differ diff --git a/images/name_prohibitions.png b/images/name_prohibitions.png new file mode 100644 index 0000000..1b0fc59 Binary files /dev/null and b/images/name_prohibitions.png differ diff --git a/images/publisher_workflow_ooh.png b/images/publisher_workflow_ooh.png new file mode 100644 index 0000000..907560f Binary files /dev/null and b/images/publisher_workflow_ooh.png differ diff --git a/images/resource_model_ooh.png b/images/resource_model_ooh.png new file mode 100644 index 0000000..1c1a306 Binary files /dev/null and b/images/resource_model_ooh.png differ diff --git a/images/time_array.png b/images/time_array.png new file mode 100644 index 0000000..64a5ab3 Binary files /dev/null and b/images/time_array.png differ